This version is in beta - expect some breaking changes.

Pull Notifications API

Version and status
Available in Sandbox Yes
Sandbox base URL https://test-api.service.hmrc.gov.uk
Available in Production Yes
Production base URL https://api.service.hmrc.gov.uk

Overview

Use this API to “pull” business event notifications that CDS generates in response to requests submitted using the CDS APIs.

When a declaration is submitted to a CDS API a HTTP status code 202 is returned. As the declaration is processed notifications are generated.

If a callback URL was provided when subscribing to the CDS API the notifications are pushed to that URL.

If a callback URL was not provided when subscribing to the CDS API the notifications are sent to this pull queue.

Pull notifications remain queued for 14 days after which they are deleted from the queue automatically.

You can get all of the notifications for your application, or you can get them for a given conversation. We recommend getting them by conversation.

Getting notifications for a given conversation

  1. Get a list of unpulled notification identifiers for a given conversation by calling GET /notifications/conversationId/{conversationId}/unpulled

  2. Iterate over this list of notification identifiers and get each unpulled notification from the unpulled queue by calling GET /notifications/unpulled/{notificationId}. When you get a notification from the unpulled queue, it will move to the pulled queue.

  3. To get a notification again after you have retrieved it, get it from the pulled queue by calling GET /notifications/pulled/{notificationId}

Versioning

When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.

Errors

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

  • 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
  • 400 to 499 if it failed because of a client error by your application
  • 500 to 599 if it failed because of an error on our server

Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.

Testing

You can use the sandbox environment to test this API.

Skip to main content

Endpoints

/notifications/conversationId/{conversationId}

Get all notifications for a conversation
GET

Get a list of all notification identifiers for the given conversation identifier.

Authorisation

This endpoint is application-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token.

Path parameters

Name Description
conversationId
string
required

Conversation identifier UUID

For example: 1446a875-eaa1-4d7a-903e-0604166d9557

Request headers

Name Description
Accept
required

Specifies the version of the API that you want to call. See versioning.

For example: application/vnd.hmrc.1.0+xml
Authorization
required
 An OAuth 2.0 Bearer Token.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Responses

HTTP status 200 (OK)

<resource href="/notifications/conversationId/4cdc771e-c77a-438f-b293-e11ac4cc4e2e/">
    <link rel="self" href="/notifications/conversationId/4cdc771e-c77a-438f-b293-e11ac4cc4e2e"/>
    <link rel="notification" href="/notifications/unpulled/7ab99957-b138-4f09-888e-ab4e8107bbe0"/>
    <link rel="notification" href="/notifications/pulled/1b941d3a-84cd-4127-a80f-36fa1f019359"/>
</resource>


Close Section
/notifications/conversationId/{conversationId}/unpulled

Get unpulled notifications for a conversation
GET

Get a list of unpulled notification identifiers for the given conversation identifier

Authorisation

This endpoint is application-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token.

Path parameters

Name Description
conversationId
string
required

Conversation identifier UUID

For example: 1446a875-eaa1-4d7a-903e-0604166d9557

Request headers

Name Description
Accept
required

Specifies the version of the API that you want to call. See versioning.

For example: application/vnd.hmrc.1.0+xml
Authorization
required
 An OAuth 2.0 Bearer Token.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Responses

HTTP status 200 (OK)

<resource href="/notifications/unpulled/">
    <link rel="self" href="/notifications/unpulled/"/>
    <link rel="notification" href="/notifications/unpulled/7ab99957-b138-4f09-888e-ab4e8107bbe0"/>
</resource>


Close Section
/notifications/conversationId/{conversationId}/pulled

Get pulled notifications for a conversation
GET

Get a list of pulled notification identifiers for the given conversation identifier

Authorisation

This endpoint is application-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token.

Path parameters

Name Description
conversationId
string
required

Conversation identifier UUID

For example: 1446a875-eaa1-4d7a-903e-0604166d9557

Request headers

Name Description
Accept
required

Specifies the version of the API that you want to call. See versioning.

For example: application/vnd.hmrc.1.0+xml
Authorization
required
 An OAuth 2.0 Bearer Token.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Responses

HTTP status 200 (OK)

<resource href="/notifications/pulled/">
    <link rel="self" href="/notifications/pulled/"/>
    <link rel="notification" href="/notifications/pulled/7ab99957-b138-4f09-888e-ab4e8107bbe0"/>
</resource>


Close Section
/notifications/unpulled

Get unpulled notifications
GET

Get a list of unpulled notification identifiers for the subscribed application

Authorisation

This endpoint is application-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token.

Request headers

Name Description
Accept
required

Specifies the version of the API that you want to call. See versioning.

For example: application/vnd.hmrc.1.0+xml
Authorization
required
 An OAuth 2.0 Bearer Token.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Responses

HTTP status 200 (OK)

