Pull Notifications API
Date | Amount |
---|---|
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
Get a list of unpulled notification identifiers for a given conversation by calling
GET /notifications/conversationId/{conversationId}/unpulled
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.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.
Endpoints
/notifications/conversationId/{conversationId}
Get all notifications for a conversation
GET
Get a list of all notification identifiers for the given conversation identifier.
Path parameters
Name | Description |
---|---|
conversationId
string
required
|
Conversation identifier UUID
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the version of the API that you want to call. See versioning. 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
Path parameters
Name | Description |
---|---|
conversationId
string
required
|
Conversation identifier UUID
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the version of the API that you want to call. See versioning. 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
Path parameters
Name | Description |
---|---|
conversationId
string
required
|
Conversation identifier UUID
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the version of the API that you want to call. See versioning. 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
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the version of the API that you want to call. See versioning. 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
Path parameters
Name | Description |
---|---|
notificationId
string
required
|
Notification identifier UUID
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the version of the API that you want to call. See versioning. 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
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the version of the API that you want to call. See versioning. 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
Path parameters
Name | Description |
---|---|
notificationId
string
required
|
Notification identifier UUID
For example: |
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the version of the API that you want to call. See versioning. 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.
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the version of the API that you want to call. See versioning. 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.
Request headers
Name | Description |
---|---|
Accept
required
|
Specifies the version of the API that you want to call. See versioning. 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