Reference

API reference

Every endpoint in v1.0.0, generated from the OpenAPI spec. Prefer to try requests in the browser? Use the interactive reference.

All requests need Authorization: Bearer <key>. Every endpoint can also return 401 (missing_key, invalid_key) and 429 (rate_limited); these are left out below to keep things short. See errors.

Account

Get the account and token balance

GET/account

Responses

200	The account the key belongs to

Example

cURLRequest

curl https://api.readyink.ai/v1/account \
  -H "Authorization: Bearer $READYINK_API_KEY"

JSONResponse · 200

{
  "object": "account",
  "name": "Acme Property Co.",
  "plan": "pay_as_you_go",
  "mode": "live",
  "key_name": "Production server",
  "balance": {
    "available": 57,
    "reserved": 0,
    "monthly": 0
  },
  "tokens_per_recipient": 1
}

Documents

List documents (newest first)

GET/documents

Parameters

Name	Type	Description
`limit`in query	integer	Default `20` · 1–100
`starting_after`in query	string	The `next_cursor` from the previous page
`status`in query	string	One of `draft`, `sending`, `out`, `completed`, `declined`, `cancelled`, `send_failed`
`created_after`in query	string	Only documents created after this time date-time

Responses

200	A page of documents
422	Invalid input (`invalid_limit`, `invalid_date`, `invalid`)

Example

cURLRequest

curl https://api.readyink.ai/v1/documents \
  -H "Authorization: Bearer $READYINK_API_KEY"

JSONResponse · 200

{
  "object": "list",
  "data": [
    {
      "id": "doc_c9x1q8",
      "object": "document",
      "title": "Mutual NDA",
      "status": "draft",
      "test_mode": false,
      "signing_mode": "parallel",
      "reminder_days": 1,
      "file_status": "awaiting_upload",
      "file_error": null,
      "page_count": 2,
      "readyink_id": "RI-7Q4K-2M9D",
      "send_error": null,
      "cost": {
        "signers": 1,
        "tokens": 1
      },
      "version_hash": "9f2c\u2026e41a",
      "final_hash": "b71d\u202609cc",
      "created_at": "2026-11-09T15:04:05Z",
      "sent_at": null,
      "completed_at": null,
      "delete_after": null,
      "recipients": [
        null
      ],
      "fields": [
        null
      ]
    }
  ],
  "has_more": false,
  "next_cursor": "doc_b81kz2"
}

Create a draft

POST/documents

Create a draft, optionally with the PDF (multipart file) and recipients. All or nothing: if any part fails, nothing is created. With a PDF, file_status starts as processing and becomes ready within seconds; add fields once it's ready.

Request body

Content type: application/json, multipart/form-data

Name	Type	Description
`title`	string	max length 200 · min length 1
`signing_mode`	string	One of `"parallel"`, `"sequential"` · Default `"parallel"`
`reminder_days`	integer or null	One of `1`, `3`, `7`, `null` · Default `7`
`recipients`	array of RecipientInput	max items 50

Or multipart/form-data

Name	Type	Description
`file`	string	The PDF (up to 25 MB) binary
`data`required	string	The JSON body (DocumentCreate) as a string

Responses

201	The new draft
400	Unreadable body (`invalid_json`, `invalid_multipart`)
409	Conflict (`duplicate_email`)
413	The PDF is too big (`file_too_large`)
422	Invalid input (`validation_failed`, `invalid_recipient`, `empty_file`, `not_a_pdf`)

Example

cURLRequest

curl https://api.readyink.ai/v1/documents \
  -H "Authorization: Bearer $READYINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "NDA", "recipients": [{"name": "Ana Diaz", "email": "ana@example.com"}]}'

JSONResponse · 201

{
  "id": "doc_c9x1q8",
  "object": "document",
  "title": "Mutual NDA",
  "status": "draft",
  "test_mode": false,
  "signing_mode": "parallel",
  "reminder_days": 1,
  "file_status": "awaiting_upload",
  "file_error": null,
  "page_count": 2,
  "readyink_id": "RI-7Q4K-2M9D",
  "send_error": null,
  "cost": {
    "signers": 1,
    "tokens": 1
  },
  "version_hash": "9f2c\u2026e41a",
  "final_hash": "b71d\u202609cc",
  "created_at": "2026-11-09T15:04:05Z",
  "sent_at": null,
  "completed_at": null,
  "delete_after": null,
  "recipients": [
    {
      "id": "rcp_def456",
      "object": "recipient",
      "name": "Ana Diaz",
      "email": "ana@example.com",
      "mobile_last4": "0142",
      "notify_via": "email",
      "role": "signer",
      "order": 1,
      "status": "pending",
      "signed_at": null,
      "declined_at": null
    }
  ],
  "fields": [
    {
      "id": "fld_9q2k",
      "object": "field",
      "type": "signature",
      "recipient_id": "rcp_def456",
      "page": 1,
      "x": 0.1,
      "y": 0.8,
      "w": 0.28,
      "h": 0.035,
      "required": true,
      "options": {}
    }
  ]
}

