API reference

Envelopes

Create, read, void, resend, and download signature envelopes.

8 endpoints. Every path below is relative to the base URL.

On this page

List envelope events
Create and send an envelope
Create and send an envelope from a template
Get an envelope
Void an envelope
Get an envelope's audit trail
Download the signed PDF
Resend to pending signers

Base URL

https://api-uat.softsages.com/core

GET`/api/v1/inkfree/envelopes`

List envelope events

Requires the X-API-Key header

Returns an event-shaped feed of envelopes, newest first, capped at 100 items.

Each item wraps the envelope in an event envelope carrying a stable id derived as sha1(envelope_id:event_type:event_time), so the same state change produces the same id whether it arrives here or over a webhook. That makes the value safe to use for cross-channel deduplication.

event_type is derived from the envelope's current status: Voided maps to envelope.voided, Signed maps to envelope.completed, and anything else maps to envelope.sent.

Parameters

Name	In	Type	Required	Description
`status`	query	string	Optional	Filter by envelope status, e.g. `Signed`, `Voided`, `Sent`.Example: Signed
`since`	query	string	Optional	Keyset cursor — ISO 8601 local date-time of the last item from the previous page. No `Z` suffix and no numeric offset; both are rejected with `400`.Example: 2026-01-15T10:30:00
`after`	query	string	Optional	Keyset cursor — envelope id of the last item from the previous page. Pair with `since`.Example: env_xyz789

Responses

200

Up to 100 envelope events, newest first.

Returns EnvelopeEvent[]

Field	Type	Required	Description
`id`	string	Optional	Stable event id — `sha1(envelope_id:event_type:event_time)`. Identical for the same state change whether delivered here or by webhook, so it is safe as a cross-channel deduplication key.
`event_type`	string	Optional	Derived from envelope status: `Voided` → `envelope.voided`, `Signed` → `envelope.completed`, otherwise `envelope.sent`.`envelope.sentenvelope.completedenvelope.voided`
`event_version`	integer	Optional	Schema version of the event wrapper.
`event_time`	string (date-time)	Optional	Envelope's update time, or creation time if never updated. Full ISO 8601 UTC offset date-time — unlike other timestamps in this API.
`envelope`	PdfSignRequest	Optional	—

200 response

[
  {
    "id": "9c1a4f2b8e6d3a5c7f0b2d4e6a8c1f3b5d7e9a0c",
    "event_type": "envelope.completed",
    "event_version": 1,
    "event_time": "2026-01-15T10:30:00Z",
    "envelope": {
      "id": "env_xyz789",
      "emailSubject": "NDA for review",
      "status": "Signed",
      "signers": [
        {
          "name": "Priya Sharma",
          "email": "priya.sharma@example.com"
        }
      ],
      "createdOn": "01/14/2026 09:00:00",
      "updatedOn": "01/15/2026 10:30:00"
    }
  }
]

400

since is not an ISO 8601 local date-time.

Returns Error

400 response

{
  "code": 400,
  "message": "since must be an ISO 8601 local date-time (e.g. 2024-01-15T10:30:00)"
}

401

The API key is missing, malformed, unknown, expired, revoked, or inactive.

Returns Error

401 response

{
  "code": 401,
  "message": "Invalid API key"
}

429

Per-key rate limit exceeded. Back off and retry.

Returns Error

429 response

{
  "code": 429,
  "message": "Rate limit exceeded. Try again later."
}

Example request

curl

curl "https://api-uat.softsages.com/core/api/v1/inkfree/envelopes" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

POST`/api/v1/inkfree/envelopes`

Create and send an envelope

Requires the X-API-Key header

Creates an envelope from documents and field placement supplied in the request body, and dispatches it to the signers.

The envelope is attributed to the creator user bound to the API key; any requestedBy in the body is ignored.

To send from an existing template instead — which is usually simpler, because the template already carries the documents and field positions — use POST /api/v1/inkfree/envelopes/from-template/{templateId}.

Parameters