<resource href="/notifications/unpulled/">
    <link rel="self" href="/notifications/unpulled/"/>
    <link rel="notification" href="/notifications/unpulled/7ab99957-b138-4f09-888e-ab4e8107bbe0"/>
</resource>


Close Section
/notifications/unpulled/{notificationId}

Get an unpulled notification
GET

Get an unpulled notification with the given notification identifier

Authorisation

This endpoint is application-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token.

Path parameters

Name Description
notificationId
string
required

Notification identifier UUID

For example: 3851c039-107a-42c9-94a9-180893e5f0d5

Request headers

Name Description
Accept
required

Specifies the version of the API that you want to call. See versioning.

For example: application/vnd.hmrc.1.0+xml
Authorization
required
 An OAuth 2.0 Bearer Token.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Responses

HTTP status 200 (OK)

<?xml version="1.0" encoding="UTF-8"?>
<_2:MetaData xmlns:_2="urn:wco:datamodel:WCO:DocumentMetaData-DMS:2"><_2:WCODataModelVersionCode>3.6</_2:WCODataModelVersionCode><_2:WCOTypeName>RES</_2:WCOTypeName><_2:ResponsibleCountryCode/><_2:ResponsibleAgencyName/><_2:AgencyAssignedCustomizationCode/><_2:AgencyAssignedCustomizationVersionCode/><_2_1:Response xmlns:_2_1="urn:wco:datamodel:WCO:RES-DMS:2">
      <_2_1:FunctionCode>03</_2_1:FunctionCode>
      <_2_1:FunctionalReferenceID>0f3ec64eec704999995ddf5a3ca9cc0b</_2_1:FunctionalReferenceID>
      <_2_1:IssueDateTime>
        <_2_2:DateTimeString formatCode="304" xmlns:_2_2="urn:wco:datamodel:WCO:Response_DS:DMS:2">20190220165953Z</_2_2:DateTimeString>
      </_2_1:IssueDateTime>
      <_2_1:Error>
        <_2_1:ValidationCode>CDS12014</_2_1:ValidationCode>
        <_2_1:Pointer>
          <_2_1:DocumentSectionCode>42A</_2_1:DocumentSectionCode>
          <_2_1:TagID>D013</_2_1:TagID>
        </_2_1:Pointer>
      </_2_1:Error>
      <_2_1:Error>
        <_2_1:ValidationCode>CDS12015</_2_1:ValidationCode>
        <_2_1:Pointer>
          <_2_1:DocumentSectionCode>42A</_2_1:DocumentSectionCode>
          <_2_1:TagID>D014</_2_1:TagID>
        </_2_1:Pointer>
      </_2_1:Error>
      <_2_1:Declaration>
        <_2_1:FunctionalReferenceID>gq8lPty99999NLgUQMSAmg</_2_1:FunctionalReferenceID>
        <_2_1:ID>19GB20GF2F99999VR4</_2_1:ID>
        <_2_1:RejectionDateTime>
          <_2_2:DateTimeString formatCode="304" xmlns:_2_2="urn:wco:datamodel:WCO:Response_DS:DMS:2">20190220165953Z</_2_2:DateTimeString>
        </_2_1:RejectionDateTime>
        <_2_1:VersionID>1</_2_1:VersionID>
      </_2_1:Declaration>
    </_2_1:Response>
</_2:MetaData>

HTTP status 400 (Bad Request)

<?xml version="1.0" encoding="UTF-8"?>
<errorResponse>
  <code>BAD_REQUEST</code>
  <message>Notification is unpulled</message>
</errorResponse>

HTTP status 404 (Not Found)

<?xml version="1.0" encoding="UTF-8"?>
<errorResponse>
  <code>NOT_FOUND</code>
  <message>Resource was not found</message>
</errorResponse>

Error scenarios

Scenario HTTP status Code

Invalid XML Payload

400 (Bad Request)

BAD_REQUEST

Invalid XML Payload

404 (Not Found)

NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section
/notifications/pulled

Get pulled notifications
GET

Get a list of pulled notification identifiers for the subscribed application

Authorisation

This endpoint is application-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token.

Request headers

Name Description
Accept
required

Specifies the version of the API that you want to call. See versioning.

For example: application/vnd.hmrc.1.0+xml
Authorization
required
 An OAuth 2.0 Bearer Token.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Responses

HTTP status 200 (OK)

<resource href="/notifications/pulled/">
    <link rel="self" href="/notifications/pulled/"/>
    <link rel="notification" href="/notifications/pulled/7ab99957-b138-4f09-888e-ab4e8107bbe0"/>
</resource>


Close Section
/notifications/pulled/{notificationId}

Get a pulled notification
GET

Get a pulled notification with the given notification identifier

Authorisation

This endpoint is application-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token.

Path parameters

Name Description
notificationId
string
required

