logo

CDS API for Developers (2024.0.0)

Download OpenAPI specification:Download

URL: https://upu.int/api License: Internal Terms of Service

CDS API for Developers.

Universal Postal Union
International Bureau
Weltpoststrasse 4
3000 Bern 15
Switzerland

CDS API Service Interface

User Access

User access methods

Login

Authenticate the user and password and return a session token access.

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

userCd
required
string

UserId to authentication

officeCd
string

Current office for session (optional)

password
required
string

Security password to authentucation

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/Login
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "userCd": "user_cd",
  • "officeCd": "DEAAAA",
  • "password": "xxxxxx"
}
Response samples
application/json
{
  • "SecurityKey": "6d2fce81-5420-4f05-80ec-4894b3166c1e",
  • "Office": "DEAAAA",
  • "AllowedOffices": [
    ]
}

Logout

Terminate the authentication session and removes the tempoarary token

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

userCd
required
string

UserId to authentication

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/Logout
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "userCd": "user_cd"
}
Response samples
application/json
{ }

Anonymous Declarations

Anonymous Declarations are declarations done by end user, before mail acceptance, without being associated yet to a mail item ID.

Convert Anonymous To CDS Declaration

Transforms an anonymous declaration into a real CDS declaration so that ITMATT can be sent to the destination post

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

anonymousDeclarationId
required
string

Id of the anonymous declaration (e.g. 9384748AU for an anonymous declaration created at Australia Post)

internationalItemId
string

The id of the mail object. If missing, the id of the declaration will also be the id of the mail item in the ITMATT messages

userCd
required
string

The user code that will author the creation of the customs response (if applicable). If the user code does not exist in CDS, it will be automatically created and linked to the organization that issued the security token.

officeCd
string

The office code that will author the creation of the customs response (if applicable)

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/ConvertAnonymousToCDSDeclaration
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "anonymousDeclarationId": "9384748AU",
  • "internationalItemId": "EE23050001XAU",
  • "userCd": "depost",
  • "officeCd": "DEAAAA"
}
Response samples
application/json
{ }

Create Or Update Anonymous Declaration

Creates/updates an anonymous declaration

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

object (AnonymousDeclaration)

Anonymous declaration to create/update.

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/CreateOrUpdateAnonymousDeclaration
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "anonymousDeclaration": {
    }
}
Response samples
application/json
{
  • "CreateOrUpdateAnonymousDeclarationResult": "string"
}

Get Anonymous Declaration

Return non-converted anonymous declarations based on a list of criteria passed as parameters

Request
Request Body schema: application/json
required

At least one of the non-required parameters has to be provided.

securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

required
object (SearchCriteria)
Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/GetAnonymousDeclaration
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "searchCriteria": {
    }
}
Response samples
application/json
{
  • "GetAnonymousDeclarationResult": [
    ]
}

Get Final Declaration Id From Anonymous Declaration Id

Searches for the final declaration Id from an anonymous declaration Id

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

anonymousDeclId
required
string

The anonymous declaration Id

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/GetFinalDeclarationIdFromAnonymousDeclarationId
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "anonymousDeclId": "9384748AU"
}
Response samples
application/json
{
  • "GetFinalDeclarationIdFromAnonymousDeclarationIdResult": "string"
}

Retrieve data

Operational methods used to retrieve data

Check Item Status

Return referral status from mail objects

Request
Request Body schema: application/json
required
securityToken
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

Array of objects (CheckItemStatusRequest)
Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/CheckItemStatus
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "Items": [
    ]
}
Response samples
application/json
{
  • "CheckItemStatusResult": [
    ]
}

Get Customs Status

Loads customs data view (status) for a specific item at post. If the customs response is not available and the forceCreateResponseIfNotAvailable param is true, the method forces creation of customs response based on the defined auto-response rules

Request
Request Body schema: application/json
required
token
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

postalOrgCd
required
string

The postal organization code (e.g. AUA - Australia Post) were the declarations and responses were created.

id
required
string

The id of the mail object

flow
required
string

Flow of the mail from the point of view of the postal organization

Enum Value Description
I

inbound

O

outbound

T

transit

forceCreateResponseIfNotAvailable
required
boolean

