API reference
Signers
Search signer assignments and delegate a signer slot.
2 endpoints. Every path below is relative to the base URL.
Base URL
https://api-uat.softsages.com/corePOST/api/v1/inkfree/envelopes/{id}/signers/{email}/delegate
Delegate a signer slot
Requires the X-API-Key header
Reassigns one signer slot to a different person. The original signer identified by {email} is replaced by the signer described in the request body, who receives a fresh signing invitation. Emits a signer.delegated event.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Required | Envelope id, a 36-character UUID.Example: env_xyz789 |
email | path | string (email) | Required | Email address of the current signer whose slot is being delegated.Example: priya.sharma@example.com |
Request body application/json · required
Schema: DocumentSigner
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Optional | Signer's display name. |
email | string (email) | Optional | Signer's email address, where the invitation is sent. |
sign | string | Optional | Signature state or captured signature reference. |
initials | string | Optional | Captured initials reference. |
group | string | Optional | Signer group, when signers are batched into rounds. |
requestRole | string | Optional | Role this signer plays, e.g. Signer, Approver, CC. |
companyName | string | Optional | Signer's company, when collected. |
title | string | Optional | Signer's job title, when collected. |
privateMessage | string | Optional | Message shown only to this signer. |
delegated | boolean | Optional | True once this slot has been delegated away.default: false |
delegatedTo | string | Optional | Email of the person this slot was delegated to. |
delegatedFrom | string | Optional | Email of the person who delegated this slot. |
id | integer | Optional | The signer's slot number. Fields refer to a signer by this number (signerIndex). Give every signer a different id when the envelope has more than one signer. Inkfree renumbers ids to the signer's position in the list (0, 1, 2, ...) and updates the signerIndex of your fields to match. |
cc | boolean | Optional | True for a recipient who only gets a copy and does not sign. A CC recipient cannot be an EMBEDDED signer.default: false |
deliveryMode | string | Optional | How this signer reaches the signing page. EMAIL (default): Inkfree emails an invitation. IN_PERSON: the sender hands the device to the signer. EMBEDDED: your own app shows the signing page in an iframe, so Inkfree sends no email or SMS to this signer. For EMBEDDED the signer needs a valid email, must be a signer (not CC), and cannot be sent a link by SMS; an access code or a one-time code is allowed and is asked inside the iframe. An approver under approval.reviewers may also be EMBEDDED (it then needs a valid email). A request that breaks these rules is refused with HTTP 406. See the Embedded signing guide in the docs.EMAILIN_PERSONEMBEDDEDdefault: "EMAIL" |
status | string | Optional | Where this signer is: Pending, Signed, Declined, Delegated or Delay (a signing delay has not elapsed). For an approver under approval.reviewers: Pending, Approved, Rejected or Skipped.read-only |
url | string | Optional | This signer's Inkfree signing link (for an approver, their approval link). Not returned for EMBEDDED signers or approvers: they sign or approve only through a signing token minted by your server.read-only |
phone | object | Optional | The signer's mobile number, needed for delivery by text or a one-time code by text: countryCode and number. |
└countryCode | string | Optional | |
└number | string | Optional | |
deliveryChannels | string[] | Optional | How an EMAIL signer is invited: email, text (SMS), or both. Text delivery needs phone and the sender's SMS consent attestation. |
order | integer | Optional | The signer's level when signerOrderRequired is true; signers on the same level are invited together. |
delayDays | integer | Optional | Signing delay before this signer is invited, in days, once their level is reached. |
delayHours | integer | Optional | Signing delay before this signer is invited, in hours. |
formUrl | string | Optional | Read-only URL of the web form attached to this signer, when the envelope was created from a template with a web form. Not the signing link; see url.read-only |
Example body
{
"name": "Sam Okafor",
"email": "sam.okafor@example.com",
"privateMessage": "Priya is out this week, so please sign in her place."
}Responses
200
Signer delegated.
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": "Signer delegated successfully."
}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/env_xyz789/signers/priya.sharma%40example.com/delegate" \
-H "X-API-Key: sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Sam Okafor",
"email": "sam.okafor@example.com",
"privateMessage": "Priya is out this week, so please sign in her place."
}'GET/api/v1/inkfree/signers
Find signer assignments by email
Requires the X-API-Key header
Returns every signer assignment matching an email address across the tenant's envelopes (pending and completed alike), newest first, capped at 100 items.
Keys in each row are the SQL column labels, in upper case. SIGNER holds the full signer object from the envelope; the remaining keys describe the envelope it belongs to.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
email | query | string (email) | Required | Signer email address to search for. Required.Example: priya.sharma@example.com |
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 signer assignments.
Returns SignerAssignmentRow[]
| Field | Type | Required | Description |
|---|---|---|---|
SIGNER | DocumentSigner | Optional | |
ENVELOPE_ID | string | Optional | Id of the envelope this assignment belongs to, a UUID. |
ENVELOPE_SUBJECT | string | Optional | Subject line of that envelope. |
ENVELOPE_STATUS | string | Optional | Status of that envelope. |
ENVELOPE_UPDATED_ON | string | Optional | When the envelope last changed. Also the sort key; results are newest-first. |
ENVELOPE_CREATED_ON | string | Optional | When the envelope was created. |
200 response
[
{
"SIGNER": {
"name": "Priya Sharma",
"email": "priya.sharma@example.com",
"sign": "signed"
},
"ENVELOPE_ID": "env_xyz789",
"ENVELOPE_SUBJECT": "NDA for review",
"ENVELOPE_STATUS": "Signed",
"ENVELOPE_UPDATED_ON": "2026-01-15T10:30:00",
"ENVELOPE_CREATED_ON": "2026-01-14T09:00:00"
}
]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 "https://api-uat.softsages.com/core/api/v1/inkfree/signers?email=priya.sharma%40example.com" \
-H "X-API-Key: sk_live_YOUR_API_KEY"