Recipients API

Manage the people on an envelope, resend invitations and create signing URLs for embedded signing.

On this page

Replace recipients
Correct a recipient
Resend the invitation
Create a signing URL

Replace recipients

PUT/v1/envelopes/{id}/recipients

Sets the complete list of recipients of a draft. Pass id to keep an existing recipient; recipients you leave out are deleted together with their fields.

Required scope:envelopes:write

Path parameters

idstring · uuidrequired
Envelope id.

Request body application/json

Body (required)ReplaceRecipientsRequest

recipientsarray of objectrequired
The complete new set, as full objects. Pass id to keep an existing recipient (and their fields); recipients you leave out are removed with their fields. For a kept recipient, omitting access_code or phone keeps the stored value. An unknown id is a 422 (param recipients.N.id).
Child attributes
- idstring · uuid
  Existing recipient to keep.
- namestringrequired
  Recipient name.
  max 255 chars
- emailstring · emailrequired
  max 255 chars
- rolestring
  Defaults to signer.
  One ofsignerin_person_signerapproverviewercc
- routing_orderinteger
  Recipients with the same number are invited together; higher numbers wait.
  default 1 · ≥ 1
- languagestring
  Language of the emails and signing page. Defaults to your account language.
  One ofenesfrdeptitnlplrujazhhi
- verificationstring
  Extra identity check before signing. Defaults to none.
  One ofnoneaccess_codeemail_otpsms_otp
- access_codestring | null
  Required when verification is access_code. Share it with the recipient yourself; it is stored hashed and never returned.
  max 64 chars
- phonestring | null
  E.164 phone number, required when verification is sms_otp. Returned masked.
- private_messagestring | null
  Note only this recipient sees.
  max 1000 chars

Response

200The envelope with its new recipients.

Response objectEnvelopeDetail

An envelope including its fields (returned by retrieve, create and every update).

objectstringrequired= "envelope"
idstring · uuidrequired
titlestringrequired
statusstringrequired
draft (not sent yet) → sent (out for signature) → completed (everyone finished). An envelope can also end as declined, voided or expired.
One ofdraftsentcompleteddeclinedvoidedexpired
messageobject
Email sent to recipients.
Child attributes
- subjectstring | null
- bodystring | null
metadataMetadata
Your own key/value pairs (string → string). Up to 20 keys; keys up to 40 characters of letters, digits, _, . and -; string values up to 500 characters (numbers are converted to strings; booleans and nested objects are rejected). Echoed on the envelope and in webhooks; filter lists with metadata[key]=value.
max 20 keys
template_idstring · uuid | null
Template the envelope was created from.
sourcestring
Created through the API or on the website.
One ofapiapp
page_countinteger
remindersobject
Child attributes
- delay_daysinteger | null
  Days before the first reminder.
- frequency_daysinteger | null
  Days between reminders after that.
recipientsarray of Recipientrequired
Sorted by routing order.
Child attributes (Recipient)
- objectstringrequired= "recipient"
- idstring · uuidrequired
- rolestringrequired
  signer signs remotely; in_person_signer signs on your device (embedded signing); approver approves without signing; viewer must open the document; cc gets a copy when it completes.
  One ofsignerin_person_signerapproverviewercc
- role_namestring | null
  Template role this recipient fills, if any.
- namestring | null
- emailstring · email | null
- routing_orderintegerrequired
- statusstringrequired
  pending: not their turn yet (or the envelope is a draft); sent: invited; viewed: opened the envelope; completed: finished; declined; delegated: handed over to someone else.
  One ofpendingsentviewedcompleteddeclineddelegated
- languagestring | null
- verificationstring
  One ofnoneaccess_codeemail_otpsms_otp
- phonestring | null
  Masked, e.g. +44 ••• ••• 4821.
- sent_atstring · date-time | null
- viewed_atstring · date-time | null
- completed_atstring · date-time | null
- declined_atstring · date-time | null
- decline_reasonstring | null
filesobjectrequired
Download URLs (authenticate with your API key). signed and certificate are null until the envelope is completed.
Child attributes
- originalstring · uri
- signedstring · uri | null
- certificatestring · uri | null
created_atstring · date-timerequired
sent_atstring · date-time | null
completed_atstring · date-time | null
declined_atstring · date-time | null
voided_atstring · date-time | null
void_reasonstring | null
expires_atstring · date-time | null
After this the envelope can no longer be signed; null = never.
fieldsarray of Field
Child attributes (Field)
- objectstringrequired= "field"
- idstringrequired
  Field id.
