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.

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

string

required

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

string

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

object[]

required

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

Show recipient

string

required

First name (1–100 chars).

string

Last name (≤100 chars).

string

required

Email address (≤255 chars).

string

default:"Signer"

One of Signer, Approver, CC.

number

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

object[]

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

Show field

number

required

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

string

required

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

number

required

1-based page number.

number

required

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

number

required

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

number

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

number

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

boolean

Whether the field must be completed.

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

string

required

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

string

required

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

number

required

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

number

Offset width in points, >0 and ≤1000.

number

Offset height in points, >0 and ≤1000.

boolean

Whether the field must be completed.

boolean

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

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.

string

The render that was sent for signature.

string

sent on creation. See the status lifecycle.

object[]

Recipient snapshot, now carrying provider-assigned ids.

number | null

string | null

Authenticated download URL; null until archived.

string | null

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

string | null

string

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
}

Projects

Templates

Renders

Signatures

Webhooks

Embed

Reference

Projects

Templates

Renders

Signatures

Webhooks

Embed

Admin

System

Create a signature request

Authorization

Body

Response

Errors

​Authorization

​Body

​Response

​Errors

Authorization

Body

Response

Errors