Get a document

GET/documents/{id}

Parameters

Name	Type	Description
`id`requiredin path	string	The document ID, like `doc_c9x1q8`

Responses

200	The document
404	No such document, recipient or field in this mode

Example

cURLRequest

curl https://api.readyink.ai/v1/documents/doc_c9x1q8 \
  -H "Authorization: Bearer $READYINK_API_KEY"

JSONResponse · 200

{
  "id": "doc_c9x1q8",
  "object": "document",
  "title": "Mutual NDA",
  "status": "draft",
  "test_mode": false,
  "signing_mode": "parallel",
  "reminder_days": 1,
  "file_status": "awaiting_upload",
  "file_error": null,
  "page_count": 2,
  "readyink_id": "RI-7Q4K-2M9D",
  "send_error": null,
  "cost": {
    "signers": 1,
    "tokens": 1
  },
  "version_hash": "9f2c\u2026e41a",
  "final_hash": "b71d\u202609cc",
  "created_at": "2026-11-09T15:04:05Z",
  "sent_at": null,
  "completed_at": null,
  "delete_after": null,
  "recipients": [
    {
      "id": "rcp_def456",
      "object": "recipient",
      "name": "Ana Diaz",
      "email": "ana@example.com",
      "mobile_last4": "0142",
      "notify_via": "email",
      "role": "signer",
      "order": 1,
      "status": "pending",
      "signed_at": null,
      "declined_at": null
    }
  ],
  "fields": [
    {
      "id": "fld_9q2k",
      "object": "field",
      "type": "signature",
      "recipient_id": "rcp_def456",
      "page": 1,
      "x": 0.1,
      "y": 0.8,
      "w": 0.28,
      "h": 0.035,
      "required": true,
      "options": {}
    }
  ]
}

Change title, signing mode or reminders

PATCH/documents/{id}

title and signing_mode change on drafts; reminder_days also while the document is out.

Parameters

Name	Type	Description
`id`requiredin path	string	The document ID, like `doc_c9x1q8`

Request body

Content type: application/json

Name	Type	Description
`title`	string	max length 200 · min length 1
`signing_mode`	string	One of `"parallel"`, `"sequential"` · Default `"parallel"`
`reminder_days`	integer or null	One of `1`, `3`, `7`, `null` · Default `7`

Responses

200	The document
404	No such document, recipient or field in this mode
409	Conflict (`not_editable`, `bad_state`)
422	Invalid input (`validation_failed`, `invalid`)

Example

cURLRequest

curl -X PATCH https://api.readyink.ai/v1/documents/doc_c9x1q8 \
  -H "Authorization: Bearer $READYINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reminder_days": 3}'

JSONResponse · 200

{
  "id": "doc_c9x1q8",
  "object": "document",
  "title": "Mutual NDA",
  "status": "draft",
  "test_mode": false,
  "signing_mode": "parallel",
  "reminder_days": 1,
  "file_status": "awaiting_upload",
  "file_error": null,
  "page_count": 2,
  "readyink_id": "RI-7Q4K-2M9D",
  "send_error": null,
  "cost": {
    "signers": 1,
    "tokens": 1
  },
  "version_hash": "9f2c\u2026e41a",
  "final_hash": "b71d\u202609cc",
  "created_at": "2026-11-09T15:04:05Z",
  "sent_at": null,
  "completed_at": null,
  "delete_after": null,
  "recipients": [
    {
      "id": "rcp_def456",
      "object": "recipient",
      "name": "Ana Diaz",
      "email": "ana@example.com",
      "mobile_last4": "0142",
      "notify_via": "email",
      "role": "signer",
      "order": 1,
      "status": "pending",
      "signed_at": null,
      "declined_at": null
    }
  ],
  "fields": [
    {
      "id": "fld_9q2k",
      "object": "field",
      "type": "signature",
      "recipient_id": "rcp_def456",
      "page": 1,
      "x": 0.1,
      "y": 0.8,
      "w": 0.28,
      "h": 0.035,
      "required": true,
      "options": {}
    }
  ]
}

Delete a draft

DELETE/documents/{id}

Parameters

Name	Type	Description
`id`requiredin path	string	The document ID, like `doc_c9x1q8`

Responses

200	Deleted
404	No such document, recipient or field in this mode
409	Conflict (`not_editable`: sent documents can be cancelled instead)

Example

cURLRequest

curl -X DELETE https://api.readyink.ai/v1/documents/doc_c9x1q8 \
  -H "Authorization: Bearer $READYINK_API_KEY"

JSONResponse · 200