Name	In	Type	Required	Description
`X-Idempotency-Key`	header	string	Optional	Client-generated key that makes creation safe to retry. Replaying the same key with an identical body returns the original response instead of creating a second envelope.Example: 0f6c1e5a-9b2d-4c7e-8a31-5f9d2b7c4e10

Request bodyapplication/json · required

Schema: PdfSignRequest

Field	Type	Required	Description
`id`	string	Optional	Envelope or template id. A 36-character UUID; `env_xyz789` here is a readability placeholder.
`emailSubject`	string	Optional	Subject line of the signing invitation.
`emailMessage`	string	Optional	Body of the signing invitation.
`signers`	DocumentSigner[]	Optional	Signers, in signing order when `signerOrderRequired` is true.
`files`	PdfFile[]	Optional	Documents in the envelope, with their field placement.
`status`	string	Optional	Current status, e.g. `Sent`, `Signed`, `Voided`.
`requestedBy`	DocumentSigner	Optional	—
`templateName`	string	Optional	Name of the template, when this object is a template.
`templateId`	string	Optional	Id of the template this envelope was created from, if any.
`currentSigners`	string[]	Optional	Emails of signers whose turn it currently is.
`signedBy`	string	Optional	Signers who have completed signing.
`signerOrderRequired`	boolean	Optional	When true, signers are invited sequentially rather than all at once.default: false
`selfSigned`	boolean	Optional	True when the sender is also the only signer.default: false
`expirationDays`	integer	Optional	Days until the envelope expires.
`scheduleTime`	string	Optional	Scheduled send time in `MM/dd/yyyy HH:mm:ss`, if the envelope is queued for later dispatch.
`createdOn`	string	Optional	Creation timestamp, formatted `MM/dd/yyyy HH:mm:ss` — not ISO 8601.
`updatedOn`	string	Optional	Last update timestamp, formatted `MM/dd/yyyy HH:mm:ss` — not ISO 8601. Reformat before using it as a `since` cursor.
`updatedBy`	string	Optional	Who last updated the envelope.
`auditId`	string	Optional	Identifier of the associated audit trail.

Example body

{
  "emailSubject": "NDA for review",
  "emailMessage": "Please sign at your earliest convenience.",
  "signers": [
    {
      "name": "Priya Sharma",
      "email": "priya.sharma@example.com"
    }
  ],
  "files": [
    {
      "unsignedPdf": "<base64-encoded PDF>",
      "pageCount": 3
    }
  ],
  "signerOrderRequired": false,
  "expirationDays": 30
}

Responses

200

Envelope created. message carries the new envelope id.

Returns ApiResponse

Field	Type	Required	Description
`code`	integer	Optional	HTTP status code, repeated in the body.
`message`	string	Optional	Created object id, or a confirmation message.

200 response

{
  "code": 200,
  "message": "env_xyz789"
}

400

The request was malformed or violated a validation rule.

Returns Error

400 response

{
  "code": 400,
  "message": "name is required"
}

401

The API key is missing, malformed, unknown, expired, revoked, or inactive.

Returns Error

401 response

{
  "code": 401,
  "message": "Invalid API key"
}

429

Per-key rate limit exceeded. Back off and retry.

Returns Error

429 response

{
  "code": 429,
  "message": "Rate limit exceeded. Try again later."
}

Example request

curl

curl -X POST "https://api-uat.softsages.com/core/api/v1/inkfree/envelopes" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "emailSubject": "NDA for review",
  "emailMessage": "Please sign at your earliest convenience.",
  "signers": [
    {
      "name": "Priya Sharma",
      "email": "priya.sharma@example.com"
    }
  ],
  "files": [
    {
      "unsignedPdf": "<base64-encoded PDF>",
      "pageCount": 3
    }
  ],
  "signerOrderRequired": false,
  "expirationDays": 30
}'

POST`/api/v1/inkfree/envelopes/from-template/{templateId}`

Create and send an envelope from a template

Requires the X-API-Key header

Creates and sends an envelope from an existing template. The template supplies the documents and the field placement; the request supplies only who fills each signer slot and the per-send email wording.

