---
title: "Create and send a signature request"
method: POST
path: "/v1/signature-requests/"
tags: ["Signature requests"]
---

# Create and send a signature request

`POST /v1/signature-requests/`

## Request

- Base URL: `https://api.pdfbetter.com`
- URL: `https://api.pdfbetter.com/v1/signature-requests/`
- Auth: HTTP bearer

Locks the current version of the document and emails recipients (in order for sequential routing). Pass full `fields` (with `assignee` = recipient key) or `useDocumentFields: true` with `assignees` by field name. `send: false` creates a draft. Uses one signature request from your plan when sent.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `documentId` string, required
  - `title` string: Default: the document title
  - `message` string
  - `routing` 'sequential' | 'parallel'
  - `recipients` object[], required
    - `key` string: Your handle for the recipient, used by `fields[].assignee` / `assignees`; default r1, r2, …
    - `name` string, required
    - `email` string, email, required
    - `role` 'signer' | 'approver' | 'cc'
    - `order` integer: Sequential routing order; default = position in the list
    - `authMethod` 'email_link' | 'access_code' | 'email_otp': email_otp: the recipient must also enter a one-time code we email them before they can open the document
    - `accessCode` string
  - `fields` object[]: Full field definitions; `assignee` is a recipient key
    - `id` string, required
    - `pageId` string, required
    - `kind` 'signature' | 'initials' | 'text' | 'date' | 'name' | 'email' | 'checkbox' | 'radio' | 'image' | 'dropdown' | 'number' | 'formula' | 'currency_usd' | 'currency_eur' | 'currency_jpy' | 'title' | 'company' | 'zip_us' | 'phone_us' | 'ein' | 'ssn' | 'age' | 'gender' | 'state_us' | 'phone_intl' | 'postal_code', required
    - `name` string, required
    - `label` string
    - `helpText` string
    - `placeholder` string
    - `box` object, required
      - `x` number, required
      - `y` number, required
      - `width` number, required
      - `height` number, required
    - `required` boolean
    - `readOnly` boolean
    - `options` string[]
    - `group` string
    - `exportValue` string
    - `decimals` integer
    - `min` number
    - `max` number
    - `maxLength` integer
    - `multiline` boolean
    - `pattern` string
    - `dateFormat` 'MM/DD/YYYY' | 'DD/MM/YYYY' | 'YYYY-MM-DD' | 'MMMM D, YYYY' | 'D MMMM YYYY' | 'DD.MM.YYYY' | 'YYYY/MM/DD'
    - `numberLocale` string
    - `country` string
    - `condition` object
      - `match` 'all' | 'any', required
      - `rules` object[], required
        - `field` string, required
        - `op` 'equals' | 'not_equals' | 'contains' | 'is_empty' | 'is_not_empty' | 'gt' | 'lt' | 'checked' | 'unchecked', required
        - `value` union
          - string
          - number
    - `style` object
      - `font` 'Helvetica' | 'Times' | 'Courier' | 'Signature'
      - `size` number
      - `color` string
      - `bold` boolean
      - `italic` boolean
      - `underline` boolean
      - `strikethrough` boolean
      - `opacity` number
      - `align` 'left' | 'center' | 'right' | 'justify'
      - `valign` 'top' | 'middle' | 'bottom'
      - `lineHeight` number
      - `paragraphSpacing` number
      - `letterSpacing` number
      - `horizontalScale` number
      - `script` 'normal' | 'superscript' | 'subscript'
      - `list` 'none' | 'bullet' | 'number'
      - `indent` integer
      - `role` 'normal' | 'heading1' | 'heading2' | 'heading3' | 'caption'
    - `defaultValue` union
      - string
      - number
      - boolean
    - `assignee` string
    - `tabOrder` integer
  - `useDocumentFields` boolean: Use the fields already placed on the document
  - `assignees` object: With useDocumentFields: field name → recipient key. Unlisted fields go to the only signer when there is exactly one.
  - `reminderEveryDays` integer, nullable
  - `expiresInDays` integer, nullable
  - `send` boolean: false = create a draft
  - `locale` 'en' | 'es' | 'ja' | 'fr' | 'de': Language of the recipients' emails, signing page and certificate: en, es, ja, fr or de. Default: your account language, else en.

## Response `201`

Create and send a signature request

- SignatureRequest
  - `object` 'signature_request', required
  - `id` string, required
  - `documentId` string, required
  - `title` string, required
  - `message` string, nullable, required
  - `status` 'draft' | 'sent' | 'completed' | 'declined' | 'canceled' | 'expired', required
  - `routing` 'sequential' | 'parallel', required
  - `reminderEveryDays` integer, nullable, required
  - `expiresAt` string, nullable, required: ISO 8601 timestamp (UTC)
  - `sentAt` string, nullable, required: ISO 8601 timestamp (UTC)
  - `completedAt` string, nullable, required: ISO 8601 timestamp (UTC)
  - `createdAt` string, required: ISO 8601 timestamp (UTC)
  - `fieldCount` integer, required
  - `hasCompletedFile` boolean, required
  - `hasCertificate` boolean, required
  - `recipients` object[], required
    - `id` string, required
    - `name` string, required
    - `email` string, required
    - `role` 'signer' | 'approver' | 'cc', required
    - `order` integer, required
    - `status` 'pending' | 'sent' | 'viewed' | 'signed' | 'declined', required
    - `authMethod` string, required
    - `sentAt` string, nullable, required: ISO 8601 timestamp (UTC)
    - `viewedAt` string, nullable, required: ISO 8601 timestamp (UTC)
    - `signedAt` string, nullable, required: ISO 8601 timestamp (UTC)
    - `declinedAt` string, nullable, required: ISO 8601 timestamp (UTC)
    - `declineReason` string, nullable, required

## Other responses

- `400`: Invalid request (see `error.details.issues`)
- `401`: Missing or invalid API key
- `402`: Your plan doesn't include this (API access needs Business) or a monthly allowance is used up
- `403`: The API key lacks the required scope
- `404`: Not found (or not yours)
- `409`: Conflict with the current state
- `422`: Validation failed
- `429`: Rate limited — see RateLimit-* and Retry-After

---

[API](https://skmtc.dev/pdfbetter/apis/pdfbetter-api.md) · [All operations](https://skmtc.dev/pdfbetter/apis/pdfbetter-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pdfbetter/apis/pdfbetter-api/revisions/6960b18754a8?raw)