Garrigues Notifications API Documentation

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.

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": true
                    }

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: EMAIL, NOTICEMAN, SMS, WFB.
data.smtp No object Required when data.provider is EMAIL. Contains SMTP notification data.
data.smtp.receiver No array of objects Required when data.provider is EMAIL. Each recipient object includes:
address (required, string, email): Recipient email address.
name (optional, string): Recipient name.
type (optional, string): Recipient type (TO, CC, BCC).
data.smtp.subject No string Required when data.provider is EMAIL. Notification subject.
data.smtp.attachments No array of objects Optional attachments for EMAIL. Each attachment includes:
filename (required, string): Attachment file name.
hash (required, string): File hash (SHA256).
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.
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.
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).
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.
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.

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

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.

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
id No string (UUID) Notification identifier. (Optional filter)
requestId No string (UUID) Request identifier to correlate notifications. (Optional filter)
states No array of string Filter notifications by state. Possible values: DRAFT, ACTIVE, DISPATCHED, DISPATCH_FAILED, DELIVERING, ERROR, SENT, OPEN, READ, ACCEPTED, NOT_ACCEPTED, RECEIVED_CONFORMING, RECEIVED_NON_CONFORMING, ANSWERED, CANCELLED.
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.noticeman.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",
                      "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"
                    }

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

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: EMAIL, NOTICEMAN, SMS, WFB.
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 (EMAIL, NOTICEMAN).
receivers[].phone No string Recipient phone for 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: EMAIL, NOTICEMAN.
data.smtp.subject No string Updated subject when data.provider is EMAIL.
data.noticeman.subject No string Updated subject when data.provider is NOTICEMAN.
data.noticeman.sender No object Updated sender when data.provider is NOTICEMAN. Includes:
address (required, string, email): Sender email.
name (optional, string): Sender name.
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.

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

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

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"
                      }
                    ]

Response: 307 Temporary Redirect

Error: 404 Document not found

Generate notification report

This endpoint starts the notification report generation process.

HTTP Request

POST /api/v1/private/reports

Example Request Body

{
                      "requestId": "e694c179-e503-4101-992e-329700c37adc",
                      "template": "notification",
                      "languageCode": "es_ES",
                      "notificationIds": [
                        "55fc5ab7-2345-41fd-8688-6d04acf2b5bc"
                      ],
                      "additionalData": {
                        "key1": "value1"
                      }
                    }

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.

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