Signatories operations
Contents
Introduction
This section covers all operations related to managing signatories for a document in a signature request.
Taking the signature request back to draft changes every signatory identifier. The
draft operation
replaces each signatory with a new row and a new signatoryId, including those who had
already acted. Any identifier you stored before drafting stops resolving, so read them again
afterwards.
Operations
Get list of signatories
This endpoint retrieves a list of signatories associated with a specific document in a signature request.
HTTP Request
GET /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/signatories
Example Response
[
{
"id": "950fac7e-5284-42ad-8044-3f4632678324",
"name": "Signatory Name",
"surnames": "Signatory Surnames",
"email": "signatory@example.com",
"phone": "123456789",
"signatureStatus": "READY_TO_SIGN",
"coordinates": [
{
"x": 100.5,
"y": 200.75,
"page": 1
}
],
"sequence": 1,
"uniqueValidator": false,
"provider": "NOTICEMAN_AND_WHATSAPP",
"registeredAt": "2023-10-23T10:34:59.483Z"
}
]
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| signatureRequestId | Yes | string (UUID) | Unique identifier for the signature request. |
| documentId | Yes | string (UUID) | Unique identifier for the document. |
| ids | No | array of string (UUID) | Filter signatories by their IDs. |
| emails | No | array of string | Filter signatories by their email addresses. |
| hasCoordinates | No | boolean | Filter signatories by whether they have coordinates. |
| orderBy | No | string | Ordering of signatories. Only the sequence field is supported: sequence:asc or sequence:desc. Any other value returns 400 Bad request. |
| page | No | integer | Page number for pagination. |
| size | No | integer | Number of items per page. |
| sort | No | array of string | Sorting criteria in the format field:order. |
Get list of signatories in a signature request
This endpoint retrieves a list of signatories associated with a signature request across all documents. Each signatory in the response includes its effective notification provider.
HTTP Request
GET /api/v1/private/signature-requests/{signatureRequestId}/signatories
Example Response
[
{
"id": "950fac7e-5284-42ad-8044-3f4632678324",
"name": "Signatory Name",
"surnames": "Signatory Surnames",
"email": "signatory@example.com",
"phone": "123456789",
"documentId": "2b066f42-8e65-4c6f-8253-ad6ded8ae436",
"signatureStatus": "READY_TO_SIGN",
"coordinates": [
{
"x": 100.5,
"y": 200.75,
"page": 1
}
],
"sequence": 1,
"uniqueValidator": false,
"provider": "NOTICEMAN_AND_WHATSAPP",
"registeredAt": "2023-10-23T10:34:59.483Z"
}
]
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| signatureRequestId | Yes | string (UUID) | Unique identifier for the signature request. |
| ids | No | array of string (UUID) | Filter signatories by their IDs. |
| emails | No | array of string | Filter signatories by their email addresses. |
| documentId | No | string (UUID) | Filter signatories by document ID. |
| hasCoordinates | No | boolean | Filter signatories by whether they have coordinates. |
| page | No | integer | Page number for pagination. |
| size | No | integer | Number of items per page. |
| sort | No | array of string | Sorting criteria in the format field:order. |
Create signatory
This endpoint creates a signatory for a document in a signature request.
HTTP Request
POST /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/signatories
Example Request Body
{
"name": "Signatory Name",
"surnames": "Signatory Surnames",
"email": "signatory@example.com",
"phone": "123456789",
"sequence": 1,
"uniqueValidator": false,
"provider": "NOTICEMAN_AND_WHATSAPP",
"coordinates": [
{
"x": 100.5,
"y": 200.75,
"page": 1
}
]
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| signatureRequestId | Yes | string (UUID) | Unique identifier for the signature request. |
| documentId | Yes | string (UUID) | Unique identifier for the document. |
| name | Yes | string | Signatory name. |
| surnames | No | string | Signatory surnames. |
| Yes | string (email) | Signatory email address. | |
| phone | No | string | Signatory phone number. |
| sequence | No | integer | Sequence number for phased signing. |
| uniqueValidator | No | boolean | If true, a single validator approval is enough for this signatory. |
| provider | No | string | Notification provider for this signatory. Possible values: NOTICEMAN, NOTICEMAN_AND_WHATSAPP, NOTICEMAN_AND_WHATSAPP_AND_RCS, NOTICEMAN_AND_RCS. Overrides the signature request provider for this participant: when notifications are sent, the participant provider takes precedence over the signature request one. Providers other than NOTICEMAN require a phone number. The same recipient (same email, name, surnames and phone) must use the same provider across the whole signature request. |
| coordinates | No | array of objects | Signature coordinates. |
| coordinates[].x | Yes (if provided) | number | X coordinate for the signature. |
| coordinates[].y | Yes (if provided) | number | Y coordinate for the signature. |
| coordinates[].page | Yes (if provided) | integer | Page number for the signature. |
Example Response
201 Created, with the signatory that was created:
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Signatory Name",
"surnames": "Signatory Surnames",
"email": "signatory@example.com",
"phone": "123456789",
"documentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"signatureStatus": "PENDING",
"registeredAt": "2026-09-17T10:15:00Z",
"coordinates": []
}
Use this route when you need the signatory identifier. Adding signatories in bulk is
convenient, but it answers 204 with no body, so you do not get the ids back and
have to read the signatories again to find them. Creating them one by one returns each
id directly.
Update signatory
This endpoint updates a signatory.
HTTP Request
PATCH /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/signatories/{signatoryId}
Example Request Body
{
"name": "Updated Name",
"surnames": "Updated Surnames",
"email": "signatory@example.com",
"phone": "123456789",
"sequence": 2,
"uniqueValidator": true,
"provider": "NOTICEMAN_AND_RCS"
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| signatureRequestId | Yes | string (UUID) | Unique identifier for the signature request. |
| documentId | Yes | string (UUID) | Unique identifier for the document. |
| signatoryId | Yes | string (UUID) | Unique identifier for the signatory. |
| name | No | string | Updated signatory name. |
| surnames | No | string | Updated signatory surnames. |
| No | string (email) | Updated signatory email address. | |
| phone | No | string | Updated signatory phone number. |
| sequence | No | integer | Updated sequence number for phased signing. |
| uniqueValidator | No | boolean | If true, a single validator approval is enough for this signatory. |
| provider | No | string | Notification provider for this signatory. Possible values: NOTICEMAN, NOTICEMAN_AND_WHATSAPP, NOTICEMAN_AND_WHATSAPP_AND_RCS, NOTICEMAN_AND_RCS. Overrides the signature request provider for this participant: when notifications are sent, the participant provider takes precedence over the signature request one. Providers other than NOTICEMAN require a phone number. |
Error: 400 Bad request | 404 Signature request, document or signatory not found | 409 Signature request status should be draft or signatory conflicts with the document | 500 Unexpected error
Update signatory coordinates
This endpoint updates the signatory coordinates.
HTTP Request
PATCH /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/signatories/{signatoryId}/coordinates
Example Request Body
{
"coordinates": [
{
"x": 120.0,
"y": 240.0,
"page": 1
}
]
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| signatureRequestId | Yes | string (UUID) | Unique identifier for the signature request. |
| documentId | Yes | string (UUID) | Unique identifier for the document. |
| signatoryId | Yes | string (UUID) | Unique identifier for the signatory. |
| coordinates | Yes | array of objects | Signature coordinates. |
| coordinates[].x | No | number | X coordinate for the signature. |
| coordinates[].y | No | number | Y coordinate for the signature. |
| coordinates[].page | No | integer | Page number for the signature. |
Update signatory sequence
This endpoint updates the signatory sequence for phased signing.
HTTP Request
PATCH /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/signatories/{signatoryId}/sequence
Example Request Body
{
"sequence": 2
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| signatureRequestId | Yes | string (UUID) | Unique identifier for the signature request. |
| documentId | Yes | string (UUID) | Unique identifier for the document. |
| signatoryId | Yes | string (UUID) | Unique identifier for the signatory. |
| sequence | Yes | integer | New sequence number for phased signing. |
Delete signatory
This endpoint deletes a signatory.
HTTP Request
DELETE /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/signatories/{signatoryId}
Error: 400 Bad request | 500 Unexpected error
Resend signatory notification
This endpoint resends the notification to a signatory.
HTTP Request
POST /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/signatories/{signatoryId}/resend
Response: 202 Accepted
Error: 404 Signature request, document or signatory not found | 409 Conflict when request or signatory state is invalid