When true and the appropriate customs response is not available, CDS will attempt to create a customs response based on the auto-response rules defined in CDS.

userCd
required
string

The user code that will author the creation of the customs response (if applicable). If the user code does not exist in CDS, it will be automatically created and linked to the organization that issued the security token.

officeCd
string

The office code that will author the creation of the customs response (if applicable)

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/GetCustomsStatus
Request samples
application/json
{
  • "token": "b5507016-7da2-4777-a161-1e8042a6a377",
  • "postalOrgCd": "AUA",
  • "id": "EE23050001XAU",
  • "flow": "I",
  • "forceCreateResponseIfNotAvailable": true,
  • "userCd": "depost",
  • "officeCd": "DEAAAA"
}
Response samples
application/json
{
  • "GetCustomsStatusResult": {
    }
}

Get Referral And ReferralResponse

Returns Referrals and Referral Responses associated with a declaration

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

postalOrgCd
required
string

The postal organization code (e.g. AUA - Australia Post) were the declarations and responses were created.

id
string

The id of the mail object

flow
required
string (MailFlow)

Flow of the mail from the point of view of the postal organization

Enum Value Description
I

inbound

O

outbound

T

transit

partnerPostalOrgCd
string

The postal organization code of the partner post, that is, the destination post for the outbound mail and the origin post for the inbound mail.

postingDtFrom
string <timestamp> (Epoch) \/Date\([0-9]+\+[0-9]{4}\)\/

The epoch (or Unix timestamp) is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds.

postingDtTo
string <timestamp> (Epoch) \/Date\([0-9]+\+[0-9]{4}\)\/

The epoch (or Unix timestamp) is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds.

eventDtFrom
string <timestamp> (Epoch) \/Date\([0-9]+\+[0-9]{4}\)\/

The epoch (or Unix timestamp) is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds.

eventDtTo
string <timestamp> (Epoch) \/Date\([0-9]+\+[0-9]{4}\)\/

The epoch (or Unix timestamp) is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds.

mailClassCd
string (MailClass)

The mail class of the item

Enum Value Description
C

Parcels

E

EMS

U

Letters

officeCd
string

The office code that will author the creation of the customs response (if applicable)

hasPendingReferral
boolean

If true, the search includes declarations with pending referrals only and Referral responses.

referralType
string

Comma separated list of referral codes

referralResponseType
string

Comma separated list of referral response codes

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/GetReferralAndReferralResponse
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "postalOrgCd": "AUA",
  • "id": "EE23050001XDE",
  • "flow": "I",
  • "partnerPostalOrgCd": "DEA",
  • "postingDtFrom": "/Date(1562748420000+0200)/",
  • "postingDtTo": "/Date(1562748420000+0200)/",
  • "eventDtFrom": "/Date(1562748420000+0200)/",
  • "eventDtTo": "/Date(1562748420000+0200)/",
  • "mailClassCd": "E",
  • "officeCd": "DEAAAA",
  • "hasPendingReferral": true,
  • "referralType": "RFI, RFS",
  • "referralResponseType": "R20, R30"
}
Response samples
application/json
{
  • "GetReferralAndReferralResponseResult": [
    ]
}

Load

Loads customs data views (mail object + declaration + response) based on a list of criteria passed as parameters.

Request
Request Body schema: application/json
required
token
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

postalOrgCd
required
string

The postal organization code (e.g. AUA - Australia Post) were the declarations and responses were created.

customsOrgCd
required
string

The customs organization code (e.g. AU - Australia Post Customs) were the declarations and responses were created

organizationTypeCd
required
string

The type of the organization making the request

Enum Value Description
P

postal organization

C

customs organization

id
string

The id of the mail object

flow
required
string (MailFlow)

Flow of the mail from the point of view of the postal organization

Enum Value Description
I

inbound

O

outbound

T

transit

partnerPostalOrgCd
string

The postal organization code of the partner post, that is, the destination post for the outbound mail and the origin post for the inbound mail.

partCountryCd
string

The ISO country code of the partner post, that is, the destination country for the outbound mail and the origin country for the inbound mail.

dtFrom
string <timestamp> (Epoch) \/Date\([0-9]+\+[0-9]{4}\)\/

