Validators operations
Contents
Introduction
Validators approve a signature process before the signatory is notified. If uniqueValidator is set to true (at signature request or signatory level), a single validator approval is enough when multiple validators exist for the same signatory.
Taking the signature request back to draft changes every validator identifier. The
draft operation
replaces each validator with a new row and a new validatorId, including those who had
already acted. Any identifier you stored before drafting stops resolving, so read them again
afterwards.
Operations
List validators
This endpoint retrieves a list of validators for a signature request.
HTTP Request
GET /api/v1/private/signature-requests/{signatureRequestId}/validators
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| signatureRequestId | Yes | string (UUID) | Unique identifier for the signature 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. |
Example Response
[
{
"id": "d6dd41c4-8f92-4a88-9d13-2f5a6c1e55b1",
"name": "Validator Name",
"surnames": "Validator Surnames",
"phone": "123456789",
"email": "validator@example.com",
"documentId": "2b066f42-8e65-4c6f-8253-ad6ded8ae436",
"signatoryId": "950fac7e-5284-42ad-8044-3f4632678324"
}
]
Get editable validators
This endpoint retrieves editable validators for a signature request.
HTTP Request
GET /api/v1/private/signature-requests/{signatureRequestId}/validators/editables
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| signatureRequestId | Yes | string (UUID) | Unique identifier for the signature request. |
| emails | No | array of string (email) | Filter by validator emails. |
Create validator
This endpoint creates a validator for a signatory. Note that, unlike update and resend, the create and delete validator routes are not nested under /signature-requests/{signatureRequestId}.
HTTP Request
POST /api/v1/private/documents/{documentId}/signatories/{signatoryId}/validators
Example Request Body
{
"name": "Validator Name",
"surnames": "Validator Surnames",
"email": "validator@example.com",
"phone": "123456789",
"provider": "NOTICEMAN_AND_WHATSAPP"
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| documentId | Yes | string (UUID) | Unique identifier for the document. |
| signatoryId | Yes | string (UUID) | Unique identifier for the signatory. |
| name | Yes | string | Validator name. |
| surnames | No | string | Validator surnames. |
| Yes | string (email) | Validator email address. | |
| phone | No | string | Validator phone number. |
| provider | No | string | Notification provider for this validator. 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 | 500 Unexpected error
Update validator
This endpoint updates a validator.
HTTP Request
PATCH /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/signatories/{signatoryId}/validators/{validatorId}
Example Request Body
{
"name": "Updated Validator",
"surnames": "Validator Surnames",
"email": "validator@example.com",
"phone": "123456789",
"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. |
| validatorId | Yes | string (UUID) | Unique identifier for the validator. |
| name | No | string | Updated validator name. |
| surnames | No | string | Updated validator surnames. |
| No | string (email) | Updated validator email address. | |
| phone | No | string | Updated validator phone number. |
| provider | No | string | Notification provider for this validator. 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, signatory or validator not found | 409 Signature request status should be draft or validator conflicts with the signatory | 500 Unexpected error
Delete validator
This endpoint deletes a validator.
HTTP Request
DELETE /api/v1/private/documents/{documentId}/signatories/{signatoryId}/validators/{validatorId}
Error: 400 Bad request | 500 Unexpected error
Resend validator notification
This endpoint resends the notification to a validator.
HTTP Request
POST /api/v1/private/signature-requests/{signatureRequestId}/documents/{documentId}/signatories/{signatoryId}/validators/{validatorId}/resend
Response: 202 Accepted
Error: 404 Signature request, document, signatory or validator not found | 409 Conflict when request or validator state is invalid
Bulk add or remove validators
This endpoint assigns validators to documents within a signature request or removes them in bulk.
HTTP Request
PATCH /api/v1/private/signature-requests/{signatureRequestId}/documents
Example Request Body (validators by signatoryId)
{
"documents": [
{
"documentId": "2b066f42-8e65-4c6f-8253-ad6ded8ae436",
"validators": [
{
"email": "validator@example.com",
"name": "Validator Name",
"surnames": "Validator Surnames",
"phone": "123456789",
"signatoryId": "950fac7e-5284-42ad-8044-3f4632678324"
}
],
"operationType": "ADD"
}
]
}
Example Request Body (validators inside signatories)
{
"documents": [
{
"documentId": "2b066f42-8e65-4c6f-8253-ad6ded8ae436",
"signatories": [
{
"email": "signatory@example.com",
"name": "Signatory Name",
"validators": [
{
"email": "validator@example.com",
"name": "Validator Name",
"surnames": "Validator Surnames",
"phone": "123456789"
}
]
}
],
"operationType": "ADD"
}
]
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| documents | Yes | array of objects | List of document participant objects. |
| documents[].documentId | Yes | string (UUID) | Identifier of the document. |
| documents[].operationType | Yes | string | Operation to perform. Possible values: ADD, DELETE. |
| documents[].validators | No | array of objects | Validators to add/remove by signatoryId. |
| documents[].signatories | No | array of objects | Signatories that include nested validators. |
| validators[].email | Yes | string (email) | Validator email address. |
| validators[].name | Yes | string | Validator name. |
| validators[].surnames | No | string | Validator surnames. |
| validators[].phone | No | string | Validator phone number. |
| validators[].signatoryId | Yes (for documents[].validators) | string (UUID) | Identifier of the signatory to validate. |
| signatories[].email | Yes (for documents[].signatories) | string (email) | Signatory email address. |
| signatories[].name | Yes (for documents[].signatories) | string | Signatory name. |
| signatories[].validators | No | array of objects | Validators attached to a signatory. |
Error: 400 Bad request | 404 Document not found, or participant not in the document | 409 Signature request status should be draft, or a participant conflicts with the document | 500 Unexpected error
Bulk edit validators (v2)
This endpoint edits validators in bulk using patch operations.
HTTP Request
PATCH /api/v1/private/signature-requests/{signatureRequestId}/bulkedit/v2
Example Request Body
{
"participants": [
{
"where": {
"email": "validator@example.com",
"documentId": "2b066f42-8e65-4c6f-8253-ad6ded8ae436"
},
"patch": [
{
"operation": "REPLACE",
"path": "/name",
"value": "Updated Validator"
},
{
"operation": "REPLACE",
"path": "/phone",
"value": "987654321"
}
]
}
]
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| participants | Yes | array of objects | List of bulk edit operations. |
| participants[].where | Yes | object | Search criteria: email, documentId. |
| participants[].patch | Yes | array of objects | Patch operations. Operations: REPLACE, REMOVE. |
| participants[].patch[].path | Yes | string | Editable paths include: /name, /surnames, /email, /phone, /provider. For /provider, the value must be one of NOTICEMAN, NOTICEMAN_AND_WHATSAPP, NOTICEMAN_AND_WHATSAPP_AND_RCS, NOTICEMAN_AND_RCS. This v2 endpoint serves signature requests in draft. On a request that is active or partially signed, /provider is edited through editable-participants (below). |
Fields that cannot be edited: identifiers, statuses, and date fields.
Error: 400 Bad request | 409 Signature request status should be draft | 500 Unexpected error
Bulk edit editable validators
This endpoint edits the validators of a signature request that is active or partially signed, using patch operations and an optional role filter. Editable paths: /name, /surnames, /email, /phone and /provider (for /provider, one of NOTICEMAN, NOTICEMAN_AND_WHATSAPP, NOTICEMAN_AND_WHATSAPP_AND_RCS, NOTICEMAN_AND_RCS). Any other path is refused.
HTTP Request
PATCH /api/v1/private/signature-requests/{signatureRequestId}/bulkedit/editable-participants
Example Request Body
{
"participants": [
{
"where": {
"email": "validator@example.com",
"role": "VALIDATOR"
},
"patch": [
{
"operation": "REPLACE",
"path": "/name",
"value": "Updated Validator"
}
]
}
]
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| participants | Yes | array of objects | List of bulk edit operations. |
| participants[].where.email | Yes | string (email) | Email of the validator to edit. |
| participants[].where.role | No | string | Role of the participant. Use VALIDATOR. |
| participants[].patch | Yes | array of objects | Patch operations. Operations: REPLACE, REMOVE. |
Error: 400 Bad request | 409 Signature request status should be active or partially signed | 500 Unexpected error