Envelopes API

An envelope is one or more PDFs sent to recipients for signature. Create, update, send, remind, void and track them.

On this page

List envelopes
Create an envelope
Retrieve an envelope
Update an envelope
Delete a draft
Replace fields
Send an envelope
Void an envelope
Send a reminder
Retrieve the audit trail

List envelopes

GET/v1/envelopes

Envelopes you own, newest first. Fields are not included; retrieve an envelope to get them.

Required scope:envelopes:read

Query parameters

statusstring
Only envelopes in this status (public names only; anything else is a 422 with param status).
One ofdraftsentcompleteddeclinedvoidedexpired
searchstring
Matches the title.
created_afterstring · date-time
ISO 8601 date or date-time (inclusive).
created_beforestring · date-time
ISO 8601 date or date-time (inclusive).
template_idstring · uuid
Only envelopes created from this template.
metadata[key]object
Exact metadata match, e.g. metadata[crm_deal_id]=D-10492. Several keys must all match.
pageinteger
Page number, starting at 1.
default 1
per_pageinteger
Items per page.
default 20

Response

200A page of envelopes.

Response objectEnvelopeList

A page of envelopes (without fields).

objectstring= "list"
dataarray of Envelope
Child attributes (Envelope)
- 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.
pageinteger
per_pageinteger
totalinteger
has_moreboolean
Whether another page follows.

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).
422Invalid filter, e.g. an unknown status (validation_failed).
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

GET /v1/envelopes

curl -G https://signkoi.com/api/v1/envelopes \
  -H "Authorization: Bearer $SIGNKOI_API_KEY" \
  --data-urlencode "status=sent" \
  --data-urlencode "metadata[crm_deal_id]=D-10492"

Example response

200 · application/json

{
  "object": "list",
  "data": [
    {
      "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"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 1,
  "has_more": false
}

Creates an envelope from one or more PDFs, optionally with recipients, fields and metadata, and sends it right away with send: true. Upload the files as multipart (file or files[]) or inline as base64 in JSON. If you pass recipients but no fields, a signature box is placed on the last page for the first signer. Counts against your plan's monthly document allowance (402 plan_limit when it is used up); requests rejected by validation use no quota, and if anything fails after the upload the envelope is removed and the quota refunded. If send is true and the envelope is not ready (for example a signer without a signature field), nothing is kept and you get a 422 with the reason as code.

Required scope:envelopes:write

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.

Request body application/json

Body (required)CreateEnvelopeRequest

filesarray of objectrequired
PDFs, base64-encoded (up to 10; the same size limits as uploads on the website, 25 MB by default). Several files are merged into one envelope in order.
1–10 items
Child attributes
- namestring
  File name, e.g. agreement.pdf. Defaults to document-N.pdf.
- content_base64stringrequired
  Base64 PDF. A data:application/pdf;base64, prefix and line breaks are accepted.
titlestring
Defaults to the first file name without its extension.
messageMessageInput
Child attributes (MessageInput)
- subjectstring | null
  Defaults to "Please sign: {title}".
  max 200 chars
- bodystring | null
  max 2000 chars
recipientsarray of RecipientInput
Child attributes (RecipientInput)
- keystring
  Your own reference for this recipient (unique within the request), so fields can point at it with recipient_key.
  max 64 chars
- 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
fieldsarray of FieldInput
If omitted, a signature box is placed on the last page for the first signer.
Child attributes (FieldInput)
- recipient_keystring
  The key of the recipient who fills the field (wins over recipient_index)…
- recipient_indexinteger
  …or their 0-based position in recipients.
  ≥ 0
- 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
- requiredboolean
  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
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
expires_in_daysinteger | null
Days the envelope stays signable after sending; null = never expires.
One of13730
remindersRemindersInput
Child attributes (RemindersInput)
- delay_daysinteger | null
  1–60
- frequency_daysinteger | null
  1–60
sendboolean
Send immediately. If sending fails validation nothing is kept and you get a 422 with the reason.
default false

Request body multipart/form-data

Body (required)CreateEnvelopeMultipart

Same as the JSON body, but upload the PDF(s) as files. recipients, fields, metadata, message and reminders are JSON-encoded strings.

filefile
One PDF…
files[]array of file
…or several (up to 10).
titlestring
recipientsstring
JSON array of RecipientInput.
fieldsstring
JSON array of FieldInput.
metadatastring
JSON object.
messagestring
JSON object {subject, body}.
remindersstring
JSON object {delay_days, frequency_days}.
expires_in_daysinteger
sendboolean

Response

201The created envelope (with fields).

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, Idempotent-Replayed.

Errors

401Missing, invalid, expired or revoked API key (api_key_missing, invalid_api_key).
402The plan's monthly document allowance is used up (plan_limit).
403The key lacks a required scope (insufficient_scope) or the account is suspended (account_suspended).
413A file, or all files together, is larger than allowed (file_too_large).
422Invalid request (validation_failed), a file problem (file_required, file_conflict, too_many_files, invalid_file, invalid_base64, file_not_pdf, invalid_pdf, invalid_json; param is file, files, files.N or files.N.content_base64), or with send: true a send check (no_recipients, missing_recipient_details, unassigned_fields, 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

POST /v1/envelopes

curl -X POST https://signkoi.com/api/v1/envelopes \
  -H "Authorization: Bearer $SIGNKOI_API_KEY" \
  -H "Idempotency-Key: 5f1d7c1e-0b8a-4c2e-9f3d-61a2b7e4c905" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Consulting agreement — Acme Ltd",
    "files": [
      {
        "name": "agreement.pdf",
        "content_base64": "JVBERi0xLjcKJcfsj6IKNSAwIG9iago8PC9MZW5ndGggNiAwIFI…"
      }
    ],
    "message": {
      "subject": "Please sign: Consulting agreement",
      "body": "Hi Maya, here is the agreement we discussed."
    },
    "recipients": [
      {
        "key": "client",
        "name": "Maya Patel",
        "email": "maya@example.com",
        "verification": "email_otp"
      },
      {
        "name": "Jonas Weber",
        "email": "jonas@example.com",
        "role": "cc",
        "routing_order": 2,
        "language": "de"
      }
    ],
    "fields": [
      {
        "recipient_key": "client",
        "type": "signature",
        "page": 1,
        "x": 0.12,
        "y": 0.82,
        "width": 0.3,
        "height": 0.06
      },
      {
        "recipient_key": "client",
        "type": "date",
        "page": 1,
        "x": 0.6,
        "y": 0.84,
        "width": 0.2,
        "height": 0.04
      }
    ],
    "metadata": {
      "crm_deal_id": "D-10492"
    },
    "expires_in_days": 30,
    "reminders": {
      "delay_days": 2,
      "frequency_days": 3
    },
    "send": true
  }'

Example response

201 · 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
    }
  ]
}