signerIndex matches the template signer's id, which is what each placed field binds to — so every field positioned for that slot follows the person named here. Read the template first with GET /api/v1/inkfree/templates/{id} to discover its signer slots.

Design-time settings — signing order, cc flags, field placement, reminders, approval configuration — come from the template and cannot be overridden per send.

Parameters

Name	In	Type	Required	Description
`templateId`	path	string	Required	Id of the template to send — a 36-character UUID.Example: tpl_abc123
`X-Idempotency-Key`	header	string	Optional	Client-generated key that makes creation safe to retry. Replaying the same key with an identical body returns the original response instead of creating a second envelope.Example: 0f6c1e5a-9b2d-4c7e-8a31-5f9d2b7c4e10

Request bodyapplication/json · required

Schema: EnvelopeFromTemplateRequest

Field	Type	Required	Description
`signers`	object[]	Required	Who fills each signer slot of the template.
`└signerIndex`	integer	Optional	Template signer slot to fill — matches the template signer's `id`. Every field placed for that slot follows the person named here.
`└name`	string	Optional	—
`└email`	string (email)	Optional	—
`emailSubject`	string	Optional	Overrides the template's invitation subject for this send.
`emailMessage`	string	Optional	Overrides the template's invitation body for this send.
`expirationDays`	integer	Optional	Days until this envelope expires.

Example body

{
  "signers": [
    {
      "signerIndex": 1,
      "name": "Priya Sharma",
      "email": "priya.sharma@example.com"
    },
    {
      "signerIndex": 2,
      "name": "Sam Okafor",
      "email": "sam.okafor@example.com"
    }
  ],
  "emailSubject": "Mutual NDA — Acme / Example",
  "emailMessage": "Countersigned copy follows once both parties sign.",
  "expirationDays": 14
}

Responses

200

Envelope created. message carries the new envelope id.

Returns ApiResponse

Field	Type	Required	Description
`code`	integer	Optional	HTTP status code, repeated in the body.
`message`	string	Optional	Created object id, or a confirmation message.

200 response

{
  "code": 200,
  "message": "env_xyz789"
}

400

The request was malformed or violated a validation rule.

Returns Error

400 response

{
  "code": 400,
  "message": "name is required"
}

401

The API key is missing, malformed, unknown, expired, revoked, or inactive.

Returns Error

401 response

{
  "code": 401,
  "message": "Invalid API key"
}

404

The envelope does not exist, or it belongs to another tenant. The two cases are deliberately indistinguishable.

Returns Error

404 response

{
  "code": 404,
  "message": "envelope not found"
}

429

Per-key rate limit exceeded. Back off and retry.

Returns Error

429 response

{
  "code": 429,
  "message": "Rate limit exceeded. Try again later."
}

Example request

curl

curl -X POST "https://api-uat.softsages.com/core/api/v1/inkfree/envelopes/from-template/tpl_abc123" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "signers": [
    {
      "signerIndex": 1,
      "name": "Priya Sharma",
      "email": "priya.sharma@example.com"
    },
    {
      "signerIndex": 2,
      "name": "Sam Okafor",
      "email": "sam.okafor@example.com"
    }
  ],
  "emailSubject": "Mutual NDA — Acme / Example",
  "emailMessage": "Countersigned copy follows once both parties sign.",
  "expirationDays": 14
}'

GET`/api/v1/inkfree/envelopes/{id}`

Get an envelope

Requires the X-API-Key header

Returns the full envelope, including signers and their current state.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Required	Envelope id — a 36-character UUID.Example: env_xyz789

Responses

200

The envelope.

Returns PdfSignRequest

