Start with custom documents

Use this approach when you need to upload a different PDF for each signing session. You have full control over the document content, recipient assignments, and field placement on every send.

When to use this: Contract variations, personalised agreements, or any workflow where the document changes with each transaction.

Overview

This guide walks through the following steps:

Create an envelope
Upload documents
Add recipients
Add fields and assign them to recipients
Send the envelope

1. Create an envelope

An envelope is the container for all signing activity. Start by creating one in draft status.

POST /api/v1/key/envelopes
X-Inspakt-Api-Key: <your-api-key>
Content-Type: application/json

{
  "name": "Service Agreement — Acme Corp",
  "expirationPeriodDays": 14,
  "reminderInitialDelayDays": 3,
  "reminderRepeatIntervalDays": 2
}

Field	Type	Required	Description
`name`	string	✅	Display name for the envelope (2–48 characters).
`expirationPeriodDays`	number	—	Days until the envelope expires (1–90).
`reminderInitialDelayDays`	number	—	Days after sending before the first reminder is sent (0–30).
`reminderRepeatIntervalDays`	number	—	Interval in days between subsequent reminders (0–30).
`reminderBeforeExpirationDays`	number	—	Days before expiration to send a final reminder (0–30).
`context`	object	—	Arbitrary key-value metadata you can attach and retrieve later.

Response

{
  "success": true,
  "payload": {
    "envelopeId": "env_01hx..."
  }
}

Save the envelopeId — it is required for all subsequent steps.

2. Upload documents

Upload one or more PDF files to the envelope. Each upload is a separate multipart/form-data request.

POST /api/v1/key/envelopes/{envelopeId}/documents
X-Inspakt-Api-Key: <your-api-key>
Content-Type: multipart/form-data

Field	Type	Required	Description
`document`	file (binary)	✅	PDF file. Maximum size: 48 MB.
`name`	string	—	Display name for the document (max 140 characters). Defaults to the filename.
`order`	number	—	Display order when multiple documents are present. Starts at `0`.
`context`	object	—	Arbitrary metadata.

Response

{
  "success": true,
  "payload": {
    "document": {
      "id": "doc_02jy...",
      "name": "Service Agreement.pdf",
      "order": 0,
      "pages": [{}, {}, {}],
      "context": {}
    }
  }
}

Save each document.id — you will need it when placing fields.

tip

The pages array contains one entry per PDF page. Use the array length to determine valid page indexes for field placement.

3. Add recipients

Add one or more recipients to the envelope. Each recipient represents a role in the signing workflow.

POST /api/v1/key/envelopes/{envelopeId}/recipients
X-Inspakt-Api-Key: <your-api-key>
Content-Type: application/json

{
  "recipient": {
    "type": "signer",
    "identifier": "counterparty",
    "roleName": "Counterparty",
    "order": 0,
    "required": true,
    "agents": [
      {
        "info": {
          "name": "Jane Smith",
          "email": "[email protected]",
          "locale": "en-US"
        }
      }
    ]
  }
}

Recipient fields

Field	Type	Required	Description
`type`	string	✅	Role type. See table below.
`identifier`	string	—	A stable slug you use to reference this recipient in field assignments (e.g. `"counterparty"`).
`roleName`	string	—	Human-readable label shown in the UI.
`order`	number	—	Signing order. Recipients with the same order sign in parallel.
`required`	boolean	—	If `true`, all fields assigned to this recipient must be completed before finalization.
`agents`	array	✅	The actual person(s) assigned to this role.

Recipient types

Type	Description
`signer`	Remotely signs the document via a signing link.
`in_person_signer`	Signs in person, hosted by a `host` recipient.
`host`	Facilitates an in-person signing session.
`delegator`	Can delegate their signing role to another person.
`viewer`	Receives a read-only copy after finalization.

Agent fields (agents[].info)

Field	Type	Description
`name`	string	Full name (required).
`email`	string	Email address. Used to send signing invitations.
`phone`	string	Phone number. Used for SMS/WhatsApp OTP.
`locale`	`en-US` \| `tr-TR`	Language for signing UI and notification emails.
`phoneContactMethod`	`sms` \| `whatsapp`	Channel for phone-based OTP delivery.

Response

{
  "success": true,
  "payload": {
    "recipient": {
      "id": "rcp_03kz...",
      "identifier": "counterparty",
      "type": "signer",
      "order": 0,
      "required": true,
      "agents": [...]
    }
  }
}