Retrieve an envelope

GET/v1/envelopes/{id}

The envelope with its recipients and fields. Field values are included once the envelope is completed. Envelopes that are not yours return 404. Field ids change whenever the fields are replaced, so don't store them long-term.

Required scope:envelopes:read

Path parameters

idstring · uuidrequired
Envelope id.

Response

200The envelope.

Returns the EnvelopeDetail object — its attributes are listed under Create an envelope.

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.").
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

GET /v1/envelopes/{id}

curl https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47 \
  -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
    }
  ]
}

Update an envelope

PATCH/v1/envelopes/{id}

Change the title, message, expiry or reminders of a draft (409 envelope_not_draft otherwise), or the metadata of any envelope. Metadata is merged: keys you send are set, keys set to null are removed, others are kept; metadata: null clears it. message: null clears subject and body; expires_in_days: null removes the expiry.

Required scope:envelopes:write

Path parameters

idstring · uuidrequired
Envelope id.

Request body application/json

Body (required)UpdateEnvelopeRequest

title, message, expires_in_days and reminders can only change while the envelope is a draft (409 envelope_not_draft otherwise). metadata can change at any time.

titlestring
messageobject | null
null clears both subject and body.
Child attributes
- subjectstring | null
  Defaults to "Please sign: {title}".
  max 200 chars
- bodystring | null
  max 2000 chars
expires_in_daysinteger | null
Days the envelope stays signable after sending; null = no expiry.
One of13730
remindersRemindersInput
Child attributes (RemindersInput)
- delay_daysinteger | null
  1–60
- frequency_daysinteger | null
  1–60
metadataobject | null
Merged into the existing metadata. Set a key to null to delete it, or pass metadata: null to clear all keys.

Response

200The updated envelope.

Returns the EnvelopeDetail object — its attributes are listed under Create an envelope.

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

PATCH /v1/envelopes/{id}

curl -X PATCH https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47 \
  -H "Authorization: Bearer $SIGNKOI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "crm_stage": "contract_sent",
      "old_key": null
    }
  }'

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
    }
  ]
}

Delete a draft

DEL/v1/envelopes/{id}

Permanently deletes a draft envelope. Sent envelopes cannot be deleted (409 envelope_not_draft); void them instead.

Required scope:envelopes:write

Path parameters

idstring · uuidrequired
Envelope id.

Response

204Deleted.

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).
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

DELETE /v1/envelopes/{id}

curl -X DELETE https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47 \
  -H "Authorization: Bearer $SIGNKOI_API_KEY"

Replace fields

PUT/v1/envelopes/{id}/fields

Sets the complete list of fields of a draft. Every field is recreated, so field ids change on each call. Coordinates are fractions (0–1) of the page, origin top-left. Every field needs a recipient_id; signature, initials, date and input fields must belong to a signer or in_person_signer.

Required scope:envelopes:write

Path parameters

idstring · uuidrequired
Envelope id.

Request body application/json

Body (required)ReplaceFieldsRequest

fieldsarray of objectrequired
The complete new set of fields; existing fields are replaced.
Child attributes
- recipient_idstring · uuidrequired
  The recipient who fills the 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
- requiredboolean
  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

Response

200The envelope with its new fields.

