> ## Documentation Index
> Fetch the complete documentation index at: https://docs.craftkit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a signature request

> POST /v1/signatures — send a succeeded render out for digital signature.

<Info>**POST** `https://api.craftkit.dev/v1/signatures`</Info>

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](/api-reference/get-signature)).

## Authorization

<ParamField header="Authorization" type="string" required>
  `Bearer ck_live_…` — a project API key. The render must belong to this key's project.
</ParamField>

<ParamField header="Idempotency-Key" type="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`.
</ParamField>

## Body

<ParamField body="renderId" type="string" required>
  UUID of the render to sign. Must be in this project and have `status: "succeeded"` with a stored
  PDF asset.
</ParamField>

<ParamField body="name" type="string">
  Human-readable request name (1–255 chars). Defaults to `Signature request <render-id-prefix>`.
</ParamField>

<ParamField body="recipients" type="object[]" required>
  1–20 recipients. At least one `fields` or `anchorTags` entry is required when any recipient is a
  `Signer`.

  <Expandable title="recipient">
    <ParamField body="firstName" type="string" required>First name (1–100 chars).</ParamField>
    <ParamField body="lastName" type="string">Last name (≤100 chars).</ParamField>
    <ParamField body="email" type="string" required>Email address (≤255 chars).</ParamField>

    <ParamField body="designation" type="string" default="Signer">
      One of `Signer`, `Approver`, `CC`.
    </ParamField>

    <ParamField body="order" type="number">
      Signing order (≥1). When supplied on any recipient, values must be unique and within
      `[1, recipientCount]`. Defaults to the array position (1-based).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="fields" type="object[]">
  Up to 200 explicit placements by page + coordinates. Coordinates are **percentages of page
  width/height (0–100), origin top-left**.

  <Expandable title="field">
    <ParamField body="recipientIndex" type="number" required>
      0-based index into `recipients`. Must reference an existing recipient.
    </ParamField>

    <ParamField body="type" type="string" required>
      One of `signature`, `initial`, `text`, `date`, `checkbox`, `dropdown`, `radio_buttons`,
      `text_area`.
    </ParamField>

    <ParamField body="page" type="number" required>1-based page number.</ParamField>
    <ParamField body="x" type="number" required>Horizontal position, 0–100 (% of page width).</ParamField>
    <ParamField body="y" type="number" required>Vertical position, 0–100 (% of page height).</ParamField>
    <ParamField body="width" type="number">Field width, >0 and ≤100 (% of page width).</ParamField>
    <ParamField body="height" type="number">Field height, >0 and ≤100 (% of page height).</ParamField>
    <ParamField body="required" type="boolean">Whether the field must be completed.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="anchorTags" type="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.

  <Expandable title="anchorTag">
    <ParamField body="anchorString" type="string" required>Literal text to anchor on (1–200 chars).</ParamField>

    <ParamField body="type" type="string" required>
      One of `signature`, `initials`, `text`, `date`, `checkbox`. Note `initials` (plural) here vs.
      `initial` in `fields`.
    </ParamField>

    <ParamField body="recipientIndex" type="number" required>
      0-based index into `recipients`. Must reference an existing recipient.
    </ParamField>

    <ParamField body="width" type="number">Offset width in points, >0 and ≤1000.</ParamField>
    <ParamField body="height" type="number">Offset height in points, >0 and ≤1000.</ParamField>
    <ParamField body="required" type="boolean">Whether the field must be completed.</ParamField>

    <ParamField body="ignoreIfNotPresent" type="boolean">
      Skip silently if the anchor text isn't found in the document.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="expirationHours" type="number">
  Hours until the request expires (1–8760). Defaults to the provider default (168).
</ParamField>

## Response

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

<ResponseField name="id" type="string">Craftkit signature request id (UUID). Use for status, cancel, download, certificate.</ResponseField>
<ResponseField name="renderId" type="string">The render that was sent for signature.</ResponseField>

<ResponseField name="name" type="string" />

<ResponseField name="status" type="string">`sent` on creation. See the status lifecycle.</ResponseField>
<ResponseField name="recipients" type="object[]">Recipient snapshot, now carrying provider-assigned `id`s.</ResponseField>

<ResponseField name="expirationHours" type="number | null" />

<ResponseField name="signedDownloadUrl" type="string | null">Authenticated download URL; `null` until archived.</ResponseField>
<ResponseField name="certificateUrl" type="string | null">Authenticated completion-certificate URL (`/v1/signatures/{id}/certificate`); `null` until available.</ResponseField>

<ResponseField name="errorMessage" type="string | null" />

<ResponseField name="createdAt" type="string" />

<ResponseField name="completedAt" type="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.         |

```bash cURL theme={null}
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
  }'
```

```json 201 theme={null}
{
  "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
}
```