{
  "id": "doc_c9x1q8",
  "object": "document",
  "deleted": true
}

Upload the PDF

POST/documents/{id}/file

For a draft created without a PDF. Multipart file, or the raw bytes with Content-Type: application/pdf. Once per document.

Parameters

Name	Type	Description
`id`requiredin path	string	The document ID, like `doc_c9x1q8`

Request body

Content type: multipart/form-data, application/pdf

Name	Type	Description
`file`required	string	The PDF (up to 25 MB) binary

Responses

200	The document, with `file_status: processing`
404	No such document, recipient or field in this mode
409	Conflict (`bad_state`: the PDF was already uploaded; `not_editable`)
413	The PDF is too big (`file_too_large`)
415	Use multipart/form-data or application/pdf
422	Invalid input (`empty_file`, `not_a_pdf`, `missing_file`)

Example

cURLRequest

curl https://api.readyink.ai/v1/documents/doc_c9x1q8/file \
  -H "Authorization: Bearer $READYINK_API_KEY" \
  -F "file=@contract.pdf"

JSONResponse · 200

{
  "id": "doc_c9x1q8",
  "object": "document",
  "title": "Mutual NDA",
  "status": "draft",
  "test_mode": false,
  "signing_mode": "parallel",
  "reminder_days": 1,
  "file_status": "awaiting_upload",
  "file_error": null,
  "page_count": 2,
  "readyink_id": "RI-7Q4K-2M9D",
  "send_error": null,
  "cost": {
    "signers": 1,
    "tokens": 1
  },
  "version_hash": "9f2c\u2026e41a",
  "final_hash": "b71d\u202609cc",
  "created_at": "2026-11-09T15:04:05Z",
  "sent_at": null,
  "completed_at": null,
  "delete_after": null,
  "recipients": [
    {
      "id": "rcp_def456",
      "object": "recipient",
      "name": "Ana Diaz",
      "email": "ana@example.com",
      "mobile_last4": "0142",
      "notify_via": "email",
      "role": "signer",
      "order": 1,
      "status": "pending",
      "signed_at": null,
      "declined_at": null
    }
  ],
  "fields": [
    {
      "id": "fld_9q2k",
      "object": "field",
      "type": "signature",
      "recipient_id": "rcp_def456",
      "page": 1,
      "x": 0.1,
      "y": 0.8,
      "w": 0.28,
      "h": 0.035,
      "required": true,
      "options": {}
    }
  ]
}

Recipients

Add a recipient (drafts)

POST/documents/{id}/recipients

Parameters

Name	Type	Description
`id`requiredin path	string	The document ID, like `doc_c9x1q8`

Request body

Content type: application/json

Name	Type	Description
`name`required	string
`email`required	string	email
`mobile`	string	US mobile number; needed for sms or both
`notify_via`	string	One of `"email"`, `"sms"`, `"both"` · Default `"email"`
`role`	string	`copy` recipients get the signed copy, sign nothing and cost nothing One of `"signer"`, `"copy"` · Default `"signer"`

Responses

201	The document
404	No such document, recipient or field in this mode
409	Conflict (`not_editable`, `duplicate_email`)
422	Invalid input (`validation_failed`, `invalid`)

Example

cURLRequest

curl https://api.readyink.ai/v1/documents/doc_c9x1q8/recipients \
  -H "Authorization: Bearer $READYINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Ana Diaz", "email": "ana@example.com"}'

JSONResponse · 201

{
  "id": "doc_c9x1q8",
  "object": "document",
  "title": "Mutual NDA",
  "status": "draft",
  "test_mode": false,
  "signing_mode": "parallel",
  "reminder_days": 1,
  "file_status": "awaiting_upload",
  "file_error": null,
  "page_count": 2,
  "readyink_id": "RI-7Q4K-2M9D",
  "send_error": null,
  "cost": {
    "signers": 1,
    "tokens": 1
  },
  "version_hash": "9f2c\u2026e41a",
  "final_hash": "b71d\u202609cc",
  "created_at": "2026-11-09T15:04:05Z",
  "sent_at": null,
  "completed_at": null,
  "delete_after": null,
  "recipients": [
    {
      "id": "rcp_def456",
      "object": "recipient",
      "name": "Ana Diaz",
      "email": "ana@example.com",
      "mobile_last4": "0142",
      "notify_via": "email",
      "role": "signer",
      "order": 1,
      "status": "pending",
      "signed_at": null,
      "declined_at": null
    }
  ],
  "fields": [
    {
      "id": "fld_9q2k",
      "object": "field",
      "type": "signature",
      "recipient_id": "rcp_def456",
      "page": 1,
      "x": 0.1,
      "y": 0.8,
      "w": 0.28,
      "h": 0.035,
      "required": true,
      "options": {}
    }
  ]
}

Change a recipient

PATCH/documents/{id}/recipients/{rid}

