DirectID Developer Documentation (all)

Download OpenAPI specification:Download

Introduction

Welcome to the DirectID developer documentation.

There are two key integration points: DirectID Connect, which will prompt your users to select a bank and walk them through the consent and authentication stages, and the DirectID Data API that you can use to interact with users, consents and bank data. Both APIs return data in JSON format.

DirectID Connect

Overview

DirectID Connect is the mechanism by which users provide their consent for us to retrieve their banking information on your behalf. It is a hosted web UI that allows a user to search for their financial institution, select it, provide consent to share the data you require, and then log in with their credentials - allowing us to fetch their data. Once their data has been successfully retrieved, or an error occurs, a webhook will inform you.

Flow

You can experience the flow an end-user will go through by booking a demo on our site, however given below is a brief description of that flow. The user will land on the bank select page where they can choose from one of your configurable favourites. These are displayed as tiles with the financial institution's logo prominently shown.

Bank Select

A user can search for a bank should it not be displayed as a favourite:

Bank Search

Once a bank is selected the user will be prompted to select an account type if the connection to the bank is performed via credential sharing:

Provider Selection

Once an account type has been selected, or if the connection to a bank is via OAuth, the user will be prompted to provide consent to share the data you have requested:

Consent Screen

The drop downs expand to explain exactly what data will be shared. Only drop downs for the data your account has been configured to request will be displayed to an end-user. Please note that you can provide your own list of terms and conditions to display, and these will be shown beneath the five bullets. Once the user consents to share their data, they will be redirected to their financial institution's online login page when we have a direct connection to an institution's API - otherwise they will be taken to a service we control that facilitates data sharing via credential sharing. Once the user has logged in, they will be redirected back to DirectID Connect:

Sharing Success

Re-authentication

DirectID Connect allows re-authentication of consents to extend the lifetime of the consent. This flow can be started when a consent is about to expire, is expired or revoked.

DirectID provides both Webhooks and Email notification V2 to notify of upcoming consent expirations, each of which can be configured for how many days prior to consent expiration they should be triggered.

To re-authenticate a consent:

  1. Get an access token for Consent API using the Authorization API (Scope should be directid.consent).
  2. Append the consent ID that needs to be re-authenticated as query parameter and add the access token as a fragment to the DID Connect url. eg: https://connect.direct.id?consent_id=<ConsentID>#access_token=<AccessToken> and send it to the end user.
  3. User will be prompted to confirm the details of re-authenticating their access:

Note: directid.consent Access Token validity period is about 1 hour. Attaching Reauthentication URL straight to the email would not end up with good user experience as URL would not be usable after 1 hour. Recommended approach is to redirect end user to your page, where end user can continue with Reauthentication and new Access Token can be requested.

Reauthentication flow

Reauthentication flow step 1

Reauthentication flow step 2

User is redirected to their bank where they will authorize the access:

Reauthentication flow step 3

If authorization was successful, user is redirected back to Connect:

Reauthentication flow step 4

The user may be required to re-select their accounts during the reauthentication flow. This will only be applicable after their consent has been marked as Revoked by calling the Revoke Consent API.

Notifications

DirectID dispatches Webhook evenType : Consent when the journey finishes. consentJourney value is set to Reauthentication. Once the journey finishes and a notification is received indicating success, you may resume fetching the data from the APIs.

API Flow

Reauthentication API flow diagram

Reconfirmation

Get access to your user's account information for longer by allowing your user to reconfirm the consent. This feature is only available in the UK.

DirectID Connect allows reconfirmation of consents to extend the lifetime of the consent. This flow should be started when a consent is about to expire. Regulation enforced by PSD2 states that consents can last up to 90 days and to continue to access the data, reconfirmation has to be received after every 90 days by the end-user.

DirectID provides both Webhooks and Email notification V2 to notify of upcoming consent expirations, each of which can be configured for how many days prior to consent expiration they should be triggered.

Starting reconfirmation flow

To reconfirm a consent:

  1. Get an access token for Consent API using the Authorization API (Scope should be directid.consent).
  2. Append the consent ID that needs to be reconfirmed as query parameter and add the access token as a fragment to the DID Connect url. eg: https://connect.direct.id?consent_id=<ConsentID>#access_token=<AccessToken> and send it to the end user.
  3. User will be prompted to reconfirm the details of their access:

Note: directid.consent Access Token validity period is about 1 hour. Attaching Reconfirmation URL straight to the email would not end up with good user experience as URL would not be usable after 1 hour. Recommended approach is to redirect end user to your page, where end user can continue with Reconfirmation and new Access Token can be requested.

Reconfirmation flow

Reconfirmation flow step 1

Reconfirmation flow step 2

Reconfirmation flow step 3

Based on a bank’s internal criteria, users may be required to re-authenticate their consent with the bank at certain times. See how this flow will look like in Re-authentication docs.

Disconnect flow

If a user doesn't wish to prolong access to the data, then they can revoke access to the bank data.

Reconfirmation disconnect flow step 1

Reconfirmation disconnect flow step 2

Reconfirmation disconnect flow step 3

Notifications

DirectID dispatches Webhook evenType : Consent when the journey finishes. consentJourney value is set to Reconfirmation. Once the journey finishes and a notification is received indicating success, you may resume fetching the data from the APIs.

API Flow

Reconfirmation API flow diagram

Configuration

Your account manager can configure a variety of settings for you, these include:

Setting Value
Favourites The list of financial institutions that are listed on the landing page as tiles
Default Country The country that is selected by default for search
Available Countries The countries whose financial institutions will be available for an end-user to search through
Notification Email If you do not wish to receive a notification of a user sharing their data via a webhook, you can provide us with an email address that will be notified instead
Terms The terms you wish to have displayed to the end user on the consent screen. These can be provided in multiple languages, and the terms matching the end-user's browser settings will be displayed in the consent screen
Redirect URL When set, the end user is redirected to that URL after they journey is complete.

Note that you can have several configurations set up (for example if your business operates in multiple regions and you wish to show different terms and have a different set of institutions available for the user to search through) and you can choose between them by passing in a parameter to the URL.

Integration

To integrate DirectID Connect, you need only include a link to our hosted UI in a location of your choice in your application or on your website. This link will be given to you by your account manager once your account has been set up.

Parameters

The URL that launches DID Connect can be provided with several parameters:

Parameter Description Mandatory
client_id Your application ID which will be provided by your account manager Yes
config_id The ID of the configuration you wish to load DirectID Connect with. This ID is decided on by you No - if not provided a default configuration will be used
customer_ref Your reference for the end user going through the DirectID Connect journey Yes
provider_id If you already know which provider the user wishes to connect with, the ID can be provided to skip the bank selection and search part of the journey No
bank_code If you already know the end users bank code, the bank code can be provided to skip the bank selection and search part of the journey if we have a registered provider for the provided bank code. Note, the country_code parameter is also required No
country_code Requried parameter if passing in the bank_code parameter No

