Domestic Postal System (DPS) API - DPS 2023 SP1 (2.1)

Download OpenAPI specification:Download

License: Contact PTC for terms and conditions

Introduction

The DPS API offers GET and POST methods to request DPS data or to import data into DPS.

This API reference explains each of the API endpoints, with example REST requests and responses included.

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

success

400

Bad Request

401

Unauthorized

500

Internal Server Error

post/identity/connect/token

Request samples

Payload

application/x-www-form-urlencoded

client_id=string&client_secret=string&grant_type=string&scope=string&username=string&password=string

Response samples

application/json

{"access_token": "0kq-fxBLR1sQZF69znZ2ENGGpo5eMi8vrLVFSrf0jVU",
"expires_in": 600,
"token_type": "Bearer",
"refresh_token": "s5fs5T6aHBXPAJnQvbOMLDAn8M20H0-7AQLNdlJO_ZE",
"scope": "DPSEXT offline_access openid",
"userInfo": {"UserEmail": "admin@admin.com",
"UserFullName": "Admin",
"ExternalReferenceId": 1,
"Facilities": [{"Id": 1,
"Code": "BHBAHA",
"Name": "Bahrain Post",
"Functions": [{"Id": 2,
"Name": "Manage users"
}
]
}
]
}
}

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.

Securitydps_auth or dps_bearer

Request

Request Body schema: application/json

refresh_token

string

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

Responses

200

success

400

Bad Request

401

Unauthorized

500

Internal Server Error

post/external-api/revoke-token

Request samples

Payload

application/json

{"refresh_token": "[refresh_token]"
}

Response samples

application/json

{ }

Mail items

This endpoint represents a collection of mail items in DPS.

Get mail items by unique ID

Get Mail Item(s) by Main Item ID operation

Securitydps_auth or dps_bearer

Request

path Parameters

unique_mail_item_identifier

required

string

The unique ID of the mail item

query Parameters

returnEventInfo

boolean

Defaults to true

Responses

200

success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/external-api/mail-items/{unique_mail_item_identifier}

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": {"Amount": "10",
"Currency": "BHD"
},
"ConsumerRegistrationNumber": "123",
"AlternativeDeliveryAddress": "address",
"AlternativeDeliveryPostcode": "postcode",
"AlternativeDeliveryCity": "city",
"InsuredAmount": {"Amount": "10",
"Currency": "BHD"
},
"CODBIC": "123",
"CODIBAN": "123",
"CustomerChargingArrangement": "DDP",
"DeliveryCharges": [{"Type": "Duties",
"Value": 2,
"Currency": "BHD"
}
],
"MailItemEvents": [{"Id": "8c30a310-03cb-445a-8c8f-84f7e54a55ec",
"EventTimeStamp": "12/10/2020 4:11:41 PM",
"Facility": "BHBAHA",
"EventType": "03",
"Condition": "string",
"PickupPoint": "string",
"Signature": "string",
"DeliveryAgent": "string",
"SignatoryName": "string",
"Reason": "string",
"Action": "string",
"property1": "string",
"property2": "string"
}
],
"property1": "string",
"property2": "string"
}

Update mail item

Update Mail Item operation

Securitydps_auth or dps_bearer

Request

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
	object or MailItemAttributes (object)
	object or EventAttributes (object)
	Array of objects (DeliveryCharges)

Responses

200

success

400

Bad Request

401

Unauthorized

500

Internal Server Error

patch/external-api/mail-items/{unique_mail_item_identifier}

Request samples

Payload

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": { },
"EventAttributes": { },
"DeliveryCharges": [{"DeliveryChargeTypeCode": "Duties",
"Amount": 200,
"CurrencyCode": "AED"
}
]
}

Response samples

application/json

{"OperationResult": "MailItemUpdated",
"MailItemUniqueId": "6b4cf4e2-474e-48b0-97db-5dd4b9c4a7e4"
}

Get mail items list

Get Mail Item by Unique ID operation

Securitydps_auth or dps_bearer

Request

query Parameters

