API docs by Redocly

Digital announcement for Registered Mails (SEN) (1.6.23)

Download OpenAPI specification:Download

Enables Sender to generate barcodes, announcement, search, track and get signed proofs for their Registered Mails.
Senders must provide the IDs matching the announcement, the logic is as follows:

  • accountID is the company account and is always mandatory
  • subaccountID is the department within the company
  • routerID is only used by routers that use this API for their clients and is mandatory for them.

Environments:

  • st2 - The development environment.
  • ac2 - The UAT environment which is to be used by the customers by default to test the application.
  • st1 - The bugfix environment, used by the development team.
  • ac1 - The bugfix environment - The issues found and fixed after production release can be tested here and is available for the customers.
  • The production environment url - https://sen.bpost.be

Authentication

ApiKeyAuthentication

Security Scheme Type: API Key
Header parameter name: x-api-key

Announcement

Registered Mail digital announcement

Enables Senders to get a barcode for an upcoming Registered Mail they announce. The announcement data provided here will later be used for Search & Track capabilities as well as Proofs generations.

The announcement can accept a barcode for users having a barcode ID (or for routers using a client's barcode ID), otherwise, bpost will attribute a barcode as a result of a correct announcement.

Specific considerations:

  • Fields marked as mandatory in the address object are mandatory for the structured format,
  • Though not marked as mandatory, at least one of name/companyName field has to be filled,
  • For now, only national mails are handled, countryCode cannot be different than "BE",
  • For customers owning a barcodeID (see below) it should be present as part of the barcode provided. For customers not owning a barcodeID, the field must not be filled and a barcode will be provided by the Sender Platform API,
  • Option Anonymous Sender is not active for now,
  • Option electronic Acknowledgement Receipt is not active for now.

Barcode Format

With this service, the barcode format is different from previous registered mails.

Registered Mail barcode now looks like: JJBEA65[AAAAA][BBBBBBBBBBB] where:
  • AAAAA: is the barcodeID, if your company owns one, this is where it value should be used,
  • BBBBBBBBBBB: is the sequence number (see it as a barcode unique identifier).
    It is always 11 characters long, starts with the value 00000000000 and ends with the value 99999999999.
As an example the barcode JJBEA650400056789456123 has a barcode ID set to 04000 (default value) and a sequence number of 56789456123.

Allowed characters in input fields
  • Uppercase and lowercase letters in English (A-Z, a-z),
  • All international accents: é, è, ü, ë, ö, ä, ç, ß, ô, etc,
  • Special characters such as ! # $ % & ' * + - / = ? ^ _
  • Alternative special characters such as " ( ) , : ; < > @
  • Spaces
  • emojis and other images are not allowed specifically
Authorizations:
ApiKeyAuthentication
path Parameters
product
required
string
Example: registeredmail

String identifier for the product. Accepted values are "registeredmail" and "judicialmail"

header Parameters
x-api-version
required
string
Example: v1

Indicates which version of the API is used to enable implementations concurrency.

x-api-key
required
string
Example: abhcn12345jnjmk

Authentication string provided by bpost. Is used to identify the user.

Request Body schema: application/json

Data related to the announcement. Contains the Sender and Receivers' addresses as well as the chosen options and optional custom reference fields.

accountID
required
integer <int64> (AccountID) <= 18 characters

Sender main account ID provided by the Account & User Management platform, matches a company

subaccountID
integer <int64> (SubaccountID) <= 18 characters

Sender subaccount ID provided by the Account & User Management platform, matches a company department

routerID
integer <int64> (RouterID) <= 18 characters

Router account ID provided by the Account & User Management platform

object

Responses

Request samples

Content type
application/json
{
  • "accountID": 843249,
  • "subaccountID": 573116,
  • "routerID": 122598,
  • "itemDetails": {
    }
}

Response samples

Content type
application/json
{
  • "announcementID": "68b0ac5b-dc14-4063-bbfc-b631a304c512",
  • "accountID": "12345",
  • "accountName": "account name",
  • "subaccountID": "12346",
  • "subAccountName": "sub account name",
  • "routerID": "12347",
  • "routerName": "router name",
  • "message": "The announced registered mail is valid",
  • "itemDetails": {
    },
  • "status": {
    }
}

Announcement process feedback. Contains data about addresses validation.

Returns process progress on bpost side along with addresses processing informations. Expects the barcode provided during the announcement.

Authorizations:
ApiKeyAuthentication
path Parameters
product
required
string
Example: registeredmail

String identifier for the product. Accepted values are "registeredmail" and "judicialmail"

header Parameters
x-api-version
required
string
Example: v1

Indicates which version of the API is used to enable implementations concurrency.

x-api-key
required
string
Example: abhcn12345jnjmk

Authentication string provided by bpost. Is used to identify the user.

Request Body schema: application/json
accountID
integer <int64> (AccountID) <= 18 characters

Sender main account ID provided by the Account & User Management platform, matches a company

subaccountID
integer <int64> (SubaccountID) <= 18 characters

Sender subaccount ID provided by the Account & User Management platform, matches a company department

routerID
integer <int64> (RouterID) <= 18 characters

Router account ID provided by the Account & User Management platform

barcode
string (Barcode) <= 50 characters

Unique ID for a mail, valid 10 years after the announcement

Responses

Request samples

Content type
application/json
{
  • "accountID": 843249,
  • "subaccountID": 573116,
  • "routerID": 122598,
  • "barcode": "JJBEA655795432848652048"
}

Response samples

Content type
application/json
{
  • "announcementID": "68b0ac5b-dc14-4063-bbfc-b631a304c512",
  • "accountID": "12345",
  • "accountName": "account name",
  • "subaccountID": "12346",
  • "subAccountName": "sub account name",
  • "routerID": "12347",
  • "routerName": "router name",
  • "barcode": "JJBEA655795432848652048",
  • "message": "string",
  • "senderAddress": {
    },
  • "receiverAddress": {
    },
  • "product": {
    },
  • "options": {
    },
  • "customerReference": {
    }
}

Search & Track

Get Registered Mail(s) statuses

Provides up to date informations on the selected barcodes

Authorizations:
ApiKeyAuthentication
path Parameters
product
required
string
Example: registeredmail

String identifier for the product. Accepted values are "registeredmail" and "judicialmail"

query Parameters
page
required
integer
Example: page=0

Zero-based page index.

size
required
integer
Example: size=50

The size of the page to be returned

header Parameters
x-api-version
required
string
Example: v1

Indicates which version of the API is used to enable implementations concurrency.

x-api-key
required
string
Example: abhcn12345jnjmk

Authentication string provided by bpost. Is used to identify the user.

Request Body schema: application/json

The Sender can input one or multiple barcodes. Providing only one barcode will get the full list of statuses in the response. Providing multiple barcodes will return, for each, the latest status.

accountID
required
integer <int64> (AccountID) <= 18 characters

Sender main account ID provided by the Account & User Management platform, matches a company

subaccountID
integer <int64> (SubaccountID) <= 18 characters

Sender subaccount ID provided by the Account & User Management platform, matches a company department

routerID
integer <int64> (RouterID) <= 18 characters

Router account ID provided by the Account & User Management platform

barcode
required
Array of strings (Barcode) [ items <= 50 characters ]

Responses

Callbacks

Request samples

Content type
application/json
{
  • "accountID": 843249,
  • "subaccountID": 573116,
  • "routerID": 122598,
  • "barcode": [
    ]
}

Response samples

Content type
application/json
{
  • "accountID": 843249,
  • "subaccountID": 573116,
  • "routerID": 122598,
  • "itemDetails": {
    }
}

Callback payload samples

Callback
POST: Sends latest item status
Content type
application/json
{
  • "accountID": "70043170045",
  • "subaccountID": "70043170045",
  • "routerID": "70043170045",
  • "itemDetail": {
    }
}

Returns the Registered Mail matching the search criterias

Given multiple criterias, returns the matching barcodes along with the data provided in the announcements. Results are paginated and the maximum number of results is 1000.
Given a user can search on different statuses, here is the statuses table:

CodeSubcodeDescription
10 The item has been announced
30 The item has been handed in to bpost (Quickstamp)
40 The item went through export customs procedures
80 The item is in transit
100 the item is out for delivery
1002The item is on the way to pickup point
1003The item is on the way
110The item could not be delivered
1101The item could not be delivered because the consignee not at home
1102The item could not be delivered because consignee moved
1103The item could not be delivered because the address is incorrect
1104The item could not be delivered, another attempt will be performed
1105 The item could not be delivered becauseof an unexpected issue
200 The item made available at pickup point
300 The item has been delivered
3001The item has been delivered at door
3004The item has been picked up by consignee at pickup point
3005The item has been delivered at Letterbox
400 The item has retuned to sender
4001 The item is retuned to sender because of a wrong address
4002The item has retuned to sender because it was refused by the receiver
4003The item has retuned to sender because it was damaged
4004The item has retuned to sender because it was not collected by addressee from the pickup point
4005The item has retuned to sender because of an unexpected issue
Authorizations:
ApiKeyAuthentication
path Parameters
product
required
string
Example: registeredmail

String identifier for the product. Accepted values are "registeredmail" and "judicialmail"

query Parameters
page
required
integer
Example: page=0

Zero-based page index.

size
required
integer <= 50
Example: size=50

The size of the page to be returned, max value is 50

header Parameters
x-api-version
required
string
Example: v1

Indicates which version of the API is used to enable implementations concurrency.

x-api-key
required
string
Example: abhcn12345jnjmk

Authentication string provided by bpost. Is used to identify the user.

Request Body schema: application/json

Valid search criterias, as default the dateFrom and DateTo values match for the previous year (current day - 365 days). All fields must be present, only filled ones will be used for searching. Fields will be treated as if partially filled.

accountID
required
integer <int64> (AccountID) <= 18 characters

Sender main account ID provided by the Account & User Management platform, matches a company

subaccountID
Array of integers
routerID
integer <int64> (RouterID) <= 18 characters

Router account ID provided by the Account & User Management platform

object

Responses

Request samples

Content type
application/json
{
  • "accountID": 843249,
  • "subaccountID": [
    ],
  • "routerID": 122598,
  • "itemDetail": {
    }
}

Response samples

Content type
application/json
{
  • "searchResponse": {
    }
}

Proofs

Proof of deposit (with Acknowledgment Receipt)

Returns a digitally signed Proof of Deposit in PDF format. If the AR option was selected during the announcement, the 2nd page related to the option will be added as soon as related data are available, on user request.

Authorizations:
ApiKeyAuthentication
path Parameters
product
required
string
Example: registeredmail

String identifier for the product. Accepted values are "registeredmail" and "judicialmail"

header Parameters
x-api-version
required
string
Example: v1

Indicates which version of the API is used to enable implementations concurrency.

x-api-key
required
string
Example: abhcn12345jnjmk

Authentication string provided by bpost. Is used to identify the user.

Request Body schema: application/json

Given a barcode, returns the related Proof of Deposit

accountID
required
integer <int64> (AccountID) <= 18 characters

Sender main account ID provided by the Account & User Management platform, matches a company

subaccountID
integer <int64> (SubaccountID) <= 18 characters

Sender subaccount ID provided by the Account & User Management platform, matches a company department

routerID
integer <int64> (RouterID) <= 18 characters

Router account ID provided by the Account & User Management platform

barcode
required
string (Barcode) <= 50 characters

Unique ID for a mail, valid 10 years after the announcement

Responses

Request samples

Content type
application/json
{
  • "accountID": 843249,
  • "subaccountID": 573116,
  • "routerID": 122598,
  • "barcode": "JJBEA655795432848652048"
}

Response samples

Content type
application/json
{
  • "accountID": "string",
  • "subaccountID": "string",
  • "routerID": "string",
  • "barcode": "JJBEA655795432848652048",
  • "itemDetails": {
    }
}