logo

Domestic Postal System (DPS) API for Developers (1.0.0)

Download OpenAPI specification:Download

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

Domestic Postal System (DPS) API for Developers.

Universal Postal Union
International Bureau
Weltpoststrasse 4
3000 Bern 15
Switzerland

Use cases

DPS use cases

DPS External API Service supports the following use cases:

  • Get Token
  • Revoke Token
  • Refresh Token
  • Get Mail Item
  • Create or Update Mail Item
  • Update Mail Item
  • Get Delivery Notification Lists
  • Get Reference Data

Authentication

dps_auth

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: https://example.com/identity/connect/token
Refresh URL: https://example.com/identity/connect/token
Scopes:
  • openid -

    include userData claim in token and access to connect/userinfo endpoint

  • DPSEXT -

    access to DPS external api

dps_bearer

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "access_token"

Authentication tokens

Generate, refresh and revoke authentication tokens.

Get or refresh token

The “connect/token” endpoint is used to programmatically refresh tokens that are required to access DPS API resources. Implemented by DPS.Services.Identity and exposed by Ocelot gateway. https://identityserver4.readthedocs.io/en/latest/endpoints/token.html

Grant type parameter is changed to refresh_token and you need to provide refresh token instead of user credentials.

Request
query Parameters
returnUserInfo
boolean

Defaults to false

Request Body schema: application/x-www-form-urlencoded
Any of:
client_id
string
client_secret
string

Optional and dependent on client setting “RequireClientSecret”

grant_type
string
scope
string

Optional and default from “AllowedScopes”

username
string
password
string
Responses
200

Supplied user name and password are valid

400

Authentication fails

401

Authentication fails

post/identity/connect/token
Request samples
    1 more
    JavaScript
curl -i -X POST \
  'https://upu.api.int/ips/dps/identity/connect/token?returnUserInfo=true' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d client_id=string \
  -d client_secret=string \
  -d grant_type=string \
  -d scope=string \
  -d username=string \
  -d password=string
Response samples
application/json
GetToken
GetToken
RefreshToken
{
  • "access_token": "0kq-fxBLR1sQZF69znZ2ENGGpo5eMi8vrLVFSrf0jVU",
  • "expires_in": 600,
  • "token_type": "Bearer",
  • "refresh_token": "s5fs5T6aHBXPAJnQvbOMLDAn8M20H0-7AQLNdlJO_ZE",
  • "scope": "DPSEXT offline_access openid",
  • "userInfo": {
    }
}

Revoke DPS API access tokens

The “revoke-token” endpoint allows revoking DPS API access tokens. Revokes bearer token provided in HTTP header Authorization and optionally refresh token provided in HTTP request body.

Request
Security:
dps_auth (DPSEXT) or dps_bearer
Request Body schema: application/json
refresh_token
string

Can be null if it wasn’t requested by “offline_access” scope

Responses
200

Token has been successfully revoked

401

Not authenticated or expired token

post/external-api/revoke-token
Request samples
    2 more
    Node.js
    JavaScript
application/json
{
  • "refresh_token": "[refresh_token]"
}

Mail items

The mail-items endpoint represents a collection of mail items in DPS.

Get mail items by unique ID

Get Mail Item(s) by Main Item ID operation

Request
Security:
dps_auth (DPSEXT) or dps_bearer
path Parameters
unique_mail_item_identifier
required
string

The unique ID of the mail item

query Parameters
returnEventInfo
boolean

Defaults to true

Responses
200

The request to retrieve a mail item has been successful

401

Not authenticated or expired token

403

Not authorized to perform this operation

404

Mail item not found

get/external-api/mail-items/{unique_mail_item_identifier}
Request samples
    1 more
    JavaScript