Returns the EnvelopeDetail object — its attributes are listed under Create an envelope.

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}/fields

curl -X PUT https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/fields \
  -H "Authorization: Bearer $SIGNKOI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {
        "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73",
        "type": "signature",
        "page": 1,
        "x": 0.12,
        "y": 0.82,
        "width": 0.3,
        "height": 0.06
      },
      {
        "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73",
        "type": "text",
        "page": 1,
        "x": 0.12,
        "y": 0.3,
        "width": 0.35,
        "height": 0.04,
        "label": "Company number",
        "required": false
      }
    ]
  }'

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
    }
  ]
}

Send an envelope

POST/v1/envelopes/{id}/send

Sends a draft: the first recipients in the routing order are invited by email. Fails with 422 and a code when the envelope is not ready: no_recipients, missing_recipient_details, missing_signature_field, unassigned_fields or expired.

Required scope:envelopes:write

Path parameters

idstring · uuidrequired
Envelope 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 sent envelope.

Returns the EnvelopeDetail object — its attributes are listed under Create an envelope.

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).
422The envelope is not ready to send: no_recipients, missing_recipient_details, unassigned_fields, missing_signature_field or expired.
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}/send

curl -X POST https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/send \
  -H "Authorization: Bearer $SIGNKOI_API_KEY" \
  -H "Idempotency-Key: 5f1d7c1e-0b8a-4c2e-9f3d-61a2b7e4c905"

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
    }
  ]
}

Void an envelope

POST/v1/envelopes/{id}/void

Cancels an envelope that is out for signature. Recipients who still had something to do are told by email, with your reason. Only sent envelopes can be voided.

Required scope:envelopes:write

Path parameters

idstring · uuidrequired
Envelope 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.

Request body application/json

Body (required)VoidEnvelopeRequest

reasonstringrequired
Shown to the recipients in the void email.
max 500 chars

Response

200The voided envelope.

Returns the EnvelopeDetail object — its attributes are listed under Create an envelope.

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; expired envelopes count as not sent).
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

POST /v1/envelopes/{id}/void

curl -X POST https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/void \
  -H "Authorization: Bearer $SIGNKOI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Terms changed; a new version follows."
  }'

Example response

200 · application/json

{
  "object": "envelope",
  "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47",
  "title": "Consulting agreement — Acme Ltd",
  "status": "voided",
  "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": "2026-11-14T12:00:00Z",
  "void_reason": "Terms changed; a new version follows.",
  "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
    }
  ]
}

Send a reminder

POST/v1/envelopes/{id}/remind

Emails the invitation again to every recipient whose turn it is (in-person signers excluded). Only for sent envelopes. Limited to 6 calls a minute per account (429 rate_limited with Retry-After).

Required scope:envelopes:write

Path parameters

idstring · uuidrequired
Envelope 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 Create an envelope.

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 nobody can be reminded (nobody_to_remind).
429More than 6 reminders 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}/remind

curl -X POST https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/remind \
  -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
    }
  ]
}

Retrieve the audit trail

GET/v1/envelopes/{id}/audit-trail

Every recorded event of the envelope, oldest first — document.created, envelope.sent, recipient.sent, recipient.viewed, recipient.completed, envelope.completed and so on. actor is the person who acted, or null for system events. IP addresses and verification codes are never included.

Required scope:envelopes:read

Path parameters

idstring · uuidrequired
Envelope id.

Query parameters

pageinteger
Page number, starting at 1.
default 1
per_pageinteger
Items per page.
default 20

Response

200The audit trail.

Response objectAuditEventList

The audit trail, oldest first.

objectstring= "list"
dataarray of AuditEvent
Child attributes (AuditEvent)
- objectstring= "audit_event"
- eventstring
  e.g. envelope.sent, recipient.viewed, recipient.completed, envelope.completed.
- actorobject | null
  Child attributes
  namestring | null
  emailstring | null
- recipient_idstring · uuid | null
- created_atstring · date-time
pageinteger
per_pageinteger
totalinteger
has_moreboolean
Whether another page follows.

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.").
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

GET /v1/envelopes/{id}/audit-trail

curl https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/audit-trail \
  -H "Authorization: Bearer $SIGNKOI_API_KEY"

Example response

200 · application/json

{
  "object": "list",
  "data": [
    {
      "object": "audit_event",
      "event": "document.created",
      "actor": {
        "name": "Rina Koh",
        "email": "rina@acme.example"
      },
      "recipient_id": null,
      "created_at": "2026-11-14T09:30:05Z"
    },
    {
      "object": "audit_event",
      "event": "envelope.sent",
      "actor": {
        "name": "Rina Koh",
        "email": "rina@acme.example"
      },
      "recipient_id": null,
      "created_at": "2026-11-14T09:30:12Z"
    },
    {
      "object": "audit_event",
      "event": "recipient.viewed",
      "actor": {
        "name": "Maya Patel",
        "email": "maya@example.com"
      },
      "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73",
      "created_at": "2026-11-15T13:58:01Z"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 3,
  "has_more": false
}