DirectID Connect can be setup to redirect to a URL. This can be setup by contacting support.

On redirection we will pass the following parameters to the redirection URL.

Parameter Description Mandatory
customer_ref Your reference for the end user going through the DirectID Connect journey Yes
state the state of the end user journey. success or error Yes
error an error code. see DirectID Connect Errors for possible codes. Yes if state is error, No otherwise
consent_id Unique ID for the end-user's Consent that allows us to fetch their data Yes if state is success, No otherwise

Notifications

Notifications are used by Direct ID to inform you of your customer’s user journey through Direct ID. Notifications come in two flavours, email and webhook. Notifications can be used to track the customer's status e.g. whether they have successfully connnected, their data is available, an invitation email has been delivered, etc. Notifications also include any errors that may have occurred. Different notifications can be set up for different providerAuthentication and dataAvailability statuses.

Email

Email notifications are useful for Dashboard product consumers, who are not utilizing DirectID APIs. These notifications will give you real-time info about connected consent details.

The email notification can be enabled by contacting support.

V1 (deprecated)

NB: Email notifications are supported for v1 notifications only.

The email notification can contain the following fields:

Parameter Description
ConsentId Unique ID for the end-user's Consent that allows us to fetch their data
CustomerReference Your reference for the end-user
ProviderAuthentication The provider authentication status for the consent: Success, Error
DataAvailability The data availability status for the consent. Populated when Provider Authentication is successful, otherwise null: Error, Partial, Complete, Processed
ErrorMessage The error message if there are any errors raised for this event (Optional)

V2

The email notification can contain the following fields:

Parameter Description
ConsentId Unique ID for the end-user's Consent
Consent Status Consent current status
Possible values: "Pending" "Active" "Revoked" "Abandoned" "Failed" "Expired" "UpcomingExpiration"
Journey Type Refers if end-user is going through process to extend consent validity.
Possible values: "Reconfirmation" "Reauthentication"
(Optional) In case of a new connection, Journey Type is not populated
Consent Period Consent start date, Consent end date
Last Updated Date when Consent status was last time updated
CustomerReference Your reference for the end-user
Data Availability The data availability status for the consent.
Possible values: "Error" "Partial" "Complete" "Processed"
(Optional) We are populating this field only if Consent Status is "Active"
Error Message The error message if there are any errors raised for this event.
(Optional) We are populating this field only if there have been any errors

Webhooks

DirectID uses webhooks to send real-time notifications to your application regarding updates to a user consent within the DirectID platform. These webhooks deliver push notifications through HTTPS requests with the data encapsulated in JSON payloads.

Configuring webhooks

To use webhooks, you will first need to set up an endpoint that accepts HTTP POST requests with the schema defined below. It is possible to apply OAuth2 authentication, if you want to make sure that no one can call your endpoint. Webhooks can be enabled by contacting support.

Payload Details

  • The HTTP Method will always be POST
  • The Content Type will always be application/json

Retry policy

If your endpoint is not able to handle the first webhook, then we will retry three times before discarding it. There will be 2 seconds, 4 seconds and 8 seconds delay between retries.

V1 (deprecated)

The webhook will contain your unique ID customerReference passed back to you as well as our internal reference consentId. The internal reference is required to access any of our endpoints about that individual.

  • You will need to set up an endpoint
  • This endpoint must be able to accept a post request from our server as defined below.

Payload Details

  • The HTTP Method will always be POST
  • The Content Type will always be application/json
  • The request JSON will have the following properties:
Property Type Nullable Details
consentId string No Unique ID for the end-user's Consent that allows us to fetch their data
applicationId string No The ID of your account in our system
customerReference string Yes Your reference for the end-user
providerAuthentication string
Enum: "Success", "Error"
No The provider authentication status for the consent
dataAvailability string
Enum: "Error", "Partial", "Complete", "Processed"
Yes The data availability status for the consent. Populated when Provider Authentication is successful, otherwise null
paymentConfirmation string
Enum: "Complete", "Incomplete"
Yes The payment confirmation status for the consent. Populated when Payment Confirmation is enabled
reauthentication boolean No Indicates whether the consent is being re-authenticated
errorMessage string Yes The error message if there are any errors raised for this event
  • Given below is a brief explanation of all the enums mentioned above

    • providerAuthentication

      Value Explanation
      "Success" Provider authentication was successful
      "Error" There was an error during provider authentication
    • dataAvailability

      Value Explanation
      null Data availability status is pending
      "Error" There has been an error in fetching data from the provider
      "Partial" Account data is available from Data API, however transaction data is still pending
      "Complete" The bank data is avaiable via the Stored Data API and Data API
      "Processed" Stored Data has been enriched and is avaiable via the Stored Data API
    • paymentConfirmation

      Value Explanation
      null Payment account confirmation is not available/enabled
      "Complete" Payment account confirmation was completed
      "Incomplete" Payment account confirmation is incomplete
  • Here is an example of the request body JSON

{
  "consentId": "207e50aa-72c0-11eb-9439-0242ac130002",
  "applicationId": "26e667b6-72c0-11eb-9439-0242ac130002",
  "customerReference": "defaultuser",
  "providerAuthentication": "Success",
  "dataAvailability": "Complete",
  "paymentConfirmation": null,
  "reauthentication": false,
  "errorMessage": null
}

V2 Webhooks

v2 event schema

Property Type Nullable Details
eventId string No Unique ID belonging to the Webhook event
eventType string
Nominally: "Consent" "Invitation"
No Indicates the type of event the webhook represents
eventTime string
UTC formatted timestamp
No Indicates the time when the webhook was sent
schemaType string
Nominally: "Consent" "Email"
No Indicates the webhook schema type
schemaVersion string No Indicates the version of the webhook schema
{
  "eventId": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
  "data": {  },
  "eventType": "Consent",
  "eventTime": "2022-01-01T00:00:00Z",
  "schemaType": "Consent",
  "schemaVersion": "1.0.0"
}

Consent schema returns a holistic overview of consent status and data availability, and provides details about connected provider, consent validity period and its journey type.

Configuring this Webhook is highly recommended in case you are using DirectID APIs.

