Migrating from Sign API v2 to v3
Sign API v3 is a preview release. The API surface may change before general availability. Do not use it in production without accepting that breaking changes may occur.
See Sign API Versions → Migrating from v2 to v3 for a side-by-side comparison of each migration step.
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.
{
"content": "<base64-encoded-pdf>",
"filename": "contract.pdf"
}
{
"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.
{
"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" }
]
}
{
"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.
Each signer only signs the documents listed in their document_signatures. A signer with no entry for a given document will not be asked to sign it.
Signing sequence
The sequence field on each signer controls the signing order across the whole request:
| Value | Behaviour |
|---|---|
1 | Signs first. Request moves to sequence 2 only after all sequence-1 signers are done. |
2, 3, … | Signs after the previous sequence group completes. |
-1 (default) | No specific order — can sign at any time. |
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:
| Field | Description |
|---|---|
page | Page number, 0-indexed, as a string ("0" = first page) |
x | Pixels from the left edge |
y | Pixels from the top edge |
width | Width of the signature box in pixels |
height | Height of the signature box in pixels |
rotation | Rotation in degrees (0–360, optional) |
By form field:
"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).
{
"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
}
]
}
}
]
}
{
"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
{
"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:
{
"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.
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.