Notification operations



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 PACKAGE and the same notifications. Keep in mind that PACKAGE takes 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 in completedIds. To find these cases, compare the reportId of each notification in the response to the PACKAGE call 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:

  • mode is missing or has a value other than the three above.
  • notifications is empty, has an empty entry or an entry without notificationId, 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, template or the languageCode of 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, with status COMPLETED, when the reports of all the notifications have been generated.
  • In GENERATE_AND_PACKAGE and PACKAGE, with status COMPLETED when the ZIP file is ready to download with Get bulk reports ZIP download URL, or with status ERROR 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 with PACKAGE and 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.