Property Type Nullable Details
consentId string No Unique reference for the consent
applicationId string No Unique ID of your account in our system that was used to request the Connect Invitation
providerId integer No Provider Id for the consent
providerName string Yes Provider name for the consent
configurationName string Yes Specific configuration of the client
customerReference string No Your reference for the end-user
consentStatus string
Enum: "Pending" "Active" "Revoked" "Abandoned" "Failed" "Expired" "UpcomingExpiration"
No Consent status
consentJourney string
Enum: "Reauthentication" "Reconfirmation"
Yes Indicates which journey type the end-user went through
consentStart string
UTC formatted timestamp
Yes Start date for the consent
consentEnd string
UTC formatted timestamp
Yes End date for the consent
statusUpdated string
UTC formatted timestamp
No Date of last status update of the consent
dataAvailability string
Enum: "Error" "Partial" "Complete" "Processed"
Yes The data availability status for the consent
(Optional) We are populating this field only if consentStatus is Active
errorMessage string Yes The error message if there are any errors raised for this event
invitationId string Yes Unique ID belonging to a particular Connect Invitation
eventType string
Nominally: "Consent"
No Indicates the type of event the webhook represents
eventTime string
UTC formatted timestamp
No Indicates the time when the webhook was sent
schemaType string
Nominally: "Consent"
No Indicates the webhook schema type
schemaVersion string No Indicates the version of the webhook schema
  • Here is an example of the request body JSON
{
  "eventId": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
  "data": {
      "consentId": "e521cf62-a45f-49c5-8372-94853fffeb55",
      "applicationId": "97ab27fa-30e2-43e3-92a3-160e80f4c0d5",
      "providerId": 0,
      "providerName": "string",
      "configurationName": "string",
      "customerReference": "string",
      "consentStatus": "Pending",
      "consentJourney": "Reconfirmation",
      "consentStart": "2019-08-24T14:15:22Z",
      "consentEnd": "2019-08-24T14:15:22Z",
      "statusUpdated": "2019-08-24T14:15:22Z",
      "dataAvailability": "string",
      "invitationId": "string"
  },
  "eventType": "Consent",
  "eventTime": "2022-01-01T00:00:00Z",
  "schemaType": "Consent",
  "schemaVersion": "1.0.0"
}
Success flow

Consent event success flow

Failure flow

Consent event failure flow

Invitation

Invitation event type webhooks are meant to be used hand in hand with DirectID Connect Invitation API product. The webhook will contain necessary information to track specific invitations through their phases.

Property Type Nullable Details
eventId string No Unique ID belonging to the Webhook event
invitationId string No Unique ID belonging to a particular Connect Invitation
emailState string
Enum: "Sent" "Received" "Opened" "Clicked" "Failed"
No Indicates state of email
customerReference string No Your reference for the end-user
smtpErrorCode string Yes Indicates the SMTP error code (if any)
smtpErrorMessage string Yes Indicates the SMTP error reason (if any)
applicationId string No Unique ID of your account in our system that was used to request the Connect Invitation
connectionStatus string
Enum: "Pending" "Cancelled" "Active" "Abandoned"
No Indicates if the end-user has actioned Connect Flow
eventType string
Nominally: "Invitation"
No Indicates the type of event the webhook represents
eventTime string
UTC formatted timestamp
No Indicates the time when the webhook was sent
schemaType string
Nominally: "Email"
No Indicates the webhook schema type
schemaVersion string No Indicates the version of the webhook schema
  • Here is an example of the request body JSON
{
  "eventId": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
  "data": {
      "invitationId": "fdd86d02-5745-4cc9-ad9a-8372d6ec2c9b",
      "applicationId": "26e667b6-72c0-11eb-9439-0242ac130002",
      "emailState": "Received",
      "customerReference": "ProposalNumber",
      "smtpErrorCode": "",
      "smtpErrorMessage": "",
      "connectionStatus": "Pending",
  },
  "eventType": "Invitation",
  "eventTime": "2022-01-01T00:00:00Z",
  "schemaType": "Email",
  "schemaVersion": "1.0.0"
}

Optional OAuth2 Authentication

If you want to make sure that no one can call your endpoint, except for verified clients, we can enable our server to connect to your OAuth2 authorisation server and get an access token. We then send it to you to authenticate you to use our API, in the same way that you connected to our OAuth2 provider. In addition to the data listed above, we will require the following details:

  • A Client ID for your OAuth authorisation server
  • A Secret Key for your OAuth authorisation server
  • An endpoint to request the access Token
  • An optional scope

Example requests

Here are two example requests we do to compete the OAuth2 Webhook flow:

  • Make a request for bearer token using the customer supplied: Authorisation Server Url, Client Id, Client Secret, and Optional Scope which returns the accessToken that we use to authenticate with their webhook URL. We use Basic authentication so the request will contain a header of the form Authorization: Basic <encodedCredentials> where encodedCredentials is a Base64 encoded ClientId:ClientSecret
  • We call the customer supplied Webhook Url using the access token returned as the bearer token
Example initial token request
curl --location -g --request POST 'https://[CustomerAuthorisationServerUrl]' \
--header 'Authorization: Basic W0NsaWVudElkXTpbQ2xpZW50U2VjcmV0XQ==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=[Optional Scope]'
Example expected response
{
  "token_type": "bearer",
  "expires_in": 123,
  "access_token": "ReturnedAccessToken"
}
Example webhook POST request
curl --location -g --request POST 'https://[CustomerWebhookUrl]' \
--header 'Authorization: Bearer [ReturnedAccessToken]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "consentId": "207e50aa-72c0-11eb-9439-0242ac130002",
  "applicationId": "26e667b6-72c0-11eb-9439-0242ac130002",
  "customerReference": "defaultuser",
  "providerAuthentication": "Success",
  "dataAvailability": "Complete",
  "paymentConfirmation": null,
  "reauthentication": false,
  "errorMessage": null
}'

DirectID APIs

Getting started: what you need

To access the DirectID Data API, you will need access credentials that will be provided to you by our support team.

These credentials will be used to obtain an access_token that is required to authenticate with the DirectID Data API endpoints.

Once your user has connected to their bank through DirectID Connect, you can call the DirectID Data API endpoints to retrieve their bank data. Each set of credentials comprises the following information:

  • A client_id, which is the OAuth public identifier for your application
  • A client_secret, which is the secret used to authenticate the client_id
  • A scope, which is used to determine API access.

To receive notifications about the user's status, you need to provide us with a webhook URL which we will notify upon successful connection with the bank. For further information please see the Webhooks section.

In summary, you'll need the following:

  • URL, resource ID, and credentials for the DirectID Data API
  • A page on which you can insert the link to DirectID Connect
  • A web service "Webhook" that we call when your user has completed their journey, and the bank data is ready

Tokenized account numbers

Providers in the U.S. are adopting the use of Tokenized Account Numbers (TANs) to reduce the potential exposure of sensitive personal information. When you fetch data from a provider that implements this method, TANs are provided instead of the full or masked account numbers. You will find the Tokenized Account Number (TAN) returned in the accountNumber field, typically located within the identifiers object in our API responses.

The functionality provided does not enable customers to conduct Bank account verification checks or perform any other form of account number matching for payment purposes.

The following providers are returning tokenized account number(s):

Chase Bank (US) - Tokenized Account Number

Security

DirectID APIs are currently supporting only TLS 1.2

Errors

DirectID Connect

If an error occurs during the DirectID Connect journey, a URL parameter error will be included in the callback and in a webhook if specified. An optional parameter of error_description may be included with further information.