The epoch (or Unix timestamp) is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds.

dtTo
string <timestamp> (Epoch) \/Date\([0-9]+\+[0-9]{4}\)\/

The epoch (or Unix timestamp) is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds.

zipFrom
string

The lower limit of the ZIP code of the sender, in case of outbound mail, or recipient, in case of inbound mail.

zipTo
string

The upper limit of the ZIP code of the sender, in case of outbound mail, or recipient, in case of inbound mail.

mailClassCd
string (MailClass)

The mail class of the item

Enum Value Description
C

Parcels

E

EMS

U

Letters

onlyWithoutResponse
required
boolean

If true, the search includes only declarations for which a customs response hasn't been created yet, otherwise all declarations.

onlyWithDeclarationOrResponse
required
boolean

If true, the search includes only objects that have either a declaration or a response associated, otherwise all of them.

recordsLimit
integer <int32>

When specified, the search count is limited to the specified value.

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/Load
Request samples
application/json
{
  • "token": "b5507016-7da2-4777-a161-1e8042a6a377",
  • "postalOrgCd": "AUA",
  • "customsOrgCd": "AU",
  • "organizationTypeCd": "P",
  • "id": "EE23050001XDE",
  • "flow": "I",
  • "partnerPostalOrgCd": "DEA",
  • "partCountryCd": "DE",
  • "dtFrom": "/Date(1562748420000+0200)/",
  • "dtTo": "/Date(1562748420000+0200)/",
  • "zipFrom": "10000",
  • "zipTo": "10001",
  • "mailClassCd": "E",
  • "onlyWithoutResponse": true,
  • "onlyWithDeclarationOrResponse": true,
  • "recordsLimit": 100
}
Response samples
application/json
{
  • "LoadResult": [
    ]
}

Load By Mail State

Loads customs data views (mail object + declaration + response) based on a list of criteria passed as parameters including the mail state code

Request
Request Body schema: application/json
required
token
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

postalOrgCd
required
string

The postal organization code (e.g. AUA - Australia Post) were the declarations and responses were created.

customsOrgCd
required
string

The customs organization code (e.g. AU - Australia Post Customs) were the declarations and responses were created.

organizationTypeCd
required
string

The type of the organization making the request

Enum Value Description
P

postal organization

C

customs organization

flow
required
string

Flow of the mail from the point of view of the postal organization

Enum Value Description
I

inbound

O

outbound

T

transit

mailStateCd
required
string

Mail state code (i.e. 1 - received from customer).

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/LoadByMailState
Request samples
application/json
{
  • "token": "b5507016-7da2-4777-a161-1e8042a6a377",
  • "postalOrgCd": "AUA",
  • "customsOrgCd": "AU",
  • "organizationTypeCd": "P",
  • "flow": "I",
  • "mailStateCd": "1"
}
Response samples
application/json
{
  • "LoadByMailStateResult": [
    ]
}

Store data

Operational methods used to create data

Create Or Update Declarations

Creates/updates a list of declarations passed as customs data views

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

Array of objects (CDSView)

The list of CDS views. Each CDS view aggregates the mail object details (e.g. item id, origin, destination, etc) and the declaration details (e.g. sender, recipient, content pieces, etc)

userCd
required
string

The user code that will author the creation of the customs response (if applicable). If the user code does not exist in CDS, it will be automatically created and linked to the organization that issued the security token.

officeCd
string

The office code that will author the creation of the customs response (if applicable)

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/CreateOrUpdateDeclarations
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "cdsViews": [
    ],
  • "userCd": "depost",
  • "officeCd": "DEAAAA"
}
Response samples
application/json
{ }

Create Or Update Responses

Creates/updates a list of responses passed as customs data views

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

Array of objects (CDSView)

The list of CDS views. Each CDS view aggregates the mail object details (e.g. item id, origin, destination, etc) and the response details (e.g. sender, recipient, content pieces, etc)

userCd
required
string

The user code that will author the creation of the customs response (if applicable). If the user code does not exist in CDS, it will be automatically created and linked to the organization that issued the security token.

officeCd
string