Field	Type	Required	Description
`id`	string	Optional	Envelope or template id. A 36-character UUID; `env_xyz789` here is a readability placeholder.
`emailSubject`	string	Optional	Subject line of the signing invitation.
`emailMessage`	string	Optional	Body of the signing invitation.
`signers`	DocumentSigner[]	Optional	Signers, in signing order when `signerOrderRequired` is true.
`files`	PdfFile[]	Optional	Documents in the envelope, with their field placement.
`status`	string	Optional	Current status, e.g. `Sent`, `Signed`, `Voided`.
`requestedBy`	DocumentSigner	Optional	—
`templateName`	string	Optional	Name of the template, when this object is a template.
`templateId`	string	Optional	Id of the template this envelope was created from, if any.
`currentSigners`	string[]	Optional	Emails of signers whose turn it currently is.
`signedBy`	string	Optional	Signers who have completed signing.
`signerOrderRequired`	boolean	Optional	When true, signers are invited sequentially rather than all at once.default: false
`selfSigned`	boolean	Optional	True when the sender is also the only signer.default: false
`expirationDays`	integer	Optional	Days until the envelope expires.
`scheduleTime`	string	Optional	Scheduled send time in `MM/dd/yyyy HH:mm:ss`, if the envelope is queued for later dispatch.
`createdOn`	string	Optional	Creation timestamp, formatted `MM/dd/yyyy HH:mm:ss` — not ISO 8601.
`updatedOn`	string	Optional	Last update timestamp, formatted `MM/dd/yyyy HH:mm:ss` — not ISO 8601. Reformat before using it as a `since` cursor.
`updatedBy`	string	Optional	Who last updated the envelope.
`auditId`	string	Optional	Identifier of the associated audit trail.

401

The API key is missing, malformed, unknown, expired, revoked, or inactive.

Returns Error

401 response

{
  "code": 401,
  "message": "Invalid API key"
}

404

The envelope does not exist, or it belongs to another tenant. The two cases are deliberately indistinguishable.

Returns Error

404 response

{
  "code": 404,
  "message": "envelope not found"
}

429

Per-key rate limit exceeded. Back off and retry.

Returns Error

429 response

{
  "code": 429,
  "message": "Rate limit exceeded. Try again later."
}

Example request

curl

curl "https://api-uat.softsages.com/core/api/v1/inkfree/envelopes/env_xyz789" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

POST`/api/v1/inkfree/envelopes/{id}/void`

Void an envelope

Requires the X-API-Key header

Voids an in-flight envelope. Pending signers can no longer sign, and the envelope transitions to Voided, which in turn emits an envelope.voided event to any matching webhook subscription.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Required	Envelope id — a 36-character UUID.Example: env_xyz789

Responses

200

Envelope voided.

Returns ApiResponse

Field	Type	Required	Description
`code`	integer	Optional	HTTP status code, repeated in the body.
`message`	string	Optional	Created object id, or a confirmation message.

200 response

{
  "code": 200,
  "message": "Sign request voided successfully."
}

401

The API key is missing, malformed, unknown, expired, revoked, or inactive.

Returns Error

401 response

{
  "code": 401,
  "message": "Invalid API key"
}

404

The envelope does not exist, or it belongs to another tenant. The two cases are deliberately indistinguishable.

Returns Error

404 response

{
  "code": 404,
  "message": "envelope not found"
}

429

Per-key rate limit exceeded. Back off and retry.

Returns Error

429 response

{
  "code": 429,
  "message": "Rate limit exceeded. Try again later."
}

Example request

curl

curl -X POST "https://api-uat.softsages.com/core/api/v1/inkfree/envelopes/env_xyz789/void" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

GET`/api/v1/inkfree/envelopes/{id}/audit`

Get an envelope's audit trail

Requires the X-API-Key header

Returns the logged audit trail for an envelope — who opened, signed, declined, or delegated, when, and from which IP address.

The response is grouped two levels deep: the outer key identifies the signer or party, the inner key the event grouping, and the value is the list of audit entries.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Required	Envelope id — a 36-character UUID.Example: env_xyz789

Responses

200

Grouped audit entries.

Returns object

401

The API key is missing, malformed, unknown, expired, revoked, or inactive.

Returns Error

401 response

{
  "code": 401,
  "message": "Invalid API key"
}

404

The envelope does not exist, or it belongs to another tenant. The two cases are deliberately indistinguishable.

Returns Error

404 response

{
  "code": 404,
  "message": "envelope not found"
}

429

Per-key rate limit exceeded. Back off and retry.

Returns Error

429 response

{
  "code": 429,
  "message": "Rate limit exceeded. Try again later."
}