Error Description
access_denied The Customer or the bank has denied consent. A reauthentication may result in a successful journey.
provider_permanent_error An error has occurred with the bank and we are not able to complete the request.
provider_unsupported_feature Feature is unsupported for provider.
customer_cancelled The customer has cancelled the DirectID Connect journey. The customer will need to complete the journey again.
unexpected_error An unexpected error has occurred which is not recoverable.

DirectID APIs

These errors will be returned via the API Endpoints in the application/json response format below. CorrelationId is our unique reference to trace the error.

{
  "Code": "string",
  "Description": "string",
  "Details": "string",
  "CorrelationId": "string"
}
HTTP Status Code Description
400 application_invalid Invalid application id was provided.
400 parameters_invalid Invalid parameters were provided.
400 template_invalid Invalid template id was provided.
401 unauthorised_client Client is not authorised.
403 account_refresh_not_allowed Refresh is not allowed for this account.
403 consent_denied Consent was denied access by the bank.
403 consent_expired Consent has expired.
403 consent_revoked Consent was revoked.
403 sca_error SCA expiry has elapsed. Please have the user re-authenticate to continue
404 account_not_found Account requested was not found.
404 client_not_found Client for the provided client id was not found.
404 configuration_not_found Configuration for the provided application id/configuration id was not found.
404 consent_not_found Consent for the provided consent id was not found.
404 invitation_not_found Email invitation for the provided invitation id was not found.
422 provider_unsupported_feature Feature is unsupported for provider.
500 unexpected_error Unexpected error has occured. Please contact our support team.
502 provider_permanent_error Provider is permanently unavailable.
502 provider_rate_limit_reached Cannot request data for this provider as the rate limit has been reached.
502 provider_temporarily_unavailable Provider is temporarily unavailable. Please try again later.

Authentication

Bearer

JWT Authorization header using the Bearer scheme.

Enter 'Bearer' [space] and then your token in the text input below.

Example: "Bearer token123"

Security Scheme Type HTTP Authorization Scheme
HTTP bearer

Get Token

Overview

To access our APIs you need to pass your client_id and client_secret, along with the scope that you are requesting, to our authentication service. If that all goes according to plan then an access_token will be returned to you, which is valid for one hour.

Integration

A request with the following payload to our endpoint should return an access token for use in subsequent calls in any of our Data API endpoints.

Key Value
grant_type client_credentials
client_id The client_id that we supplied to you
client_secret The client_secret that we supplied to you
scope The scope value for the API that you need access to

Please find below the scopes values for our APIs, these values need to be specified when requesting a token:

API Scope
DirectID Consent Service directid.consent
DirectID Data API directid.data
DirectID Stored Data API directid.stored_data
DirectID Advanced Insights API directid.advanced_insights
DirectID Connect Invitation API directid.connect_invitation

Assuming the authentication was successful, you should receive a 200 OK response.

The important fields in the authentication response are:

Field Description
expires_in The number of seconds before the token expires (defaults to 3600 seconds)
token_type Bearer
access_token The token you will use in subsequent requests

If you expect to make repeated and/or delayed calls using this access_token, you should pay attention to the expires_in field and request a new token if you have exceeded the expiration time.

Using the acccess token

Once you have the access_token, you'll assign it to the Authorization header with a prefix of Bearer. More information can be found here .

Request a token for the provided scope and grant type (only client_credentials supported)

Request Body schema: application/x-www-form-urlencoded
grant_type
string or null
client_id
string or null
client_secret
string or null
scope
string or null

Responses

Response samples

Content type
application/json
{
  • "tokenType": "string",
  • "expiresIn": 0,
  • "accessToken": "string"
}

Connect Invitation

OVERVIEW

Connect Invitation API offers the capability to effortlessly send Connect invitations to your users. It is underpinned by DirectID's outbound email solution which supports dynamic components that provide flexible email content and customisation. The email subject, sender address and message will be configured in the email template for you by our support team.

Get immediate feedback about email delivery using our v2 webhooks, which will inform you if the invitation email's state has been Sent, Received, Opened, Clicked, or Failed. This provides additional tracking possibilities to build more sophisticated workflows based on time period and see if the customer has actioned a Connect Invitation email during the configured period.

AUTHENTICATION

This API requires a bearer token using the directid.connect_invitation scope.

Gets a single email invitation

Authorizations:
Bearer
path Parameters
invitationId
required
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Sends an email invitation

Authorizations:
Bearer
Request Body schema:

Request details including recipient name, email, etc

customerReference
required
string non-empty ^[a-zA-Z\d_. \+\-\(\)]{1,100}$

Customer reference for this recipient, an example would be a unique identifier of this user in customer's internal systems

