Getting started
Overview
Before you can integrate with our API, you need to have been onboarded by us as a customer and have a valid authentication profile set up. This authentication profile includes your Digital Certificate and secure API token. The API token needs to be included in the header of all REST API calls. You can find information about how to generate these in our introduction section.
Common Parameters
We utilise HTTP-request headers for our API calls which include Authorization, DigitalSignature and X-Request-Id headers. In all our responses we will send an X-Correlation-Id in the header.
GET requests have an Authorization header.
NON-GET requests such as POST, PATCH and DELETE have an Authorization header.
Authorization
- string
- header
- Required
- get
- post
- patch
- delete
- request
Your API token retrieved from the portal.
DigitalSignature
- string
- header
- Required
- post
- patch
- delete
- request
This is a hash of the request body signed with your private key.
X-Request-Id
- string
- header
- Required
- post
- patch
- delete
- request
This is what we use for idempotency and enables a duplication check. You generate this identifier which must be unique for any subsequent requests sent for at least 24 hours after the initial request was sent.
If an X-Request-Id Header is not supplied, or is invalid, a 400:Bad Request HTTP status code response will be returned.
If ClearBank® detects a duplicate, a 409: Conflict HTTP status code response will be returned.
X-Correlation-Id
- string
- header
- response
This is a unique identifier generated by ClearBank® for the request. ClearBank® would require this identifier for troubleshooting purposes. Therefore, it is recommended you store this response header.
Authenticate your API calls
We use your API token to authenticate your requests and allow you to securely access protected resources.
The base URL for your environment is either:
- Simulation
https://institution-api-sim.clearbank.co.uk/ - Production
https://institution-api.clearbank.co.uk/
Your API token should be included in your HTTP Authorization header. Please refer to Common Parameters for more information.
This example request shows the API token in the Authorization , DigitalSignature and X-Request-Id header.
curl -v -POST https://institution-api-sim.clearbank.co.uk/v1/Test \-H “Authorization: Bearer <<your api token>>”-H “DigitalSignature: <<digitalsignature>>”-H “X-Request-Id: <<X-request-ID>>”-d ‘{ "body": "hello world!" }’
The response shows results from the test call
{"Message": "hello world!"}
To confirm that authentication and signature verification are working as expected, when you send a POST/v1/Test request you will receive a FITestEvent webhook from ClearBank® (if you are subscribed to it).
We use webhooks to deliver transaction confirmation notifications and account-specific reconciliations to your system as soon as such events occur on your account. Please refer to Test Webhooks for more information.
All TEST Endpoints
FITestEvent Webhook
To confirm that authentication and signature verification is working as expected, when you send a POST /v1/Test request you will receive a FITestEvent webhook from ClearBank®.