Welcome to the Atto developer documentation.

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

Please note: Scope and url deprecation

Scopes with the format of directid.scope have been deprecated and support for them will end by the end of 2024. Please use the api:scope format instead.
Domain directid.co has been deprecated and support for it will end by the end of 2024. Please use the atto.co domain.

Atto 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.

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.

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

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:

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:

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 Atto Connect:

Atto 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.

Atto 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 api: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 Atto Connect url. eg: https://connect.atto.co?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: api: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.

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

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

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

Atto 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

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.

Atto 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.

Atto 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 api:consent).
2. Append the consent ID that needs to be reconfirmed as query parameter and add the access token as a fragment to the Atto Connect url. eg: https://connect.atto.co?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: api: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.

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.

Notifications

Atto 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

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

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.

To integrate Atto 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.

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

Consents can be grouped together using the user_id parameter which will allow for an aggregated account view across multiple consents.

Atto 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.

Notifications are used by Atto to inform you of your customer’s user journey through Atto. 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 notifications are useful for Dashboard product consumers, who are not utilizing Atto APIs. These notifications will give you real-time info about connected consent details.

The email notification can be enabled by contacting support.

V2

The email notification can contain the following fields:

Atto uses webhooks to send real-time notifications to your application regarding updates to a user consent within the Atto 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.

{
  "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

{
  "eventId": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
  "data": {  },
  "eventType": "Consent",
  "eventTime": "2022-01-01T00:00:00Z",
  "schemaType": "Consent",
  "schemaVersion": "1.0.0"
}

Consent

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 Atto APIs.

• 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"
}

Consent event flow

Success flow

Failure flow

Invitation

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

• 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
}'

To access the Atto 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 Atto Data API endpoints.

Once your user has connected to their bank through Atto Connect, you can call the Atto 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 Atto Data API
• A page on which you can insert the link to Atto Connect
• A web service "Webhook" that we call when your user has completed their journey, and the bank data is ready

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

Atto APIs are currently supporting only TLS 1.2

To ensure fair and consistent access to our services while maintaining the highest level of performance for all users, we have implemented the following limits for our APIs:

• Authorized Endpoints: 500 requests per 60 seconds
• Unauthorized Endpoint (Get Token): 600 requests per 60 seconds

Exceeding rate limits

When a given rate limit has been exceeded, the server will respond with a 429 Too Many Requests status code. This response will include a Retry-After: n header indicating the number of seconds to wait before another request will be permitted. Example response body:

{ 
    "statusCode": 429, 
    "message": "Rate limit is exceeded. Try again in 52 seconds." 
}

Banks often set rate limits on the number of calls that can be made at once. If Atto exceeds these rate limits we will receive a 429 response from the banks. Since the limit is set by the bank, it is unfortunately out of Atto’s control. Furthermore, each bank has its own logic as to how it applies rate limits and varies widely, it is important to spread out your API calls throughout the day.

A Breaking Change in the API is any modification that can potentially break existing integration.

This requires API consumers to alter their existing code or configurations to maintain compatibility with the updated version.

Atto classifies the following as breaking changes:

• Changes to the API contract: Changing or removing existing endpoints, altering method signatures, or adding or changing required input parameters.

• Behavioral changes: Changing the data types, error handling mechanisms, or adding or updating validation rules.

• Deprecation of features: Removing or significantly altering existing features or functionality.

• Authorisation/Authentication modifications: Changing security requirements or access controls.

Any non-breaking or additive changes in the API refer to any modification that should not affect existing functionality or usage of the API for its consumers.

These changes are backward-compatible, meaning that they can be safely integrated into existing applications without requiring code modifications.

Atto classifies the following as non-breaking changes:

• Addition of new features: Introducing new endpoints, methods, optional parameters, headers or response fields to existing products.

• Non-disruptive enhancements: Performance improvements, refactoring, or internal changes that do not alter the external API contract.

• Bug fixes: Resolving issues or glitches that do not change the existing API behavior.

• Documentation updates: Improving or expanding the API documentation without changing the API itself.

Atto will inform consumers about breaking changes within a reasonable amount of time before deploying to Production.

If an error occurs during the Atto 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.

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"
}

JWT Authorization header using the Bearer scheme.

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

Example: "Bearer token123"

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.

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

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

The important fields in the authentication response are:

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 .

OVERVIEW

Connect Invitation API offers the capability to effortlessly send Connect invitations to your users. It is underpinned by Atto'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 api:connect_invitation scope.

Overview

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

Overview

This allows you to revoke an active consent. Please note that this will not remove any stored data for the consent.

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.

Overview

The most common use case is fetching user's bank account data from the Atto 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 Atto 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.

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 Atto 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.

Overview

Verify an individual’s income using Atto 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 Atto Connect, you can use the GET /income-verification/v1/consents/{consentId}/verifications endpoint to verify an individual's income.

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 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 api:data scope

Overview

This set of APIs provides the same functionality as the Data API but the data is stored with Atto. 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.