recipientEmail
required
string <email> non-empty ^[\u00c0-\u01ffa-zA-Z0-9_\.-]+@([\u00c0-\u01f...

Email address of the recipient to whom the email is going to be sent

recipientName
required
string non-empty ^([\u00c0-\u01ffa-zA-Z'\d_. \+\-\(\)]){1,100}...

Name of the recipient (e.g. full name of the person)

templateId
string or null

Template ID to be used for the email, if not specified the default template from configuration will be used

Responses

Request samples

Content type
{
  • "templateId": "string",
  • "recipientName": "string",
  • "recipientEmail": "user@example.com",
  • "customerReference": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get Consents

Overview

This allows you retrieve details for consents such as expiry date, status, provider, permissions and any other detail about the consent that has been stored.

Retrieve list of consents.

Authorizations:
Bearer
query Parameters
consentStatus
string

Optional filter to get consents with a particular status.

configurationName
string

Optional filter to get consents only for a particular configuration name for the client.

providerId
integer <int32>

Optional filter to get consents only for a particular provider id.

customerReference
string

Optional filter to get consents that match the customer reference exactly.

from
string <date-time>

Optional filter to get consents which have been created/updated after the from date.

to
string <date-time>

Optional filter to get consents which have been created/updated before the to date.

offset
integer <int32>
Default: 0

Number of consents to skip.

limit
integer <int32>
Default: 0

Maximum number of consents in the response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a consent by consent ID.

Authorizations:
Bearer
path Parameters
consentId
required
string

The consent ID to fetch the consent details for. This should be a uuid.

Responses

Response samples

Content type
application/json
{
  • "consentId": "e521cf62-a45f-49c5-8372-94853fffeb55",
  • "applicationId": "97ab27fa-30e2-43e3-92a3-160e80f4c0d5",
  • "providerId": 0,
  • "providerName": "string",
  • "configurationName": "string",
  • "customerReference": "string",
  • "consentDurationType": "Single",
  • "consentStatus": "Pending",
  • "consentStart": "2019-08-24T14:15:22Z",
  • "consentEnd": "2019-08-24T14:15:22Z",
  • "duration": "string",
  • "daysOfHistoricalTransactions": 0,
  • "statusUpdated": "2019-08-24T14:15:22Z",
  • "statusDetails": "string",
  • "permissions": [
    ],
  • "invitationId": "string",
  • "journeyType": "Reauthentication"
}

Revoke a consent.

Authorizations:
Bearer
path Parameters
consentId
required
string

The consent ID for the consent to revoke.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "description": "string",
  • "details": "string",
  • "correlationId": "string"
}

Bank Account Verification

Overview

If you only need to verify that the shared bank account(s) belong(s) to a certain person, instead of fetching all the bank account data, you can simply call the account verification endpoint.

In addition to comparing account identifiers (account number, bank code), Bank Account Verification will apply a set of sophisticated algorithms and rules in attempts to determine whether the provided account holder name matches that retrieved from the bank. While we do our best to perform the comparison regardless of the name format, we recommend you ask your user to provide their name as it appears on their bank statement.

Integration

In response to your call, you will receive a JSON object containing the verification result and optionally a reason of a failed verification.

We currently support IBAN or a bank code as account identifiers. Given below is a list of supported bank codes for a country/region.

Bank Code Region
Routing Number US, CA
Sort Code UK
BIC Global provided the bank is part of SWIFT. Please note not all banks will expose this even if they are part of the SWIFT network.

Trigger a bank account validation. Deprecated

Returns a result with an accompanying error code if validation is inconclusive.

Authorizations:
Bearer
path Parameters
consentId
required
string

The consent ID to fetch the account information for

Request Body schema:

Bank account details

accountHolderName
required
string non-empty

Individual associated with the target account

required
object (DirectID.Data.API.Models.AccountVerification.Request.LegacyIdentifier)

Responses

Request samples

Content type
{
  • "accountHolderName": "string",
  • "identifier": {
    }
}

Response samples

Content type
application/json
{
  • "result": "Pass",
  • "reason": "AccountIdentifierNotFound"
}

Trigger a bank account validation. Deprecated

Returns a result with an accompanying error code if validation is inconclusive.

Authorizations:
Bearer
path Parameters
consentId
required
string

The consent ID to fetch the account information for

Request Body schema:

Bank account details

accountHolderName
required
string non-empty

Individual associated with the target account

required
object (DirectID.Data.API.Models.AccountVerification.Request.Identifier)
ignoreMiddleNames
boolean

Flag to indicate if matching with middle names is enabled

Responses

Request samples

Content type
{
  • "accountHolderName": "string",
  • "identifier": {
    },
  • "ignoreMiddleNames": true
}

Response samples

Content type
application/json
{
  • "result": "Pass",
  • "reason": "AccountIdentifierNotFound",
  • "matchedAccount": {
    },
  • "matchedAccountHolderName": "string"
}

Trigger a bank account validation.

Returns a result with an accompanying error code if validation is inconclusive.

Authorizations:
Bearer
path Parameters
consentId
required
string

The consent ID to fetch the account information for

Request Body schema:

Bank account details

accountHolderName
required
string non-empty

Individual associated with the target account

required
object (DirectID.Data.API.Models.AccountVerification.Request.Identifier)
ignoreMiddleNames
boolean

Flag to indicate if matching with middle names is enabled

Responses

Request samples

Content type
{
  • "accountHolderName": "string",
  • "identifier": {
    },
  • "ignoreMiddleNames": true
}

Response samples

Content type
application/json
{
  • "result": "Pass",
  • "reason": "AccountIdentifierNotFound",
  • "matchedAccount": {
    },
  • "matchedAccountHolderName": "string"
}

Bank Data

Overview

The most common use case is fetching user's bank account data from the DirectID Data API.

Deprecated endpoint

The endpoint /data/v1/consents/{consentId}/accounts, previously returned all the data we received from the bank/data provider including all transactions along with any data enrichment (if enabled for your configuration) we provide at the time of the request.

Latest endpoints

The above endpoint has been split into the following:

  • /data/v2/consents/{consentId}/accounts (Returns a list containing all accounts shared for a consent)

  • /data/v2/consents/{consentId}/accounts/{accountId} (Returns a specific account shared for a consent)

  • /data/v2/consents/{consentId}/accounts/{accountId}/balances (Returns the balance information for a specific account)

  • /data/v2/consents/{consentId}/accounts/{accountId}/transactions (Returns a list of transactions tied to a specific account. The data returned by this endpoint is paginated and subsequent calls using the links provided in response body may be required to retrieve the full data set)

It's important to note that when trying to fetch 3 months or more worth of data OR if the account has lots of transactions, it is best to use the paginated endpoint for this owing to the large volume of data involved.

The transaction data returned via this endpoint has a sliding date window which is dependent upon the time of connection and the configured days of historical transactions. For instance, if the user connected their account on the 15th of the Month, and the client has been configured to return the last 10 days of transactions, the transactions fetched will be from the 5th to the 15th. If this data is requested 2 days later from the time of initial connection (15th), i.e. on the 17th this will return the transactions from the 7th to the 17th.

Pagination Strategy

We have added a links component to our responses to easily paginate through large volumes of data. The next and prev links represent relative uris. You can append our baseUrl to get the next or prev set of data if available as indicated below:

"links": {
  "prev": "/relativeUri/for_previous_page",
  "next": "/relativeUri/for_next_page"
  }

Please note for the UK Banks the SCA rules apply as well in addition to the sliding date range, the maximum allowed date range is last 90 days after the SCA expiry.

For Data retention see our Bank Data Stored API.

Strong Customer Authentication (UK)

SCA (Strong Customer Authentication) applies only to the banks that expose the Account Information Services PSD2 APIs.

After a user has authenticated using SCA with their bank, your client can fetch all the data from the DirectID Data API which they have consented to share. This data may include one or more of the following data clusters.

  • Parties
  • Balances
  • Transactions

Following is the list of the banks for the PSD2 integration that have a short lived SCA and allow only access to a limited set of data after the expiration.

Bank SCA Expiry Time
AIB Group (UK) 5 mins
Bank of Scotland 45 mins
Danske Bank (UK) 15 mins
First Direct 60 mins
Halifax 45 mins
HSBC (UK) 60 mins
Lloyds Bank 45 mins
Marks & Spencer 60 mins
Monzo 5 mins
Nationwide Building Society 60 mins
Tide Business 10 mins
MBNA 45 mins
Revolut 5 mins
Tesco Bank 5 mins
TSB 10 mins
Virgin Money 60 mins
Capital One (UK) 5 mins
Chase (UK)* 60 mins

For all other OpenBanking PSD2 bank's that are not listed above, their SCA expires after 90 days.

After the short lived SCA expiration, the client can retrieve Balances, Account Information and only fetch the last 90 days of transactions (given that the user has consented to share 90 or more days of transactions) except for the "Parties" cluster.

*After SCA expiry Chase (UK) is only allowing access to Balances and Transactions data clusters. Based on this, Account Information is not available which makes it impossible to fetch bank data via Data API. If you are using DirectID storage, then it is possible to fetch data via Stored Data API. Refreshes via Stored Data API are also not possible for the same reason as Data API.

If you need the user's complete transaction history and "Parties" data that they have consented to share, you should consider fetching and storing it before the SCA expiration, ideally right after the user has connected their account.

Get all accounts Deprecated

Returns a list containing the accounts shared for a consent.

Does a fresh pull from the external provider.

Authorizations:
Bearer
path Parameters
consentId
required
string

The consent ID to fetch the account information for

header Parameters
endUser-Ip
string

The IP address of the end user. If provided will enable unlimited data refreshes for open banking providers that support this feature.

Responses

Response samples

Content type
application/json
{
  • "providerId": "string",
  • "providerName": "string",
  • "countryCode": "string",
  • "requestDateTime": "string",
  • "accounts": [
    ]
}

Get all accounts

Returns a list containing the accounts shared for a consent.

Does a fresh pull from the external provider.

Authorizations:
Bearer
path Parameters
consentId
required
string

The consent ID to fetch the account information for

header Parameters
endUser-Ip
string

The IP address of the end user. If provided will enable unlimited data refreshes for open banking providers that support this feature.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Get single account

Returns a specific account shared for a consent.

Does a fresh pull from the external provider.

Authorizations:
Bearer
path Parameters
consentId
required
string

The consent ID for which we want to fetch account information

accountId
required
string

The account ID for which we want to fetch account information

header Parameters
endUser-Ip
string

The IP address of the end user. If provided will enable unlimited data refreshes for open banking providers that support this feature.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": { }
}

Get balances for account

Returns the balance information for a specific account.

Does a fresh pull from the external provider.

Authorizations:
Bearer
path Parameters
consentId
required
string

The consent ID for which we want to fetch balance information

accountId
required
string

The account ID for which we want to fetch balance information

header Parameters
endUser-Ip
string

The IP address of the end user. If provided will enable unlimited data refreshes for open banking providers that support this feature.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": { }
}

Get transactions for account

Returns a list of transactions tied to a specific account.

The data returned by this endpoint is paginated and subsequent calls using the links provided in response body may be required to retrieve the full data set.

Does a fresh pull from the external provider.

Authorizations:
Bearer
path Parameters
consentId
required
string

The consent ID for which we want to fetch balance information

accountId
required
string

The account ID for which we want to fetch balance information

query Parameters
from
string <date-time>

Filter from date (Recommended format: yyyy-MM-dd)

to
string <date-time>

Filter to date (Recommended format: yyyy-MM-dd)

pageId
string

Page Id (Represents an encoded uuid for Next or Prev uris from the bank transaction responses)

header Parameters
endUser-Ip
string

The IP address of the end user. If provided will enable unlimited data refreshes for open banking providers that support this feature.

Responses

Response samples

Content type
application/json
{
  • "links": {
    },
  • "data": [
    ],
  • "meta": {
    }
}

Income Verification

Overview

Verify an individual’s income using DirectID Income Verification.

This solution, which accesses the individual’s bank statements for up to 12 months, is powered using our own unique algorithms and will return both single and multiple income streams to provide an accurate income figure along with a confidence score. Benefits can be included or excluded in the income calculation.

Verified income is up to three main recurring income streams plus all benefit streams if present. Only credit transactions with amount > £50 are considered in the ranking mechanism, smaller credit transactions are ignored. In addition, all benefit streams will be shown if present, regardless the value. The main income streams are prioritized by total amount, their rank values are One, Two or Three . The benefit streams are returned in any case. Benefits aren't ranked, and rank is null for them. For example, if there are 3 recurring income streams and 2 benefit streams, then 5 income streams will be returned in total.

Integration

If the individual has connected their account using DirectID Connect, you can use the GET /income-verification/v1/consents/{consentId}/verifications endpoint to verify an individual's income.

Gets the income verifications for the accounts shared for a consent.

Authorizations:
Bearer
path Parameters
consentId
required
string

The consent ID to fetch the income verifications results for

query Parameters
accountId
string

The account ID to fetch the income verification for. If not specified, all accounts associated with this session are returned

includeFlags
boolean
Default: false

Includes the flags used to calculate the confidence score

excludeBenefits
boolean
Default: false

Excludes the benefits from the income streams

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Affordability

Overview

The Affordability API allows you to understand what a customer’s discretionary and non-discretionary spend looks like, by understanding non-discretionary and discretionary spending, allied with income, calculating affordability becomes easy.

This API allows our customers to harness the power of our insights platform on the bank data they already have.

Integration

If you wish to get the affordability for a given consent, you can to do so using the GET /affordability/v1/consents/:consentId endpoint. Please ensure that this product is enabled for your app by talking to support before using this endpoint.

There is one additional request parameters that can be specified when making a request:

  • includeFlexibleCosts, when true, returns transactions marked as flexible and will include those transactions in the affordability calculation. When this value is false, it will still return the transactions marked as flexible but will omit those transactions from the affordability calculation. Please note that flexibleCosts and estimatedFlexibleCosts values will be still shown in case there have been transactions that are associated with flexible costs, but these values are not taken into account while calculating estimatedAffordability. Note, the default value for this parameter is true

In response to your call, you will receive a JSON object containing each months affordability with an estimated total for the months supplied with the account details.

Authentication

This API requires a bearer token using the directid.data scope

Get affordability for the accounts shared for a consent.

Maximum of 12 months returned

Authorizations:
Bearer
path Parameters
consentId
required
string

The consent ID to fetch the affordability results for

query Parameters
includeFlexibleCosts
boolean
Default: true

Includes the flags used to calculate the confidence score

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Bank Data (stored)

Overview

This set of APIs provides the same functionality as the Data API but the data is stored with DirectID. There is an an endpoint that refreshes that data as well. This set of APIs can be enabled by contacting support.

Refresh rules

To keep it consistent across banks, only certain data is refreshed.

  • Account details with the exception of party data is always refreshed.
  • Balances are always refreshed.
  • Transactions are aggregated i.e. new data is merged with old data based on transactionId if that is present otherwise it is done using date of the transaction.
  • Any other data is not refreshed and will be kept from the initial connection.

Deletes all the stored data associated with the consent

Please note this does not revoke the consent.

Authorizations:
Bearer
path Parameters
consentId
required
string

Unique reference for the consent

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "description": "string",
  • "details": "string",
  • "correlationId": "string"
}

Returns a list of accounts for a consent.

Authorizations:
Bearer
path Parameters
consentId
required
string

Unique reference for the user consent

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Returns balances for an account for a consent.

Authorizations:
Bearer
path Parameters
consentId
required
string

Unique reference for the user consent

accountId
required
string

Unique identifier for the account at the institution

Responses

Response samples

Content type
application/json
{
  • "current": {
    },
  • "available": {
    }
}

Returns a list of transactions for an account for a consent.

Authorizations:
Bearer
path Parameters
consentId
required
string

Unique reference for the consent

accountId
required
string

Unique identifier for the account at the institution

query Parameters
searchTerm
string

Term to search in all searchable transaction fields [Description, TransactionCategory.Category, TransactionClassification.Classification].

sortField
string (DirectID.Insights.Service.Models.SortField)
Enum: "Description" "Amount" "Category" "Classification" "Date"

Sort by field

sortDesc
boolean

Sorting direction "true" is descending, "false" is ascending. Default is "true".

indicator
string (DirectID.Insights.Service.Models.BankData.CreditDebitIndicator)
Enum: "Credit" "Debit"

Filter by transaction CreditDebitIndicator.

category
Array of strings

Filter by category.

classification
Array of strings

Filter by classification.

from
string <date-time>

Filter from date (Recommended format: yyyy-MM-dd)

to
string <date-time>

Filter to date (Recommended format: yyyy-MM-dd)

offset
integer <int32> [ 0 .. 2147483647 ]

Pagination offset.

limit
integer <int32> [ 0 .. 2147483647 ]

Pagination limit. Default value is 25.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Returns provider details for a consent.

Authorizations:
Bearer
path Parameters
consentId
required
string

Unique reference for the user consent

Responses

Response samples

Content type
application/json
{
  • "consentId": "string",
  • "customerReference": "string",
  • "providerId": "string",
  • "providerName": "string",
  • "countryCode": "string",
  • "consentExpiryDate": "string",
  • "connectedDate": "string",
  • "updatedDate": "string"
}

Refreshes data for a consent.

Please note only 4 refreshes are allowed in a 24 hour period.

Authorizations:
Bearer
path Parameters
consentId
required
string

Unique reference for the consent

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "description": "string",
  • "details": "string",
  • "correlationId": "string"
}

