NAV Navbar
HTTP C#

Introduction

Welcome to the DirectID DirectID Data API.

There are two key integration points: the 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 are RESTful and return data in JSON format.

DirectID Connect

Integrations

Browser to Browser

In the case of a website integration (desktop/mobile).

Requirements

Flow

The launcher initiates the launch of a new page with our DirectID Connect Core running in it.

DirectID Connect Core communicates with the Launch Container via the window.postMessage() mechanism (this safely enables cross-origin communication between Core and the Launch Container).

The Launch Container gets updated and gives feedback to the user about the status of their journey (success, failure, in progress).

Integration

<script async src="https://directid-cdn.azureedge.net/directidconnect/prod/directid-connect.js"></script>

Only two lines of code are required to integrate the Launch Container into your web page:

<div id="directid-connect" data-client-id="yourclientid" data-customer-ref="yourcustomerreference"/>

Access to the actions and listeners of the DirectID Connect Launch Container is available via the window.directid.connect variable.

Launch Container id and data set information

App (webview) to Browser

In the case of an app (webview) integration.

Requirement

Flow

The launcher initiates the launch of a new page with our DirectID Connect Core running in it.

DirectID Connect Core communicates with your app via the DirectID webhook mechanism. The Launch Container must be updated by the app using Actions. This will give feedback to the user about the status of their journey. (success, failure, in progress).

Integration

<script async src="https://directid-cdn.azureedge.net/directidconnect/prod/directid-connect.js"></script>

<div id="directid-connect" data-client-id="yourclientid" data-customer-ref="yourcustomerreference"/>

Two lines of code are required to integrate the Launch Container in your web page:

Access to the actions and listeners of the DirectID Connect Launch Container is available via the window.directid.connect variable.

Launch Container id and data set information

Actions

See Actions and Listeners for more details.

App (native) to Browser

In the case of a native app integration.

Requirement:

Flow

The app is responsible for initiating the launch of a new page with our DirectID Connect Core running in it.

DirectID Connect Core communicates with your app via the DirectID webhook mechanism.

Your app is responsible for giving feedback to the user about their journey (success, failure, in progress).

Integration

Your application needs to provide the user with a means to use the DirectID Connect feature, for example: a button in your app view or in your app settings.

https://connect.directid.co/?client_id=yourclientid&customer_ref=yourcustomerreference

Query parameters:

Actions and Listeners

Actions

The following actions are applicable when using App to Browser flow (aka. webhook flow)

Listeners (for Browser to Browser flow only)

DirectID Data API

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:

If you want to know more about OAuth, you can check the OAuth documentation here and here

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.

In summary, you'll need the following:

Fetching the access token

Introduction

To access our APIs you need to pass your client_id and client_secret, along with the resource (the name of the API) that you want to call, to Microsoft's Azure Active Directory (AAD) authentication service. If that all goes according to plan then they will return an access_token to you, which is valid for one hour.

This access_token is actually a JWT token and is attached to any subsequent request into our APIs to verify your identity and ensure that any data retrieved is assigned to you.

OK, let's write some code. You'll need to be sending a POST request to the Azure Active Directory authentication endpoint, with the following properties in the body:

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
resource The Resource ID that we sent you

Request

https://login.windows.net/directiddirectory.onmicrosoft.com/oauth2/token

POST that to the following URL:

Response

{
   "token_type": "Bearer",
   "expires_in": "3600",
   "ext_expires_in": "0",
   "expires_on": "1529193701",
   "not_before": "1529189801",
   "resource": "https://directiddirectory.onmicrosoft.com/DirectID.API", 
   "access_token": "...access-token..."
}

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 (defauls to 3600 seconds)
expires_on The time when the access token expires, expressed as the number of seconds from 1970-01-01T0:0:0Z UTC
access_token The token you will use in susbsequent requests

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

Get an access token

Request

POST: https://login.windows.net/directiddirectory.onmicrosoft.com/oauth2/token
grant_type = "client_credentials"
client_id = client_id
client_secret = client_secret
resource = resource_id
// NOTE: Requires newtonsoft.json package
// From packagemanager console, type "install-package newtonsoft.json"
static async Task<string> GetAccessToken(string client_id, string client_secret, string resource_id)
{
    var client = new HttpClient();

    var values = new Dictionary<string, string>
    {
        { "grant_type", "client_credentials" },
        { "client_id", client_id },
        { "client_secret", client_secret },
        { "resource", resource_id }
    };

    var content = new FormUrlEncodedContent(values);
    var response = await client.PostAsync("https://login.windows.net/directiddirectory.onmicrosoft.com/oauth2/token", content);

    if (response.IsSuccessStatusCode)
    {
        var responseJson = await response.Content.ReadAsStringAsync();
        var data =  (dynamic) JObject.Parse(responseJson);
        return data.access_token;   // This gets the access_token, but you could also compose a complex object that includes the expiration time
    }
    else
        throw new HttpRequestException(response.StatusCode.ToString());
}

Using the acccess_token

GET: https://the-directid-api/get-some-resource
Authorization = "Bearer _access_token_"
static async Task<HttpResponseMessage> GetResponse(string url, string access_token)
{
    var client = new HttpClient();

    client.DefaultRequestHeaders.Add("Authorization", $"Bearer {access_token}");

    return await client.GetAsync(url);
}

Once you have the access_token, you'll assign it to the Authorization header token with a prefix of "Bearer":

Fetching bank account data

Request