curl -i -X GET \
  'https://upu.api.int/ips/dps/external-api/mail-items/:unique_mail_item_identifier?returnEventInfo=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "Id": "12f4283b-7cd2-4a09-b02b-0b32a5132e09",
  • "MainIdentifier": "CA000000001AZ",
  • "MailProductType": "Parcel_intl",
  • "State": "BPROC",
  • "Weight": "10",
  • "OriginCountry": "BH",
  • "SenderName": "sender",
  • "SenderAddress": "address",
  • "SenderPostcode": "postcode",
  • "SenderCity": "city",
  • "SenderPhone": "phone",
  • "SenderEmail": "email",
  • "SenderPOBox": "pobox",
  • "DestinationCountry": "IT",
  • "RecipientName": "recipient",
  • "RecipientAddress": "address",
  • "RecipientPostcode": "postcode",
  • "RecipientCity": "city",
  • "RecipientPhone": "phone",
  • "RecipientEmail": "email",
  • "RecipientPOBox": "pobox",
  • "DeliveryInstructions": "instructions",
  • "AlternateIdentifier": "id",
  • "PostalStatus": "01",
  • "DeliveryServiceType": "1",
  • "CODAmount": {
    },
  • "ConsumerRegistrationNumber": "123",
  • "AlternativeDeliveryAddress": "address",
  • "AlternativeDeliveryPostcode": "postcode",
  • "AlternativeDeliveryCity": "city",
  • "InsuredAmount": {
    },
  • "CODBIC": "123",
  • "CODIBAN": "123",
  • "CustomerChargingArrangement": "DDP",
  • "DeliveryCharges": [
    ],
  • "MailItemEvents": [
    ],
  • "property1": "string",
  • "property2": "string"
}

Update mail item

Update Mail Item operation

Request
Security:
dps_auth (DPSEXT) or dps_bearer
path Parameters
unique_mail_item_identifier
required
string

The unique ID of the mail item

Request Body schema: application/json
ForceDuplicate
boolean
Identifier
string

Mail item identifier

MailProductType
string
EventType
string
Username
string
Facility
boolean

Facility ID

Timestamp
string <date-time>

Format: YYYY-MM-DDThh:mm:ss TZD

string or MailItemAttributes (object)
string or EventAttributes (object)
Array of objects (DeliveryCharges)
Responses
200

Operation successfully executed

400

Invalid mail item object

401

Not authenticated or expired token

403

Not authorized to perform this operation

404

Mail item with a given unique identifier not found

patch/external-api/mail-items/{unique_mail_item_identifier}
Request samples
    2 more
    Node.js
    JavaScript
application/json
{
  • "ForceDuplicate": false,
  • "Identifier": "EE000006452BH",
  • "MailProductType": "EMS - AUT",
  • "EventType": "03",
  • "Username": "SuperAdmin",
  • "Facility": "0006-1",
  • "Timestamp": "2020-03-19T16:25:30.666 +03:00",
  • "MailItemAttributes": "string",
  • "EventAttributes": "string",
  • "DeliveryCharges": [
    ]
}
Response samples
application/json
{
  • "OperationResult": "MailItemUpdated",
  • "MailItemUniqueId": "6b4cf4e2-474e-48b0-97db-5dd4b9c4a7e4"
}

Get mail items list

Get Mail Item by Unique ID operation

Request
Security:
dps_auth (DPSEXT) or dps_bearer
query Parameters
itemId
required
string

The itemId is mandatory and represents a main item identifier.

returnEventInfo
boolean

Defaults to true

Responses
200

The request to retrieve mail items has been successful

401

Not authenticated or expired token

403

Not authorized to perform this operation

get/external-api/mail-items
Request samples
    1 more
    JavaScript
curl -i -X GET \
  'https://upu.api.int/ips/dps/external-api/mail-items?itemId=string&returnEventInfo=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
[
  • {
    }
]

Create or update mail item

Create or Update Mail Item operation

Request
Security:
dps_auth (DPSEXT) or dps_bearer
Request Body schema: application/json
ForceDuplicate
boolean
Identifier
string

Mail item identifier

MailProductType
string
EventType
string
Username
string
Facility
boolean

Facility ID

Timestamp
string <date-time>

YYYY-MM-DDThh:mm:ss TZD

string or MailItemAttributes (object)
string or EventAttributes (object)
Array of objects (DeliveryCharges)
Responses
200

Operation successfully executed

400

Invalid mail item object

401

Not authenticated or expired token

403

Not authorized to perform this operation

post/external-api/mail-items
Request samples
    2 more
    Node.js
    JavaScript