Notification identifier UUID

For example: 3851c039-107a-42c9-94a9-180893e5f0d5

Request headers

Name Description
Accept
required

Specifies the version of the API that you want to call. See versioning.

For example: application/vnd.hmrc.1.0+xml
Authorization
required
 An OAuth 2.0 Bearer Token.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Responses

HTTP status 200 (OK)

<?xml version="1.0" encoding="UTF-8"?>
<_2:MetaData xmlns:_2="urn:wco:datamodel:WCO:DocumentMetaData-DMS:2"><_2:WCODataModelVersionCode>3.6</_2:WCODataModelVersionCode><_2:WCOTypeName>RES</_2:WCOTypeName><_2:ResponsibleCountryCode/><_2:ResponsibleAgencyName/><_2:AgencyAssignedCustomizationCode/><_2:AgencyAssignedCustomizationVersionCode/><_2_1:Response xmlns:_2_1="urn:wco:datamodel:WCO:RES-DMS:2">
      <_2_1:FunctionCode>03</_2_1:FunctionCode>
      <_2_1:FunctionalReferenceID>0f3ec64eec704999995ddf5a3ca9cc0b</_2_1:FunctionalReferenceID>
      <_2_1:IssueDateTime>
        <_2_2:DateTimeString formatCode="304" xmlns:_2_2="urn:wco:datamodel:WCO:Response_DS:DMS:2">20190220165953Z</_2_2:DateTimeString>
      </_2_1:IssueDateTime>
      <_2_1:Error>
        <_2_1:ValidationCode>CDS12014</_2_1:ValidationCode>
        <_2_1:Pointer>
          <_2_1:DocumentSectionCode>42A</_2_1:DocumentSectionCode>
          <_2_1:TagID>D013</_2_1:TagID>
        </_2_1:Pointer>
      </_2_1:Error>
      <_2_1:Error>
        <_2_1:ValidationCode>CDS12015</_2_1:ValidationCode>
        <_2_1:Pointer>
          <_2_1:DocumentSectionCode>42A</_2_1:DocumentSectionCode>
          <_2_1:TagID>D014</_2_1:TagID>
        </_2_1:Pointer>
      </_2_1:Error>
      <_2_1:Declaration>
        <_2_1:FunctionalReferenceID>gq8lPty99999NLgUQMSAmg</_2_1:FunctionalReferenceID>
        <_2_1:ID>19GB20GF2F99999VR4</_2_1:ID>
        <_2_1:RejectionDateTime>
          <_2_2:DateTimeString formatCode="304" xmlns:_2_2="urn:wco:datamodel:WCO:Response_DS:DMS:2">20190220165953Z</_2_2:DateTimeString>
        </_2_1:RejectionDateTime>
        <_2_1:VersionID>1</_2_1:VersionID>
      </_2_1:Declaration>
    </_2_1:Response>
</_2:MetaData>

HTTP status 400 (Bad Request)

<?xml version="1.0" encoding="UTF-8"?>
<errorResponse>
  <code>BAD_REQUEST</code>
  <message>Notification is unpulled</message>
</errorResponse>

HTTP status 404 (Not Found)

<?xml version="1.0" encoding="UTF-8"?>
<errorResponse>
  <code>NOT_FOUND</code>
  <message>Resource was not found</message>
</errorResponse>

Error scenarios

Scenario HTTP status Code

Invalid XML Payload

400 (Bad Request)

BAD_REQUEST

Invalid XML Payload

404 (Not Found)

NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section
/notifications

Get all available notifications (deprecated)
GET

This endpoint has been deprecated. It will be removed in a future release.

Get a list of all notification identifiers for the subscribed application.

Authorisation

This endpoint is application-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token.

Request headers

Name Description
Accept
required

Specifies the version of the API that you want to call. See versioning.

For example: application/vnd.hmrc.1.0+xml
Authorization
required
 An OAuth 2.0 Bearer Token.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Responses

HTTP status 200 (OK)

<resource href="/notifications/">
    <link rel="self" href="/notifications/"/>
    <link rel="notification" href="/notifications/7ab99957-b138-4f09-888e-ab4e8107bbe0"/>
</resource>


Close Section
/notifications/{id}

Retrieve and delete a notification from the queue (deprecated)
DELETE

This endpoint has been deprecated. It will be removed in a future release.

Get a notification with the given notification identifier. The notification will be returned in the response body and then deleted from the queue.

Authorisation

This endpoint is application-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token.

Request headers

Name Description
Accept
required

Specifies the version of the API that you want to call. See versioning.

For example: application/vnd.hmrc.1.0+xml
Authorization
required
 An OAuth 2.0 Bearer Token.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Responses

HTTP status 200 (OK)

<example>
  Saved Message
</example>


Close Section

Skip to main content

Is this page not working properly? (opens in new tab)