The office code that will author the creation of the customs response (if applicable)

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/CreateOrUpdateResponses
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "cdsViews": [
    ],
  • "userCd": "depost",
  • "officeCd": "DEFRAA"
}
Response samples
application/json
{ }

Create Referral

Creates a referral for a declaration (for inbound items)

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

id
required
string

The id of the mail object

postOrgCd
required
string

The postal organization code of the post (e.g. AUA - Australia Post).

partnerPostOrgCd
required
string

The postal organization code of the partner post (e.g. DEA - Deutsche Post).

required
object (Referral)
Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/CreateReferral
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "id": "EE23050001XAU",
  • "postOrgCd": "AUA",
  • "partnerPostOrgCd": "DEA",
  • "referral": {
    }
}
Response samples
application/json
{ }

Create Referral Response

Creates a response to a referral (for outbound items)

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

id
required
string

The id of the mail object

postOrgCd
required
string

The postal organization code of the post (e.g. AUA - Australia Post).

partnerPostOrgCd
required
string

The postal organization code of the partner post (e.g. DEA - Deutsche Post).

required
object (ReferralResponse)
Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/CreateReferralResp
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "id": "EE23050001XAU",
  • "postOrgCd": "AUA",
  • "partnerPostOrgCd": "DEA",
  • "referralResponse": {
    }
}
Response samples
application/json
{ }

Store Declaration

Stores a declaration to CDS database

Request
Request Body schema: application/json
required
token
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

required
object (MailObject)

Mail object details (e.g. item ID, origin, destination, posting date)

required
object (Declaration)

Declaration details

evtCd
required
integer <int32>

The event code against which the declaration is stored

Enum Value Description
1

create/update draft

2

Store final declaration (automatic transfer)

6

Send declaration to customs

7

Send declaration to destination post

userCd
required
string

The user code that will author the creation of the customs response (if applicable). If the user code does not exist in CDS, it will be automatically created and linked to the organization that issued the security token.

officeCd
string

The office code that will author the creation of the customs response (if applicable)

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/StoreDeclaration
Request samples
application/json
{
  • "token": "b5507016-7da2-4777-a161-1e8042a6a377",
  • "mailObject": {
    },
  • "decl": {
    },
  • "evtCd": 1,
  • "userCd": "depost",
  • "officeCd": "DEAAAA"
}
Response samples
application/json
{ }

Store Response

Stores a response to CDS database

Request
Request Body schema: application/json
required
token
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

required
object (MailObject)

Mail object details (e.g. item ID, origin, destination, posting date)

required
object (Response)

Response details from the destination customs (applicable for outbound mail only)

evtCd
required
integer <int32>

The event code against which the declaration is stored

Enum Value Description
1

create/update draft

2

Store final declaration (automatic transfer)

6

Send declaration to customs

7

Send declaration to destination post

userCd
required
string

The user code that will author the creation of the customs response (if applicable). If the user code does not exist in CDS, it will be automatically created and linked to the organization that issued the security token.

officeCd
string

The office code that will author the creation of the customs response (if applicable)

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/StoreResponse
Request samples
application/json
{
  • "token": "b5507016-7da2-4777-a161-1e8042a6a377",
  • "mailObject": {
    },
  • "resp": {
    },
  • "evtCd": 1,
  • "userCd": "depost",
  • "officeCd": "DEAAAA"
}
Response samples
application/json
{ }

Update Mail State

Updates the mail state of the mail object

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

id
required
string

The id of the mail object

postalOrgCd
required
string

The postal organization code (e.g. AUA - Australia Post) were the declarations and responses were created.

partnerPostalOrgCd
required
string

The partner postal organization code

flow
required
string

Flow of the mail from the point of view of the postal organization

Enum Value Description
I

inbound

O

outbound

T

transit

mailState
integer <int32>

The state of the mail item

Enum Value Description
1

Received from customer

2

Arrived at OOE

10

Departed OOE

50

Arrived IOE

52

Departed IOE

userCd
required
string

The user code that will author the creation of the customs response (if applicable). If the user code does not exist in CDS, it will be automatically created and linked to the organization that issued the security token.

officeCd
string

