Guides

Recipients

Recipients are the people on a document. Signers fill in fields and sign. Copy recipients get the signed PDF and cost nothing.

Roles

Role	Signs?	Cost	Gets the signed copy
`signer` (default)	Yes	1 token per signer (see `tokens_per_recipient`)	Yes
`copy`	No	Free	Yes

Add a recipient

Add recipients when you create the document, or one at a time on a draft with POST /documents/{id}/recipients. Each email can appear only once on a document; a repeat returns 409 duplicate_email.

curl https://api.readyink.ai/v1/documents/doc_c9x1q8/recipients \
  -H "Authorization: Bearer $READYINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sam Lee",
    "email": "sam@example.com",
    "mobile": "+13175550142",
    "notify_via": "both"
  }'

await fetch(`${BASE}/documents/${docId}/recipients`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Sam Lee", email: "sam@example.com", mobile: "+13175550142", notify_via: "both" }),
});

requests.post(f"{BASE}/documents/{doc_id}/recipients", headers=H, json={
    "name": "Sam Lee", "email": "sam@example.com",
    "mobile": "+13175550142", "notify_via": "both",
})

Property	Notes
`name`	Required.
`email`	Required. Every recipient needs an email, even if they're notified by text.
`mobile`	A US mobile number. Required for `sms` or `both`. Responses show only `mobile_last4`.
`notify_via`	`email` (default), `sms` or `both`.
`role`	`signer` (default) or `copy`.

Signing order

Each recipient has an order. With signing_mode: "sequential", signers get the link one at a time in that order. With parallel, everyone gets it at once.

Recipient statuses

Status	Meaning
`pending`	Not notified yet, for example waiting for an earlier signer.
`notified`	The signing link was sent.
`viewed`	They opened the document.
`signed`	They signed. See `signed_at`.
`declined`	They declined. See `declined_at`.

Change or remove a recipient

On a draft, PATCH /documents/{id}/recipients/{rid} takes the full recipient, and DELETE removes them along with their fields.

On a document that's out, you can only fix an email address. Send exactly {"email": "…"}. The old link stops working and a new request goes to the new address.

cURL

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"}'

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