logo

Domestic Postal System (DPS) API - DPS 2021 (1.2/1.3)

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

Supplied user name and password are valid

400

Authentication fails

401

Authentication fails

post/identity/connect/token
Request samples
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": {
    }
}

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

Token has been successfully revoked

401

Not authenticated or expired token

post/external-api/revoke-token
Request samples
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

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

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}
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

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

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
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

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

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
Response samples
application/json
[
  • {
    }
]

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

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
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

Securitydps_auth or dps_bearer
Request
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
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

Securitydps_auth or dps_bearer
Request
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
Response samples
application/json
{
  • "PickupPoints": [
    ],
  • "ProductTypes": [
    ],
  • "StandardCollections": [ ],
  • "CustomCollections": [ ],
  • "PaymentMethods": [
    ],
  • "Disclaimers": [
    ]
}

Mail Services

The mail-services endpoints can be used to manage PO Box subscriptions.

Create PO Box subscription

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

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
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

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

Invalid input

401

Not authenticated or expired token

403

Not authorized to perform this operation

404

Subscription not found

get/external-api/mail-services/po-box-subscriptions
Request samples
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
[
  • {
    }
]