Office code

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/UpdateMailState
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "id": "EE23050001XAU",
  • "postalOrgCd": "AUA",
  • "partnerPostalOrgCd": "FRA",
  • "flow": "I",
  • "mailState": 1,
  • "userCd": "depost",
  • "officeCd": "PTLISA"
}
Response samples
application/json
{ }

Update Mail State For Transit ItemsDeprecated

Updates the mail state of the mail object

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

id
required
string

The id of the mail object

postalOrgCd
required
string

The postal organization code (e.g. AUA - Australia Post) were the declarations and responses were created.

partnerPostalOrgCd
required
string

The partner postal organization code

flow
required
string

Flow of the mail from the point of view of the postal organization

Enum Value Description
I

inbound

O

outbound

T

transit

mailState
integer <int32>

The state of the mail item

Enum Value Description
1

Received from customer

2

Arrived at OOE

10

Departed OOE

50

Arrived IOE

52

Departed IOE

itemDestPostalOrgCd
string

The item destination postal organization code. Mandatory when flow is T (transit).

userCd
required
string

The user code that will author the creation of the customs response (if applicable). If the user code does not exist in CDS, it will be automatically created and linked to the organization that issued the security token.

officeCd
string

Office code

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/UpdateMailState_ForTransitItems
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "id": "EE23050001XAU",
  • "postalOrgCd": "AUA",
  • "partnerPostalOrgCd": "FRA",
  • "flow": "I",
  • "mailState": 1,
  • "itemDestPostalOrgCd": "DEA",
  • "userCd": "depost",
  • "officeCd": "PTLISA"
}
Response samples
application/json
{ }

Update Mail State and Get Customs Status

Updates the mail state of the mail object and loads customs data view (status) for a specific item at post (Operational method)

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

id
required
string

The id of the mail object

postalOrgCd
required
string

The postal organization code (e.g. AUA - Australia Post) were the declarations and responses were created.

partnerPostalOrgCd
required
string

The partner postal organization code

flow
required
string

Flow of the mail from the point of view of the postal organization

Enum Value Description
I

inbound

O

outbound

T

transit

mailState
integer <int32>

The state of the mail item

Enum Value Description
1

Received from customer

2

Arrived at OOE

10

Departed OOE

50

Arrived IOE

52

Departed IOE

forceCreateResponseIfNotAvailable
required
boolean

When true and the appropriate customs response is not available, CDS will attempt to create a customs response based on the auto-response rules defined in CDS. Mandatory parameter

itemDestPostalOrgCd
string

The item destination postal organization code. Mandatory when flow is T (transit)

userCd
required
string

The user code that will author the creation of the customs response (if applicable). If the user code does not exist in CDS, it will be automatically created and linked to the organization that issued the security token.

officeCd
string

The office code that will author the creation of the customs response (if applicable)

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/UpdateMailStateAndGetCustomsStatus
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "id": "EE23050001XAU",
  • "postalOrgCd": "AUA",
  • "partnerPostalOrgCd": "FRA",
  • "flow": "I",
  • "mailState": 1,
  • "forceCreateResponseIfNotAvailable": true,
  • "itemDestPostalOrgCd": "DEA",
  • "userCd": "depost",
  • "officeCd": "PTLISA"
}
Response samples
application/json
{
  • "UpdateMailStateAndGetCustomsStatusResult": {
    }
}

Utilities

Utilities

Convert Currency

Converts an amount from a currency type to another

Request
Request Body schema: application/json
required
token
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

organizationCd
string

The organization code (e.g. AUA - Australia Post) whose defined exchange rates are used for conversion

fromCurrencyCd
string

Source ISO currency code (e.g. USD)

toCurrencyCd
string

Target ISO currency code (e.g. CAD)

amount
number <double>

Amount to be converted

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/ConvertCurrency
Request samples
application/json
{
  • "token": "b5507016-7da2-4777-a161-1e8042a6a377",
  • "organizationCd": "AUA",
  • "fromCurrencyCd": "USD",
  • "toCurrencyCd": "CAD",
  • "amount": 3.2
}
Response samples
application/json
{
  • "ConvertCurrencyResult": 2.1239673903
}

Create New Declaration

Creates a new blank declaration without storing in the CDS database

Request
Request Body schema: application/json
required
token
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

postalOrgCd
required
string