On a draft, send the full recipient. On a document that's out, send exactly {"email": "…"}: the old link stops working and a new request goes to the new address.

Parameters

Name	Type	Description
`id`requiredin path	string	The document ID, like `doc_c9x1q8`
`rid`requiredin path	string	The recipient ID, like `rcp_def456`

Request body

Content type: application/json

Send one of these shapes:

RecipientInput

Name	Type	Description
`name`required	string
`email`required	string	email
`mobile`	string	US mobile number; needed for sms or both
`notify_via`	string	One of `"email"`, `"sms"`, `"both"` · Default `"email"`
`role`	string	`copy` recipients get the signed copy, sign nothing and cost nothing One of `"signer"`, `"copy"` · Default `"signer"`

RecipientEmailChange

Name	Type	Description
`email`required	string	email

Responses

200	The document
404	No such document, recipient or field in this mode
409	Conflict (`not_editable`, `duplicate_email`, `bad_state`)
422	Invalid input (`validation_failed`, `invalid`)

Example

cURLRequest

curl -X PATCH https://api.readyink.ai/v1/documents/doc_c9x1q8/recipients/rcp_def456 \
  -H "Authorization: Bearer $READYINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "ana.diaz@example.com"}'

JSONResponse · 200

{
  "id": "doc_c9x1q8",
  "object": "document",
  "title": "Mutual NDA",
  "status": "draft",
  "test_mode": false,
  "signing_mode": "parallel",
  "reminder_days": 1,
  "file_status": "awaiting_upload",
  "file_error": null,
  "page_count": 2,
  "readyink_id": "RI-7Q4K-2M9D",
  "send_error": null,
  "cost": {
    "signers": 1,
    "tokens": 1
  },
  "version_hash": "9f2c\u2026e41a",
  "final_hash": "b71d\u202609cc",
  "created_at": "2026-11-09T15:04:05Z",
  "sent_at": null,
  "completed_at": null,
  "delete_after": null,
  "recipients": [
    {
      "id": "rcp_def456",
      "object": "recipient",
      "name": "Ana Diaz",
      "email": "ana@example.com",
      "mobile_last4": "0142",
      "notify_via": "email",
      "role": "signer",
      "order": 1,
      "status": "pending",
      "signed_at": null,
      "declined_at": null
    }
  ],
  "fields": [
    {
      "id": "fld_9q2k",
      "object": "field",
      "type": "signature",
      "recipient_id": "rcp_def456",
      "page": 1,
      "x": 0.1,
      "y": 0.8,
      "w": 0.28,
      "h": 0.035,
      "required": true,
      "options": {}
    }
  ]
}

Remove a recipient (drafts; their fields go too)

DELETE/documents/{id}/recipients/{rid}

Parameters

Name	Type	Description
`id`requiredin path	string	The document ID, like `doc_c9x1q8`
`rid`requiredin path	string	The recipient ID, like `rcp_def456`

Responses

200	The document
404	No such document, recipient or field in this mode
409	Conflict (`not_editable`)

Example

cURLRequest

curl -X DELETE https://api.readyink.ai/v1/documents/doc_c9x1q8/recipients/rcp_def456 \
  -H "Authorization: Bearer $READYINK_API_KEY"

JSONResponse · 200

{
  "id": "doc_c9x1q8",
  "object": "document",
  "title": "Mutual NDA",
  "status": "draft",
  "test_mode": false,
  "signing_mode": "parallel",
  "reminder_days": 1,
  "file_status": "awaiting_upload",
  "file_error": null,
  "page_count": 2,
  "readyink_id": "RI-7Q4K-2M9D",
  "send_error": null,
  "cost": {
    "signers": 1,
    "tokens": 1
  },
  "version_hash": "9f2c\u2026e41a",
  "final_hash": "b71d\u202609cc",
  "created_at": "2026-11-09T15:04:05Z",
  "sent_at": null,
  "completed_at": null,
  "delete_after": null,
  "recipients": [
    {
      "id": "rcp_def456",
      "object": "recipient",
      "name": "Ana Diaz",
      "email": "ana@example.com",
      "mobile_last4": "0142",
      "notify_via": "email",
      "role": "signer",
      "order": 1,
      "status": "pending",
      "signed_at": null,
      "declined_at": null
    }
  ],
  "fields": [
    {
      "id": "fld_9q2k",
      "object": "field",
      "type": "signature",
      "recipient_id": "rcp_def456",
      "page": 1,
      "x": 0.1,
      "y": 0.8,
      "w": 0.28,
      "h": 0.035,
      "required": true,
      "options": {}
    }
  ]
}

Fields

Add one field or many

POST/documents/{id}/fields

Send one field, or up to 200 as {"fields": [...]}. All or nothing. The pages must be ready (file_status: ready). Positions are 0–1 fractions of the page from the top-left corner.