Example request

curl

curl "https://api-uat.softsages.com/core/api/v1/inkfree/envelopes/env_xyz789/audit" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

GET`/api/v1/inkfree/envelopes/{id}/document`

Download the signed PDF

Requires the X-API-Key header

Streams the signed PDF as a binary application/pdf response with Content-Disposition: attachment.

Only signed=true is supported in v1; passing signed=false returns 400.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Required	Envelope id — a 36-character UUID.Example: env_xyz789
`signed`	query	boolean	Optional	Must be `true`. Retrieving the unsigned original is not supported in v1.Example: true

Responses

200

The signed PDF.

Returns a binary application/pdf body.

Content-Disposition — attachment; filename="<envelope>-signed.pdf"

400

signed=false was requested.

Returns Error

400 response

{
  "code": 400,
  "message": "only signed=true is supported in v1"
}

401

The API key is missing, malformed, unknown, expired, revoked, or inactive.

Returns Error

401 response

{
  "code": 401,
  "message": "Invalid API key"
}

404

The envelope does not exist, or it belongs to another tenant. The two cases are deliberately indistinguishable.

Returns Error

404 response

{
  "code": 404,
  "message": "envelope not found"
}

429

Per-key rate limit exceeded. Back off and retry.

Returns Error

429 response

{
  "code": 429,
  "message": "Rate limit exceeded. Try again later."
}

Example request

curl

curl "https://api-uat.softsages.com/core/api/v1/inkfree/envelopes/env_xyz789/document" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -o envelope-signed.pdf

POST`/api/v1/inkfree/envelopes/{id}/resend`

Resend to pending signers

Requires the X-API-Key header

Re-sends the signing invitation to every signer who has not yet completed their part. Signers who already signed are not emailed again.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Required	Envelope id — a 36-character UUID.Example: env_xyz789

Responses

200

Invitation resent.

Returns ApiResponse

Field	Type	Required	Description
`code`	integer	Optional	HTTP status code, repeated in the body.
`message`	string	Optional	Created object id, or a confirmation message.

200 response

{
  "code": 200,
  "message": "Sign request resent successfully."
}

401

The API key is missing, malformed, unknown, expired, revoked, or inactive.

Returns Error

401 response

{
  "code": 401,
  "message": "Invalid API key"
}

404

The envelope does not exist, or it belongs to another tenant. The two cases are deliberately indistinguishable.

Returns Error

404 response

{
  "code": 404,
  "message": "envelope not found"
}

429

Per-key rate limit exceeded. Back off and retry.

Returns Error

429 response

{
  "code": 429,
  "message": "Rate limit exceeded. Try again later."
}

Example request

curl

curl -X POST "https://api-uat.softsages.com/core/api/v1/inkfree/envelopes/env_xyz789/resend" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

GET/api/v1/inkfree/envelopes

Parameters

Responses

Example request

POST/api/v1/inkfree/envelopes

Parameters

Request bodyapplication/json · required

Responses

Example request

POST/api/v1/inkfree/envelopes/from-template/{templateId}

Parameters

Request bodyapplication/json · required

Responses

Example request

GET/api/v1/inkfree/envelopes/{id}

Parameters

Responses

Example request

POST/api/v1/inkfree/envelopes/{id}/void

Parameters

Responses

Example request

GET/api/v1/inkfree/envelopes/{id}/audit

Parameters

Responses

Example request

GET/api/v1/inkfree/envelopes/{id}/document

Parameters

Responses

Example request

POST/api/v1/inkfree/envelopes/{id}/resend

Parameters

Responses

Example request

GET`/api/v1/inkfree/envelopes`

POST`/api/v1/inkfree/envelopes`

POST`/api/v1/inkfree/envelopes/from-template/{templateId}`

GET`/api/v1/inkfree/envelopes/{id}`

POST`/api/v1/inkfree/envelopes/{id}/void`

GET`/api/v1/inkfree/envelopes/{id}/audit`

GET`/api/v1/inkfree/envelopes/{id}/document`

POST`/api/v1/inkfree/envelopes/{id}/resend`