Save each recipient.id — it is required when assigning fields.

info

Repeat this request for each participant. For sequential signing, assign different order values. For parallel signing, use the same order value.

4. Add fields

Place interactive fields on the documents and assign each one to a recipient. All fields for the envelope can be submitted in a single request.

POST /api/v1/key/envelopes/{envelopeId}/fields
X-Inspakt-Api-Key: <your-api-key>
Content-Type: application/json

{
  "fields": [
    {
      "type": "simple_signature",
      "recipientId": "rcp_03kz...",
      "identifier": "counterparty_signature",
      "label": "Signature",
      "required": true,
      "config": {},
      "views": [
        {
          "documentId": "doc_02jy...",
          "page": 2,
          "location": { "x": 320, "y": 640 },
          "size": { "width": 200, "height": 60 }
        }
      ]
    },
    {
      "type": "text",
      "recipientId": "rcp_03kz...",
      "identifier": "counterparty_name",
      "label": "Full Name",
      "required": true,
      "config": {},
      "views": [
        {
          "documentId": "doc_02jy...",
          "page": 1,
          "location": { "x": 100, "y": 200 },
          "size": { "width": 240, "height": 32 }
        }
      ]
    }
  ]
}

Field types

Type	Description
`simple_signature`	Drawn or typed signature.
`biometric_signature`	Signature with biometric data capture.
`text`	Free-form text input.
`checkbox`	Single boolean checkbox.
`radio`	One selection from a group.
`binary_choice`	Accept / Decline choice.

Field placement (views[])

Field	Type	Required	Description
`documentId`	string	✅	ID of the document where the field is placed.
`page`	number	✅	Zero-based page index within the document.
`location.x`	number	✅	Horizontal position in points from the left edge.
`location.y`	number	✅	Vertical position in points from the top edge.
`size.width`	number	✅	Field width in points.
`size.height`	number	✅	Field height in points.

tip

A field can appear on multiple pages by including more than one entry in its views array. This is useful for initials that need to appear on every page.

5. Send the envelope

Once documents, recipients, and fields are in place, send the envelope. This transitions its status from draft to sent and dispatches signing notifications to all recipients.

PUT /api/v1/key/envelopes/{envelopeId}/send
X-Inspakt-Api-Key: <your-api-key>

Response

{
  "success": true,
  "payload": {
    "completed": true
  }
}

Recipients will immediately receive signing invitations via email and/or SMS according to their agent configuration.

caution

Once sent, the documents, recipients, and field assignments can no longer be modified. To cancel a sent envelope, use the void endpoint.

Complete example

# 1 — Create envelope
curl -X POST https://next.inspakt.com/api/v1/key/envelopes \
  -H "X-Inspakt-Api-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Service Agreement — Acme Corp", "expirationPeriodDays": 14}'

# 2 — Upload document (replace with your PDF path)
curl -X POST https://next.inspakt.com/api/v1/key/envelopes/env_01hx.../documents \
  -H "X-Inspakt-Api-Key: <key>" \
  -F "document=@/path/to/agreement.pdf" \
  -F "name=Service Agreement.pdf"

# 3 — Add recipient
curl -X POST https://next.inspakt.com/api/v1/key/envelopes/env_01hx.../recipients \
  -H "X-Inspakt-Api-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "type": "signer",
      "identifier": "counterparty",
      "required": true,
      "agents": [{"info": {"name": "Jane Smith", "email": "[email protected]", "locale": "en-US"}}]
    }
  }'

# 4 — Add signature field
curl -X POST https://next.inspakt.com/api/v1/key/envelopes/env_01hx.../fields \
  -H "X-Inspakt-Api-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [{
      "type": "simple_signature",
      "recipientId": "rcp_03kz...",
      "identifier": "signature",
      "label": "Signature",
      "required": true,
      "config": {},
      "views": [{"documentId": "doc_02jy...", "page": 2, "location": {"x": 320, "y": 640}, "size": {"width": 200, "height": 60}}]
    }]
  }'

# 5 — Send
curl -X PUT https://next.inspakt.com/api/v1/key/envelopes/env_01hx.../send \
  -H "X-Inspakt-Api-Key: <key>"

Overview​

1. Create an envelope​

2. Upload documents​

3. Add recipients​

4. Add fields​

5. Send the envelope​

Complete example​

Overview

1. Create an envelope

2. Upload documents

3. Add recipients

4. Add fields

5. Send the envelope

Complete example