Bulk Request API Specification
This chapter contains information on the header, request, and response body required to make a successful bulk request with the EPC compliant API for Banks. You can read about the error status and codes here.
Document History
| Version | Date | Description |
|---|---|---|
| 1.0 | 15 Jan 2025 | Original Digital Version. Aligned with PDF V1.0 |
Headers
- Name
X-Request-Id- Type
- String
- Tag(s)
- Mandatory
- Description
A RFC4122 UUID used as a correlation id.
- Name
Content-Type- Type
- application/x-ndjson
- Tag(s)
- Mandatory
- Description
Content type and encoding of the request.
- Name
Authorization- Type
- Bearer
- Tag(s)
- Mandatory
- Description
Oauth 2.0 bearer token.
- Name
Accept-Language- Type
- String
- Tag(s)
- Optional
- Description
Can be provided by the Requesting PSP to be used as language in the 'nameSuggestion' response field (when data is available in the given language).
- Format: ISO 639.
Example of Request headers
| Header name | Example |
|---|---|
| X-Request-Id | 123e4567-e89b-12d3-a456-42661417400 |
| Content-Type | application/x-ndjson;charset=utf-8 |
| Authorization | Bearer <your bearer token> |
| Accept-Language | EN |
Request body
Two combinations are supported as VOP requests (A) Name + IBAN and (B) Identifier Code + IBAN. In case of Natural Person, only combination (A) is possible. The body of the request is a file in NDJSON format, applying the following data model for each record in the file. The client should stream the NDJSON file.
- Name
uetr- Type
- String
- Tag(s)
- Mandatory
- Description
The Unique End-to-End Transaction Reference (UETR) is an RFC4122 UUID used as a record-level correlation ID to uniquely track and trace individual transactions throughout the process.
- Name
party- Type
- Object
- Tag(s)
- Mandatory
- Description
Provide information about the identification of the Payee.
- Name
name- Type
- String
- Tag(s)
- Description
The name of the Payment Counterparty.
- Mandatory for Natural Person.
- Optional for organisations.
- Usage Rule: If ‘name’ is included, the ‘identification’ object cannot be used in the same request.
- Format: Max. 140 characters.
- Name
identification- Type
- String
- Tag(s)
- Description
Organisation’s legal identification.
- Required if ‘name’ is not provided.
- Usage Rule: If ‘identification’ is included, the ‘name’ field cannot be used in the same request.
- Name
organisationId- Type
- array of object
- Tag(s)
- Description
Used to verify whether an organisation ID matches a bank account.
- Name
lei- Type
- String
- Tag(s)
- Description
Legal entity identification as an alternate identification for a party. LEI is a code allocated to a party as described in ISO 17442 "Financial Services - Legal Entity Identifier (LEI)".
- Usage Rule: If ‘lei’ is used, ‘other’ and ‘anyBIC’ fields cannot be used.
- Format:
^[0-9]{4}00[A-Z0-9]{12}[[A-Z]0-9]{2}?$ - Example: '549300DTUYXVMJXZNY7'
- Name
others- Type
- Object
- Tag(s)
- Description
Object defined to add another type of legal identification besides 'Legal Entity Identifier'.
- Usage Rule: Can only be used if ‘lei’ and ‘anyBIC’ are not used.
- Name
identification- Type
- String
- Tag(s)
- Mandatory
- Description
The identification code of the Payment Counterparty.
- Format: Max. 256 characters.
- Name
schemeNameCode- Type
- Enum
- Tag(s)
- Description
The type of the identification code of the Payment Counterparty. As an exception, the use of either ‘schemeNameCode’ or ‘schemeNameProprietary’ is mandatory when the ‘identification code’ is used.
- Find the code list in here.
- Name
schemeNamePropietary- Type
- String
- Tag(s)
- Description
Name of the identification scheme, in a free text form. As an exception, the use of either ‘schemeNameCode’ or ‘schemeNameProprietary’ is mandatory when the ‘identification code’ is used.
- Format: Max. 35 characters.
- Name
issuer- Type
- String
- Tag(s)
- Description
Entity that assigns the identification.
- Format: Max. 35 characters.
- Name
partyAccount- Type
- Object
- Tag(s)
- Mandatory
- Description
Payment account details of the Payee.
- Name
iban- Type
- String
- Tag(s)
- Description
The Payment Account Number of the Payment Counterparty. The IBAN needs to be valid, otherwise it results in a validation error.
- Format:
[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}
- Format:
- Name
unstructuredRemittanceInformation- Type
- String
- Tag(s)
- Optional
- Description
Additional information about the account number sent by the Requester.
- Example: 'Customer Reference: CUST123456'
- Name
partyAgent- Type
- Object
- Tag(s)
- Description
Identification of the Responding PSP.
- Name
financialInstitutionId- Type
- Object
- Tag(s)
- Description
Financial Institution object.
- Name
bicfi- Type
- String
- Tag(s)
- Description
Identification of the Responding PSP (Swift BIC). BIC of the Agent.
- Format:
[A-Z]{4}[A-Z]{2}[1-9][A-Z]{2}[1-9][A-Z]{3} - Example:
- 8 characters: ‘DEUTDEFF’
- 11 characters: ‘DEUTDEFF500’
- Format:
- Name
requestingAgent- Type
- Object
- Tag(s)
- Description
Identification of the Requesting PSP.
- Name
financialInstitutionId- Type
- Object
- Tag(s)
- Description
Financial Institution object.
- Name
bicfi- Type
- String
- Tag(s)
- Description
Identification of the Responding PSP (Swift BIC). BIC of the Agent.
- Format:
[A-Z]{4}[A-Z]{2}[1-9][A-Z]{2}[1-9][A-Z]{3} - Example:
- 8 characters: ‘DEUTDEFF’
- 11 characters: ‘DEUTDEFF500’
- Format:
Response body
The response is the taskId of the bulk request.
-
Successful response (HTTP 200 - described below)
-
Error response (HTTPXXX - described in Errors)
- Name
taskId- Type
- String
- Tag(s)
- Mandatory
- Description
The unique ID of the bulk request, used to retrieve the status and ultimately the result file when completed.
Request
{"uetr":"13b8472f-d796-436a-ba76-0be4ec234206","party":{"name":"Henri Groenen"},"partyAccount":{"iban":"NL11RABO1234567890"},"unstructuredRemittanceInformation":"1234512345","partyAgent":{"financialInstitutionId":{"bicfi":"ABCDBEBBXXX"}},"requestingAgent":{"financialInstitutionId":{"bicfi":"ABCDBEBBXXX"}}}
Response
{
"taskId": "12930484-129284501-ecernb"
}
List of Enumeration values
schemeNameCode
The type of the identification code of the Payment Counterparty. Used when performing a organisation ID check.
| Enumeration value | Description | Format | Example |
|---|---|---|---|
| BANK | RequestBankPartyIdentification. Bank party identification is requested. This is a unique and unambiguous assignment made by a specific bank or similar financial institution to identify a relationship as defined between the bank and its client. | Format: [CountryCode][BankCode][BranchCode] | Example: 'US123BANK001' |
| CBID | RequestCentralBankIdentificationNumber. Central bank identification number is requested. This is a unique identification number assigned by a central bank to identify an organisation. | Format: (CB)(0-9)[9-12 digits] | Example: 'CB123456789' |
| CHID | RequestClearingIdentificationNumber. Clearing identification number is requested. This is a unique identification number assigned by a clearing house to identify an organisation | Format: (A-Z)(2-4 letters)(0-9)(4-6 digits) | Example: 'CHCLRG1234' |
| CINC | RequestCertificateOfIncorporationNumber. Certificate of incorporation number is requested. This is a unique identification number assigned by a designated authority to a certificate of incorporation and used to identify an organisation. | Format: (INC)(0-9)(7-10 digits) | Example: 'INC1234567' |
| COID | RequestCountryIdentificationCode. Country identification code is requested. This is a country authority given organisation identification (e.g., corporate registration number). | Format: (A-Z)(2 digits)(0-9)(8-10 digits) | Example: 'US123456789' |
| CUST | RequestCustomerNumber. Customer number is requested. This is a number assigned by an issuer to identify a customer or a number assigned by a party to identify a creditor or debtor relationship. | Format: (CUST)(0-9)(6-8 digits) | Example: 'CUST789456' |
| DUNS | RequestDataUniversalNumberingSystem. Data universal number is requested. This is a unique identification number provided by Dun & Bradstreet to identify an organisation. | Format: (0-9)(9 digits) | Example: '123456789' |
| EMPL | RequestEmployeeIdentificationNumber. Employee Identification Number is requested. | Format: (EMP)(0-9)[6-8 digits] | Example: 'EMP123456' |
| GS1G | RequestGS1GLNIdentifier. GS1GLN (Global location number) identifier is requested. This is a non-significant reference number used to identify legal entities, functional entities, or physical entities according to GS1 numbering scheme rules. The number is used to retrieve detailed information that is linked to it. | Format: (0-9)(13-14 digits) | Example: 'GLN1234567890123' |
| SREN | RequestSIREN. SIREN number is requested. This is a 9 digit code assigned by INSEE, the French National Institute for Statistics and Economic Studies, to identify an organisation in France. | Format: (0-9)(9 digits) | Example: '123456789' |
| SRET | RequestSIRET. SIRET number is requested. This is a 14 digit code assigned by INSEE, the French National Institute for Statistics and Economic Studies, to identify an organisation unit in France. It consists of the SIREN number, followed by a five digit classification number, to identify the local geographical unit of that entity. | Format: (0-9)(14 digits) | Example: '12345678912345' |
| TXID | RequestTaxIdentificationNumber. Tax Identification Number is requested. | Format: (TX)(0-9)(8-12 digits) | Example: 'TX123456789' |
| BDID | RequestBusinessDomainIdentifier. Identifier of the business domain in which the organisation is active is requested. | Format: (BUSDOM)(0-9)(5-10 digits) | Example: 'BUSDOM12345' |
| BOID | RequestBusinessOtherIdentification. Other identification of the organisation is requested. | - | - |