itemId required	string The itemId is mandatory and represents a main item identifier.
returnEventInfo	boolean Defaults to true

Responses

200

success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/external-api/mail-items

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": {"Amount": "10",
"Currency": "BHD"
},
"ConsumerRegistrationNumber": "123",
"AlternativeDeliveryAddress": "address",
"AlternativeDeliveryPostcode": "postcode",
"AlternativeDeliveryCity": "city",
"InsuredAmount": {"Amount": "10",
"Currency": "BHD"
},
"CODBIC": "123",
"CODIBAN": "123",
"CustomerChargingArrangement": "DDP",
"DeliveryCharges": [{"Type": "Duties",
"Value": 2,
"Currency": "BHD"
}
],
"MailItemEvents": [{"Id": "8c30a310-03cb-445a-8c8f-84f7e54a55ec",
"EventTimeStamp": "12/10/2020 4:11:41 PM",
"Facility": "BHBAHA",
"EventType": "03",
"Condition": "string",
"PickupPoint": "string",
"Signature": "string",
"DeliveryAgent": "string",
"SignatoryName": "string",
"Reason": "string",
"Action": "string",
"property1": "string",
"property2": "string"
}
],
"property1": "string",
"property2": "string"
}
]

Create or update mail item

Create or Update Mail Item operation

Securitydps_auth or dps_bearer

Request

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

success

400

Bad Request

401

Unauthorized

500

Internal Server Error

post/external-api/mail-items

Request samples

Payload

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": [{"DeliveryChargeTypeCode": "Duties",
"Amount": 200,
"CurrencyCode": "AED"
}
]
}

Response samples

application/json

[{"OperationResult": "MailItemCreated",
"MailItemUniqueId": "6b4cf4e2-474e-48b0-97db-5dd4b9c4a7e4"
}
]

Distribution Notification Lists (for Distribution Agents)

This endpoint represents a list of DNLs for a given agent.

Get distribution Notification lists

Get distribution Notification Lists for Distribution Agents

Securitydps_auth or dps_bearer

Request

path Parameters

distribution_agent_id

required

string

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

query Parameters

facilityId

required

string

Facility code

Responses

200

success

400

Bad request: Invalid facility id

401

Unauthorized

404

Delivery agent with a given unique identifier does not exist

500

Internal Server Error

get/external-api/delivery-agents/{distribution_agent_id}/dnls

Response samples

application/json

{"Id": "1",
"Label": "SuperAdmin",
"Items": {"Id": "559a5cb3-5364-477d-aec8-58b323d22a2f",
"MainIdentifier": "bulk110200000006564",
"MailProductType": "Bulk",
"State": "BPROC",
"Weight": "10",
"OriginCountry": "IT",
"SenderName": "string",
"SenderAddress": "string",
"SenderPostcode": "string",
"SenderCity": "NAPOLI",
"SenderPhone": "string",
"SenderEmail": "string",
"DestinationCountry": "IT",
"RecipientName": "RAF",
"RecipientAddress": "address",
"RecipientPostcode": "postcode",
"RecipientCity": "city",
"RecipientPhone": "phone",
"RecipientEmail": "email",
"AlternateIdentifier": "id",
"PostalStatus": "01",
"DeliveryServiceType": "1",
"CODAmount": {"Amount": "10",
"Currency": "BHD"
},
"ConsumerRegistrationNumber": "123",
"AlternativeDeliveryAddress": "address",
"AlternativeDeliveryPostcode": "postcode",
"AlternativeDeliveryCity": "city",
"InsuredAmount": {"Amount": "10",
"Currency": "BHD"
},
"CODBIC": "123",
"CODIBAN": "123",
"CustomerChargingArrangement": "DDP"
}
}

Reference Data

This endpoint can be used to retrieve DPS reference data that is required by DPS.

Get reference data

Securitydps_auth or dps_bearer

Request

query Parameters

