Document Signing

The Signing API lets you create signing envelopes for cases, promote documents into envelopes, and track the signing lifecycle. External signers receive magic-link emails to sign documents without an Optimaite account.

Endpoints

Method	Path	Description
GET	/api/v1/cases/{case_id}/signed-documents	List signing envelopes for a case
POST	/api/v1/cases/{case_id}/signing-envelopes	Create a signing envelope
POST	/api/v1/signing/promote-to-envelope	Promote documents into a draft envelope

The Signing Envelope Object

{
  "id": "env_01ABCDEFG",
  "case_id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Employment Agreement -- Smith",
  "status": "in_progress",
  "documents": [
    {
      "id": "sigdoc_01",
      "document_id": "doc_01ABCDEF",
      "filename": "employment_agreement.pdf"
    }
  ],
  "signers": [
    {
      "id": "signer_01",
      "name": "John Smith",
      "email": "john.smith@example.com",
      "role": "signer",
      "status": "pending",
      "signed_at": null
    }
  ],
  "created_at": "2026-05-20T10:00:00Z",
  "completed_at": null
}

Create a Signing Envelope

POST /api/v1/cases/{case_id}/signing-envelopes

{
  "title": "Employment Agreement -- Smith",
  "document_ids": ["doc_01ABCDEF"],
  "signers": [
    {
      "name": "John Smith",
      "email": "john.smith@example.com",
      "role": "signer"
    },
    {
      "name": "HR Director",
      "email": "hr@company.de",
      "role": "signer"
    }
  ],
  "signing_order": "sequential",
  "send_emails": true
}

When send_emails is true, each signer receives a magic-link email to access and sign the document.

Response

Returns 201 Created with the full envelope object.

Promote Documents to Envelope

POST /api/v1/signing/promote-to-envelope

Convert existing Optimaite documents into a draft signing envelope:

{
  "case_id": "550e8400-e29b-41d4-a716-446655440000",
  "document_ids": ["doc_01ABCDEF", "doc_02GHIJKL"],
  "title": "NDA Package"
}

This creates a draft envelope. Add signers and send it separately.

List Signed Documents

GET /api/v1/cases/{case_id}/signed-documents

Returns all signing envelopes linked to a case, including their current status.

Response

{
  "data": [
    {
      "id": "env_01ABCDEFG",
      "title": "Employment Agreement -- Smith",
      "status": "completed",
      "signers": [
        { "name": "John Smith", "status": "signed", "signed_at": "2026-05-21T09:30:00Z" },
        { "name": "HR Director", "status": "signed", "signed_at": "2026-05-22T11:00:00Z" }
      ]
    }
  ]
}

Envelope Status Lifecycle

draft -> sent -> in_progress -> completed
                                    \-> expired
                                    \-> declined

Status	Description
draft	Envelope created, not yet sent to signers
sent	Signer emails have been sent
in_progress	At least one signer has opened the document
completed	All signers have signed
expired	Signing deadline passed without completion
declined	A signer declined to sign

Error Responses

Status	Code	Meaning
400	NO_DOCUMENTS	No document IDs provided
400	NO_SIGNERS	No signers provided
403	AUTH_INSUFFICIENT_SCOPE	Missing documents:write scope
404	CASE_NOT_FOUND	Case ID does not exist
404	DOCUMENT_NOT_FOUND	One or more document IDs do not exist

Next Steps

• Documents -- Manage documents to sign
• Cases -- Link envelopes to cases
• Parties -- Signer contact management