The postal organization code (e.g. AUA - Australia Post) were the declarations and responses were created.

customsOrgCd
required
string

The customs organization code (e.g. AU - Australia Post Customs) were the declarations and responses were created.

itemId
required
string

The id of the mail object

mailFlow
required
string

Flow of the mail from the point of view of the postal organization

Enum Value Description
I

inbound

O

outbound

T

transit

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/CreateNewDeclaration
Request samples
application/json
{
  • "token": "b5507016-7da2-4777-a161-1e8042a6a377",
  • "postalOrgCd": "AUA",
  • "customsOrgCd": "AU",
  • "itemId": "EE23050001XAU",
  • "mailFlow": "I"
}
Response samples
application/json
{
  • "CreateNewDeclarationResult": {
    }
}

Create New Response

Creates a new response without storing in the CDS database

Request
Request Body schema: application/json
required
token
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

postalOrgCd
required
string

The postal organization code (e.g. AUA - Australia Post) were the declarations and responses were created.

customsOrgCd
required
string

The customs organization code (e.g. AU - Australia Post Customs) were the declarations and responses were created.

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/CreateNewResponse
Request samples
application/json
{
  • "token": "b5507016-7da2-4777-a161-1e8042a6a377",
  • "postalOrgCd": "AUA",
  • "customsOrgCd": "AU"
}
Response samples
application/json
{
  • "CreateNewResponseResult": {
    }
}

Get Decision Name And Category From Code

Determines the customs decision name (e.g. item must be presented, item is cleared) and category (e.g. Hold, clearance, prohibition) from a decision code

Request
Request Body schema: application/json
required
token
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

decisionCode
string

The decision code from customs as contained in the Response object (e.g. 1 - item must be presented, 2 - item is cleared, etc)

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/GetDecisionNameAndCategoryFromCode
Request samples
application/json
{
  • "token": "b5507016-7da2-4777-a161-1e8042a6a377",
  • "decisionCode": "1"
}
Response samples
application/json
{
  • "GetDecisionNameAndCategoryFromCodeResult": [
    ]
}

Get Heartbeat

Returns an heartbeat object with the last time of each CDS component was used

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

userCd
string

The user code.

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/GetHeartbeat
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "userCd": "depost"
}
Response samples
application/json
{
  • "GetHeartbeatResult": {
    }
}

Load Ref Data Cocktail

Returns a SimpleRefDataCocktail for the language passed as parameter

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

languageCd
string
Default: "EN"

'Language code to get the reference data. Ex: PT (for Portuguese), FR (for French), ES (for Spanish). If null or not provided, EN (English) will be used.'

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/LoadRefDataCocktail
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "languageCd": "PT"
}
Response samples
application/json
{
  • "LoadRefDataCocktailResult": {
    }
}

HS Codes

HS Codes

Restriction Prohibition

Restriction prohibition methods

Get Restriction Prohibition By Description

Returns restrictions or prohibition for a certain good

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

destinationPostalOrgCd
required
string

The postal destination of the good

sendingCountryCd
required
string

ISO country code of the country where the good is originating from

goodDescription
required
string

Full or partial description of good in English (use short words, i.e. tobacco)

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/GetRestrictionProhibitionByDescription
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "destinationPostalOrgCd": "FRA",
  • "sendingCountryCd": "FR",
  • "goodDescription": "tobacco"
}
Response samples
application/json
{
  • "GetRestrictionProhibitionByDescriptionResult": [
    ]
}

Get Restriction Prohibition By Description By Country

Returns restrictions or prohibition for a certain good

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

destinationCountryCd
required
string

ISO country code of the destination country of the good

sendingCountryCd
required
string

ISO country code of the country where the good is originating from

goodDescription
required
string

Description of good (preferable in English. French or Spanish may be used with lower search efficiency, other languages may be supported on demand)

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/GetRestrictionProhibitionByDescriptionByCountry
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "destinationCountryCd": "FR",
  • "sendingCountryCd": "FR",
  • "goodDescription": "tobacco"
}
Response samples
application/json
{
  • "GetRestrictionProhibitionByDescriptionByCountryResult": [
    ]
}

Get Restriction Prohibitions By Descriptions