Parameters

Name	Type	Description
`id`requiredin path	string	The document ID, like `doc_c9x1q8`

Request body

Content type: application/json

Send one of these shapes:

FieldInput

Name	Type	Description
`type`required	string	One of `"signature"`, `"initials"`, `"date"`, `"name"`, `"email"`, `"phone"`, `"company"`, `"job_title"`, `"address"`, `"website"`, `"short_text"`, `"long_text"`, `"number"`, `"dropdown"`, `"single_choice"`, `"multiple_choice"`
`recipient_id`required	string
`page`required	integer	min 1
`x`required	number	Left edge, fraction of page width min 0 · max 1
`y`required	number	Top edge, fraction of page height min 0 · max 1
`w`required	number	min 0 · max 1
`h`required	number	min 0 · max 1
`required`	boolean	Default `true`
`options`	object	Text types: placeholder, maxLength, prefill. number: min, max, decimals. dropdown, single_choice, multiple_choice: choices (required). Others: {}.

Batch: {"fields": [ … ]} (1–200 items)

Responses

201	The document
404	No such document, recipient or field in this mode
409	Conflict (`file_not_ready`, `not_editable`)
422	Invalid input (`invalid_field`, `invalid_fields`)

Example

cURLRequest

curl https://api.readyink.ai/v1/documents/doc_c9x1q8/fields \
  -H "Authorization: Bearer $READYINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields": [{"type": "signature", "recipient_id": "rcp_def456", "page": 1, "x": 0.1, "y": 0.8, "w": 0.28, "h": 0.035}]}'

JSONResponse · 201

{
  "id": "doc_c9x1q8",
  "object": "document",
  "title": "Mutual NDA",
  "status": "draft",
  "test_mode": false,
  "signing_mode": "parallel",
  "reminder_days": 1,
  "file_status": "awaiting_upload",
  "file_error": null,
  "page_count": 2,
  "readyink_id": "RI-7Q4K-2M9D",
  "send_error": null,
  "cost": {
    "signers": 1,
    "tokens": 1
  },
  "version_hash": "9f2c\u2026e41a",
  "final_hash": "b71d\u202609cc",
  "created_at": "2026-11-09T15:04:05Z",
  "sent_at": null,
  "completed_at": null,
  "delete_after": null,
  "recipients": [
    {
      "id": "rcp_def456",
      "object": "recipient",
      "name": "Ana Diaz",
      "email": "ana@example.com",
      "mobile_last4": "0142",
      "notify_via": "email",
      "role": "signer",
      "order": 1,
      "status": "pending",
      "signed_at": null,
      "declined_at": null
    }
  ],
  "fields": [
    {
      "id": "fld_9q2k",
      "object": "field",
      "type": "signature",
      "recipient_id": "rcp_def456",
      "page": 1,
      "x": 0.1,
      "y": 0.8,
      "w": 0.28,
      "h": 0.035,
      "required": true,
      "options": {}
    }
  ]
}

Move, resize or change a field (drafts)

PATCH/documents/{id}/fields/{fid}

Parameters

Name	Type	Description
`id`requiredin path	string	The document ID, like `doc_c9x1q8`
`fid`requiredin path	string	The field ID, like `fld_9q2k`

Request body

Content type: application/json

Name	Type	Description
`recipient_id`	string
`page`	integer	min 1
`x`	number	min 0 · max 1
`y`	number	min 0 · max 1
`w`	number	min 0 · max 1
`h`	number	min 0 · max 1
`required`	boolean
`options`	object

Responses

200	The document
404	No such document, recipient or field in this mode
409	Conflict (`not_editable`)
422	Invalid input (`validation_failed`, `invalid`)

Example

cURLRequest

curl -X PATCH https://api.readyink.ai/v1/documents/doc_c9x1q8/fields/fld_9q2k \
  -H "Authorization: Bearer $READYINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"x": 0.12, "y": 0.82}'

JSONResponse · 200

{
  "id": "doc_c9x1q8",
  "object": "document",
  "title": "Mutual NDA",
  "status": "draft",
  "test_mode": false,
  "signing_mode": "parallel",
  "reminder_days": 1,
  "file_status": "awaiting_upload",
  "file_error": null,
  "page_count": 2,
  "readyink_id": "RI-7Q4K-2M9D",
  "send_error": null,
  "cost": {
    "signers": 1,
    "tokens": 1
  },
  "version_hash": "9f2c\u2026e41a",
  "final_hash": "b71d\u202609cc",
  "created_at": "2026-11-09T15:04:05Z",
  "sent_at": null,
  "completed_at": null,
  "delete_after": null,
  "recipients": [
    {
      "id": "rcp_def456",
      "object": "recipient",
      "name": "Ana Diaz",
      "email": "ana@example.com",
      "mobile_last4": "0142",
      "notify_via": "email",
      "role": "signer",
      "order": 1,
      "status": "pending",
      "signed_at": null,
      "declined_at": null
    }
  ],
  "fields": [
    {
      "id": "fld_9q2k",
      "object": "field",
      "type": "signature",
      "recipient_id": "rcp_def456",
      "page": 1,
      "x": 0.1,
      "y": 0.8,
      "w": 0.28,
      "h": 0.035,
      "required": true,
      "options": {}
    }
  ]
}

