Start from a template

Use this approach when the document layout and field positions are consistent across signings. Templates eliminate repetitive setup — documents, fields, and recipient roles are defined once and reused for every send.

When to use this: NDAs, standard service agreements, onboarding packets, or any workflow where the document structure is fixed and only the recipient details change.

Prerequisites

A template must be configured before you can use this guide. The template should have:

At least one document uploaded
All signing fields placed and assigned to recipient roles
All recipient roles defined (with identifiers)

Templates can be created and configured either through the Inspakt customer panel or via the Templates API.

tip

Use the Get Envelope endpoint on a previously sent envelope to inspect its recipient identifiers before building your jumpstart payload.

Overview

The template workflow requires only three steps:

Jumpstart an envelope from the template
Send the envelope

The jumpstart request creates a ready-to-send envelope with all documents and fields already in place. You only need to supply the recipient details.

1. Jumpstart an envelope

Create a new envelope from an existing template in a single request. Provide the actual persons for each recipient role defined in the template.

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

{
  "name": "NDA — Acme Corp Q2",
  "recipients": [
    {
      "identifier": "counterparty",
      "agents": [
        {
          "info": {
            "name": "Jane Smith",
            "email": "[email protected]",
            "locale": "en-US"
          }
        }
      ]
    }
  ]
}

Request body

Field	Type	Required	Description
`name`	string	—	Display name for this envelope (2–48 characters). Defaults to the template name.
`recipients`	array	✅	Assignments for each recipient role defined in the template.

Recipient assignment (recipients[])

Field	Type	Required	Description
`identifier`	string	—	The `identifier` of the recipient role as defined in the template. Must match exactly.
`id`	string	—	Alternative to `identifier` — use the recipient's UUID from the template.
`agents`	array	✅	The actual person(s) assigned to this role for this envelope.

Agent fields (agents[].info)

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

info

You must provide an entry in recipients for every role defined in the template. Roles not listed will not have agents assigned and may prevent sending.

Response

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

The returned envelope is in draft status with all template documents and fields already applied.

Possible errors

Name	Cause
`Template.NotFound`	The `templateId` does not exist or does not belong to your team.

2. Send the envelope

Dispatch the envelope to all recipients. This transitions its status from draft to sent.

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

Response

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

Recipients receive signing invitations immediately via email and/or SMS based on their agent configuration.

caution

Once sent, the envelope cannot be modified. To cancel, use the void endpoint.

Assigning a contact or group to a recipient role

Instead of providing inline agent details, you can reference an existing contact or contact group:

{
  "recipients": [
    {
      "identifier": "counterparty",
      "agents": [
        {
          "contactId": "cnt_07ab..."
        }
      ]
    }
  ]
}

Field	Description
`contactId`	ID of a contact created via the Contacts API.
`groupId`	ID of a contact group. All group members are assigned as agents to the role.
`userId`	ID of an internal Inspakt team user.

Complete example

# 1 — Jumpstart from template
curl -X POST https://next.inspakt.com/api/v1/key/envelopes/jumpstart/tpl_05xy... \
  -H "X-Inspakt-Api-Key: <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NDA — Acme Corp Q2",
    "recipients": [
      {
        "identifier": "counterparty",
        "agents": [
          {
            "info": {
              "name": "Jane Smith",
              "email": "[email protected]",
              "locale": "en-US"
            }
          }
        ]
      }
    ]
  }'

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

Comparison: custom documents vs. template

	Custom documents	From template
Document source	Uploaded per envelope	Pre-configured in template
Field placement	Defined per envelope	Pre-configured in template
API calls to send	5 (create, upload, recipients, fields, send)	2 (jumpstart, send)
Best for	Variable documents	Consistent document layouts

Prerequisites​

Overview​

1. Jumpstart an envelope​

2. Send the envelope​

Assigning a contact or group to a recipient role​

Complete example​

Comparison: custom documents vs. template​