The EasyInk Public API allows integration with the e-signature platform to manage signing sessions, participants, documents, and complete signing workflows.
All API requests require authentication using JWT Bearer tokens.
Including the token in requests:
Authorization: Bearer {your-jwt-token}
How to obtain a token:
The API uses the Authorization Code Flow (OAuth 2.0) for authentication. This is a three-step process that involves redirecting the user to the Identity Provider and then exchanging an authorization code for an access token.
Step 1: Get Client Secret Contact your EasyInk administrator to get the client ID and client secret.
Step 2: Get Authorization Code Redirect the user to the authorize endpoint in a browser:
https://identity.easyink.io/connect/authorizehttps://identity-staging.easyink.io/connect/authorizeCallback URL:
https://easyink.iohttps://staging.easyink.ioQuery Parameters:
response_type: codeclient_id: {client-id}scope: openid hermes_api hermes_idp profileredirect_uri: {prod-or-staging-callback-url}code_challenge: {random-pkce-challenge}code_challenge_method: S256Step 3: Exchange Code for Token
After successful login, the user is redirected to your redirect_uri with a code parameter. Exchange this code for a token:
POST https://identity.easyink.io/connect/tokenPOST https://identity-staging.easyink.io/connect/tokenRequest Body (URL-encoded):
grant_type: authorization_codeclient_id: {client-id}client_secret: {client-secret}code: {received-code}redirect_uri: {prod-or-staging-callback-url}code_verifier: {pkce-verifier-that-was-used-for-generating-pkce-challenge}Using Postman:
OAuth 2.0.Authorization Code (With PKCE)https://easyink.io https://identity.easyink.io/connect/authorizehttps://identity.easyink.io/connect/token{client-id}{client-secret}S256openid hermes_api hermes_idp profileToken properties:
exp claim)All error responses follow a consistent format using the ApiError model. Errors include:
Common error codes:
ValidationError - Invalid request dataNotFound - Resource does not existUnauthorized - Missing or invalid authenticationForbidden - Insufficient permissionsInternalServerError - Server-side errorCreates a new empty signing session draft that can be configured before sending to participants.
Typical workflow after creation:
What you get:
Basic information for creating the draft
object or null Information about the user creating the draft and their preferences. If not provided, defaults to the authenticated user's settings. | |
| subject | string or null <= 500 characters Subject/title of the signing session shown to participants in emails and the signing interface. Should clearly identify the purpose of the signing (e.g., "Employment Contract - John Smith"). |
{- "subject": "Employment Agreement - John Smith"
}"3fa85f64-5717-4562-b3fc-2c963f66afa6"Uploads a document file and adds it as a document for signing to the session draft.
Supported formats:
What happens:
File requirements:
After upload:
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session draft |
Document file to upload as multipart form data
| fileContent required | string <binary> Binary content of the PDF or Word document |
"7c9e6679-7425-40de-944b-e07fc1f90ae7"Adds a new signer participant to a signing session draft.
Prerequisites:
What happens:
Note: This is for regular signing sessions. For bulk sessions, use the bulk participants endpoint.
| id required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session draft |
Participant information including name, contact details, and delivery preferences
| deliveryMethods | Array of strings or null non-empty Enum: "Email" "Sms" Methods for delivering the signing link to the participant:
Multiple methods can be specified for better delivery reliability. |
string or null <email> <= 256 characters Email address for sending signing invitations. Required if Email is included in deliveryMethods. | |
| firstName | string or null [ 1 .. 100 ] characters Participant's first (given) name |
| language | string Default: "English" Enum: "English" "Spanish" Preferred language for the participant's signing interface and notifications:
|
| lastName | string or null [ 1 .. 100 ] characters Participant's last (family) name |
| middleName | string or null <= 100 characters Participant's middle name or initial (optional) |
| phone | string or null^\d{10}$ Phone number for sending SMS notifications. Required if Sms is included in deliveryMethods. Must be a 10-digit phone number. |
{- "firstName": "John",
- "middleName": null,
- "lastName": "Smith",
- "email": "john.smith@example.com",
- "phone": null,
- "deliveryMethods": [
- "Email"
], - "language": "English"
}"9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"Adds a single signature field to a document in the signing session draft.
Prerequisites:
Typical workflow:
| id required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session draft |
Signature field configuration including type, position, and options
| documentId | string <uuid> ID of the document where the signature field will be placed |
object Declaration of the signature field to create, including type, position, and options. The server will assign a unique ID to the created field. | |
| participantId | string or null <uuid> ID of the participant who will fill this field. |
{- "participantId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
- "documentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
- "field": {
- "type": "Signature",
- "placement": {
- "page": 1,
- "positionX": 100,
- "positionY": 200,
- "sizeX": 200,
- "sizeY": 50
}, - "options": {
- "isRequired": true,
- "forType": "Signature"
}
}
}"1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"Downloads the complete document for signing in its original PDF format.
Use cases:
Response:
| documentId required | string <uuid> Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 Unique identifier of the document to download |
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session draft |
| Content-Disposition | string Example: "attachment; filename=\"Employment_Agreement.pdf\"" Suggested filename for download |
| Content-Length | integer Size of the PDF file in bytes |
{- "error": {
- "code": "ValidationError",
- "message": "Document processing is in progress. Try again later."
}
}Removes a document for signing from the signing session draft.
Important:
Use cases:
Cascade deletions:
| documentId required | string <uuid> Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 Unique identifier of the document to remove |
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session draft |
Downloads the complete attachment document in PDF format.
Use cases:
Response:
| attachmentId required | string <uuid> Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 Unique identifier of the attachment document |
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session draft |
| Content-Disposition | string Example: "attachment; filename=\"Employee_Handbook.pdf\"" Filename for download |
{- "error": {
- "code": "ValidationError",
- "message": "Document processing is in progress. Try again later."
}
}Removes an attachment document from the signing session draft.
Important:
Use cases:
| attachmentId required | string <uuid> Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 Unique identifier of the attachment to remove |
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session draft |
Adds the currently authenticated user as a participant to the signing session draft.
Convenience endpoint: This is a shortcut for adding yourself without providing all your details. User information is automatically retrieved from your profile:
Note: This method does not set any delivery methods by default. To specify delivery methods (e.g., Email, SMS), you must use the Update Participant endpoint after adding yourself.
When to use:
Automatic settings:
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session draft |
| deliveryMethods | Array of strings or null Enum: "Email" "Sms" Methods for delivering the signing link to the participant. Multiple methods can be specified for redundancy. |
string or null <email> <= 256 characters Email address for sending signing invitations and notifications | |
| firstName | string or null <= 100 characters Participant's first (given) name |
| id | string <uuid> Unique identifier of the participant in the signing session |
| initialsBlobId | string or null <uuid> Optional reference to a pre-saved initials image blob. If provided, these initials can be automatically applied to initial fields. |
| language | string Default: "English" Enum: "English" "Spanish" Preferred language for notifications and the signing interface |
| lastName | string or null <= 100 characters Participant's last (family) name |
| middleName | string or null <= 100 characters Participant's middle name or initial (optional) |
| phone | string or null^\d{10}$ Phone number for SMS notifications (10 digits) |
| role | string Enum: "Initiator" "Signer" Role of the participant in the signing session:
|
| signatureBlobId | string or null <uuid> Optional reference to a pre-saved signature image blob. If provided, this signature can be automatically applied to signature fields. |
| userId | string or null <uuid> Optional link to a registered user account in the system. If specified, pre-fills participant information from their profile. |
{- "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
- "firstName": "John",
- "middleName": "Robert",
- "lastName": "Smith",
- "email": "john.smith@example.com",
- "phone": "2025551234",
- "role": "Signer",
- "userId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "deliveryMethods": [
- "Email"
], - "language": "English",
- "signatureBlobId": null,
- "initialsBlobId": null
}Updates all information for an existing participant in the draft session.
What can be updated:
Important:
| participantId required | string <uuid> Example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d Unique identifier of the participant to update |
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session draft |
Complete updated participant information
| deliveryMethods | Array of strings or null non-empty Enum: "Email" "Sms" Updated delivery methods for sending signing invitations. Changing this will trigger a new invitation to be sent. |
string or null <email> <= 256 characters Updated email address for the participant. Required if Email is in deliveryMethods. | |
| firstName | string or null [ 1 .. 100 ] characters Updated first (given) name of the participant |
| language | string Default: "English" Enum: "English" "Spanish" Updated language preference for UI and notifications |
| lastName | string or null [ 1 .. 100 ] characters Updated last (family) name of the participant |
| middleName | string or null <= 100 characters Updated middle name or initial (optional) |
| phone | string or null^\d{10}$ Updated phone number for the participant. Required if Sms is in deliveryMethods. Must be a 10-digit phone number. |
{- "firstName": "John",
- "middleName": "Robert",
- "lastName": "Smith",
- "email": "john.smith@newcompany.com",
- "phone": null,
- "deliveryMethods": [
- "Email"
], - "language": "English"
}{- "error": {
- "code": "ValidationError",
- "message": "Participant Id is required"
}
}Removes a participant from the signing session draft.
Important:
Use cases:
Cascade deletions:
| participantId required | string <uuid> Example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d Unique identifier of the participant to remove |
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session draft |
{- "error": {
- "code": "ValidationError",
- "message": "Participant Id is required"
}
}Sets up a one-by-one (sequential) signing order for participants in the draft session.
Sequential Signing Workflow:
Use cases:
Requirements:
| id required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session draft |
Ordered array of participant IDs defining the signing sequence
| participantsOrder | Array of strings or null <uuid> non-empty [ items <uuid > ] Ordered array of participant IDs defining the signing sequence. The participant at index 0 signs first, index 1 signs second, etc. All participants in the session must be included in this array. Example workflow with 3 participants:
|
{- "participantsOrder": [
- "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
- "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
]
}{- "error": {
- "code": "ValidationError",
- "message": "There are some participants missed in signing order definition: 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d, 2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e"
}
}Configures the signing session for parallel (all-at-once) signing mode where all participants receive invitations simultaneously and can sign in any order.
Parallel Signing Behavior:
Use cases:
Comparison with Sequential:
This is the default mode - only use this endpoint if you previously set one-by-one order and want to switch back to parallel mode.
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session draft |
{- "error": {
- "code": "NotFound",
- "message": "Signing session draft does not exists"
}
}Removes a signature field from the signing session draft.
Important cascade behavior:
This operation automatically removes all dependent fields as well.
If other fields have dependsOn pointing to this field, they will also be deleted.
Example: If you delete a signature field that has a date field depending on it, both the signature field AND the date field are removed.
Response: Returns an array of all removed field IDs (the requested field plus any dependents).
Use cases:
Restrictions:
| signatureFieldId required | string <uuid> Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 Unique identifier of the signature field to remove |
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session draft |
[- "7c9e6679-7425-40de-944b-e07fc1f90ae7"
]Updates the configuration options for an existing signature field in the draft.
What can be updated:
Important:
Use cases:
| signatureFieldId required | string <uuid> Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 Unique identifier of the signature field to update |
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session draft |
Updated options (must match the field type)
| isRequired | boolean Default: false Whether the participant must fill this field to complete signing. Required fields prevent session completion until filled. |
{- "isRequired": false,
- "forType": "Signature"
}{- "error": {
- "code": "ValidationError",
- "message": "Field options must target the field type"
}
}Updates the position and size of a signature field on the document page.
Use cases:
Requirements:
Coordinate system reminder:
| signatureFieldId required | string <uuid> Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 Unique identifier of the signature field to reposition |
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session draft |
New position and size for the signature field
| page | integer <int32> >= 1 Page number where the element is placed (1-based index, first page is 1) |
| positionX | number <double> >= 0 Horizontal position of the element's bottom-left corner in points. Distance from the left edge of the page. |
| positionY | number <double> >= 0 Vertical position of the element's bottom-left corner in points. Distance from the bottom edge of the page (NOT from top). |
| sizeX | number <double> >= 0.1 Width of the rectangular area in points |
| sizeY | number <double> >= 0.1 Height of the rectangular area in points |
{- "page": 1,
- "positionX": 395,
- "positionY": 792,
- "sizeX": 200,
- "sizeY": 50
}{- "error": {
- "code": "ValidationError",
- "message": "Position on X-axis cannot be less than 0"
}
}Checks whether a signing session draft exists without retrieving its full details.
Performance benefit: Returns only HTTP status code without response body, making it faster and more lightweight than GET for existence checks.
Use cases:
Response codes:
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the draft session to check |
{- "error": {
- "code": "ValidationError",
- "message": "Validation failed for one or more fields",
- "innerErrors": [
- {
- "code": "RequiredField",
- "message": "The 'email' field is required"
}
]
}
}Retrieves complete details of a signing session draft including all documents, participants, signature fields, and configuration.
Returned information:
Use cases:
Before starting the session: Use this endpoint to verify the draft is complete and ready.
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session draft |
Array of objects or null (SigningConfigurationAttachment) Reference/supporting documents that participants can view but not sign | |
Array of objects or null (BulkParticipant) Participants for bulk signing sessions (only used if isBulkSession = true) | |
Array of objects or null (SigningConfigurationDocument) Primary documents that participants will sign | |
| initiatorUserId | string <uuid> ID of the user who created this draft |
| isBulkSession | boolean Whether this is a bulk signing session where multiple participants sign identical documents. When true, use bulkParticipants array; when false, use participants array. |
| isLocked | boolean Whether the draft is locked from modifications. |
| isSessionCopyDisabled | boolean Whether creating copies/duplicates of this session is disabled (organization policy setting) |
| isValidBulkParticipant | boolean or null Validation status for bulk participants (only relevant when isBulkSession = true). Null if not a bulk session or not yet validated. |
| isVoidDisabled | boolean Whether the void operation is disabled for this session (organization policy setting) |
| organizationId | string <uuid> Organization to which this signing session belongs |
Array of objects or null (PageLabel) Auto-generated labels showing metadata like session IDs or timestamps on signed documents | |
Array of objects or null (SigningConfigurationParticipant) Participants for regular signing sessions (ignored if isBulkSession = true) | |
| reminderFrequency | string or null Enum: "Never" "Daily" "Weekly" How often to send reminder notifications to participants who haven't signed:
|
| settingsSetId | string <uuid> Reference to the settings template applied to this session (branding, policies, etc.) |
Array of objects or null (SignatureField) Interactive fields where participants provide signatures, dates, initials, etc. | |
object Configuration for the order in which participants receive and complete signing | |
| signingSessionId | string <uuid> Unique identifier of the signing session draft |
| subject | string or null <= 500 characters Subject/title of the signing session shown to participants in notifications and UI |
| timestampFormat | string Default: "Usa" Enum: "Usa" "Spanish" Format for displaying dates and times in the session |
{- "signingSessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
- "organizationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
- "settingsSetId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
- "initiatorUserId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "timestampFormat": "Usa",
- "isBulkSession": false,
- "isLocked": false,
- "isVoidDisabled": false,
- "isSessionCopyDisabled": false,
- "isValidBulkParticipant": null,
- "subject": "Employment Agreement - John Smith",
- "documents": [
- {
- "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
- "title": "Employment Contract",
- "blobId": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
- "status": "ProcessingReady",
- "pages": [ ]
}
], - "attachments": [ ],
- "participants": [
- {
- "id": "4d5e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
- "firstName": "John",
- "lastName": "Smith",
- "email": "john.smith@example.com",
- "role": "Signer",
- "language": "English"
}
], - "bulkParticipants": null,
- "signatureFields": [ ],
- "pageLabels": [ ],
- "reminderFrequency": "Daily",
- "signingOrderSettings": {
- "type": "AllAtOnce",
- "participantsOrder": null
}
}Updates basic parameters of a signing session draft including subject and reminder settings.
What can be updated:
What cannot be updated via this endpoint:
Use cases:
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session draft |
Updated session parameters
| reminderFrequency | string or null Enum: "Never" "Daily" "Weekly" Frequency for sending automatic reminder notifications to participants who haven't signed:
Reminders are only sent during active signing sessions, not for drafts. |
| subject | string or null <= 500 characters Updated subject/title of the signing session. This appears in email notifications and the signing interface header. |
{- "subject": "Employment Agreement - John Smith (Updated)",
- "reminderFrequency": "Daily"
}{- "error": {
- "code": "ValidationError",
- "message": "Subject cannot exceed 500 characters"
}
}Creates a new draft by duplicating an existing signing session without voiding the original.
Use cases:
What is copied:
What is NOT copied:
After duplication:
Original session: Remains unchanged and can be in any status except Voided or Expired.
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the session to duplicate |
Optional custom subject for the new draft
| subject | string or null <= 500 characters Optional custom subject/title for the duplicated signing session |
{- "subject": "Q1 2025 Review Agreement"
}"7c9e6679-7425-40de-944b-e07fc1f90ae7"Permanently deletes a signing session draft and all associated data.
What is deleted:
Important:
Use cases:
To cancel a started session: Use the void operation instead of delete.
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the draft session to delete |
{- "error": {
- "code": "ValidationError",
- "message": "Signing session draft is locked and cannot be removed"
}
}Creates a new draft by copying an existing signing session, then voids the original session.
Atomic operation:
Use cases:
What is copied:
What is NOT copied:
Requirements:
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the session to recreate and void |
Optional new subject and mandatory void reason
| subject | string or null <= 500 characters Optional custom subject/title for the recreated signing session |
| voidReason | string or null [ 1 .. 1000 ] characters Reason for voiding the original signing session (required when recreating) |
{- "subject": "Employment Agreement - Corrected Version",
- "voidReason": "Original document contained incorrect salary information"
}"7c9e6679-7425-40de-944b-e07fc1f90ae7"Lightweight check for signing session existence without retrieving full details.
Performance benefit:
Use cases:
Response interpretation:
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session |
{- "error": {
- "code": "ValidationError",
- "message": "Validation failed for one or more fields",
- "innerErrors": [
- {
- "code": "RequiredField",
- "message": "The 'email' field is required"
}
]
}
}Retrieves complete details of an active or completed signing session including all documents, participants, status, and signed document availability.
Returned information:
Use cases:
Performance note: This endpoint returns complete session data. For lightweight existence checks, use the HEAD operation instead.
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session |
object Combined document merging all participants' signatures into one file. Only available after the session is finished. | |
Array of objects or null (SigningViewAttachment) Reference/supporting documents attached to the session | |
| bulkSessionId | string or null <uuid> ID of the parent bulk session if this is a child session in a bulk signing workflow. Null for regular (non-bulk) signing sessions. |
| canBeCopied | boolean Whether the current user has permission to duplicate/copy this session |
| canBeVoided | boolean Whether the current user has permission to void (cancel) this session |
Array of objects or null (SigningViewDocument) Primary documents that participants sign | |
Array of objects or null (SigningViewParticipant) All participants in the session with their current signing status | |
Array of objects or null (SignedDocument) Individual signed document copies generated for each participant after they complete signing. Each participant gets their own copy with their signatures applied. | |
| signingSessionId | string <uuid> Unique identifier of the signing session |
| status | string Enum: "Draft" "ReadyToStart" "Pending" "InProgress" "Finished" "Declined" "Voided" "Expired" Current status of the signing session lifecycle:
|
| subject | string or null Subject/title of the signing session |
{- "signingSessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
- "bulkSessionId": null,
- "subject": "Employment Agreement - December 2024",
- "canBeVoided": true,
- "canBeCopied": true,
- "status": "Finished",
- "documents": [
- {
- "documentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
- "title": "Employment Contract.pdf"
}
], - "participants": [
- {
- "participantId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
- "firstName": "John",
- "lastName": "Smith",
- "email": "john.smith@example.com",
- "role": "Signer",
- "status": "Signed",
- "signedAt": "2024-12-17T14:30:00Z"
}
], - "signedDocuments": [
- {
- "signedDocumentId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
- "title": "Employment Contract - John Smith (Signed).pdf",
- "processingStatus": "Ready"
}
], - "attachments": [ ],
- "allInOneDocument": {
- "title": "Employment Agreement - All Signatures.pdf",
- "status": "Ready"
}
}Converts a draft signing session to ReadyToStart status, making it ready to send to participants.
What this operation does:
Prerequisites:
After conversion:
Typical flow:
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the draft session to convert |
{- "error": {
- "code": "ValidationError",
- "message": "Session configuration is invalid. Check that all documents, participants, and fields are configured."
}
}Initiates the signing session by sending invitations to participants. This transitions the session from ReadyToStart to InProgress/Pending status.
Prerequisites - session must have:
What happens:
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session to start |
{- "error": {
- "code": "ValidationError",
- "message": "Session must have at least one document before starting"
}
}Updates delivery methods and contact information for a participant in an active signing session.
When to use:
Important restrictions:
What happens:
| participantId required | string <uuid> Example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d Unique identifier of the participant to update |
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session |
Updated delivery methods and contact information
| deliveryMethods | Array of strings or null Enum: "Email" "Sms" Methods to use for delivering the signing link to the participant. Available methods:
Multiple methods can be specified for redundancy. |
string or null <email> <= 256 characters Email address for the participant. Required if Email is included in deliveryMethods. Must be a valid email format. | |
| phone | string or null^\d{10}$ Phone number for the participant. Required if Sms is included in deliveryMethods. Must be a 10-digit phone number. |
{- "deliveryMethods": [
- "Email"
], - "email": "participant@newcompany.com",
- "phone": null
}{- "error": {
- "code": "ValidationError",
- "message": "Delivery method can't be changed because the participant has already used the signing link"
}
}Downloads an attachment document from an active or completed signing session.
Attachments vs Documents:
Use cases:
Availability: Available in all session statuses except Draft.
| attachmentId required | string <uuid> Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 Unique identifier of the attachment to download |
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session |
| Content-Disposition | string Example: "attachment; filename=\"Company_Policy_Handbook.pdf\"" Suggested filename for download |
| Content-Type | string Example: "application/pdf" |
{- "error": {
- "code": "ValidationError",
- "message": "Attachment '7c9e6679-7425-40de-944b-e07fc1f90ae7' not found"
}
}Downloads the original document for signing from a signing session in PDF format.
Important: This returns the ORIGINAL document without any signatures applied. For signed documents with signatures, use the signed documents endpoint.
Use cases:
Document state:
For signed versions:
| documentId required | string <uuid> Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 Unique identifier of the document to download |
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session |
| Content-Disposition | string Example: "attachment; filename=\"Employment_Agreement_Original.pdf\"" Suggested filename |
| Content-Type | string Example: "application/pdf" |
{- "error": {
- "code": "ValidationError",
- "message": "Document '7c9e6679-7425-40de-944b-e07fc1f90ae7' not found"
}
}Voids (cancels/annuls) an active signing session, preventing any further actions.
What happens:
When to use:
Alternative: Consider using "Recreate" instead if you need a corrected version.
| id required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session to void |
Void reason
| reason | string or null [ 1 .. 1000 ] characters Reason for voiding the signing session. This will be visible to all participants and stored in the audit trail. |
{- "reason": "Document contained incorrect information"
}{- "error": {
- "code": "ValidationError",
- "message": "Voiding reason is required"
}
}Search and filter signing sessions with pagination and sorting support.
Returns a paginated list of signing sessions matching the specified criteria. Results can be filtered by status and sorted by multiple properties.
Use cases:
| pageIndex | integer >= 0 Default: 0 Zero-based page index for pagination (0 = first page) |
| pageSize | integer [ 1 .. 100 ] Default: 20 Example: pageSize=20 Number of items to return per page (max 100) |
Array of objects (PropertySorting) Example: sorting.properties=[object Object]&sorting.properties=[object Object] Array of sorting rules applied in order of priority. Example: To sort by status ascending, then by creation date descending:
| |
| statuses | Array of strings Items Enum: "Draft" "ReadyToStart" "InProgress" "NeedToSign" "Finished" "Declined" "Voided" "Expired" "NeedsAction" Example: statuses=InProgress&statuses=NeedToSign Filter signing sessions by status. Multiple statuses can be specified. Status values:
|
Array of objects or null (SigningSessionItem) Array of signing session items matching the search criteria. Empty array if no sessions match the filters. | |
| pageIndex | integer <int32> >= 0 Current page index (0-based, matches the request parameter) |
| pagesCount | integer <int32> >= 0 Total number of pages available based on pageSize and totalItemsCount |
| pageSize | integer <int32> >= 1 Number of items per page (matches the request parameter) |
| totalItemsCount | integer <int32> >= 0 Total number of sessions matching the search criteria across all pages |
{- "items": [
- {
- "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
- "isBulk": false,
- "subject": "Employment Agreement",
- "created": "2024-12-17T10:00:00Z",
- "status": "InProgress",
- "currentUserNeedToSign": false,
- "hasNotificationErrors": false,
- "canBeDeleted": true
}, - {
- "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
- "isBulk": false,
- "subject": "NDA Agreement",
- "created": "2024-12-16T15:30:00Z",
- "status": "Finished",
- "currentUserNeedToSign": false,
- "hasNotificationErrors": false,
- "canBeDeleted": true
}
], - "totalItemsCount": 47,
- "pagesCount": 3,
- "pageIndex": 0,
- "pageSize": 20
}Retrieves summary statistics about signing sessions grouped by status for the current user.
Returned statistics:
Use cases:
Scope: Only includes sessions visible to the authenticated user based on:
| draftsCount | integer <int32> >= 0 Number of sessions in Draft status (being configured, not yet sent). Only includes drafts created by or visible to the current user. |
| inProgressCount | integer <int32> >= 0 Number of sessions in InProgress status (sent to participants, awaiting signatures). Includes sessions where at least one participant has started but not all have finished. |
| needsActionCount | integer <int32> >= 0 Number of sessions requiring immediate user attention. May include sessions with errors, declined sessions, or sessions awaiting approval. |
| readyToStartCount | integer <int32> >= 0 Number of sessions in ReadyToStart status (configured and ready to send to participants). Requires manual action to initiate sending. |
| sessionsToSignCount | integer <int32> >= 0 Number of sessions where the current user is a participant and needs to sign. Includes sessions in any status where user action is pending. |
{- "sessionsToSignCount": 3,
- "draftsCount": 5,
- "readyToStartCount": 2,
- "inProgressCount": 12,
- "needsActionCount": 1
}Downloads a completed signed document with signatures applied for a specific participant.
What's included:
Availability:
Use cases:
| documentId required | string <uuid> Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 Unique identifier of the signed document |
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the signing session |
| Content-Disposition | string Example: "attachment; filename=\"Employment_Agreement_John_Smith_Signed.pdf\"" Suggested filename including participant name |
| Content-Type | string Example: "application/pdf" |
{- "error": {
- "code": "ValidationError",
- "message": "Signed document is not available until participant completes signing"
}
}Downloads a combined PDF containing all signed documents from all participants with complete audit trail information.
Document contents (in order):
Availability:
Use cases:
File characteristics:
| signingSessionId required | string <uuid> Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unique identifier of the completed signing session |
| Content-Disposition | string Example: "attachment; filename=\"Employment_Agreement_All_Signatures.pdf\"" Filename for the combined document |
| Content-Type | string Example: "application/pdf" |
| Content-Length | integer File size in bytes |
{- "error": {
- "code": "ValidationError",
- "message": "All-in-one document compilation failed."
}
}