Income Verification (stored)

Overview

This set of APIs provides the same functionality as the Income Verification endpoint but use the data and calculation that is stored instead of fetching it from the banks.

Gets the income verifications for the accounts shared for a consent.

Authorizations:
Bearer
path Parameters
consentId
required
string

The consent ID to fetch the income verifications results for

query Parameters
accountId
string

The account ID to fetch the income verification for. If not specified, all accounts associated with this session are returned

includeFlags
boolean
Default: false

Includes the flags used to calculate the confidence score

excludeBenefits
boolean
Default: false

Excludes the benefits from the income streams

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Payment Account Confirmation

Overview

The Payment Confirmation stage allows a user to select an account which they would like to receive payments into. It is an optional stage in DirectID Connect. This endpoint allows the customer to retrieve the information that has been submitted by the user.

Retrieves user entered payment account confirmation

Authorizations:
Bearer
path Parameters
consentId
required
string

The consent Id to fetch the payment account confirmation

Responses

Response samples

Content type
application/json
{
  • "consentId": "string",
  • "applicationId": "string",
  • "accountId": "string",
  • "accountNumber": "string",
  • "bankCode": "string",
  • "accountNumberSource": "Bank",
  • "bankCodeSource": "Bank"
}

Affordability (stored)

Overview

This set of APIs provides the same functionality as the Affordability endpoint but use the data and calculation that is stored instead of fetching it from the banks. After a refresh for a consent has been completed the monthly affordabilities data is updated and the estimated figures returned by this endpoint are recalculated.

