Envelopes

An envelope is one or more PDFs sent to one or more recipients. It carries the recipients, the fields they fill, your message and metadata, and — once complete — the signed PDF and a certificate of completion.

Lifecycle#

Recipients have their own status: pending (not their turn yet) → sent (invited) → viewed → completed, or declined / delegated.

Create from a PDF#

POST/v1/envelopes takes up to 10 PDFs (merged in order) plus everything else in one request. With send: true it goes out straight away; without it you get a draft to finish later.

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": "JVBERi0xLjcKJcfsj6IK…"
      }
    ],
    "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"
      },
      {
        "key": "ceo",
        "name": "Rina Koh",
        "email": "rina@acme.example",
        "routing_order": 2
      },
      {
        "name": "Jonas Weber",
        "email": "jonas@example.com",
        "role": "cc",
        "routing_order": 3
      }
    ],
    "fields": [
      {
        "recipient_key": "client",
        "type": "signature",
        "page": 3,
        "x": 0.12,
        "y": 0.78,
        "width": 0.3,
        "height": 0.06
      },
      {
        "recipient_key": "client",
        "type": "date",
        "page": 3,
        "x": 0.12,
        "y": 0.86,
        "width": 0.2,
        "height": 0.04
      },
      {
        "recipient_key": "ceo",
        "type": "signature",
        "page": 3,
        "x": 0.58,
        "y": 0.78,
        "width": 0.3,
        "height": 0.06
      }
    ],
    "metadata": {
      "crm_deal_id": "D-10492"
    },
    "expires_in_days": 30,
    "reminders": {
      "delay_days": 2,
      "frequency_days": 3
    },
    "send": true
  }'

• JSON: put each PDF in files[].content_base64. A data:application/pdf;base64, prefix and line breaks are fine; name is optional (defaults to document-1.pdf, …).
• Multipart: upload file (one) or files[] (several), and pass recipients, fields, metadata, message and reminders as JSON strings.
• title defaults to the first file name without its extension. Files have the same size limit as uploads on the website.
• expires_in_days is one of 1, 3, 7 or 30 (or null for never); reminders take delay_days and frequency_days between 1 and 60.
• Every envelope counts against the monthly allowance. Requests rejected by validation use none; if something fails after the upload, the envelope is removed and the allowance refunded.

curl https://signkoi.com/api/v1/envelopes \
  -H "Authorization: Bearer $SIGNKOI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "files[]=@agreement.pdf" \
  -F "files[]=@annex.pdf" \
  -F 'recipients=[{"key":"client","name":"Maya Patel","email":"maya@example.com"}]' \
  -F 'fields=[{"recipient_key":"client","type":"signature","page":3,"x":0.12,"y":0.78,"width":0.3,"height":0.06}]'

Recipients and routing#

• routing_order (default 1) sets the order. Recipients with the same number are invited together; higher numbers wait until everyone before them has finished.
• language picks the language of their emails and signing page (en, es, fr, de, pt, it, nl, pl, ru, ja, zh, hi).
• verification adds an identity check: access_code (you share the code yourself; pass it as access_code), email_otp, or sms_otp (needs phone in E.164 format). Codes are never returned by the API and phones come back masked.
• Give a recipient a key (unique, up to 64 characters) to reference them from fields.

Changing recipients

• On a draft, PUT/v1/envelopes/{id}/recipients replaces the whole list. Pass a recipient’s id to keep them and their fields; anyone you leave out is removed with their fields.
• After sending, fix a typo with PATCH/v1/envelopes/{id}/recipients/{rid}. A new email address gets a fresh link (the old one stops working) and a new invitation if it’s their turn.
• Re-send one invitation with POST/v1/envelopes/{id}/recipients/{rid}/resend, or remind everyone whose turn it is with POST/v1/envelopes/{id}/remind.

Placing fields#

Fields are positioned with page (1-based) and x, y, width, height as fractions of the page, measured from the top-left corner — the same system the website editor uses. Because they are fractions, the same numbers work for A4 and US Letter.

To convert from PDF points (origin bottom-left), with a page of W × H points: x = left / W, y = (H − top) / H, width = w / W, height = h / H. Width must be at least 0.02 and height at least 0.01.

• At creation, point a field at its recipient with recipient_key or recipient_index (0-based position in recipients; the key wins if you pass both).
• On a draft, PUT/v1/envelopes/{id}/fields replaces all fields; each needs a recipient_id. Every field is recreated, so field ids change — don’t store them.
• Signature, initials, date and input fields belong to a signer or in_person_signer. Approvers, viewers and cc recipients get no fields. Every signer needs at least one signature field.
• Without any fields, Signkoi puts a signature box on the last page for the first signer.

Send#

Send a draft with POST/v1/envelopes/{id}/send. Signkoi runs the same checks as the website and answers 422 with a code if something is missing:

Before sending you can still change the title, message, expiry and reminders with PATCH/v1/envelopes/{id}; after sending only metadata can change (409 envelope_not_draft otherwise).

Track progress#

• GET/v1/envelopes/{id} returns the envelope with every recipient’s status and timestamps, and its fields. Field values appear once the envelope is completed.
• GET/v1/envelopes filters by status, search (title), created_after / created_before (inclusive), template_id and metadata[key].
• GET/v1/envelopes/{id}/audit-trail lists every event, oldest first — without IP addresses or codes.
• Best of all, let webhooks tell you when something changes.

Download the results#

The files object holds download URLs; call them with your API key like any other endpoint.

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

The signed PDF is digitally sealed and timestamped; anyone can check it at signkoi.com/verify.

Void and delete#

• POST/v1/envelopes/{id}/void cancels an envelope that is out for signature. A reason is required and shown to the recipients who still had something to do.
• DEL/v1/envelopes/{id} removes a draft for good. Sent envelopes can’t be deleted — void them.