Returns restrictions or prohibition for a given list of descriptions

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

destinationPostalOrgCd
required
string

The postal destination of the good

sendingCountryCd
required
string

ISO country code of the country where the good is originating from

goodDescriptions
required
Array of strings

List of full or partial description of good in English (use short words, i.e. tobacco)

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/GetRestrictionProhibitionsByDescriptions
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "destinationPostalOrgCd": "FRA",
  • "sendingCountryCd": "FR",
  • "goodDescriptions": [
    ]
}
Response samples
application/json
{
  • "GetRestrictionProhibitionsByDescriptionsResult": [
    ]
}

Get Restriction Prohibitions By Descriptions By Country

Returns restrictions or prohibition for a given list of descriptions

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

destinationCountryCd
required
string

ISO country code of the destination country of the good

sendingCountryCd
required
string

ISO country code of the country where the good is originating from

goodDescriptions
required
Array of strings

List of full or partial description of good in English (use short words, i.e. tobacco)

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/GetRestrictionProhibitionsByDescriptionsByCountry
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "destinationCountryCd": "FR",
  • "sendingCountryCd": "FR",
  • "goodDescriptions": [
    ]
}
Response samples
application/json
{
  • "GetRestrictionProhibitionsByDescriptionsByCountryResult": [
    ]
}

Get Restriction Prohibition By HS

Returns restrictions or prohibition for a certain good

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

destinationPostalOrgCd
required
string

The postal destination of the good

sendingCountryCd
required
string

ISO country code of the country where the good is originating from

goodHSCode
required
string

HS code of the good

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/GetRestrictionProhibitionByHS
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "destinationPostalOrgCd": "FRA",
  • "sendingCountryCd": "FR",
  • "goodHSCode": "240210"
}
Response samples
application/json
{
  • "GetRestrictionProhibitionByHSResult": [
    ]
}

Get Restriction Prohibition By HS By Country

Returns restrictions or prohibition for a certain good

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

destinationCountryCd
required
string

ISO country code of the destination country of the good

sendingCountryCd
required
string

ISO country code of the country where the good is originating from

goodHSCode
required
string

HS code of the good

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/GetRestrictionProhibitionByHSByCountry
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "destinationCountryCd": "FR",
  • "sendingCountryCd": "FR",
  • "goodHSCode": "240210"
}
Response samples
application/json
{
  • "GetRestrictionProhibitionByHSByCountryResult": [
    ]
}

Is Item Restricted Prohibited

Checks if a mail item is prohibited/restricted

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

mailItemID
required
string

The mail item ID to which we want to check if it restricted/prohibited

returnRestrictionsProhibitions
boolean

To determine if the list of restriction/prohibitions found should be returned. True to return the list. False not to return the list.

originCountryCd
string

ISO country code of the country where the good is originating from (i.e. FR).

destinationCountryCd
string

ISO country code of the country where the good is destined to (i.e. FR).

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/IsItemRestrictedProhibited
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "mailItemID": "EE23050001XAU",
  • "returnRestrictionsProhibitions": true,
  • "originCountryCd": "FR",
  • "destinationCountryCd": "FR"
}
Response samples
application/json
{
  • "IsItemRestrictedProhibitedResult": true,
  • "restrictionsProhibitions": [
    ]
}

Watchdog

Watchdog methods

Get Watchdog Item Info

Returns the current watchdog information for a given item. If more than one item with the same itemId is found, the function returns the most recent item.

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

itemId
required
string

The id of the mail object

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/GetWatchdogItemInfo
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "itemId": "EE23050001XAU"
}
Response samples
application/json
{
  • "GetWatchdogItemInfoResult": {
    }
}

Set Watchdog Item Info

Sets the current watchdog information for a new or existing item together with item's destination, mail class and posting date. If more than one item with the same itemId is found, an error is thrown.

Request
Request Body schema: application/json
required
securityToken
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

itemId
required
string

The id of the mail object

destinationPostalOrgCd
string

The postal destination of the good (i.e. AUA, FRA, etc.). If this parameter is null and the item does not yet exist in CDS, a ZZZ value is assumed.

mailClassCd
string