Gets the affordability for the transactions shared for a consent.

Authorizations:
Bearer
path Parameters
consentId
required
string

The consent ID to fetch the affordability for

query Parameters
accountId
string

The account ID to fetch the affordability for. If not specified, all accounts associated with this session are returned

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Consumer Financial Health

Overview

DirectID Financial Health API allows you to understand your customer's affordability and cash balance history with our enriched calculations that give insight into financial health. Having processed the account transactional data we offer several most relevant calculations that describe the applicant's income and outgoings patterns. With this service, the lender can understand how big and stable the income is, what is the expense side and how the cash balance looks like on a regular basis. To capture the trends, it is possible to compare and analyse all the indicators for different time lapses up to one year.


INTEGRATION

If the individual has connected their account using DirectID Connect, you can use the GET /advanced-insights/v1/consents/{consentId}/consumer-financial-health endpoint to verify an individual's financial health.


Authentication

This API requires a bearer token using the directid.advanced_insights scope. Also bear in mind that this API works only when data storage is enabled


Details

We are taking customers' current balance as a basis for the calculation. Current balance does not contain any Pending transactions and drawn Overdraft amount. However our API response contains available balance amount, which will include Pending transactions and drawn Overdraft amount if there are any.

  • In case it is possible to get 365 days worth of data from the bank, then the service will return calculations for all available periods: lastThirtyDays, lastSixtyDays, lastNinetyDays, lastOneEightyDays, lastThreeSixtyDays.

  • If data period is less than 365 days (for example 90 days), then service will return calculations for lastThirtyDays, lastSixtyDays and lastNinetyDays. Calculations for all other periods will be equal to lastNinetyDays.

  • If the account has had no recent activity then some of the calculations will likely be zero. For example, if there have been no transactions within the past 30 days, then the Total Credit and Total Debit for the lastThirtyDays would be zero. The remaining values will be calculated based on the account balance amount.

  • If data period is more than 365 days, then we will return all available periods up to lastThreeSixtyDays.

  • To capture the most recent developments and account trends it is recommended to analyze each calculation over all time periods.

Get Consumer Financial Health

Authorizations:
Bearer
path Parameters
consentId
required
string

The consent ID to fetch the Financial Health Results

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Business Financial Health

Overview

DirectID Financial Health API allows you to understand your customer's affordability and cash balance history with our enriched calculations that give insight into financial health. Having processed the account transactional data we offer several most relevant calculations that describe the applicant's income and outgoings patterns. With this service, the lender can understand how big and stable the income is, what is the expense side and how the cash balance looks like on a regular basis. To capture the trends, it is possible to compare and analyse all the indicators for different time lapses up to one year.


INTEGRATION

If the individual has connected their account using DirectID Connect, you can use the GET /advanced-insights/v1/consents/{consentId}/business-financial-health endpoint to verify a business' financial health.


Authentication

This API requires a bearer token using the directid.advanced_insights scope. Also bear in mind that this API works only when data storage is enabled


Details

We are taking customers' current balance as a basis for the calculation. Current balance does not contain any Pending transactions and drawn Overdraft amount. However our API response contains available balance amount, which will include Pending transactions and drawn Overdraft amount if there are any.

  • In case it is possible to get 365 days worth of data from the bank, then the service will return calculations for all available periods: lastThirtyDays, lastSixtyDays, lastNinetyDays, lastOneEightyDays, lastThreeSixtyDays.

  • If data period is less than 365 days (for example 90 days), then service will return calculations for lastThirtyDays, lastSixtyDays and lastNinetyDays. Calculations for all other periods will be equal to lastNinetyDays.

  • If the account has had no recent activity then some of the calculations will likely be zero. For example, if there have been no transactions within the past 30 days, then the Total Credit and Total Debit for the lastThirtyDays would be zero. The remaining values will be calculated based on the account balance amount.

  • If data period is more than 365 days, then we will return all available periods up to lastThreeSixtyDays.

  • To capture the most recent developments and account trends it is recommended to analyze each calculation over all time periods.