static async Task<dynamic> GetBankTransactions(string getBankDataUrl, string sessionRef, string accessToken)
{
    var client = new HttpClient();

    string url = $"{getBankDataUrl}/bank/v1/sessions/{sessionRef}/accounts";
    System.Diagnostics.Debug.WriteLine(url);
    client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);

    var response = await client.SendAsync(new HttpRequestMessage(HttpMethod.Get, url));
    if (response.IsSuccessStatusCode)
    {
        var responseJson = await response.Content.ReadAsStringAsync();
        var data = (dynamic)JObject.Parse(responseJson);
        return data;        // Returns dynamic set of accounts, balances and transactions
    }

    else
        throw new HttpRequestException(response.StatusCode.ToString());
}

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

Response

{
    "providerName": "NatWest",
    "requestDateTime": "2018-06-27T15:40:59Z",
    "accounts": [
        {
            "accountId": "EE12F286DB386481CFE9CE105FDF6DF9",
            "currencyCode": "GBP",
            "displayName": null,
            "accountType": null,
            "accountSubType": "CURRENTACCOUNT",
            "identifiers": {
                "sortCode": "603099",
                "accountNumber": "34489999",
                "secondaryIdentification": null
            },
            "balances": {
                "current": {
                    "amount": 28.11,
                    "creditDebitIndicator": "CREDIT"
                },
                "available": {
                    "amount": 28.11,
                    "creditDebitIndicator": "CREDIT"
                }
            },
            "transactions": [
                {
                    "description": "J SMITH OPEN BANKING JOHN FP 04/05/18 1429 100000000355255449",
                    "amount": 1,
                    "creditDebitIndicator": "CREDIT",
                    "status": "BOOKED",
                    "bookingDate": "2018-05-03T23:00:00Z"
                },
                {
                    "description": "FRED BLOGGS HSBC FP 04/05/18 1435 FP18124O10823549",
                    "amount": 1.23,
                    "creditDebitIndicator": "CREDIT",
                    "status": "BOOKED",
                    "bookingDate": "2018-05-03T23:00:00Z"
                },
                {
                    "description": "J SMITH OPEN BANKING JOHN FP 04/05/18 1429 100000000355255326",
                    "amount": 1,
                    "creditDebitIndicator": "CREDIT",
                    "status": "BOOKED",
                    "bookingDate": "2018-05-03T23:00:00Z"
                },
                {
                    "description": "9005 27APR18 C TRAVERSE THEATRE EDINBURGH GB",
                    "amount": 4.8,
                    "creditDebitIndicator": "DEBIT",
                    "status": "BOOKED",
                    "bookingDate": "2018-04-29T23:00:00Z"
                },
                {
                    "description": "9005 26APR18 IZ *LIVECRUMBS EDINBURGH GB",
                    "amount": 13.2,
                    "creditDebitIndicator": "DEBIT",
                    "status": "BOOKED",
                    "bookingDate": "2018-04-26T23:00:00Z"
                },
                {
                    "description": "PAYM TECHNOLOGIES THE IDCO LTD FP 25/04/18 1301 3469664110315276AH",
                    "amount": 50,
                    "creditDebitIndicator": "CREDIT",
                    "status": "BOOKED",
                    "bookingDate": "2018-04-24T23:00:00Z"
                }
            ]
        }
    ]
}

The returned data is a construct as described in the DirectID Data API Reference, but here's a sample:

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

static async Task<dynamic> PerformAccountVerification(string accountVerificationUrl, string sessionRef, string accessToken, string jsonPayload)
{
    var client = new HttpClient();

    string url = $"{accountVerificationUrl}/account-verification/v1/sessions/{sessionRef}/verifications";
    System.Diagnostics.Debug.WriteLine(url);
    client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);

    var content = new HttpStringContent(jsonPayload, UnicodeEncoding.UTF8, "application/json");

    var response = await client.PostAsync(url, content);
    if (response.IsSuccessStatusCode)
    {
        var responseJson = await response.Content.ReadAsStringAsync();
        var data = (dynamic)JObject.Parse(responseJson);
        return data;        // Returns a JSON object containing the result of verification
    }

    else
        throw new HttpRequestException(response.StatusCode.ToString());
}

Bank Account Verification requires HTTP POST request. Please remember about setting Authorization header containing your (Bearer) access token. jsonPayload is a string representation of request body as described in DirectID Connect API Reference under Account Verification section.

Response

{
    "match": true,
    "errorCode": null
}

{
    "match": false,
    "errorCode": "ACCOUNT_IDENTIFIER_NOT_FOUND"
}

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

For a full list of available error codes, please refer to API Reference.

Webhooks

Webhooks are used by Direct ID to inform you of your customer’s user journey through Direct ID. Webhooks come in two flavours, email and API. Webhooks can be used to track the successful verifications or give you real time information about the problems your users are experiencing.

Email Hook

The email hook can be enabled via your account manager.

The email hook can be configured to email you when a customer verifies his or her bank details. You can then log into the dashboard and download their transactions, or, alternatively the email hook can be configured to email you if a user experiences a problem attempting to verify themselves.

API Hook (Simple)

The Simple API hook can be enabled via your account manager. The API Hook can be configured to call an endpoint on your backend system in the result of success or user error.

Success Hook

The success hook will contain your unique ID rpUser_Id passed back to you as well as our internal reference user_id. The internal reference is required to access any of our endpoints about that individual.

Request Details

{
 "rpUser_Id":"<your user id>",
 "user_id":"<our user id>"
}

Error Hooks

The error hook can be enabled via your account manager. When your users experience a problem the hook is triggered to inform you of the user issue so you can help your users fix the problem as soon as possible.

Request Details

{
 "error_code": "<the error code>",
 "error_message": "<the error message>",
 "user_id": "<our user id>",
 "rpUser_Id": "<your user id>"
}

API Hooks (OAuth2)

Alternatively, 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 in the same way, as you connected to our OAuth2 provider to authenticate you to use our API. In addition to the data listed above, we will require the following details:-