culture required	string Culture code Example: culture=en-us
categories	string List of selected categories Example: categories=chargeTypes,eventTypes
filter	string Filter reference data Example: filter=validForDPSMobile
lastDownload	string Return only reference data categories that have changed since the lastDownload parameter with format yyyyMMddHHmmss UTC time Example: lastDownload=20231231010101

Responses

200

success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/external-api/delivery-app/reference-data

Response samples

application/json

{"PickupPoints": [{"Id": 3,
"Code": "DT1234",
"Name": "Delivery Test",
"OpeningHours": "09:00 to 22:00"
}
],
"ProductTypes": [{"Code": "PC",
"Name": "International parcel",
"MainIdentifierFormat": "^[Cc][A-z]{1}\\d{8}(\\d{1}|[Xx])[A-z]{2}$",
"DeliveryCharges": [{"DeliveryChargeTypeCode": "Duties",
"Amount": 200,
"CurrencyCode": "AED"
}
],
"Events": [{"Code": "06",
"Attributes": [{"Name": "Condition",
"Label": "Condition",
"Type": "Object",
"DataSource": {"Type": null,
"Name": null
}
}
]
}
],
"IntrinsicAttributes": [{"Name": "RecipientName",
"Label": "Recipient name",
"Type": "string",
"Regex": "^.{0,35}$",
"DataSource": {"Type": "StandardCollection",
"Name": "Condition"
},
"DefaultValue": "60",
"AutomaticRenewal": false
}
]
}
],
"StandardCollections": [ ],
"CustomCollections": [ ],
"PaymentMethods": [{"Code": "Cash",
"Name": "Cash",
"MinimumAmount": 0,
"MaximumAmount": 100
}
],
"DisclaimersText": "Hello, I am the disclaimer text for DPS mobile",
"ChargeTypes": [{"Code": "Duties",
"Name": "Duties & taxes",
"Charges": "Delivery"
}
],
"StateTypes": [{"ObjectTypeCode": "MI",
"Code": "BPROC",
"Name": "Being processed",
"RelevantParty": "Recipient",
"IconCode": "normal"
}
],
"EventTypes": [{"Code": "01",
"ObjectTypeCode": "MI",
"Name": "Acceptance",
"ResultingState": "BPROC",
"InitialStates": ["NEW",
"BPROC"
],
"ValidForDPSMobile": true,
"Charges": "string",
"IconCode": "string"
}
],
"Settings": {"MaxImageSizeKB": "2048",
"DpsMobile": {"DpsMobileCreateItemIfItemLookupNotAvailable": true,
"DpsMobileTimeoutForItemLookupInMilliseconds": 40
}
}
}

Mail Services

These endpoints can be used to manage PO Box subscriptions.

Create PO Box subscription

Securitydps_auth or dps_bearer

Request

Request Body schema: application/json

CustomerCode required	string The code of the registered customer whose subscriptions shall be retrieved
POBoxNumber required	string The number of the PO Box whose subscriptions shall be retrieved
RentType required	string The type of rental of the subscription to be retrieved Enum: "Personal" "Commercial"
SubscriptionPeriod required	string The period of the subscription Enum: "Custom" "Monthly" "Quarterly" "Semiannually" "Annually"
ValidityDateFrom required	string <date> Subscription start date. Date in the format ‘YYYY-MM-DD’. Mandatory
ValidityDateTo	string <date> Subscription end date. Date in the format ‘YYYY-MM-DD’. Mandatory ONLY if the 'subscription period' is 'custom'
AutomaticRenewal	boolean Default: false Whether the subscription is automatically renewed for the same duration upon expiry
CustomerName	string The customer name
CustomerAddress	string The customer address
CustomerCity	string The customer city
CustomerPostcode	string The customer postcode
CustomerCountry	string The customer country code
CustomerIDNumber	string The ID number of the registered customer which the subscription refers to
CustomerEmail	string The customer email address
CustomerMobilePhone	string The customer mobile phone
CustomerLandlinePhone	string The customer landline phone
IsPaid	boolean Default: false Optional

Responses

200

success

400

Bad Request

401

Unauthorized

500

Internal Server Error

post/external-api/mail-services/po-box-subscription

