# Migrating from Sign API v2 to v3

:::warning{title="Preview — Subject to Change"}

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.

:::

## 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`.

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

```json title="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.

```json title="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" }
  ]
}
```

```json title="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.

:::info{title="Not every signer signs every document"}

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:**

```json
"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).

```json title="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
          }
        ]
      }
    }
  ]
}
```

```json title="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

```json title="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`:

```json
{
  "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.

```bash
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.