Check notifications

Notifications provide status updates as your documents progress through processing stages.

After you submit a document, Sovos generates notifications at each processing stage. You can use the notifications API for the following tasks:

Retrieve notifications to check document status
Understand the notification response structure and metadata
Process notifications and handle duplicates or out-of-order delivery
Mark notifications as read to keep polling results current

Retrieve notifications

Sovos provides multiple endpoints to retrieve notifications based on country, document, or notification ID.

After you submit a document, Sovos sends notifications as the document progresses through processing stages. Retrieve notifications to monitor document status and extract attachments.

Notification endpoints


Endpoint	Use when	Returns
`GET /notifications/{countryCode}`	Check for new notifications across all documents	Unread notifications only (default)
`GET /notifications/{countryCode}?includeAcknowledged=true`	Retrieve all notifications including already-read ones	All notifications
`GET /documents/{countryCode}/{documentId}/notifications`	Get all notifications for a specific document	All notifications for that document
`GET /notifications/{countryCode}/{notificationId}`	Retrieve a specific notification	Single notification

Note:

GET /notifications/{countryCode} returns only unread notifications by default. Mark notifications as read after processing to prevent retrieving them again.

Important:

Configure notifications for each product to define which status codes trigger them. Without configuration, documents still progress through their lifecycle, but polling the notifications endpoint returns no results. The Configure Product article covers notification setup details.

Query parameters

Pagination


Parameter	Description	Default
`page`	Page number	`1`
`perPage`	Results per page	`10`

Filtering


Parameter	Description	Default
`includeAcknowledged`	Include read notifications	`false`
`status`	Filter by read or unread status	—

Notification response structure

The notification response contains pagination information and an array of notification objects with metadata.

Response format

{
  "timestamp": 1601669463,
  "status": 200,
  "success": true,
  "message": "Notifications Listed",
  "data": {
    "pageState": {
      "page": 1,
      "perPage": 10,
      "totalEntries": 55
    },
    "notifications": [
      {
        "notificationId": "f2fa3f84-ba97-4e7a-9c02-85e468cc7012",
        "createdDate": 1601025028,
        "appPrefix": "INV",
        "content": "PEFwcGxpY2F0aW9uUmVzcG9uc2U+...base64...</ApplicationResponse>",
        "metadata": {
          "productId": "pl_Faktura",
          "documentId": "637366217796159052",
          "erpDocumentId": "INV-2024-001",
          "erpSystemId": "SAP-ERP",
          "processType": "0",
          "taxId": "1234567890",
          "sciCloudStatusCode": "200",
          "sciResponseCode": "AP",
          "sciStatusAction": "NOA"
        }
      }
    ]
  }
}

Note:

The example shown is simplified for clarity. Your response might include additional fields depending on the country and processing stage.

Response fields

Top level


Field	Type	Description
`timestamp`	Integer	Unix time stamp of the response
`status`	Integer	HTTP status code
`success`	Boolean	Request success indicator
`message`	String	Human-readable message
`data`	Object	Contains pagination state and the notifications array

Pagination (pageState)


Field	Type	Description
`page`	Integer	Current page number
`perPage`	Integer	Results per page
`totalEntries`	Integer	Total notifications available

Notification object


Field	Type	Description
`notificationId`	String (UUID)	Unique notification identifier
`createdDate`	Integer	Unix time stamp when the notification was created
`appPrefix`	String	Application prefix (for example, "INV")
`content`	String	Base64-encoded ApplicationResponse XML
`metadata`	Object	Document processing details

Note:

The content field contains the complete ApplicationResponse XML with status codes and attachments. The Application Responses and Status Codes article covers how to interpret the response content.

Metadata fields


Field	Type	Description
`productId`	String	Product identifier
`documentId`	String	Sovos-generated document ID
`erpDocumentId`	String	Your ERP document reference
`erpSystemId`	String	Source ERP system identifier
`processType`	String	Document direction: `"0"` = outbound, `"1"` = inbound
`taxId`	String	Company tax ID
`sciCloudStatusCode`	String	Current processing status
`sciResponseCode`	String	Overall compliance status
`sciStatusAction`	String	Action required

Notification parameters

Each notification includes guaranteed and optional metadata parameters depending on the processing stage.

Guaranteed parameters

These fields are always present in every notification per the API schema:


Field	Type	Description
`productId`	String	Product identifier
`documentId`	String	Sovos-generated document ID
`erpDocumentId`	String	Your ERP document reference
`erpSystemId`	String	Source ERP system identifier
`processType`	String	Direction ("0" = outbound, "1" = inbound)