Remove a field (drafts)

DELETE/documents/{id}/fields/{fid}

Parameters

Name	Type	Description
`id`requiredin path	string	The document ID, like `doc_c9x1q8`
`fid`requiredin path	string	The field ID, like `fld_9q2k`

Responses

200	The document
404	No such document, recipient or field in this mode
409	Conflict (`not_editable`)

Example

cURLRequest

curl -X DELETE https://api.readyink.ai/v1/documents/doc_c9x1q8/fields/fld_9q2k \
  -H "Authorization: Bearer $READYINK_API_KEY"

JSONResponse · 200

{
  "id": "doc_c9x1q8",
  "object": "document",
  "title": "Mutual NDA",
  "status": "draft",
  "test_mode": false,
  "signing_mode": "parallel",
  "reminder_days": 1,
  "file_status": "awaiting_upload",
  "file_error": null,
  "page_count": 2,
  "readyink_id": "RI-7Q4K-2M9D",
  "send_error": null,
  "cost": {
    "signers": 1,
    "tokens": 1
  },
  "version_hash": "9f2c\u2026e41a",
  "final_hash": "b71d\u202609cc",
  "created_at": "2026-11-09T15:04:05Z",
  "sent_at": null,
  "completed_at": null,
  "delete_after": null,
  "recipients": [
    {
      "id": "rcp_def456",
      "object": "recipient",
      "name": "Ana Diaz",
      "email": "ana@example.com",
      "mobile_last4": "0142",
      "notify_via": "email",
      "role": "signer",
      "order": 1,
      "status": "pending",
      "signed_at": null,
      "declined_at": null
    }
  ],
  "fields": [
    {
      "id": "fld_9q2k",
      "object": "field",
      "type": "signature",
      "recipient_id": "rcp_def456",
      "page": 1,
      "x": 0.1,
      "y": 0.8,
      "w": 0.28,
      "h": 0.035,
      "required": true,
      "options": {}
    }
  ]
}

Sending

Quote, send and cancel.

Cost to send now, and anything to fix first

GET/documents/{id}/quote

Parameters

Name	Type	Description
`id`requiredin path	string	The document ID, like `doc_c9x1q8`

Responses

200	The quote
404	No such document, recipient or field in this mode

Example

cURLRequest

curl https://api.readyink.ai/v1/documents/doc_c9x1q8/quote \
  -H "Authorization: Bearer $READYINK_API_KEY"

JSONResponse · 200

{
  "object": "quote",
  "document_id": "doc_c9x1q8",
  "signers": 1,
  "copies": 0,
  "tokens": 1,
  "balance_available": 57,
  "balance_after": 56,
  "enough_tokens": true,
  "problems": [
    "string"
  ],
  "can_send": true
}

Send for signature

POST/documents/{id}/send

Requires Idempotency-Key, so a retry never sends or charges twice. Rate limited to 10 a minute per key. Test keys send for 0 tokens.

Parameters

Name	Type	Description
`id`requiredin path	string	The document ID, like `doc_c9x1q8`
`Idempotency-Key`requiredin header	string	A unique string (up to 200 characters). A retry with the same key and request returns the first response with `Idempotent-Replayed: true`; the same key with a different request is a 409. Remembered per API key for 24 hours.

Request body

Content type: application/json · optional

Name	Type	Description
`quote_tokens`	integer	The `tokens` from your quote; refused with 409 `quote_changed` if the cost changed min 0

Responses

200	The document, with `status: out`
400	`idempotency_key_required`, `idempotency_key_too_long`
402	Not enough tokens (`insufficient_tokens`)
404	No such document, recipient or field in this mode
409	Conflict (`quote_changed` (with `tokens`), `bad_state`, `idempotency_conflict`)
422	Something must be fixed first (`not_ready_to_send`)

Example

cURLRequest

curl https://api.readyink.ai/v1/documents/doc_c9x1q8/send \
  -H "Authorization: Bearer $READYINK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"quote_tokens": 1}'

JSONResponse · 200