- recipient_idstring · uuid | null
  The recipient who fills this field.
- typestringrequired
  One ofsignatureinitialsnameemailcompanytitledatetextnumbercheckboxradiodropdownattachmentformulanote
- pageintegerrequired
  Page number, 1-based.
  ≥ 1
- xnumberrequired
  Left edge as a fraction of the page width (origin top-left).
  0–1
- ynumberrequired
  Top edge as a fraction of the page height (origin top-left).
  0–1
- widthnumberrequired
  Width as a fraction of the page width.
  0.02–1
- heightnumberrequired
  Height as a fraction of the page height.
  0.01–1
- requiredbooleanrequired
  Whether the recipient must fill the field.
- labelstring | null
  Label shown to the recipient.
  max 120 chars
- placeholderstring | null
  max 120 chars
- optionsarray of string | null
  Choices for dropdown (and the value of each radio button).
  max 50 items
- group_namestring | null
  Groups radio buttons; required for radio fields.
  max 120 chars
- default_valuestring | null
  Pre-filled value. Required for note fields (the text shown).
  max 2000 chars
- validationstring | null
  Input format check for text fields.
  One ofemailnumberphonezipdate
- formulastring | null
  Only for formula fields, e.g. [qty] * [price].
  max 500 chars
- read_onlyboolean
- font_sizeinteger | null
  8–20
- valuestring | boolean | object | any | null
  Only present once the envelope is completed. Text value; true/false for checkboxes; { "filled": true } for signature, initials and attachment fields; null if left empty.

Response headers: X-Request-Id, Signkoi-Version, X-RateLimit-Limit, X-RateLimit-Remaining.

Errors

401Missing, invalid, expired or revoked API key (api_key_missing, invalid_api_key).
403The key lacks a required scope (insufficient_scope) or the account is suspended (account_suspended).
404No such resource, or it belongs to someone else (resource_missing, e.g. "No such envelope." / "No such recipient.").
409The envelope is not a draft (envelope_not_draft).
422Invalid parameters (validation_failed, with param and errors) or a business rule failed (e.g. missing_signature_field).
429Too many requests (rate_limited): your key's per-minute limit, or an endpoint's own limit. Wait for Retry-After seconds.
500Something went wrong on our side (internal_error). Safe to retry with the same Idempotency-Key.

Every error uses the error object.

Example request

PUT /v1/envelopes/{id}/recipients

curl -X PUT https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/recipients \
  -H "Authorization: Bearer $SIGNKOI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      {
        "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73",
        "name": "Maya Patel",
        "email": "maya@example.com",
        "verification": "email_otp"
      },
      {
        "name": "Jonas Weber",
        "email": "jonas@example.com",
        "role": "cc",
        "routing_order": 2
      }
    ]
  }'

Example response

200 · application/json