Request samples

Payload

application/json

{"CustomerCode": "ABC12345",
"POBoxNumber": "madel12",
"RentType": "Personal",
"SubscriptionPeriod": "Custom",
"ValidityDateFrom": "2020-11-04",
"ValidityDateTo": "2020-11-15",
"AutomaticRenewal": false,
"CustomerName": "John Smith",
"CustomerAddress": "Main Street 123",
"CustomerCity": "Capital City",
"CustomerPostcode": "12345",
"CustomerCountry": "BH",
"CustomerIDNumber": "12345",
"CustomerEmail": "john.smith@gmail.com",
"CustomerMobilePhone": "+123456789",
"CustomerLandlinePhone": "+123456789",
"IsPaid": true
}

Response samples

application/json

{"OperationResult": "POBoxSubcriptionCreated",
"poBoxSubscriptionUniqueId": "[ID of the created PO Box subscription]"
}

Retrieve PO Box subscriptions

Securitydps_auth or dps_bearer

Request

Request Body schema: application/json

CreationDateFrom	string <date> Subscriptions to be retrieved shall be created on or after the specified date-time. Date in the format ‘yyyy-MM-ddTHH:mm:sss’. Pls N.B. this is mandatory if values for the parameters CreationDateTo, ValidityDateFrom and ValidityDateTo are not specified.
CreationDateTo	string <date> Subscriptions to be retrieved shall be created before the specified date-time. Date in the format ‘yyyy-MM-ddTHH:mm:sss’. Pls N.B. this is mandatory if values for the parameters CreationDateFrom, ValidityDateFrom and ValidityDateTo are not specified.
ValidityDateFrom	string <date> Subscriptions to be retrieved shall be still active on the date specified here. Date in the format ‘YYYY-MM-DD’. Pls N.B. this is mandatory if values for the parameters CreationDateFrom, CreationDateTo and ValidityDateTo are not specified.
ValidityDateTo	string <date> Subscriptions to be retrieved shall be already active on the date specified here. Date in the format ‘YYYY-MM-DD’. Pls N.B. this is mandatory if values for the parameters CreationDateFrom, CreationDateTo and ValidityDateFrom are not specified.
CustomerCode	string The code of the registered customer whose subscriptions shall be retrieved
CustomerIDNumber	string The ID number of the registered customer whose subscriptions shall be retrieved
POBoxNumber	string The number of the PO Box whose subscriptions shall be retrieved
RentType	string The type of rental of the subscription to be retrieved Enum: "Personal" "Commercial"

Responses

200

success

400

Bad Request

401

Unauthorized

404

Not Found

500

Internal Server Error

get/external-api/mail-services/po-box-subscriptions

Request samples

Payload

application/json

{"CreationDateFrom": "2021-12-01T00:00:00.000",
"CreationDateTo": "2021-12-01T00:00:00.000",
"ValidityDateFrom": "2020-11-04",
"ValidityDateTo": "2020-11-04",
"CustomerCode": "ABC12345",
"CustomerIDNumber": "12345",
"POBoxNumber": "madel12",
"RentType": "Personal"
}

Response samples

application/json

[{"poBoxNumber": "987",
"poBoxFacilityID": "123",
"poBoxType": "Small",
"customerCode": "JD12345",
"customerIDNumber": "12345",
"customerName": "John Doe",
"subscriptionActiveFrom": "2021-01-01",
"subscriptionActiveTo": "2021-12-31",
"subscriptionPeriod": "Annualy",
"subscriptionCreationDateTime": "2021-11-30T12:02:53.123",
"autoRenewal": true,
"rentType": "Personal",
"paid": false,
"onlineTransID": "25100"
}
]

Misc

This endpoint can be used to retrieve DPS backend version

Get DPS backend version

Securitydps_auth or dps_bearer

Request

query Parameters

caller

string

Caller code

Example: caller=DPSMobile

Responses

200

success

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/external-api/version

Response samples

application/json

{"ProductName": "DPS",
"ProductVersion": "2.0.0"
}