Optional parameters

These fields may be absent depending on the processing stage:


Field	Type	Description
`taxId`	String	Company Tax ID
`sciCloudStatusCode`	String	Current processing status (typically present)
`sciResponseCode`	String	Overall compliance status (typically present) Uses status codes also documented in the Understanding Application Responses and Status Codes article.
`sciGovtStatusCode`	String	Tax authority response code
`sciStatusAction`	String	Action required Uses status codes also documented in the Understanding Application Responses and Status Codes article.

Tip:

For information about handling errors such as 4xx and 5xx responses, and retry strategies, see Error handling.

Process notifications

Implement safeguards to prevent duplicate processing and handle notifications that arrive out of order.

Prevent duplicate processing

If your system polls frequently or has multiple instances retrieving notifications, track processed notifications to avoid duplicate handling:

const processedNotifications = new Set()

function processNotification(notification) {
  // Skip if already processed
  if (processedNotifications.has(notification.notificationId)) {
    return
  }
  
  // Process the notification
  handleNotification(notification)
  
  // Mark as processed
  processedNotifications.add(notification.notificationId)
}

Tip:

Apply duplicate processing prevention to systems with multiple polling instances or very frequent polling intervals. Single-instance implementations that mark notifications as read immediately after processing typically don't need it.

Handle out-of-order delivery

Notifications may arrive out of sequence. Use the createdDate time stamp to order them chronologically:

function processNotifications(notifications) {
  // Sort by creation timestamp
  notifications.sort((a, b) => a.createdDate - b.createdDate)
  
  // Process in chronological order
  for (const notification of notifications) {
    processNotification(notification)
  }
}

Poll for notifications

Poll the notifications endpoint to check for new status updates across all your documents.

Use the following pattern to poll for notifications, process them, and mark them as read:

async function pollForNotifications(countryCode) {
  const response = await fetch(`/notifications/${countryCode}?perPage=50`)
  const data = await response.json()
  
  if (data.success && data.data.notifications.length > 0) {
    // Process notifications
    processNotifications(data.data.notifications)
    
    // Mark as read
    const ackPayload = data.data.notifications.map(n => ({
      status: "read",
      notificationId: n.notificationId
    }))
    
    await acknowledgeNotifications(countryCode, ackPayload)
  }
  
  return data.data.notifications
}

Pagination

If totalEntries exceeds perPage, retrieve additional pages:

async function getAllNotifications(countryCode) {
  let allNotifications = []
  let page = 1
  let hasMore = true
  
  while (hasMore) {
    const response = await fetch(
      `/notifications/${countryCode}?page=${page}&perPage=50`
    )
    const data = await response.json()
    
    allNotifications.push(...data.data.notifications)
    
    const { page: currentPage, perPage, totalEntries } = data.data.pageState
    hasMore = (currentPage * perPage) < totalEntries
    page++
  }
  
  return allNotifications
}

Alternative: Poll transmission status

For real-time tracking of a specific document immediately after submission, you can poll the transmission status endpoint with the jobState parameter. This provides active status checking rather than waiting for the system to generate notifications.

Your country implementation guide covers transmission status polling guidance and intervals.

Mark notifications as read

Mark notifications as read after processing to prevent retrieving them again in future polls.

Use the PUT /notifications/{countryCode} endpoint to acknowledge notifications after you process them.

Send a PUT request to /notifications/{countryCode} with an array of objects that contain the notificationId and status set to "read".

Request format:

[
  {
    "status": "read",
    "notificationId": "834723c7-8069-406c-8e75-948b5299c677"
  },
  {
    "status": "read",
    "notificationId": "d824a530-5666-4b3c-aaf1-003f68659f3c"
  }
]

Verify that the response returns a success value of true.

Expected response:

{
  "timestamp": 1601673284,
  "status": 200,
  "success": true,
  "message": "Notifications acknowledged successfully."
}

After you mark notifications as read, they do not appear in GET /notifications/{countryCode} requests, which return unread notifications by default. To retrieve read notifications, add includeAcknowledged=true to your request.

For per-notification status reporting in large batches, use the PUT /notifications/{countryCode}/bulk endpoint. This returns HTTP 207 Multi-Status with results for each notification.

Sovos Docs

Check notifications

Retrieve notifications

Notification endpoints

Query parameters

Notification response structure

Response format

Response fields

Notification parameters

Guaranteed parameters

Optional parameters

Process notifications

Prevent duplicate processing

Handle out-of-order delivery

Poll for notifications

Alternative: Poll transmission status

Mark notifications as read

sovos-footer