application/json
{
  • "ForceDuplicate": "false",
  • "Identifier": "EE000006452BH",
  • "MailProductType": "EMS - AUT",
  • "EventType": "03",
  • "Username": "SuperAdmin",
  • "Facility": "0006-1",
  • "Timestamp": "2020-03-19T16:25:30.666 +03:00",
  • "MailItemAttributes": "string",
  • "EventAttributes": "string",
  • "DeliveryCharges": [
    ]
}
Response samples
application/json
[
  • {
    }
]

Delivery Notification Lists (for a Delivery Agent)

The delivery-agent\{delivery_agent_id}/dnls endpoint represents a list of DNLs for a given delivery agent.

Get delivery notification lists

Get Delivery Notification Lists for Delivery Agent operation

Request
Security:
dps_auth (DPSEXT) or dps_bearer
path Parameters
delivery_agent_id
required
string

The unique identifier of a delivery agent for whom we request DNLs

query Parameters
facilityId
required
string

Facility code

Responses
200

The request to retrieve delivery notification lists for a given delivery agent has been successful

400

Bad request: Invalid facility id

401

Not authenticated or expired token

403

Not authorized to perform this operation

404

Delivery agent with a given unique identifier does not exist

get/external-api/delivery-agents/{delivery_agent_id}/dnls
Request samples
    1 more
    JavaScript
curl -i -X GET \
  'https://upu.api.int/ips/dps/external-api/delivery-agents/:delivery_agent_id/dnls?facilityId=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "Id": "1",
  • "Label": "SuperAdmin",
  • "Items": {
    }
}

Reference Data (for Delivery App)

The delivery-app/reference-data endpoint can be used to retrieve DPS reference data that is required by the Delivery App.

Get reference data for delivery app

Get Reference Data for Delivery App operation

Request
Security:
dps_auth (DPSEXT) or dps_bearer
query Parameters
culture
required
string

Culture code

Example: culture=en-us
Responses
200

The request to retrieve DPS reference data has been successful

401

Not authenticated or expired token

403

Not authorized to perform this operation

get/external-api/delivery-app/reference-data
Request samples
    1 more
    JavaScript
curl -i -X GET \
  'https://upu.api.int/ips/dps/external-api/delivery-app/reference-data?culture=en-us' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "PickupPoints": [
    ],
  • "ProductTypes": [
    ],
  • "StandardCollections": [ ],
  • "CustomCollections": [ ],
  • "PaymentMethods": [
    ],
  • "Disclaimers": [
    ]
}

Mail Services

The mail-services/po-box-subscription endpoint can be used to create a PO Box subscription.

Create PO Box subscription

Create PO Box subscription

Request
Security:
dps_auth (DPSEXT) or dps_bearer
Request Body schema: application/json
CustomerCode
string

This information or 'customer ID number' is required

CustomerIDNumber
string

This information or 'customer code' is required

POBoxNumber
required
string

Mandatory

RentType
required
string

Mandatory

Enum: "Personal" "Commercial"
SubscriptionPeriod
required
string

Mandatory

Enum: "Custom" "Monthly" "Quarterly" "Semiannually" "Annually"
ActiveFrom
required
string <date>

Date in the format ‘YYYY-MM-DD’. Mandatory

ActiveTo
string <date>

Date in the format ‘YYYY-MM-DD’. Mandatory ONLY if the 'subscription period' is 'custom'

AutomaticRenewal
boolean
Default: false

Optional

IsPaid
boolean
Default: false

Optional

Responses
200

Operation successfully executed

400

Invalid PO Box subscription object

401

Not authenticated or expired token

403

Not authorized to perform this operation

post/external-api/mail-services/po-box-subscription
Request samples
    2 more
    Node.js
    JavaScript
application/json
{
  • "CustomerCode": "string",
  • "CustomerIDNumber": "12345",
  • "POBoxNumber": "madel12",
  • "RentType": "Personal",
  • "SubscriptionPeriod": "Custom",
  • "ActiveFrom": "2020-11-04",
  • "ActiveTo": "2020-11-15",
  • "AutomaticRenewal": false,
  • "IsPaid": true
}
Response samples
application/json
{
  • "OperationResult": "POBoxSubcriptionCreated",
  • "poBoxSubscriptionUniqueId": "[ID of the created PO Box subscription]"
}