Create a signature request

POST https://api.craftkit.dev/v1/signatures

Takes a succeeded render, pushes its PDF to the signature service as an atomic create-and-send signing request, and returns the persisted request at 201. The provider emails the recipients and hosts the signing UI; lifecycle changes flow back to Craftkit (see Status lifecycle).

Authorization

string

required

Bearer ck_live_… — a project API key. The render must belong to this key’s project.

Idempotency-Key

string

Optional. A retried POST with the same key returns the original request instead of minting (and billing) a second signing envelope. Keys are scoped per project; a replay returns 200.

Body

renderId

string

required

UUID of the render to sign. Must be in this project and have status: "succeeded" with a stored PDF asset.

name

string

Human-readable request name (1–255 chars). Defaults to Signature request <render-id-prefix>.

recipients

object[]

required

1–20 recipients. At least one fields or anchorTags entry is required when any recipient is a Signer.

Show recipient

firstName

string

required

First name (1–100 chars).

lastName

string

Last name (≤100 chars).

string

required

Email address (≤255 chars).

designation

string

default:"Signer"

One of Signer, Approver, CC.

order

number

Signing order (≥1). When supplied on any recipient, values must be unique and within [1, recipientCount]. Defaults to the array position (1-based).

fields

object[]

Up to 200 explicit placements by page + coordinates. Coordinates are percentages of page width/height (0–100), origin top-left.

Show field

recipientIndex

number

required

0-based index into recipients. Must reference an existing recipient.

type

string

required

One of signature, initial, text, date, checkbox, dropdown, radio_buttons, text_area.

page

number

required

1-based page number.

number

required

Horizontal position, 0–100 (% of page width).

number

required

Vertical position, 0–100 (% of page height).

width

number

Field width, >0 and ≤100 (% of page width).

height

number

Field height, >0 and ≤100 (% of page height).

required

boolean

Whether the field must be completed.

anchorTags

object[]

Up to 200 text-anchor placements (recommended for Craftkit templates — add the anchor string to the template body and reference it here). Anchor width/height are points relative to the matched text, not page percentages.

Show anchorTag

anchorString

string

required

Literal text to anchor on (1–200 chars).

type

string

required

One of signature, initials, text, date, checkbox. Note initials (plural) here vs. initial in fields.

recipientIndex

number

required

0-based index into recipients. Must reference an existing recipient.

width

number

Offset width in points, >0 and ≤1000.

height

number

Offset height in points, >0 and ≤1000.

required

boolean

Whether the field must be completed.

ignoreIfNotPresent

boolean

Skip silently if the anchor text isn’t found in the document.

expirationHours

number

Hours until the request expires (1–8760). Defaults to the provider default (168).

Response

201 when the request is created, or 200 when an idempotency key matched an existing request.

string

Craftkit signature request id (UUID). Use for status, cancel, download, certificate.

renderId

string

The render that was sent for signature.

name

string

status

string

sent on creation. See the status lifecycle.

recipients

object[]

Recipient snapshot, now carrying provider-assigned ids.

expirationHours

number | null

signedDownloadUrl

string | null

Authenticated download URL; null until archived.

certificateUrl

string | null

Authenticated completion-certificate URL (/v1/signatures/{id}/certificate); null until available.

errorMessage

string | null

createdAt

string

completedAt

string | null

Errors

Status	code	Meaning
400	`invalid_json`	Body is not valid JSON.
400	`invalid_request`	Body failed schema validation (`issues` included).
401	`unauthorized`	Missing/invalid/revoked key.
402	`signature_credits_exhausted`	The signature service account is out of credits.
404	`not_found`	No such render in this key’s project.
409	`conflict`	Render is not ready for signing (not `succeeded`, or no PDF).
413	`document_too_large`	Rendered PDF exceeds the 20MB signing limit.
502	`signature_provider_error`	The signature service rejected the create-and-send request.
503	`signatures_unavailable`	Digital signatures are not configured on this server.

cURL

curl -X POST https://api.craftkit.dev/v1/signatures \
  -H "Authorization: Bearer $CRAFTKIT_API_KEY" \
  -H "Idempotency-Key: sign-order-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "renderId": "0193c2c3-1111-7aaa-8bbb-000000000001",
    "name": "Charter handover — BK-12345",
    "recipients": [
      { "firstName": "Jane", "lastName": "Doe", "email": "jane@example.com", "designation": "Signer", "order": 1 }
    ],
    "anchorTags": [
      { "anchorString": "{{sign_here}}", "type": "signature", "recipientIndex": 0, "required": true }
    ],
    "expirationHours": 168
  }'

201

{
  "id": "0193c2c3-2222-7aaa-8bbb-000000000002",
  "renderId": "0193c2c3-1111-7aaa-8bbb-000000000001",
  "name": "Charter handover — BK-12345",
  "status": "sent",
  "recipients": [
    {
      "id": "rcp_8e10-12ab34cd56ef",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "expirationHours": 168,
  "signedDownloadUrl": null,
  "certificateUrl": null,
  "errorMessage": null,
  "createdAt": "2026-06-05T10:00:00.000Z",
  "completedAt": null
}

​Authorization

​Body

​Response

​Errors

Authorization

Body

Response

Errors