Migrating from Sign API v2 to v3

The v3 Draft Workflow

The core difference in v3 is a document-first, explicit-initiation model. A signature request always starts in DRAFT and nothing is sent to signers until you explicitly initiate it. This gives you full control to assemble and configure everything before committing.

The four steps are: upload documents → create SR → assign signers → initiate.

Step 1 — Upload documents

Every document must be uploaded before it can be referenced in a signature request. Upload each PDF separately and save the returned id.

POST /v3/documents
{
  "content": "<base64-encoded-pdf>",
  "filename": "contract.pdf"
}

Response
{
  "id": "doc-aaa-111",
  "name": "contract.pdf",
  "version_id": "ver-aaa-111"
}

You can upload up to 50 documents to include in a single signature request.

Step 2 — Create the signature request

Reference the uploaded document IDs in the documents array. The SR is created in DRAFT — no emails are sent yet.

POST /v3/signature-requests
{
  "title": "Q1 2025 Agreements",
  "message": "Please sign the documents assigned to you.",
  "quality": "AES",
  "legislation": "ZERTES",
  "documents": [
    { "id": "doc-aaa-111" },
    { "id": "doc-bbb-222" }
  ]
}

Response (status_overall: DRAFT)
{
  "id": "sr-xyz-999",
  "status_overall": "DRAFT",
  ...
}

Step 3 — Add signers and assign documents

Each signer is added via a separate call. The document_signatures array controls which documents the signer must sign, in what order, and where their signature appears on the page.

Signing sequence

The sequence field on each signer controls the signing order across the whole request:

Visual signature placement

Within document_signatures, the optional visual_signature field places the signer's visible signature stamp on the page. You can position it by coordinates or by PDF form field name.

By coordinates:

By form field:

Code
"visual_signature": {
  "form_field": "SignatureField1"
}

Example: two signers, two documents, each signs only one

Alice signs only doc-aaa-111 (first), Bob signs only doc-bbb-222 (after Alice).

POST /v3/signature-requests/sr-xyz-999/signatures — Alice
{
  "account_email": "alice@example.com",
  "sequence": 1,
  "document_signatures": [
    {
      "document_id": "doc-aaa-111",
      "visual_signature": {
        "positions": [
          {
            "page": "0",
            "x": 300,
            "y": 600,
            "width": 180,
            "height": 80
          }
        ]
      }
    }
  ]
}

POST /v3/signature-requests/sr-xyz-999/signatures — Bob
{
  "account_email": "bob@example.com",
  "sequence": 2,
  "document_signatures": [
    {
      "document_id": "doc-bbb-222",
      "visual_signature": {
        "positions": [
          {
            "page": "2",
            "x": 100,
            "y": 700,
            "width": 180,
            "height": 80
          }
        ]
      }
    }
  ]
}

Example: one signer signs both documents

POST /v3/signature-requests/sr-xyz-999/signatures — Carol
{
  "account_email": "carol@example.com",
  "sequence": 1,
  "document_signatures": [
    {
      "document_id": "doc-aaa-111",
      "visual_signature": {
        "positions": [{ "page": "0", "x": 300, "y": 600, "width": 180, "height": 80 }]
      }
    },
    {
      "document_id": "doc-bbb-222",
      "visual_signature": {
        "form_field": "CarolSignatureField"
      }
    }
  ]
}

Signers without a Skribble account

Use signer_identity_data instead of account_email:

Code
{
  "signer_identity_data": {
    "email_address": "external@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "language": "en"
  },
  "sequence": 1,
  "document_signatures": [
    { "document_id": "doc-aaa-111" }
  ]
}

Step 4 — Initiate

Once all signers are configured, initiate the request. This transitions it from DRAFT to OPEN and sends invitation emails — starting with sequence 1 signers.

Code
POST /v3/signature-requests/sr-xyz-999/initiate

No request body is needed. Signers in later sequence groups receive their invitations automatically once earlier groups complete.