{
  "id": "doc_c9x1q8",
  "object": "document",
  "title": "Mutual NDA",
  "status": "draft",
  "test_mode": false,
  "signing_mode": "parallel",
  "reminder_days": 1,
  "file_status": "awaiting_upload",
  "file_error": null,
  "page_count": 2,
  "readyink_id": "RI-7Q4K-2M9D",
  "send_error": null,
  "cost": {
    "signers": 1,
    "tokens": 1
  },
  "version_hash": "9f2c\u2026e41a",
  "final_hash": "b71d\u202609cc",
  "created_at": "2026-11-09T15:04:05Z",
  "sent_at": null,
  "completed_at": null,
  "delete_after": null,
  "recipients": [
    {
      "id": "rcp_def456",
      "object": "recipient",
      "name": "Ana Diaz",
      "email": "ana@example.com",
      "mobile_last4": "0142",
      "notify_via": "email",
      "role": "signer",
      "order": 1,
      "status": "pending",
      "signed_at": null,
      "declined_at": null
    }
  ],
  "fields": [
    {
      "id": "fld_9q2k",
      "object": "field",
      "type": "signature",
      "recipient_id": "rcp_def456",
      "page": 1,
      "x": 0.1,
      "y": 0.8,
      "w": 0.28,
      "h": 0.035,
      "required": true,
      "options": {}
    }
  ]
}

Cancel a document that's out

POST/documents/{id}/cancel

Links stop working and pending signers are emailed. Tokens come back only if no one had opened it (tokens_returned). Requires Idempotency-Key.

Parameters

Name	Type	Description
`id`requiredin path	string	The document ID, like `doc_c9x1q8`
`Idempotency-Key`requiredin header	string	A unique string (up to 200 characters). A retry with the same key and request returns the first response with `Idempotent-Replayed: true`; the same key with a different request is a 409. Remembered per API key for 24 hours.

Responses

200	The document, with `status: cancelled`
400	`idempotency_key_required`
404	No such document, recipient or field in this mode
409	Conflict (`bad_state`, `idempotency_conflict`)

Example

cURLRequest

curl -X POST https://api.readyink.ai/v1/documents/doc_c9x1q8/cancel \
  -H "Authorization: Bearer $READYINK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

JSONResponse · 200

{
  "id": "doc_c9x1q8",
  "object": "document",
  "title": "Mutual NDA",
  "status": "draft",
  "test_mode": false,
  "signing_mode": "parallel",
  "reminder_days": 1,
  "file_status": "awaiting_upload",
  "file_error": null,
  "page_count": 2,
  "readyink_id": "RI-7Q4K-2M9D",
  "send_error": null,
  "cost": {
    "signers": 1,
    "tokens": 1
  },
  "version_hash": "9f2c\u2026e41a",
  "final_hash": "b71d\u202609cc",
  "created_at": "2026-11-09T15:04:05Z",
  "sent_at": null,
  "completed_at": null,
  "delete_after": null,
  "recipients": [
    {
      "id": "rcp_def456",
      "object": "recipient",
      "name": "Ana Diaz",
      "email": "ana@example.com",
      "mobile_last4": "0142",
      "notify_via": "email",
      "role": "signer",
      "order": 1,
      "status": "pending",
      "signed_at": null,
      "declined_at": null
    }
  ],
  "fields": [
    {
      "id": "fld_9q2k",
      "object": "field",
      "type": null,
      "recipient_id": "rcp_def456",
      "page": 1,
      "x": 0.1,
      "y": 0.8,
      "w": 0.28,
      "h": 0.035,
      "required": true,
      "options": {}
    }
  ],
  "tokens_returned": 1
}

Results

Signed PDF, certificate and activity.

Download the signed PDF

GET/documents/{id}/signed-pdf

Redirects to a download link valid for 10 minutes. Completed documents only.

Parameters

Name	Type	Description
`id`requiredin path	string	The document ID, like `doc_c9x1q8`

Responses

302	Redirect to the sealed PDF
404	No such document, recipient or field in this mode
409	Conflict (`not_completed`)

Example

cURLRequest

curl -L https://api.readyink.ai/v1/documents/doc_c9x1q8/signed-pdf \
  -H "Authorization: Bearer $READYINK_API_KEY" \
  -o out.pdf

Download the certificate of completion

GET/documents/{id}/certificate

Redirects to a download link valid for 10 minutes. Completed documents only.

Parameters

Name	Type	Description
`id`requiredin path	string	The document ID, like `doc_c9x1q8`

Responses

302	Redirect to the certificate
404	No such document, recipient or field in this mode
409	Conflict (`not_completed`)

Example

cURLRequest

curl -L https://api.readyink.ai/v1/documents/doc_c9x1q8/certificate \
  -H "Authorization: Bearer $READYINK_API_KEY" \
  -o out.pdf

The document's activity (oldest first)

GET/documents/{id}/events

Parameters

Name	Type	Description
`id`requiredin path	string	The document ID, like `doc_c9x1q8`

Responses

200	Events
404	No such document, recipient or field in this mode

Example

cURLRequest