{
  "object": "envelope",
  "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47",
  "title": "Consulting agreement — Acme Ltd",
  "status": "draft",
  "message": {
    "subject": "Please sign: Consulting agreement",
    "body": "Hi Maya, here is the agreement we discussed."
  },
  "metadata": {
    "crm_deal_id": "D-10492"
  },
  "template_id": null,
  "source": "api",
  "page_count": 3,
  "reminders": {
    "delay_days": 2,
    "frequency_days": 3
  },
  "recipients": [
    {
      "object": "recipient",
      "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73",
      "role": "signer",
      "role_name": null,
      "name": "Maya Patel",
      "email": "maya@example.com",
      "routing_order": 1,
      "status": "pending",
      "language": "en",
      "verification": "email_otp",
      "phone": null,
      "sent_at": null,
      "viewed_at": null,
      "completed_at": null,
      "declined_at": null,
      "decline_reason": null
    },
    {
      "object": "recipient",
      "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08",
      "role": "cc",
      "role_name": null,
      "name": "Jonas Weber",
      "email": "jonas@example.com",
      "routing_order": 2,
      "status": "pending",
      "language": "de",
      "verification": "none",
      "phone": null,
      "sent_at": null,
      "viewed_at": null,
      "completed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "files": {
    "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original",
    "signed": null,
    "certificate": null
  },
  "created_at": "2026-11-14T09:30:05Z",
  "sent_at": null,
  "completed_at": null,
  "declined_at": null,
  "voided_at": null,
  "void_reason": null,
  "expires_at": null,
  "fields": [
    {
      "object": "field",
      "id": "48213",
      "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73",
      "type": "signature",
      "page": 1,
      "x": 0.12,
      "y": 0.82,
      "width": 0.3,
      "height": 0.06,
      "required": true,
      "label": null,
      "placeholder": null,
      "options": null,
      "group_name": null,
      "default_value": null,
      "validation": null,
      "formula": null,
      "read_only": false,
      "font_size": null
    },
    {
      "object": "field",
      "id": "48214",
      "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73",
      "type": "date",
      "page": 1,
      "x": 0.6,
      "y": 0.84,
      "width": 0.2,
      "height": 0.04,
      "required": true,
      "label": null,
      "placeholder": null,
      "options": null,
      "group_name": null,
      "default_value": null,
      "validation": null,
      "formula": null,
      "read_only": false,
      "font_size": null
    }
  ]
}

Correct a recipient

PATCH/v1/envelopes/{id}/recipients/{rid}

Fixes a recipient's details while the envelope is out for signature and the recipient has not finished. Changing the email issues a new signing link (the old one stops working) and re-sends the invitation if it is their turn.

Required scope:envelopes:write

Path parameters

idstring · uuidrequired
Envelope id.
ridstring · uuidrequired
Recipient id.

Request body application/json

Body (required)UpdateRecipientRequest

Correct a recipient who has not finished yet. Changing the email issues a new signing link (the old one stops working) and re-sends the invitation if it is their turn.

namestring
Recipient name.
max 255 chars
emailstring · email
max 255 chars
languagestring
Language of the emails and signing page. Defaults to your account language.
One ofenesfrdeptitnlplrujazhhi
verificationstring
Extra identity check before signing. Defaults to none.
One ofnoneaccess_codeemail_otpsms_otp
access_codestring | null
Required when verification is access_code. Share it with the recipient yourself; it is stored hashed and never returned.
max 64 chars
phonestring | null
E.164 phone number, required when verification is sms_otp. Returned masked.
private_messagestring | null
Note only this recipient sees.
max 1000 chars

Response

200The envelope with the corrected recipient.

Returns the EnvelopeDetail object — its attributes are listed under Replace recipients.

Response headers: X-Request-Id, Signkoi-Version, X-RateLimit-Limit, X-RateLimit-Remaining.

Errors

401Missing, invalid, expired or revoked API key (api_key_missing, invalid_api_key).
403The key lacks a required scope (insufficient_scope) or the account is suspended (account_suspended).
404No such resource, or it belongs to someone else (resource_missing, e.g. "No such envelope." / "No such recipient.").
409The envelope is not out for signature (envelope_not_sent) or the recipient has finished (recipient_finished).
422Invalid parameters (validation_failed, with param and errors) or a business rule failed (e.g. missing_signature_field).
429Too many requests (rate_limited): your key's per-minute limit, or an endpoint's own limit. Wait for Retry-After seconds.
500Something went wrong on our side (internal_error). Safe to retry with the same Idempotency-Key.

Every error uses the error object.

Example request

PATCH /v1/envelopes/{id}/recipients/{rid}

curl -X PATCH https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/recipients/c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73 \
  -H "Authorization: Bearer $SIGNKOI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "maya.patel@example.com"
  }'

Example response

200 · application/json