The mail class (e.g. E - EMS, U - Letters, C - Parcels). If this parameter is null and the item does not yet exist in CDS, the mail class will be determined from the itemId.

postingDate
string <timestamp> (Epoch) \/Date\([0-9]+\+[0-9]{4}\)\/

The epoch (or Unix timestamp) is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds.

object (WatchdogInfo)
Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/SetWatchdogItemInfo
Request samples
application/json
{
  • "securityToken": "63de3b10-521c-4dbb-8836-59da8dad803e",
  • "itemId": "EE23050001XAU",
  • "destinationPostalOrgCd": "AUA",
  • "mailClassCd": "E",
  • "postingDate": "/Date(1562748420000+0200)/",
  • "watchdogInfo": {
    }
}
Response samples
application/json
{ }

Marketed Good

Marketed good methods

Load Marketed Good

Loads a list of marketed goods. Either seller or buyer organization must be provided.

Request
Request Body schema: application/json
required
token
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

sellerOrganizationCd
string

Seller organization code

buyerOrganizationCd
string

Buyer organization code

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/LoadMarketedGood
Request samples
application/json
{
  • "token": "b5507016-7da2-4777-a161-1e8042a6a377",
  • "sellerOrganizationCd": "AUA",
  • "buyerOrganizationCd": "FRA"
}
Response samples
application/json
{
  • "LoadMarketedGoodResult": [
    ]
}

Store Marketed Good

Stores a marketed good

Request
Request Body schema: application/json
required
token
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

object (MarketedGood)

The marketed good to be stored

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/StoreMarketedGood
Request samples
application/json
{
  • "token": "b5507016-7da2-4777-a161-1e8042a6a377",
  • "marketedGood": {
    }
}
Response samples
application/json
{ }

Postal Services

Postal services methods

Load Postal Services

Loads a list of postal services provided by an origin postal organization to a destination postal organization

Request
Request Body schema: application/json
required
token
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

origOrganizationCd
required
string

The origin postal destination of the service

destOrganizationCd
required
string

The destination postal destination of the service

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/LoadPostalServices
Request samples
application/json
{
  • "token": "b5507016-7da2-4777-a161-1e8042a6a377",
  • "origOrganizationCd": "AUA",
  • "destOrganizationCd": "FRA"
}
Response samples
application/json
{
  • "LoadPostalServicesResult": [
    ]
}

Store Postal Service

Stores a postal service

Request
Request Body schema: application/json
required
token
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

object (PostalService)
Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/StorePostalService
Request samples
application/json
{
  • "token": "b5507016-7da2-4777-a161-1e8042a6a377",
  • "postalService": {
    }
}
Response samples
application/json
{ }

Print

Print methods

Print Customs Declaration

Prints CN22 associated with the mail item ID passed as parameter

Request
Request Body schema: application/json
required
token
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

mailItemId
required
string

The mail item ID to which CN22 is to be printed

userCd
required
string

The user code that authors the document printing

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/PrintCustomsDeclaration
Request samples
application/json
{
  • "token": "b5507016-7da2-4777-a161-1e8042a6a377",
  • "mailItemId": "EE23050001XAU",
  • "userCd": "depost"
}
Response samples
application/json
{
  • "PrintCustomsDeclarationResult": "string"
}

Print Doc

Prints document associated to customs declaration

Request
Request Body schema: application/json
required
token
required
string <uuid> (Token)

The security token used to authorize the web method call.
The security token must be defined by the CDS administrator at organization level.

required
object (CDSView)

CDS data facade. Aggregates mail object, declaration, response from customs, response from destination customs (applicable for outbound mail only)

userCd
required
string

The user code that will author the creation of the customs response (if applicable). If the user code does not exist in CDS, it will be automatically created and linked to the organization that issued the security token.

officeCd
string

The office code that will author the creation of the customs response (if applicable)

Responses
200

Successfully retrieved the response

400

ValidationException response

401

Unauthorized response

post/PrintDoc
Request samples
application/json
{
  • "token": "b5507016-7da2-4777-a161-1e8042a6a377",
  • "cdsView": {
    },
  • "userCd": "depost",
  • "officeCd": "DEAAAA"
}
Response samples
application/json
{
  • "PrintDocResult": "string"
}