Notification operations
Contents
- Introduction
-
Operations
- Create a new notification (v2)
- Reserved metadata keys
- Search notifications
- Get notification detail
- Hot edit a notification in live channels
- Cancel a notification
- Resend a notification
- Clone a notification
- Delete bulk notifications
- Add receivers to a notification request
- Delete receivers from a notification request
- Update a notification request
- Delete a draft notification request
- Activate a notification request
- Add attachments to a notification request
- Delete a notification request attachment
- Create upload URL for a request attachment
- Create download URL for a request attachment
- Generate notification report
- Get report PDF download URL
- Get report package download URL
- Generate or package reports in bulk
- Get bulk reports ZIP download URL
- Bulk reports webhook
Introduction
Once you have the token, you can start creating and managing notifications with the API. This module manages notification requests, receivers, attachments, and reports.
Operations
Create a new notification (v2)
This endpoint is used to create a new notification request using the v2 payload. The data block depends on the selected provider.
One request, one channel. All the receivers of a request must belong to the
same channel; mixing receivers of different channels fails with a
500. To reach the same person through two channels, create two
requests.
Phone numbers must be E.164, with the +, and must be mobile. A
correctly formatted landline is rejected.
A channel can exist in the contract and be switched off for your tenant. In
that case the answer is a 400 with
#PROVIDER_TENANT_CONFIGURATION_NOT_ALLOWED#. It is configuration, not a
malformed request: ask your EADFactory contact to enable it.
content is conditional: send either content or the
template under data.<channel>.template.
HTTP Request
POST /api/v1/private/notifications/v2
With the following information provided as JSON:
Example Request Body
{
"requestId": "e694c179-e503-4101-992e-329700c37adc",
"content": "Notification content goes here.",
"language": "en",
"data": {
"provider": "NOTICEMAN",
"noticeman": {
"notificationType": "NO_RESPONSE",
"sender": {
"address": "sender@example.com",
"name": "Sender Name"
},
"receiver": [
{
"address": "recipient@example.com",
"name": "Recipient Name",
"type": "TO",
"phone": "+34666777888"
}
],
"subject": "Notification Subject",
"scheduledAt": "2023-10-23T10:34:59.483Z",
"reminder": 24,
"limitResponse": 48,
"attachments": [
{
"filename": "document.pdf",
"hash": "a313d30bb73885f79a80332995d6546308e3a77d944674c5758d68d67c52664d"
}
]
}
},
"metadata": {
"caseId": "12345"
},
"autosend": false
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| requestId | No | string (UUID) | Optional request identifier. If not provided, the system generates it. |
| content | Yes | string | Notification content or body. |
| language | Yes | string | Language code (e.g., "en"). |
| data | Yes | object | Provider-specific notification data. Only the block matching data.provider is allowed. |
| data.provider | Yes | string | Provider type. Possible values: SMTP, NOTICEMAN, SMS, WFB, RCS.
Note: the former EMAIL value was renamed to SMTP in February 2026 (breaking change); EMAIL is no longer accepted. |
| data.smtp | No | object | Required when data.provider is SMTP. Contains SMTP notification data. |
| data.smtp.sender | No | object | Optional sender object with:
address (string, email): Sender email address. name (optional, string): Sender name. addressReplyTo (optional, string, email): Reply-to email address. |
| data.smtp.receiver | No | array of objects | Required when data.provider is SMTP. Each recipient object includes:
address (required, string, email): Recipient email address. name (optional, string): Recipient name. type (optional, string): Recipient type (TO, CC, BCC). metadata (optional, object): Metadata key/value pairs for the recipient. |
| data.smtp.subject | No | string | Required when data.provider is SMTP. Notification subject. |
| data.smtp.attachments | No | array of objects | Optional attachments for SMTP. Each attachment includes:
filename (required, string): Attachment file name. hash (required, string): File hash (SHA256). fileSize (optional, integer): File size in bytes (minimum 1). |
| data.smtp.externalAttachments | No | array of objects | Optional attachments referencing files already stored in the platform. Each item includes:
id (required, string): Identifier of the external file. type (required, string): File type. Possible values: EVIDENCE, REPORT, REPORT_PACKAGE. filename (required, string): Attachment file name. hash (optional, string): File hash (SHA256). |
| data.smtp.template | No | string | Optional template for the notification. |
| data.smtp.parameters | No | object | Optional key/value parameters used with the template. |
| data.noticeman | No | object | Required when data.provider is NOTICEMAN. Contains Noticeman notification data. |
| data.noticeman.notificationType | No | string | Required when data.provider is NOTICEMAN. Possible values: NO_RESPONSE, ACCEPTED_OR_NOT, RECEIVED_AGREE, LONG_RESPONSE. |
| data.noticeman.sender | No | object | Required when data.provider is NOTICEMAN. Sender object with:
address (required, string, email): Sender email address. name (optional, string): Sender name. addressReplyTo (optional, string, email): Reply-to email address. |
| data.noticeman.receiver | No | array of objects | Required when data.provider is NOTICEMAN. Each recipient object includes:
address (required, string, email): Recipient email address. name (optional, string): Recipient name. type (optional, string): Recipient type (TO, CC, BCC). phone (optional, string): Recipient phone. metadata (optional, object): Metadata key/value pairs for the recipient. |
| data.noticeman.subject | No | string | Required when data.provider is NOTICEMAN. Notification subject. |
| data.noticeman.attachments | No | array of objects | Optional attachments for NOTICEMAN. Each attachment includes:
filename (required, string): Attachment file name. hash (required, string): File hash (SHA256). fileSize (optional, integer): File size in bytes (minimum 1). |
| data.noticeman.externalAttachments | No | array of objects | Optional attachments referencing files already stored in the platform. Each item includes:
id (required, string): Identifier of the external file. type (required, string): File type. Possible values: EVIDENCE, REPORT, REPORT_PACKAGE. filename (required, string): Attachment file name. hash (optional, string): File hash (SHA256). |
| data.noticeman.template | No | string | Optional template for the notification. |
| data.noticeman.parameters | No | object | Optional key/value parameters used with the template. |
| data.noticeman.scheduledAt | No | string (date-time) | Optional scheduled date/time for sending the notification. |
| data.noticeman.reminder | No | integer | Optional reminder hours before notification expiry (between 24 and 720). |
| data.noticeman.limitResponse | No | integer | Optional time limit in hours for response (between 0 and 720). |
| data.sms | No | object | Required when data.provider is SMS. Contains SMS notification data. |
| data.sms.receiverAddresses | No | array of string | Required when data.provider is SMS. Recipient phone numbers. |
| data.wfb | No | object | Required when data.provider is WFB. Contains WFB notification data. |
| data.wfb.receiverAddresses | No | array of string | Required when data.provider is WFB. Recipient phone numbers. |
| data.rcs | No | object | Required when data.provider is RCS. Contains RCS notification data. |
| data.rcs.receiverAddresses | No | array of string | Required when data.provider is RCS. Recipient phone numbers. |
| data.rcs.type | No | string | Required when data.provider is RCS. RCS message type. Possible values: TEXT, TEMPLATE. |
| data.rcs.templateId | No | integer | Optional RCS template identifier. |
| data.rcs.templateAttributes | No | object | Optional key/value attributes used to fill the RCS template. |
| data.rcs.auxiliarySmsText | No | string | Optional auxiliary SMS text. |
| data.rcs.scheduleDate | No | string (date-time) | Optional scheduled date/time for sending the notification. |
| data.rcs.priority | No | integer | Optional message priority. |
| metadata | No | object | Optional metadata key/value pairs for the request. |
| autosend | No | boolean | If true, notifications are dispatched automatically once attachments are ready or when there are no attachments. If false, use the activate request operation. If the request has attachments, use false and activate it once every file is uploaded (see Dispatch notifications). |
Response: 201 Notification created successfully
Example Response
{
"requestId": "e694c179-e503-4101-992e-329700c37adc",
"notificationIds": [ "55fc5ab7-2345-41fd-8688-6d04acf2b5bc" ],
"uploadLinks": [
{
"url": "http://example.io",
"expiration": "2023-10-23T10:34:59.483Z",
"filename": "document.pdf",
"fileId": "9b11ee36-9d70-44f3-9fd1-3138dae8f2a6"
}
]
}
Error: 500 Unexpected error
Reserved metadata keys
The metadata map of a notification is free for your own keys, with one
exception: four names are read by the platform and change how the WhatsApp
follow-up message is sent when a certified notification is dispatched. If you use those
names for your own data, you will change that behaviour by accident.
| Key | What it does |
|---|---|
templateWFB |
Name of the WhatsApp template to use. Without it, the default for the language of
the notification is used (nm_wfb_template_es or
nm_wfb_template_en) |
signatureRequestName |
Takes the place of the subject as the first template parameter |
resendLink |
When present, the subject used as first parameter is stripped of its "Certified notification: " prefix |
resendChannels |
Comma-separated list of channels for the follow-up. If it does not include
WFB, no WhatsApp message is sent. Without this key, the tenant
default decides |
The template always takes two parameters, in this order: the subject (or
signatureRequestName) and the landing URL.
This follow-up only happens for certified notifications that carry a phone number. WhatsApp as a channel of its own does exist, but it does not take a template.
Search notifications
This endpoint allows you to search for notifications based on query parameters. You can filter by request, state, sender, recipient, subject, and paginate the results.
The state filter looks at the history, not at the current state. Every
notification has been in DRAFT at some point, so filtering by
DRAFT returns all of them. It answers "has it ever been in this state",
which is rarely the question you meant to ask.
The states array does not come ordered. The current state is the
one with the latest registeredAt, not the last element of the array.
The same piece of data is called state in the search results and
type in the notification detail.
HTTP Request
GET /api/v1/private/notifications
Example Response
{
"records": [
{
"id": "bc360722-ef0b-452d-a4ae-26934cbc9f25",
"requestId": "afd6b65c-af85-479a-8789-86d7239cf064",
"type": "NO_RESPONSE",
"senderAddress": "sender@example.com",
"senderName": "Sender Name",
"recipientAddress": "recipient@example.com",
"recipientName": "Recipient Name",
"subject": "Notification Subject",
"content": "Notification content goes here.",
"notificationAttachments": [],
"language": "en",
"states": [
{
"notificationId": "bc360722-ef0b-452d-a4ae-26934cbc9f25",
"registeredAt": "2023-10-23T10:34:59.483Z",
"state": "DRAFT"
}
],
"phone": "",
"reminderHours": 24,
"scheduledAt": "2023-10-23T10:34:59.483Z",
"limitResponse": 48,
"autosend": true,
"provider": "NOTICEMAN"
}
],
"_metadata": {
"currentPage": 0,
"totalPages": 1,
"pageSize": 20,
"totalRecords": 100
}
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| ids | No | array of string (UUID) | Notification identifiers to filter by. (Optional filter) |
| requestId | No | string (UUID) | Request identifier to correlate notifications. (Optional filter) |
| states | No | array of string | Filter notifications that have been through that state at some point, not notifications whose current state is that one. Possible values: DRAFT, ACTIVE, DISPATCHED, DISPATCH_FAILED, DELIVERING, ERROR, SENT, OPEN, READ, ACCEPTED, NOT_ACCEPTED, RECEIVED_CONFORMING, RECEIVED_NON_CONFORMING, ANSWERED, CANCELLED, BOUNCED, RELAYED. |
| filters.common.recipients | No | array of string | Filter notifications by recipient addresses. (Optional) |
| filters.email.subject | No | string | Filter notifications by subject text. (Optional) |
| filters.email.noticeman.type | No | array of string | Filter Noticeman notifications by type. Possible values: NO_RESPONSE, ACCEPTED_OR_NOT, RECEIVED_AGREE, LONG_RESPONSE. (Optional) |
| filters.email.sender | No | array of string | Filter notifications by sender email addresses. (Optional) |
| page | No | integer | Pagination: Page number to retrieve. (Optional) |
| size | No | integer | Pagination: Number of items per page. (Optional) |
| sort | No | array of string | Sorting criteria in the format field:order (e.g., requestId:ASC, sender:DESC). (Optional) |
Error: 400 Bad request
Get notification detail
This endpoint retrieves detailed information for a specific notification identified by its unique identifier.
HTTP Request
GET /api/v1/private/notifications/{notificationId}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| notificationId | Yes | string (UUID) | Unique identifier for the notification. (Required) |
Example Response
{
"id": "86b26824-f646-406d-b039-cdb142d46cd4",
"externalId": "NTC-00001",
"senderAddress": "sender@example.com",
"senderName": "Sender Name",
"senderAddressReplyTo": "reply-to@example.com",
"recipientAddress": "recipient@example.com",
"recipientName": "Recipient Name",
"subject": "Notification Subject",
"content": "Notification content goes here.",
"states": [
{
"registeredAt": "2023-10-23T10:34:59.483Z",
"type": "DRAFT"
}
],
"type": "NO_RESPONSE",
"phone": "+34666777888",
"reminderHours": 24,
"scheduledAt": "2023-10-23T10:34:59.483Z",
"limitResponse": 48,
"notificationAttachments": [
{
"fileId": "18bb63be-743f-47b3-a7f0-7f76ee79b89c",
"filename": "document.pdf",
"hash": "a313d30bb73885f79a80332995d6546308e3a77d944674c5758d68d67c52664d",
"fileType": "NOTIFICATION_ATTACHMENT",
"attachmentStatus": "READY_TO_SEND",
"fileSize": 1024
}
],
"metadata": {
"caseId": "12345"
},
"provider": "NOTICEMAN"
}
The states array contains the state history of the notification. Possible values for type are: DRAFT, ACTIVE, DISPATCHED, DISPATCH_FAILED, DELIVERING, ERROR, SENT, OPEN, READ, ACCEPTED, NOT_ACCEPTED, RECEIVED_CONFORMING, RECEIVED_NON_CONFORMING, ANSWERED, CANCELLED, BOUNCED, RELAYED.
For RCS notifications the response also includes the fields rcsType (string), templateId (integer), templateAttributes (object), priority (integer) and auxiliarySmsText (string).
Error: 400 Bad request
Hot edit a notification in live channels
This endpoint clones a live Noticeman notification with updated recipient data and cancels the original notification.
HTTP Request
PATCH /api/v1/private/notifications/{notificationId}
Example Request Body
{
"name": "Recipient Name",
"address": "recipient@example.com",
"phone": "+34666777888"
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| notificationId | Yes | string (UUID) | Notification identifier. (Required) |
| name | Yes | string | New recipient name. |
| address | Yes | string (email) | New recipient email address. |
| phone | No | string | New recipient phone number, if applicable. |
Response: 200 Notification updated successfully
Example Response
{
"oldNotificationId": "86b26824-f646-406d-b039-cdb142d46cd4",
"newNotificationId": "e694c179-e503-4101-992e-329700c37adc"
}
Error: 409 Notification has wrong active status
Cancel a notification
This endpoint cancels an active notification. This operation is only available for Noticeman notifications in active states.
HTTP Request
POST /api/v1/private/notifications/{notificationId}/cancel
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| notificationId | Yes | string (UUID) | Notification identifier. (Required) |
Response: 200 Notification cancelled successfully
Error: 409 Notification has wrong active status
Resend a notification
This endpoint clones a Noticeman notification, cancels the original, and sends a new notification.
HTTP Request
POST /api/v1/private/notifications/{notificationId}/resend
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| notificationId | Yes | string (UUID) | Notification identifier. (Required) |
Response: 200 Notification resent successfully
Example Response
{
"oldNotificationId": "86b26824-f646-406d-b039-cdb142d46cd4",
"newNotificationId": "e694c179-e503-4101-992e-329700c37adc"
}
Error: 409 Notification has wrong active status
Clone a notification
This endpoint clones a Noticeman notification without cancelling the original. The request body is optional: it can be used to override the recipient email, subject or sender data in the cloned notification; any field not provided keeps the value of the original notification.
HTTP Request
POST /api/v1/private/notifications/{notificationId}/clone
Example Request Body
{
"requestId": "e694c179-e503-4101-992e-329700c37adc",
"recipientEmail": "recipient@example.com",
"subject": "Notification Subject",
"senderName": "Sender Name",
"senderAddress": "sender@example.com"
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| notificationId | Yes | string (UUID) | Notification identifier. (Required) |
| requestId | No | string (UUID) | Optional request identifier for the cloned notification. It must not exist in the system; if not provided, the system generates it. |
| recipientEmail | No | string (email) | Optional new recipient email address for the cloned notification. |
| subject | No | string | Optional new subject for the cloned notification. |
| senderName | No | string | Optional new sender name for the cloned notification. |
| senderAddress | No | string (email) | Optional new sender email address for the cloned notification. |
Response: 201 Notification cloned successfully
Example Response
{
"oldNotificationId": "86b26824-f646-406d-b039-cdb142d46cd4",
"newNotificationId": "e694c179-e503-4101-992e-329700c37adc"
}
Error: 400 Bad request
Error: 404 Notification not found
Error: 409 Notification has wrong active status
Delete bulk notifications
This endpoint starts an asynchronous process that deletes the given notifications in bulk. The deletion is irreversible.
HTTP Request
DELETE /api/v1/private/bulk/notifications
Example Request Body
{
"requestId": "e694c179-e503-4101-992e-329700c37adc",
"ids": [
"55fc5ab7-2345-41fd-8688-6d04acf2b5bc"
]
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| requestId | Yes | string (UUID) | Identifier for the bulk delete process. |
| ids | Yes | array of string (UUID) | List of notification identifiers to delete (maximum 100). |
Response: 204 Notifications delete request accepted. The deletion runs asynchronously after the request is accepted.
Error: 404 Some notification not found
Error: 409 Some notification exists in other process
Add receivers to a notification request
This endpoint adds new receivers to a draft notification request.
HTTP Request
POST /api/v1/private/notifications/requests/{requestId}/receivers
Example Request Body
{
"receivers": [
{
"provider": "NOTICEMAN",
"type": "TO",
"address": "recipient@example.com",
"name": "Recipient Name",
"phone": "+34666777888"
}
]
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| requestId | Yes | string (UUID) | Request identifier. (Required) |
| receivers | Yes | array of objects | List of receivers to add. |
| receivers[].provider | Yes | string | Receiver provider. Possible values: SMTP, NOTICEMAN, SMS, WFB.
Note: the former EMAIL value was renamed to SMTP in February 2026 (breaking change); EMAIL is no longer accepted. |
| receivers[].type | Yes (NOTICEMAN) | string | Recipient type for NOTICEMAN. Possible values: TO, CC, BCC. |
| receivers[].address | Yes | string | Email or phone address depending on provider. |
| receivers[].name | No | string | Recipient name (SMTP, NOTICEMAN). |
| receivers[].phone | No | string | Recipient phone for NOTICEMAN. |
| receivers[].metadata | No | object | Optional metadata key/value pairs for the receiver (SMTP, NOTICEMAN). |
Response: 201 Receivers added successfully
Example Response
{
"requestId": "e694c179-e503-4101-992e-329700c37adc",
"notificationIds": [ "55fc5ab7-2345-41fd-8688-6d04acf2b5bc" ]
}
Error: 409 All notifications with this requestId not in DRAFT status
Delete receivers from a notification request
This endpoint deletes receivers from a draft notification request by notification IDs.
HTTP Request
DELETE /api/v1/private/notifications/requests/{requestId}/receivers
Example Request Body
{
"notificationIds": [
"55fc5ab7-2345-41fd-8688-6d04acf2b5bc"
]
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| requestId | Yes | string (UUID) | Request identifier. (Required) |
| notificationIds | Yes | array of string (UUID) | List of notification identifiers to remove from the request. |
Response: 204 Receivers deleted successfully
Error: 409 Request is not in DRAFT status
Update a notification request
This endpoint updates a draft notification request. Use it to modify content, language, metadata, or provider-specific settings.
HTTP Request
PATCH /api/v1/private/notifications/requests/{requestId}
Example Request Body
{
"content": "Updated notification content.",
"language": "en",
"metadata": {
"caseId": "12345"
},
"data": {
"provider": "NOTICEMAN",
"noticeman": {
"subject": "Updated subject",
"sender": {
"address": "sender@example.com",
"name": "Sender Name"
},
"scheduledAt": "2023-10-23T10:34:59.483Z",
"reminder": 24,
"limitResponse": 48
}
}
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| requestId | Yes | string (UUID) | Request identifier. (Required) |
| content | No | string | Updated notification content. |
| language | No | string | Updated language code. |
| metadata | No | object | Updated metadata key/value pairs. |
| data.provider | No | string | Provider type. Possible values: SMTP, NOTICEMAN.
Note: the former EMAIL value was renamed to SMTP in February 2026 (breaking change); EMAIL is no longer accepted. |
| data.smtp.subject | No | string | Updated subject when data.provider is SMTP. Required when the data.smtp block is present. |
| data.smtp.sender | No | object | Updated sender when data.provider is SMTP. Required when the data.smtp block is present. Includes:
address (required, string, email): Sender email. name (optional, string): Sender name. addressReplyTo (optional, string, email): Reply-to email address. |
| data.noticeman.subject | No | string | Updated subject when data.provider is NOTICEMAN. Required when the data.noticeman block is present. |
| data.noticeman.sender | No | object | Updated sender when data.provider is NOTICEMAN. Required when the data.noticeman block is present. Includes:
address (required, string, email): Sender email. name (optional, string): Sender name. addressReplyTo (optional, string, email): Reply-to email address. |
| data.noticeman.notificationType | No | string | Updated notification type when data.provider is NOTICEMAN. Possible values: NO_RESPONSE, ACCEPTED_OR_NOT, RECEIVED_AGREE, LONG_RESPONSE. |
| data.noticeman.scheduledAt | No | string (date-time) | Updated scheduled date/time for sending the notification. |
| data.noticeman.reminder | No | integer | Updated reminder hours before notification expiry (between 24 and 720). |
| data.noticeman.limitResponse | No | integer | Updated time limit in hours for response (between 0 and 720). |
Response: 204 Request updated successfully
Error: 400 Bad request
Delete a draft notification request
This endpoint deletes a notification request in DRAFT status.
HTTP Request
DELETE /api/v1/private/notifications/requests/{requestId}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| requestId | Yes | string (UUID) | Request identifier. (Required) |
Response: 204 Request deleted successfully
Error: 409 Request is not in DRAFT status
Activate a notification request
This endpoint activates a draft notification request and dispatches the notifications. Use this when autosend is false.
HTTP Request
POST /api/v1/private/notifications/requests/{requestId}/activate
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| requestId | Yes | string (UUID) | Request identifier. (Required) |
Response: 202 Activation request accepted
Error: 422 Activation preconditions not met
Add attachments to a notification request
This endpoint adds attachments to a draft notification request and returns upload links.
HTTP Request
POST /api/v1/private/notifications/requests/{requestId}/attachments
Example Request Body
{
"attachments": [
{
"fileName": "document.pdf",
"hash": "a313d30bb73885f79a80332995d6546308e3a77d944674c5758d68d67c52664d"
}
]
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| requestId | Yes | string (UUID) | Request identifier. (Required) |
| attachments | Yes | array of objects | List of attachments to add. |
| attachments[].fileName | Yes | string | Attachment file name. |
| attachments[].hash | Yes | string | File hash (SHA256). |
| attachments[].fileId | No | string (UUID) | Optional file identifier. If not provided, the system generates it. |
| attachments[].fileSize | No | integer | Optional file size in bytes (minimum 1). |
Note: this operation expects the attachment file name in the fileName field (camelCase), while the create notification (v2) operation uses filename (lowercase). This naming difference is part of the current API.
Response: 201 Attachments added successfully
Example Response
{
"requestId": "e694c179-e503-4101-992e-329700c37adc",
"notificationIds": [ "55fc5ab7-2345-41fd-8688-6d04acf2b5bc" ],
"uploadLinks": [
{
"url": "http://example.io",
"expiration": "2023-10-23T10:34:59.483Z",
"fileId": "9b11ee36-9d70-44f3-9fd1-3138dae8f2a6"
}
]
}
Error: 500 Unexpected error
Delete a notification request attachment
This endpoint deletes an attachment from a draft notification request.
HTTP Request
DELETE /api/v1/private/notifications/requests/{requestId}/attachments/{fileId}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| requestId | Yes | string (UUID) | Request identifier. (Required) |
| fileId | Yes | string (UUID) | Attachment file identifier. (Required) |
Response: 204 Attachment deleted successfully
Error: 422 Deletion preconditions not met
Create upload URL for a request attachment
This endpoint generates a temporary upload URL for adding an attachment to an existing request. The file must be in WAITING_FILE status.
HTTP Request
POST /api/v1/private/requests/{requestId}/attachments/{attachmentId}/upload-url
Note: the base path of this operation is /api/v1/private/requests/... (without /notifications). This is intentional and matches the API.
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| requestId | Yes | string (UUID) | Identifier of the request. (Required) |
| attachmentId | Yes | string (UUID) | Identifier of the attachment (fileId). (Required) |
Example Response
{
"url": "http://example.io",
"expiration": "2023-10-23T10:34:59.483Z"
}
Error: 404 File not found
Error: 409 File should be in WAITING_FILE status
Error: 500 Unexpected error
Create download URL for a request attachment
This endpoint generates a temporary download URL for a request attachment.
HTTP Request
POST /api/v1/private/requests/{requestId}/attachments/{attachmentId}/download-url
Note: the base path of this operation is /api/v1/private/requests/... (without /notifications). This is intentional and matches the API.
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| requestId | Yes | string (UUID) | Identifier of the request. (Required) |
| attachmentId | Yes | string (UUID) | Identifier of the attachment (fileId). (Required) |
Response: 307 Temporary Redirect. The response body contains the presigned download URL and its expiration:
Example Response
[
{
"url": "http://example.io",
"expiration": "2023-10-23T10:34:59.483Z"
}
]
Error: 404 Attachment not found
Generate notification report
This endpoint starts the notification report generation process.
HTTP Request
POST /api/v1/private/reports
Example Request Body
{
"reportId": "9b11ee36-9d70-44f3-9fd1-3138dae8f2a6",
"requestId": "e694c179-e503-4101-992e-329700c37adc",
"template": "notification",
"languageCode": "es_ES",
"notificationIds": [
"55fc5ab7-2345-41fd-8688-6d04acf2b5bc"
],
"additionalData": {
"key1": "value1"
},
"embedAttachmentsEnabled": true
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| reportId | No | string (UUID) | Optional report identifier. If not provided, the system generates it. |
| requestId | Yes | string (UUID) | Notification request identifier. |
| template | Yes | string | Template to use for report generation. |
| languageCode | Yes | string | Locale language code (e.g., "es_ES"). |
| notificationIds | No | array of string (UUID) | List of notification identifiers to include in the report. |
| additionalData | No | object | Additional data to be used in the report generation process. |
| embedAttachmentsEnabled | No | boolean | If true, the notification attachments are embedded in the report. |
Response: 201 Generated report
Example Response
{
"reportId": "9b11ee36-9d70-44f3-9fd1-3138dae8f2a6",
"requestId": "e694c179-e503-4101-992e-329700c37adc",
"template": "notification",
"languageCode": "es_ES",
"notificationIds": [
"55fc5ab7-2345-41fd-8688-6d04acf2b5bc"
],
"additionalData": {
"key1": "value1"
}
}
Error: 409 Conflict
Get report PDF download URL
This endpoint returns the URL and expiration time to download the report PDF.
HTTP Request
GET /api/v1/private/reports/{reportId}/file
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| reportId | Yes | string (UUID) | Report identifier. (Required) |
Example Response
[
{
"url": "http://example.io",
"expiration": "2023-10-23T10:34:59.483Z"
}
]
Error: 404 Report not found
Get report package download URL
This endpoint returns the URL and expiration time to download the report package.
HTTP Request
GET /api/v1/private/reports/{reportId}/package
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| reportId | Yes | string (UUID) | Report identifier. (Required) |
Example Response
[
{
"url": "http://example.io",
"expiration": "2023-10-23T10:34:59.483Z"
}
]
Error: 404 Report not found
Generate or package reports in bulk
This endpoint starts an asynchronous process that works on the reports of several notifications at once. The mode field selects what the process does:
GENERATE: generates a new report (PDF and report package) for each notification, as Generate notification report does for one.GENERATE_AND_PACKAGE: generates a new report for each notification and, when all of them are ready, builds a single ZIP file with their PDFs.PACKAGE: generates nothing. It takes the latest completed report of each notification and builds a single ZIP file with their PDFs.
The response only confirms that the process has started. When it finishes, the result is sent to your webhook (see Bulk reports webhook). In GENERATE_AND_PACKAGE and PACKAGE, download the ZIP file with Get bulk reports ZIP download URL once the webhook has arrived with status COMPLETED.
The process does not finish, and no webhook is sent, in these cases:
- The report of a notification cannot be generated. To get the reports that were completed, call this endpoint again with
PACKAGEand the same notifications. Keep in mind thatPACKAGEtakes the latest completed report of each notification, even one generated before the first process: if the new report of a notification did not finish and the notification already had a completed report, the ZIP file includes that earlier report and the notification is listed incompletedIds. To find these cases, compare thereportIdof each notification in the response to thePACKAGEcall with the one in the response to the first call: when they differ, the report in the ZIP file is an earlier one. - One of its notifications is deleted before the process finishes (see Delete bulk notifications). Deleting a notification deletes every bulk report process that contains it, or that contains a report it shares with other notifications, whatever its status.
HTTP Request
POST /api/v1/private/bulk/reports
Example Request Body
{
"mode": "GENERATE_AND_PACKAGE",
"template": "NOTIFICATION",
"embedAttachmentsEnabled": true,
"notifications": [
{
"notificationId": "55fc5ab7-2345-41fd-8688-6d04acf2b5bc",
"languageCode": "es",
"additionalData": {
"qrUrl": "https://example.com/qr/55fc5ab7"
}
},
{
"notificationId": "86b26824-f646-406d-b039-cdb142d46cd4",
"languageCode": "en"
}
]
}
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| mode | Yes | string | What the process does. Possible values: GENERATE, GENERATE_AND_PACKAGE, PACKAGE. |
| template | Yes (GENERATE, GENERATE_AND_PACKAGE) | string | Template to use for the generation of every report. Ignored in PACKAGE. |
| embedAttachmentsEnabled | No | boolean | If true, the notification attachments are embedded in every report. If not provided, the configuration of your tenant applies. Ignored in PACKAGE. |
| notifications | Yes | array of objects | Notifications to work on, one entry per notification. A notification cannot appear twice. Maximum 300 notifications per call by default; the limit is configured for each tenant. |
| notifications[].notificationId | Yes | string (UUID) | Notification identifier. |
| notifications[].languageCode | Yes (GENERATE, GENERATE_AND_PACKAGE) | string | Language of the report of this notification. Possible values: es, en (lowercase). Any other value produces the report in Spanish. Ignored in PACKAGE. |
| notifications[].additionalData | No | object (string values) | Additional data to be used in the generation of the report of this notification (for example, qrUrl). The keys embedAttachmentsEnabled, embedMaxPages and embedMaxSizeMb are ignored: use embedAttachmentsEnabled of the request instead. Ignored in PACKAGE. |
Response: 201 Bulk report process started
Example Response
{
"bulkReportProcessId": "0e9ee9f6-25d1-4dbd-8f27-e582d5b6f4a2",
"mode": "GENERATE_AND_PACKAGE",
"status": "STARTED",
"reports": [
{
"notificationId": "55fc5ab7-2345-41fd-8688-6d04acf2b5bc",
"reportId": "9b11ee36-9d70-44f3-9fd1-3138dae8f2a6"
},
{
"notificationId": "86b26824-f646-406d-b039-cdb142d46cd4",
"reportId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
]
}
In GENERATE and GENERATE_AND_PACKAGE, reportId is the new report of each notification, which you can also download on its own with Get report PDF download URL once it is ready. In PACKAGE, reportId is the latest completed report of each notification, which is the one selected for the ZIP file. A notification without a completed report has no reportId: it is left out of the ZIP file and listed in missingIds of the webhook.
Error: 400 Bad request. The whole request is rejected, and no report is generated, when:
modeis missing or has a value other than the three above.notificationsis empty, has an empty entry or an entry withoutnotificationId, or has more entries than the maximum allowed. In the last case, the error message gives the maximum for your tenant.- A notification does not exist, appears more than once, is being deleted, is still in DRAFT, or was not sent with a provider that supports reports (NOTICEMAN or SCASC).
- In GENERATE or GENERATE_AND_PACKAGE,
templateor thelanguageCodeof a notification is missing or blank, or a SCASC notification has no evidence that can be retrieved for its report. - In PACKAGE, none of the notifications has a completed report.
In the third and fourth cases of the list above, the error message starts with Bulk report rejected: and lists every problem found, separated by ; (a semicolon and a space), as <notificationId>: <reason> or template: REQUIRED, for example Bulk report rejected: 55fc5ab7-2345-41fd-8688-6d04acf2b5bc: NOT_FOUND; 86b26824-f646-406d-b039-cdb142d46cd4: DRAFT. The reasons are NOT_FOUND, DUPLICATED, DELETION_IN_PROGRESS, DRAFT, PROVIDER_NOT_SUPPORTED, SCASC_EVIDENCE_NOT_RETRIEVABLE and LANGUAGE_CODE_REQUIRED. The other cases have their own error message.
Error: 409 Bulk report not configured for the tenant. Your tenant has no maximum of notifications configured, so it cannot start bulk report processes.
Get bulk reports ZIP download URL
This endpoint returns the URL and expiration time to download the ZIP file built by a bulk report process in GENERATE_AND_PACKAGE or PACKAGE mode. The ZIP file is ready when the Bulk reports webhook arrives with status COMPLETED; until then, the response is an empty list.
The ZIP file contains only the PDF of each report, at its root, with no folders and no report packages. Each PDF is named <subject>_<recipient>_Certificate_<id>.pdf, where <subject> is the subject of its notification shortened to the report name length configured for your tenant, <recipient> is the recipient of its notification shortened to twice that length, and <id> is the first 8 characters of its reportId, for example Payment reminder_Recipient Name_Certificate_9b11ee36.pdf. In the subject and the recipient, the characters that are not valid in Windows file names (/ \ : * ? " < > |) and the control characters are replaced by _, and trailing dots and spaces are removed; a notification without subject gives a name that starts with _. If your tenant has no report name length configured, each PDF is named <reportId>.pdf. In both cases, the name before .pdf is cut to 200 characters and loses any dots and spaces at its beginning and end. If two PDFs of the same ZIP file get the same name, ignoring case, _2, _3 and so on are added before .pdf from the second one, for example Payment reminder_Recipient Name_Certificate_9b11ee36_2.pdf. A report shared by several notifications is included only once.
The download URL expires at the time given in expiration; after that, call this endpoint again to get a new one. The ZIP file itself does not expire, but it is deleted, together with its bulk report process, when one of its notifications, or another notification that shares one of its reports, is deleted.
HTTP Request
GET /api/v1/private/bulk/reports/{bulkReportProcessId}/file
Where
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| bulkReportProcessId | Yes | string (UUID) | Bulk report process identifier, as returned by Generate or package reports in bulk. (Required) |
Example Response
[
{
"url": "http://example.io",
"expiration": "2023-10-23T10:34:59.483Z"
}
]
Error: 404 Bulk report process not found or without ZIP. It is returned when the process does not exist or has been deleted, and for a process in GENERATE mode, because it has no ZIP file.
Error: 409 Bulk report process ended in ERROR without package. The process ended with status ERROR, so its ZIP file was never built. Start a new bulk report process to get the ZIP file.
Bulk reports webhook
When a bulk report process finishes, its result is sent as an HTTP POST request to the webhook URLs configured for reports at client level. The request carries a Tenant header with the name of your tenant and, if a token is configured for your webhook, the Authorization header. The JSON body has two fields:
eventType: always NotificationReportBulkProcessCompletedEvent for this webhook.data: the result of the process.
{
"eventType": "NotificationReportBulkProcessCompletedEvent",
"data": {
"bulkReportProcessId": "0e9ee9f6-25d1-4dbd-8f27-e582d5b6f4a2",
"mode": "PACKAGE",
"status": "COMPLETED",
"totalNotifications": 3,
"completedCount": 2,
"missingCount": 1,
"completedIds": [
"55fc5ab7-2345-41fd-8688-6d04acf2b5bc",
"86b26824-f646-406d-b039-cdb142d46cd4"
],
"missingIds": [
"e694c179-e503-4101-992e-329700c37adc"
]
}
}
A process sends it at most once, when it finishes; a process that does not finish sends none (see Generate or package reports in bulk). It is sent:
- In
GENERATE, withstatusCOMPLETED, when the reports of all the notifications have been generated. - In
GENERATE_AND_PACKAGEandPACKAGE, withstatusCOMPLETED when the ZIP file is ready to download with Get bulk reports ZIP download URL, or withstatusERROR when the ZIP file cannot be built. A process in ERROR has no ZIP file; to build it again, call Generate or package reports in bulk withPACKAGEand the same notifications.
In GENERATE and GENERATE_AND_PACKAGE, each report of the process also sends its own webhook to the same URLs, as when it is generated on its own: its eventType is NotificationReportGenerationProcessTransitToCompletedEvent and its data has the reportId. Use eventType to tell both kinds apart.
The fields of data are the same with both values of status:
| Parameter | Mandatory | Datatype | Description |
|---|---|---|---|
| bulkReportProcessId | Yes | string (UUID) | Identifier returned by Generate or package reports in bulk. |
| mode | Yes | string | Mode of the request. Possible values: GENERATE, GENERATE_AND_PACKAGE, PACKAGE. |
| status | Yes | string | Result of the process. Possible values: COMPLETED, ERROR. ERROR only happens in GENERATE_AND_PACKAGE and PACKAGE, when the ZIP file cannot be built. |
| totalNotifications | Yes | integer | Number of notifications in the request. |
| completedCount | Yes | integer | Number of notifications in completedIds. |
| completedIds | Yes | array of string (UUID) | Notifications with a report in the process, in ascending order: all of them in GENERATE and GENERATE_AND_PACKAGE, and those with a completed report in PACKAGE. If the PDF of one of these reports cannot be found when the ZIP file is built, the ZIP file is built without it and its notification is still listed here. |
| missingCount | Yes | integer | Number of notifications in missingIds. Always 0 in GENERATE and GENERATE_AND_PACKAGE. |
| missingIds | No | array of string (UUID) | Only in PACKAGE: notifications left out of the ZIP file because they have no completed report, in ascending order. It is not present when there are none, so it never appears in GENERATE and GENERATE_AND_PACKAGE. |