Get Business Financial Health

Authorizations:
Bearer
path Parameters
consentId
required
string

The consent ID to fetch the Financial Health Results

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Categorisation Engine

Overview

Obtain deeper insights from transaction data, providing you with accurate and automated transaction enrichment.

DirectID’s Categorisation Engine gives you the opportunity to understand how your customer’s use their money. We use machine learning and big data to classify and categorise all transactions to give you a rich and comprehensive understanding of your customer’s financial habits. We also predict a merchant name for the supplied transaction.

Integration

If you wish to categorise any transactions that you have, you can to do so using the POST /insights-engine/v1/enrich-transactions endpoint. This will be using the data supplied via the endpoint in the request. Please ensure that this product is enabled for your app by talking to support before using this endpoint.

In response to your call, you will receive a JSON object containing the original transations with added classes and categories along with confidence score, and merchant name.

Authentication

This API requires a bearer token using the directid.data scope

Adds categorisation, classification and predicts a merchant name for transactions supplied.

Authorizations:
Bearer
query Parameters
useLegacyCategorisation
boolean
Default: false

Flag whether to use the latest or legacy categorisation service

confidenceFloor
number <double>
Default: 0

Value from 0.0 to 1.0 which will return transactions as uncategorised if the category confidence is below this value

Request Body schema:

Request body for categorisation

countryCode
required
string non-empty

Country code for the account of the transactions

currencyCode
required
string non-empty

Currency code for the transactions, currently supported codes are GBP and USD.

referenceId
required
string non-empty

Unique identifier for the categorisation request

Array of objects or null (DirectID.Data.API.Models.Categorisation.Request.CategorisationTransaction)

Transaction data. Maximum limit for the number of transactions is 5000.

Responses

Request samples

Content type
{
  • "referenceId": "string",
  • "countryCode": "string",
  • "currencyCode": "string",
  • "transactions": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Income Verification Engine

Overview

Verify an individual’s income using DirectID Income Verification.

This solution, which accesses the individual’s bank statements for up to 12 months, is powered using our own unique algorithms and will return both single and multiple income streams to provide an accurate income figure along with a confidence score. Benefits can be included or excluded in the income calculation.

Verified income is up to three main recurring income streams plus all benefit streams if present. Only credit transactions with amount > £50 are considered in the ranking mechanism, smaller credit transactions are ignored. In addition, all benefit streams will be shown if present, regardless the value. The main income streams are prioritized by total amount, their rank values are One, Two or Three . The benefit streams are returned in any case. Benefits aren't ranked, and rank is null for them. For example, if there are 3 recurring income streams and 2 benefit streams, then 5 income streams will be returned in total.

Integration

If you wish to verify an individual's income with your own transaction data, you can to do so using the POST /insights-engine/v1/income-verification endpoint. This will be using the data supplied via the endpoint in the request. Please ensure that this product is enabled for your app by talking to support before using this endpoint.

There are two additional query parameters that can be specified when making a request:

  • excludeBenefits that will omit transactions and income streams that were identified as benefits (UK only)
  • includeFlags that will return an extended response containing all the flags used in calculating confidence score rather than just the confidence score itself.

In response to your call, you will receive a JSON object containing relevant income streams along with confidence score and estimated salary for each one, as well as a total confidence score and estimated salary for all income streams combined.

Authentication

This API requires a bearer token using the directid.data scope

Processes the income verifications for the accounts supplied.

Authorizations:
Bearer
Request Body schema:
accountId
required
string non-empty

Unique identifier for the account to be verified for income

currencyCode
required
string non-empty

Currency code for the transactions, currently supported codes are GBP and USD.

includeFlags
boolean

Includes the flags used to calculate the confidence score

excludeBenefits
boolean

Excludes the benefits from the income streams

Array of objects or null (DirectID.Data.API.Models.IncomeVerification.Request.API.IncomeVerificationTransaction)

Responses

Request samples

Content type
{
  • "accountId": "string",
  • "includeFlags": true,
  • "excludeBenefits": true,
  • "currencyCode": "string",
  • "transactions": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Affordability Engine

Overview

The Affordability Engine allows you to understand what a customer’s discretionary and non-discretionary spend looks like, by understanding non-discretionary and discretionary spending, allied with income, calculating affordability becomes easy.

This API allows our customers to harness the power of our insights platform on the bank data they already have.

Integration

If you wish to calculate affordability with any transactions that you have, you can to do so using the POST /insights-engine/v1/affordability endpoint. This will be using the data supplied via the endpoint in the request. Please ensure that this product is enabled for your app by talking to support before using this endpoint.

There are one additional request parameters that can be specified when making a request:

  • includeFlexibleCosts, when true, returns transactions marked as flexible and will include those transactions in the affordability calculation. When this value is false, it will still return the transactions marked as flexible but will omit those transactions from the affordability calculation. Please note that flexibleCosts and estimatedFlexibleCosts values will be still shown in case there have been transactions that are associated with flexible costs, but these values are not taken into account while calculating estimatedAffordability. Note, the default value for this parameter is true

In response to your call, you will receive a JSON object containing each months affordability with an estimated total for the months supplied.

There is a maximum transaction threshold of 5000 which will return an invalid request response if the number of transaction sent is greater than this.

Authentication

This API requires a bearer token using the directid.data scope

Processes affordability for the transactions supplied.

Maximum of 12 months returned

Authorizations:
Bearer
query Parameters
useLegacyCategorisation
boolean
Default: false

Flag whether to use the latest or legacy categorisation service

confidenceFloor
number <double>
Default: 0

Value from 0.0 to 1.0 which will return transactions as uncategorised if the category confidence is below this value

Request Body schema:

The BYOD affordability processing request

countryCode
required
string non-empty

Country code for the account of the transactions

currencyCode
required
string non-empty

Currency code for the transactions, currently supported codes are GBP and USD.

referenceId
required
string non-empty

Unique identifier for the account to have the affordability calculated

includeFlexibleCosts
boolean

Includes flexible costs in the affordability calculation

Array of objects or null (DirectID.Data.API.Models.Affordability.Request.AffordabilityTransaction)

Responses

Request samples

Content type
{
  • "referenceId": "string",
  • "includeFlexibleCosts": true,
  • "currencyCode": "string",
  • "countryCode": "string",
  • "transactions": [
    ]
}

Response samples

Content type
application/json
{
  • "referenceId": "string",
  • "countryCode": "string",
  • "currencyCode": "string",
  • "affordabilityMonths": [
    ],
  • "estimatedCalculatedIncome": 0.1,
  • "estimatedFixedCosts": 0.1,
  • "estimatedFlexibleCosts": 0.1,
  • "estimatedDebtFees": 0.1,
  • "estimatedAffordability": 0.1
}