curl https://api.readyink.ai/v1/documents/doc_c9x1q8/events \
  -H "Authorization: Bearer $READYINK_API_KEY"

JSONResponse · 200

{
  "object": "list",
  "data": [
    {
      "id": "doc_c9x1q8",
      "object": "event",
      "type": "sent",
      "description": "Ana Diaz signed",
      "actor": "owner",
      "recipient_id": "rcp_def456",
      "created_at": "2026-11-09T15:04:05Z"
    }
  ],
  "has_more": false
}

Objects

The main objects the API returns.

Account

Name	Type	Description
`object`	string	Always `"account"`
`name`	string
`plan`	string	One of `"pay_as_you_go"`, `"team"`
`mode`	string	The mode of the key used One of `"live"`, `"test"`
`key_name`	string
`balance`	object
`balance.available`	integer
`balance.reserved`	integer	Held for sends in progress
`balance.monthly`	integer	Team plan's monthly tokens left
`tokens_per_recipient`	integer

Document

Name	Type	Description
`id`	string
`object`	string	Always `"document"`
`title`	string
`status`	string	One of `"draft"`, `"sending"`, `"out"`, `"completed"`, `"declined"`, `"cancelled"`, `"send_failed"`
`test_mode`	boolean
`signing_mode`	string	One of `"parallel"`, `"sequential"`
`reminder_days`	integer or null	One of `1`, `3`, `7`, `null`
`file_status`	string	One of `"awaiting_upload"`, `"processing"`, `"ready"`, `"failed"`
`file_error`	string or null
`page_count`	integer or null
`readyink_id`	string or null	Stamped on the signed copy; set when sealed
`send_error`	string or null
`cost`	object
`cost.signers`	integer
`cost.tokens`	integer
`version_hash`	string or null	SHA-256 of what was sent
`final_hash`	string or null	SHA-256 of the sealed PDF
`created_at`	string	date-time
`sent_at`	string or null	date-time
`completed_at`	string or null	date-time
`delete_after`	string or null	date-time
`recipients`	array of Recipient
`fields`	array of Field

Recipient

Name	Type	Description
`id`	string
`object`	string	Always `"recipient"`
`name`	string
`email`	string
`mobile_last4`	string or null
`notify_via`	string	One of `"email"`, `"sms"`, `"both"`
`role`	string	One of `"signer"`, `"copy"`
`order`	integer	min 1
`status`	string	One of `"pending"`, `"notified"`, `"viewed"`, `"signed"`, `"declined"`
`signed_at`	string or null	date-time
`declined_at`	string or null	date-time

Field

Name	Type	Description
`id`	string
`object`	string	Always `"field"`
`type`	string	One of `"signature"`, `"initials"`, `"date"`, `"name"`, `"email"`, `"phone"`, `"company"`, `"job_title"`, `"address"`, `"website"`, `"short_text"`, `"long_text"`, `"number"`, `"dropdown"`, `"single_choice"`, `"multiple_choice"`
`recipient_id`	string
`page`	integer
`x`	number
`y`	number
`w`	number
`h`	number
`required`	boolean
`options`	object

Quote

Name	Type	Description
`object`	string	Always `"quote"`
`document_id`	string
`signers`	integer
`copies`	integer
`tokens`	integer
`balance_available`	integer
`balance_after`	integer
`enough_tokens`	boolean
`problems`	array of string	Empty when it can be sent
`can_send`	boolean

Event

Name	Type	Description
`id`	string
`object`	string	Always `"event"`
`type`	string	What happened. Current types: `sent`, `sender_not_signing`, `self_sign`, `send_failed`, `notified`, `cancelled`, `recipient_email_changed`, `texted`, `text_reminded`, `text_delivered`, `text_failed`, `text_not_sent`, `reminded`, `opened`, `code_sent`, `verified`, `verify_failed`, `verify_locked`, `sample_opened`, `consented`, `link_reissued`, `signed`, `declined`, `completed`, `sealed`, `delivered`, `downloaded`, `ai_created`, `ai_suggested`, `ai_accepted`. New types may be added; show `description` for any you don't recognize.
`description`	string
`actor`	string	One of `"owner"`, `"api"`, `"recipient"`, `"system"`, `"admin"`, `"ai_claude"`, `"ai_chatgpt"`
`recipient_id`	string or null
`created_at`	string	date-time

Error

Name	Type	Description
`error`required	object
`error.type`required	string	One of `"invalid_request"`, `"authentication_error"`, `"payment_required"`, `"forbidden"`, `"not_found"`, `"conflict"`, `"rate_limit_error"`, `"api_error"`
`error.code`required	string	The specific reason; branch on this
`error.message`required	string	A sentence you can show a person
`error.param`	string	The input it's about (dot path)
`error.doc_url`required	string

Something unclear or missing? Email info@readyink.ai or use the contact page. A real person will reply.