Download OpenAPI specification:Download
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.
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.
Supplied user name and password are valid
Authentication fails
Authentication fails
client_id=string&client_secret=string&grant_type=string&scope=string&username=string&password=string
{- "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"
}
]
}
]
}
}
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.
Token has been successfully revoked
Not authenticated or expired token
{- "refresh_token": "[refresh_token]"
}
Get Mail Item(s) by Main Item ID operation
The request to retrieve a mail item has been successful
Not authenticated or expired token
Not authorized to perform this operation
Mail item not found
{- "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",
- "Pick-upPoint": "string",
- "Signature": "string",
- "DeliveryAgent": "string",
- "SignatoryName": "string",
- "Reason": "string",
- "Action": "string",
- "property1": "string",
- "property2": "string"
}
], - "property1": "string",
- "property2": "string"
}
Update Mail Item operation
Operation successfully executed
Invalid mail item object
Not authenticated or expired token
Not authorized to perform this operation
Mail item with a given unique identifier not found
{- "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",
- "CurrencyCode": "AED",
- "Amount": 200
}
]
}
{- "OperationResult": "MailItemUpdated",
- "MailItemUniqueId": "6b4cf4e2-474e-48b0-97db-5dd4b9c4a7e4"
}
Get Mail Item by Unique ID operation
The request to retrieve mail items has been successful
Not authenticated or expired token
Not authorized to perform this operation
[- {
- "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",
- "Pick-upPoint": "string",
- "Signature": "string",
- "DeliveryAgent": "string",
- "SignatoryName": "string",
- "Reason": "string",
- "Action": "string",
- "property1": "string",
- "property2": "string"
}
], - "property1": "string",
- "property2": "string"
}
]
Create or Update Mail Item operation
Operation successfully executed
Invalid mail item object
Not authenticated or expired token
Not authorized to perform this operation
{- "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",
- "CurrencyCode": "AED",
- "Amount": 200
}
]
}
[- {
- "OperationResult": "MailItemCreated",
- "MailItemUniqueId": "6b4cf4e2-474e-48b0-97db-5dd4b9c4a7e4"
}
]
The delivery-agent\{delivery_agent_id}/dnls
endpoint represents a list of DNLs for a given delivery agent.
Get Delivery Notification Lists for Delivery Agent operation
The request to retrieve delivery notification lists for a given delivery agent has been successful
Bad request: Invalid facility id
Not authenticated or expired token
Not authorized to perform this operation
Delivery agent with a given unique identifier does not exist
{- "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"
}
}
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 operation
The request to retrieve DPS reference data has been successful
Not authenticated or expired token
Not authorized to perform this operation
{- "PickupPoints": [
- {
- "Id": 0,
- "Code": "string",
- "Name": "string",
- "OpeningHours": "string"
}
], - "ProductTypes": [
- {
- "Code": "string",
- "Name": "string",
- "DeliveryCharges": [
- {
- "DeliveryChargeType": {
- "Code": "string",
- "Name": "string"
}, - "DefaultAmount": 0,
- "CurrencyCode": "string"
}
], - "NonDeliveryAttributes": [
- {
- "Name": "string",
- "Label": "string",
- "Type": "object",
- "IsMandatory": true,
- "DataSource": {
- "Type": "StandardCollection",
- "Name": "string"
}, - "Regex": "string"
}
], - "DeliveryAttributes": [
- {
- "Name": "string",
- "Label": "string",
- "Type": "object",
- "IsMandatory": true,
- "DataSource": {
- "Type": "StandardCollection",
- "Name": "string"
}, - "Regex": "string"
}
], - "NonDeliveryEventCode": "string",
- "DeliveryEventCode": "string"
}
], - "StandardCollections": [ ],
- "CustomCollections": [ ],
- "PaymentMethods": [
- {
- "Code": "string",
- "Name": "string",
- "MinimumAmount": 0,
- "MaximumAmount": 0
}
], - "Disclaimers": [
- {
- "Code": "string",
- "Name": "string"
}
]
}
Create PO Box subscription
success
Invalid PO Box subscription object
Not authenticated or expired token
Not authorized to perform this operation
{- "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
}
{- "OperationResult": "POBoxSubcriptionCreated",
- "poBoxSubscriptionUniqueId": "[ID of the created PO Box subscription]"
}
Retrieve PO Box subscriptions
success
Invalid input
Not authenticated or expired token
Not authorized to perform this operation
Subscription not found
{- "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"
}
[- {
- "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"
}
]