{
  "object": "envelope",
  "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47",
  "title": "Consulting agreement — Acme Ltd",
  "status": "sent",
  "message": {
    "subject": "Please sign: Consulting agreement",
    "body": "Hi Maya, here is the agreement we discussed."
  },
  "metadata": {
    "crm_deal_id": "D-10492"
  },
  "template_id": null,
  "source": "api",
  "page_count": 3,
  "reminders": {
    "delay_days": 2,
    "frequency_days": 3
  },
  "recipients": [
    {
      "object": "recipient",
      "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73",
      "role": "signer",
      "role_name": null,
      "name": "Maya Patel",
      "email": "maya.patel@example.com",
      "routing_order": 1,
      "status": "sent",
      "language": "en",
      "verification": "email_otp",
      "phone": null,
      "sent_at": "2026-11-14T09:30:12Z",
      "viewed_at": null,
      "completed_at": null,
      "declined_at": null,
      "decline_reason": null
    },
    {
      "object": "recipient",
      "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08",
      "role": "cc",
      "role_name": null,
      "name": "Jonas Weber",
      "email": "jonas@example.com",
      "routing_order": 2,
      "status": "pending",
      "language": "de",
      "verification": "none",
      "phone": null,
      "sent_at": null,
      "viewed_at": null,
      "completed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "files": {
    "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original",
    "signed": null,
    "certificate": null
  },
  "created_at": "2026-11-14T09:30:05Z",
  "sent_at": "2026-11-14T09:30:12Z",
  "completed_at": null,
  "declined_at": null,
  "voided_at": null,
  "void_reason": null,
  "expires_at": "2026-12-14T09:30:12Z",
  "fields": [
    {
      "object": "field",
      "id": "48213",
      "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73",
      "type": "signature",
      "page": 1,
      "x": 0.12,
      "y": 0.82,
      "width": 0.3,
      "height": 0.06,
      "required": true,
      "label": null,
      "placeholder": null,
      "options": null,
      "group_name": null,
      "default_value": null,
      "validation": null,
      "formula": null,
      "read_only": false,
      "font_size": null
    },
    {
      "object": "field",
      "id": "48214",
      "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73",
      "type": "date",
      "page": 1,
      "x": 0.6,
      "y": 0.84,
      "width": 0.2,
      "height": 0.04,
      "required": true,
      "label": null,
      "placeholder": null,
      "options": null,
      "group_name": null,
      "default_value": null,
      "validation": null,
      "formula": null,
      "read_only": false,
      "font_size": null
    }
  ]
}

Resend the invitation

POST/v1/envelopes/{id}/recipients/{rid}/resend

Emails the invitation again to one recipient whose turn it is. Limited to 10 calls a minute per account.

Required scope:envelopes:write

Path parameters

idstring · uuidrequired
Envelope id.
ridstring · uuidrequired
Recipient id.

Headers

Idempotency-Keystring
Any unique string (1–255 chars), e.g. a UUID. Retrying with the same key and body within 24 hours returns the original response instead of repeating the action.

Response

200The envelope.

Returns the EnvelopeDetail object — its attributes are listed under Replace recipients.

Response headers: X-Request-Id, Signkoi-Version, X-RateLimit-Limit, X-RateLimit-Remaining.

Errors

401Missing, invalid, expired or revoked API key (api_key_missing, invalid_api_key).
403The key lacks a required scope (insufficient_scope) or the account is suspended (account_suspended).
404No such resource, or it belongs to someone else (resource_missing, e.g. "No such envelope." / "No such recipient.").
409Not possible right now: envelope_not_sent, recipient_not_active (not their turn yet), recipient_finished or recipient_in_person (in-person signers get no email).
429More than 10 resends a minute (rate_limited), or your key's rate limit.
500Something went wrong on our side (internal_error). Safe to retry with the same Idempotency-Key.

Every error uses the error object.

Example request

POST /v1/envelopes/{id}/recipients/{rid}/resend

curl -X POST https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/recipients/c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73/resend \
  -H "Authorization: Bearer $SIGNKOI_API_KEY"

Example response

200 · application/json

{
  "object": "envelope",
  "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47",
  "title": "Consulting agreement — Acme Ltd",
  "status": "sent",
  "message": {
    "subject": "Please sign: Consulting agreement",
    "body": "Hi Maya, here is the agreement we discussed."
  },
  "metadata": {
    "crm_deal_id": "D-10492"
  },
  "template_id": null,
  "source": "api",
  "page_count": 3,
  "reminders": {
    "delay_days": 2,
    "frequency_days": 3
  },
  "recipients": [
    {
      "object": "recipient",
      "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73",
      "role": "signer",
      "role_name": null,
      "name": "Maya Patel",
      "email": "maya@example.com",
      "routing_order": 1,
      "status": "sent",
      "language": "en",
      "verification": "email_otp",
      "phone": null,
      "sent_at": "2026-11-14T09:30:12Z",
      "viewed_at": null,
      "completed_at": null,
      "declined_at": null,
      "decline_reason": null
    },
    {
      "object": "recipient",
      "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08",
      "role": "cc",
      "role_name": null,
      "name": "Jonas Weber",
      "email": "jonas@example.com",
      "routing_order": 2,
      "status": "pending",
      "language": "de",
      "verification": "none",
      "phone": null,
      "sent_at": null,
      "viewed_at": null,
      "completed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "files": {
    "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original",
    "signed": null,
    "certificate": null
  },
  "created_at": "2026-11-14T09:30:05Z",
  "sent_at": "2026-11-14T09:30:12Z",
  "completed_at": null,
  "declined_at": null,
  "voided_at": null,
  "void_reason": null,
  "expires_at": "2026-12-14T09:30:12Z",
  "fields": [
    {
      "object": "field",
      "id": "48213",
      "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73",
      "type": "signature",
      "page": 1,
      "x": 0.12,
      "y": 0.82,
      "width": 0.3,
      "height": 0.06,
      "required": true,
      "label": null,
      "placeholder": null,
      "options": null,
      "group_name": null,
      "default_value": null,
      "validation": null,
      "formula": null,
      "read_only": false,
      "font_size": null
    },
    {
      "object": "field",
      "id": "48214",
      "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73",
      "type": "date",
      "page": 1,
      "x": 0.6,
      "y": 0.84,
      "width": 0.2,
      "height": 0.04,
      "required": true,
      "label": null,
      "placeholder": null,
      "options": null,
      "group_name": null,
      "default_value": null,
      "validation": null,
      "formula": null,
      "read_only": false,
      "font_size": null
    }
  ]
}

Create a signing URL

POST/v1/envelopes/{id}/recipients/{rid}/signing-url

Returns a URL that opens the signing page for this recipient, for embedded or in-person signing in your own app. Only for the recipient whose turn it is (409 not_recipients_turn otherwise). Each call is recorded in the audit trail. Never send this URL to anyone but the recipient.

Required scope:envelopes:write

Path parameters

idstring · uuidrequired
Envelope id.
ridstring · uuidrequired
Recipient id.

Headers

Idempotency-Keystring
Any unique string (1–255 chars), e.g. a UUID. Retrying with the same key and body within 24 hours returns the original response instead of repeating the action.

Response

200The signing URL.

Response objectSigningUrl

objectstring= "signing_url"
urlstring · uri
Opens the signing page for this recipient. Treat it like a password: do not log or share it.
recipient_idstring · uuid

Response headers: X-Request-Id, Signkoi-Version, X-RateLimit-Limit, X-RateLimit-Remaining.

Errors

401Missing, invalid, expired or revoked API key (api_key_missing, invalid_api_key).
403The key lacks a required scope (insufficient_scope) or the account is suspended (account_suspended).
404No such resource, or it belongs to someone else (resource_missing, e.g. "No such envelope." / "No such recipient.").
409The envelope is not out for signature (envelope_not_sent), or it is not this recipient's turn (not_recipients_turn).
429Too many requests (rate_limited): your key's per-minute limit, or an endpoint's own limit. Wait for Retry-After seconds.
500Something went wrong on our side (internal_error). Safe to retry with the same Idempotency-Key.

Every error uses the error object.

Example request

POST /v1/envelopes/{id}/recipients/{rid}/signing-url

curl -X POST https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/recipients/c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73/signing-url \
  -H "Authorization: Bearer $SIGNKOI_API_KEY"

Example response

200 · application/json

{
  "object": "signing_url",
  "url": "https://signkoi.com/s/8kQ2…",
  "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73"
}

Recipients API

Replace recipients#

Path parameters

Request body application/json

Response

Errors

Example request

Example response

Correct a recipient#

Path parameters

Request body application/json

Response

Errors

Example request

Example response

Resend the invitation#

Path parameters

Headers

Response

Errors

Example request

Example response

Create a signing URL#

Path parameters

Headers

Response

Errors

Example request

Example response

Replace recipients

Correct a recipient

Resend the invitation

Create a signing URL