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 theapi:scope
format instead.
Domaindirectid.co
has been deprecated and support for it will end by the end of 2024. Please use theatto.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:
api:consent
).https://connect.atto.co?consent_id=<ConsentID>#access_token=<AccessToken>
and send it to the end user.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.
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.
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.
To reconfirm a consent:
api:consent
).https://connect.atto.co?consent_id=<ConsentID>#access_token=<AccessToken>
and send it to the end user.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.
If a user doesn't wish to prolong access to the data, then they can revoke access to the bank data.
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.
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.
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:
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 Atto 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 Atto 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 |
user_id | The unique identifier for a user allowing a grouping of consents, formatted as a 36-character GUID (e.g., 123e4567-e89b-12d3-a456-426614174000 ) |
No |
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.
Parameter | Description | Mandatory |
---|---|---|
customer_ref | Your reference for the end user going through the Atto Connect journey (Max 255 Characters) | Yes |
state | the state of the end user journey. success or error |
Yes |
error | an error code. see Atto 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 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.
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) |
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 |
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.
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.
POST
application/json
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.
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.
POST
application/json
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
}
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 Atto 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 |
{
"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"
}
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.
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 |
{
"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"
}
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:
Here are two example requests we do to compete the OAuth2 Webhook flow:
Basic
authentication so the request will contain a header of the form Authorization: Basic <encodedCredentials>
where encodedCredentials is a Base64 encoded ClientId:ClientSecret
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]'
{
"token_type": "bearer",
"expires_in": 123,
"access_token": "ReturnedAccessToken"
}
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:
client_id
, which is the OAuth public identifier for your applicationclient_secret
, which is the secret used to authenticate the client_idscope
, 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:


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


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:
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.
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 Atto Connect journey. The customer will need to complete the journey again. |
unexpected_error |
An unexpected error has occurred which is not recoverable. |
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. |
429 |
n/a | See API Rate Limits |
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. |
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 |
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.
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 |
---|---|
Atto Consent Service | api:consent |
Atto Data API | api:data |
Atto Stored Data API | api:stored_data |
Atto Advanced Insights API | api:advanced_insights |
Atto Connect Invitation API | api: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.
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 .
grant_type | string |
client_id | string |
client_secret | string |
scope | string |
{- "tokenType": "string",
- "expiresIn": 0,
- "accessToken": "string"
}
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.
This API requires a bearer token using the api:connect_invitation
scope.
invitationId required | string |
{- "data": {
- "invitationId": "550a4884-8473-4f2e-a6cf-551c16767d59",
- "recipientName": "string",
- "recipientEmail": "string",
- "customerReference": "string",
- "invitationCreated": "2019-08-24T14:15:22Z",
- "activities": [
- {
- "event": "Sent",
- "eventDate": "2019-08-24T14:15:22Z",
- "smtpErrorCode": "string",
- "smtpErrorMessage": "string"
}
]
}, - "meta": {
- "totalRecords": 0
}
}
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 |
{- "templateId": "string",
- "recipientName": "string",
- "recipientEmail": "user@example.com",
- "customerReference": "string"
}
{- "data": {
- "invitationId": "550a4884-8473-4f2e-a6cf-551c16767d59"
}, - "meta": {
- "totalRecords": 0
}
}
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.
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. |
userId | string Optional filter to get consents associated with userId |
offset | integer <int32> Default: 0 Number of consents to skip. |
limit | integer <int32> Default: 0 Maximum number of consents in the response. |
[- {
- "consentId": "e521cf62-a45f-49c5-8372-94853fffeb55",
- "applicationId": "97ab27fa-30e2-43e3-92a3-160e80f4c0d5",
- "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
- "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": [
- "string"
], - "invitationId": "string",
- "journeyType": "Reauthentication"
}
]
consentId required | string The consent ID to fetch the consent details for. This should be a uuid. |
{- "consentId": "e521cf62-a45f-49c5-8372-94853fffeb55",
- "applicationId": "97ab27fa-30e2-43e3-92a3-160e80f4c0d5",
- "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
- "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": [
- "string"
], - "invitationId": "string",
- "journeyType": "Reauthentication"
}
This allows you to revoke an active consent. Please note that this will not remove any stored data for the consent.
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.
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. |
Returns a result with an accompanying error code if validation is inconclusive.
consentId required | string The consent ID to fetch the account information for |
Bank account details
accountHolderName required | string non-empty Individual associated with the target account |
required | object (DirectID.Data.API.Models.AccountVerification.Request.LegacyIdentifier) |
{- "accountHolderName": "string",
- "identifier": {
- "bankCodeType": "SortCode",
- "iban": "string",
- "bankCode": "string",
- "accountNumber": "string",
- "countryCode": "string"
}
}
{- "result": "Pass",
- "reason": "AccountIdentifierNotFound"
}
Returns a result with an accompanying error code if validation is inconclusive.
consentId required | string The consent ID to fetch the account information for |
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 |
{- "accountHolderName": "string",
- "identifier": {
- "iban": "string",
- "bic": "string",
- "bankCode": "string",
- "accountNumber": "string",
- "countryCode": "string"
}, - "ignoreMiddleNames": true
}
{- "result": "Pass",
- "reason": "AccountIdentifierNotFound",
- "matchedAccount": {
- "countryCode": "string",
- "accountNumber": "string",
- "bankCode": "string",
- "iban": "string",
- "bic": "string",
- "type": "Iban"
}, - "matchedAccountHolderName": "string"
}
Returns a result with an accompanying error code if validation is inconclusive.
consentId required | string The consent ID to fetch the account information for |
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 |
{- "accountHolderName": "string",
- "identifier": {
- "iban": "string",
- "bic": "string",
- "bankCode": "string",
- "accountNumber": "string",
- "countryCode": "string"
}, - "ignoreMiddleNames": true
}
{- "result": "Pass",
- "reason": "AccountIdentifierNotFound",
- "matchedAccount": {
- "countryCode": "string",
- "accountNumber": "string",
- "bankCode": "string",
- "iban": "string",
- "bic": "string",
- "type": "Iban"
}, - "matchedAccountHolderName": "string"
}
The most common use case is fetching user's bank account data from the Atto Data API.
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.
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.
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.
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.
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 |
Capital One (UK) | 5 mins |
Chase (UK)* | 60 mins |
Co-operative Bank (UK) | 30 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 |
MBNA | 45 mins |
Monzo | 5 mins |
Nationwide Building Society | 60 mins |
NatWest group | 60 mins |
Revolut | 5 mins |
Royal Bank of Scotland | 60 mins |
Smile (UK) | 30 mins |
Tesco Bank | 5 mins |
TSB | 10 mins |
Tide Business | 10 mins |
Ulster Bank | 60 mins |
Virgin Money | 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 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.
Returns a list containing the accounts shared for a consent.
Does a fresh pull from the external provider.
consentId required | string The consent ID to fetch the account information for |
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. |
{- "providerId": "string",
- "providerName": "string",
- "countryCode": "string",
- "requestDateTime": "string",
- "accounts": [
- {
- "accountId": "string",
- "currencyCode": "string",
- "displayName": "string",
- "accountHolderNames": "string",
- "accountType": "Business",
- "accountSubType": "ChargeCard",
- "identifiers": {
- "accountNumber": "string",
- "bankCode": "string",
- "bic": "string",
- "iban": "string",
- "secondaryIdentification": "string"
}, - "parties": [
- {
- "partyId": "string",
- "fullName": "string",
- "addresses": [
- {
- "address": "string",
- "type": "Business",
- "city": "string",
- "postcode": "string",
- "country": "string",
- "countrySubDivision": "string"
}
], - "partyType": "Delegate",
- "isIndividual": true,
- "isAuthorizingParty": true,
- "emailAddress": "string",
- "phoneNumbers": [
- {
- "type": "Home",
- "phoneNumber": "string"
}
]
}
], - "balances": {
- "current": {
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "creditLines": [
- {
- "amount": 0.1,
- "creditLineType": "NA",
- "included": true,
- "predicted": true
}
]
}, - "available": {
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "creditLines": [
- {
- "amount": 0.1,
- "creditLineType": "NA",
- "included": true,
- "predicted": true
}
]
}
}, - "transactions": [
- {
- "transactionId": "string",
- "description": "string",
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "status": "Pending",
- "transactionCode": {
- "code": "string",
- "subCode": "string"
}, - "proprietaryTransactionCode": {
- "code": "string",
- "issuer": "string"
}, - "bookingDate": "string",
- "merchantDetails": {
- "merchantName": "string",
- "merchantCategoryCode": "string"
}, - "enrichedData": {
- "category": {
- "id": 0,
- "name": "string",
- "confidence": 0.1
}, - "class": {
- "id": 0,
- "name": "string",
- "confidence": 0.1
}, - "predictedMerchantName": "string"
}
}
]
}
]
}
Returns a list containing the accounts shared for a consent.
Does a fresh pull from the external provider.
consentId required | string The consent ID to fetch the account information for |
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. |
{- "data": {
- "providerId": "string",
- "providerName": "string",
- "countryCode": "string",
- "requestDateTime": "string",
- "accounts": [
- {
- "accountId": "string",
- "currencyCode": "string",
- "displayName": "string",
- "accountHolderNames": "string",
- "accountType": "Business",
- "accountSubType": "ChargeCard",
- "identifiers": {
- "accountNumber": "string",
- "bankCode": "string",
- "bic": "string",
- "iban": "string",
- "secondaryIdentification": "string"
}, - "parties": [
- {
- "partyId": "string",
- "fullName": "string",
- "addresses": [
- {
- "address": "string",
- "type": "Business",
- "city": "string",
- "postcode": "string",
- "country": "string",
- "countrySubDivision": "string"
}
], - "partyType": "Delegate",
- "isIndividual": true,
- "isAuthorizingParty": true,
- "emailAddress": "string",
- "phoneNumbers": [
- {
- "type": "Home",
- "phoneNumber": "string"
}
]
}
]
}
]
}, - "meta": {
- "totalRecords": 0
}
}
Returns a specific account shared for a consent.
Does a fresh pull from the external provider.
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 |
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. |
{- "data": {
- "providerId": "string",
- "providerName": "string",
- "countryCode": "string",
- "requestDateTime": "string",
- "account": {
- "accountId": "string",
- "currencyCode": "string",
- "displayName": "string",
- "accountHolderNames": "string",
- "accountType": "Business",
- "accountSubType": "ChargeCard",
- "identifiers": {
- "accountNumber": "string",
- "bankCode": "string",
- "bic": "string",
- "iban": "string",
- "secondaryIdentification": "string"
}, - "parties": [
- {
- "partyId": "string",
- "fullName": "string",
- "addresses": [
- {
- "address": "string",
- "type": "Business",
- "city": "string",
- "postcode": "string",
- "country": "string",
- "countrySubDivision": "string"
}
], - "partyType": "Delegate",
- "isIndividual": true,
- "isAuthorizingParty": true,
- "emailAddress": "string",
- "phoneNumbers": [
- {
- "type": "Home",
- "phoneNumber": "string"
}
]
}
]
}
}, - "meta": { }
}
Returns the balance information for a specific account.
Does a fresh pull from the external provider.
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 |
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. |
{- "data": {
- "current": {
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "creditLines": [
- {
- "amount": 0.1,
- "creditLineType": "NA",
- "included": true,
- "predicted": true
}
]
}, - "available": {
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "creditLines": [
- {
- "amount": 0.1,
- "creditLineType": "NA",
- "included": true,
- "predicted": true
}
]
}
}, - "meta": { }
}
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.
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 |
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) |
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. |
{- "links": {
- "next": "string",
- "prev": "string"
}, - "data": [
- {
- "transactionId": "string",
- "description": "string",
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "status": "Pending",
- "transactionCode": {
- "code": "string",
- "subCode": "string"
}, - "proprietaryTransactionCode": {
- "code": "string",
- "issuer": "string"
}, - "bookingDate": "string",
- "merchantDetails": {
- "merchantName": "string",
- "merchantCategoryCode": "string"
}, - "enrichedData": {
- "category": {
- "id": 0,
- "name": "string",
- "confidence": 0.1
}, - "class": {
- "id": 0,
- "name": "string",
- "confidence": 0.1
}, - "predictedMerchantName": "string"
}
}
], - "meta": {
- "totalPages": 0
}
}
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.
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.
consentId required | string The consent ID to fetch the income verifications results for |
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 |
[- {
- "accountDetails": {
- "accountId": "string",
- "bankCode": "string",
- "accountNumber": "string",
- "accountType": "Business",
- "accountSubType": "ChargeCard",
- "currencyCode": "string",
- "accountHolderNames": "string",
- "customerReference": "string",
- "parties": [
- {
- "accountHolderName": "string",
- "isIndividual": true,
- "isAuthorizingParty": true,
- "partyType": "Delegate"
}
]
}, - "incomeStreams": [
- {
- "month1": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month2": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month3": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month4": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month5": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month6": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month7": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month8": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month9": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month10": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month11": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "estimatedIncome": 0.1,
- "confidenceScore": 0.1,
- "confidenceScoreFlags": {
- "incomeForLast3Months": true,
- "varianceTolerance5Percent": true,
- "varianceTolerance10Percent": true,
- "mostRecentCheckValue": true,
- "stabilityOverall": 0.1,
- "stability6Months": 0.1
}, - "name": "string",
- "numberOfDeposits": 0,
- "isBenefit": true,
- "isSalary": true,
- "rank": "One"
}
], - "incomeStreamsSummary": {
- "month1": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month2": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month3": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month4": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month5": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month6": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month7": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month8": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month9": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month10": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month11": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "estimatedIncome": 0.1,
- "confidenceScore": 0.1,
- "confidenceScoreFlags": {
- "incomeForLast3Months": true,
- "varianceTolerance5Percent": true,
- "varianceTolerance10Percent": true,
- "mostRecentCheckValue": true,
- "stabilityOverall": 0.1,
- "stability6Months": 0.1
}
}, - "verifiedIncomeStatus": "UnsupportedAccountType"
}
]
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.
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.
This API requires a bearer token using the api:data
scope
Maximum of 12 months returned
consentId required | string The consent ID to fetch the affordability results for |
includeFlexibleCosts | boolean Default: true Includes the flags used to calculate the confidence score |
[- {
- "accountDetails": {
- "accountId": "string",
- "bankCode": "string",
- "accountNumber": "string",
- "accountType": "Business",
- "accountSubType": "ChargeCard",
- "currencyCode": "string",
- "accountHolderNames": "string",
- "customerReference": "string",
- "parties": [
- {
- "accountHolderName": "string",
- "isIndividual": true,
- "isAuthorizingParty": true,
- "partyType": "Delegate"
}
]
}, - "affordabilityMonths": [
- {
- "month": 0,
- "year": 0,
- "monthDateTime": "2019-08-24T14:15:22Z",
- "calculatedIncome": 0.1,
- "fixedCosts": 0.1,
- "flexibleCosts": 0.1,
- "debtFees": 0.1,
- "affordability": 0.1
}
], - "estimatedCalculatedIncome": 0.1,
- "estimatedFixedCosts": 0.1,
- "estimatedFlexibleCosts": 0.1,
- "estimatedDebtFees": 0.1,
- "estimatedAffordability": 0.1
}
]
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.
To keep it consistent across banks, only certain data is refreshed.
transactionId
if that is present otherwise it is done using date of the transaction.Please note this does not revoke the consent.
consentId required | string Unique reference for the consent |
{- "code": "string",
- "description": "string",
- "details": "string",
- "correlationId": "string"
}
consentId required | string Unique reference for the user consent |
[- {
- "accountId": "string",
- "currencyCode": "string",
- "displayName": "string",
- "accountHolderNames": "string",
- "accountType": "Business",
- "accountSubType": "ChargeCard",
- "identifiers": {
- "accountNumber": "string",
- "bankCode": "string",
- "iban": "string",
- "bic": "string",
- "secondaryIdentification": "string"
}, - "parties": [
- {
- "partyId": "string",
- "fullName": "string",
- "addresses": [
- {
- "address": "string",
- "type": "Business",
- "city": "string",
- "postcode": "string",
- "country": "string",
- "countrySubDivision": "string"
}
], - "partyType": "Delegate",
- "isIndividual": true,
- "isAuthorizingParty": true,
- "emailAddress": "string",
- "phoneNumbers": [
- {
- "type": "Home",
- "phoneNumber": "string"
}
]
}
]
}
]
consentId required | string Unique reference for the user consent |
accountId required | string Unique identifier for the account at the institution |
{- "current": {
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "creditLines": [
- {
- "amount": 0.1,
- "creditLineType": "NA",
- "included": true,
- "predicted": true
}
]
}, - "available": {
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "creditLines": [
- {
- "amount": 0.1,
- "creditLineType": "NA",
- "included": true,
- "predicted": true
}
]
}
}
consentId required | string Unique reference for the consent |
accountId required | string Unique identifier for the account at the institution |
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. |
{- "data": [
- {
- "transactionId": "string",
- "description": "string",
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "status": "Pending",
- "transactionCode": {
- "code": "string",
- "subCode": "string"
}, - "proprietaryTransactionCode": {
- "code": "string",
- "issuer": "string"
}, - "bookingDate": "string",
- "merchantDetails": {
- "merchantName": "string",
- "merchantCategoryCode": "string"
}, - "enrichedData": {
- "category": {
- "id": 0,
- "name": "string",
- "confidence": 0.1
}, - "class": {
- "id": 0,
- "name": "string",
- "confidence": 0.1
}, - "predictedMerchantName": "string"
}
}
], - "meta": {
- "totalRecords": 0
}
}
consentId required | string Unique reference for the user consent |
{- "consentId": "string",
- "customerReference": "string",
- "providerId": "string",
- "providerName": "string",
- "countryCode": "string",
- "consentExpiryDate": "string",
- "connectedDate": "string",
- "updatedDate": "string"
}
Please note only 4 refreshes are allowed in a 24 hour period.
consentId required | string Unique reference for the consent |
{- "code": "string",
- "description": "string",
- "details": "string",
- "correlationId": "string"
}
consentId required | string Unique reference for the user consent |
accountId required | string Unique identifier for the account at the institution |
{- "current": {
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "creditLines": [
- {
- "amount": 0.1,
- "creditLineType": "NA",
- "included": true,
- "predicted": true
}
]
}, - "available": {
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "creditLines": [
- {
- "amount": 0.1,
- "creditLineType": "NA",
- "included": true,
- "predicted": true
}
]
}
}
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.
consentId required | string The consent ID to fetch the income verifications results for |
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 |
[- {
- "accountDetails": {
- "accountId": "string",
- "bankCode": "string",
- "accountNumber": "string",
- "accountType": "Business",
- "accountSubType": "ChargeCard",
- "currencyCode": "string",
- "accountHolderNames": "string",
- "parties": [
- {
- "partyName": "string",
- "isIndividual": true,
- "isAuthorizingParty": true,
- "partyType": "string"
}
]
}, - "incomeStreams": [
- {
- "month1": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month2": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month3": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month4": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month5": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month6": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month7": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month8": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month9": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month10": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month11": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "estimatedIncome": 0.1,
- "confidenceScore": 0.1,
- "confidenceScoreFlags": {
- "incomeForLast3Months": true,
- "varianceTolerance5Percent": true,
- "varianceTolerance10Percent": true,
- "mostRecentCheckValue": true,
- "stabilityOverall": 0.1,
- "stability6Months": 0.1
}, - "name": "string",
- "numberOfDeposits": 0,
- "isBenefit": true,
- "rank": "One"
}
], - "incomeStreamsSummary": {
- "month1": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month2": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month3": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month4": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month5": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month6": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month7": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month8": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month9": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month10": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month11": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "estimatedIncome": 0.1,
- "confidenceScore": 0.1,
- "confidenceScoreFlags": {
- "incomeForLast3Months": true,
- "varianceTolerance5Percent": true,
- "varianceTolerance10Percent": true,
- "mostRecentCheckValue": true,
- "stabilityOverall": 0.1,
- "stability6Months": 0.1
}
}, - "verifiedIncomeStatus": "UnsupportedAccountType"
}
]
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 Atto Connect. This endpoint allows the customer to retrieve the information that has been submitted by the user.
consentId required | string The consent Id to fetch the payment account confirmation |
{- "consentId": "string",
- "applicationId": "string",
- "accountId": "string",
- "accountNumber": "string",
- "bankCode": "string",
- "accountNumberSource": "Bank",
- "bankCodeSource": "Bank"
}
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.
consentId required | string The consent ID to fetch the affordability for |
accountId | string The account ID to fetch the affordability for. If not specified, all accounts associated with this session are returned |
[- {
- "accountDetails": {
- "accountId": "string",
- "bankCode": "string",
- "accountNumber": "string",
- "accountType": "Business",
- "accountSubType": "ChargeCard",
- "currencyCode": "string",
- "accountHolderNames": "string",
- "parties": [
- {
- "accountHolderName": "string",
- "isIndividual": true,
- "isAuthorizingParty": true,
- "partyType": "Delegate"
}
]
}, - "monthAffordabilities": [
- {
- "month": 0,
- "year": 0,
- "monthDateTime": "2019-08-24T14:15:22Z",
- "calculatedIncome": 0.1,
- "fixedCosts": 0.1,
- "flexibleCosts": 0.1,
- "debtFees": 0.1,
- "affordability": 0.1
}
], - "estimatedCalculatedIncome": 0.1,
- "estimatedFixedCosts": 0.1,
- "estimatedFlexibleCosts": 0.1,
- "estimatedDebtFees": 0.1,
- "estimatedAffordability": 0.1,
- "avgEstimatedAffordability": 0.1,
- "avgCalculatedIncome": 0.1,
- "affordabilityTransactions": [
- {
- "affordabilityTransactionId": 0,
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "description": "string",
- "bookingDate": "2019-08-24T14:15:22Z",
- "categoryName": "string",
- "affordabilityType": "Fixed"
}
]
}
]
Using real-time bank transactions, Atto’s predictive models help optimise approval rates, profit, churn, and prevent unexpected losses to provide a comprehensive view of a portfolio’s lifetime value. Our models are designed to be used throughout the customer lifecycle, giving businesses a unique opportunity to project a customer’s risk profile. With the ability to identify potential risks early on, risk managers can make fast, informed decisions to reduce bad debt and maximise profitability.
Bank transaction information allows lenders to make more informed lending decisions, especially for those with a limited credit history or unconventional financial profiles. It provides a comprehensive view of an individual’s financial health, enabling lenders to assess risk more accurately and offer tailored financial products and services.
Please note that this product is running in Beta version, and you should not make decisions solely on this.
If you wish to receive the Atto score, you can do so using the GET /atto-score/v1/consents/{consentId}/accounts/{accountId}
endpoint.
In response to your call, you will receive a JSON object containing the score.
This API requires a bearer token using the api:advanced_insights
scope
consentId required | string The consent ID for which we want to fetch the atto-score |
accountId required | string The account ID for which we want to fetch the atto-score |
{- "data": {
- "accountId": "string",
- "attoScore": 0,
- "probabilityOfDefault": 0.1,
- "dateGenerated": "string",
- "version": "string",
- "range": {
- "minScore": 0,
- "maxScore": 0
}
}, - "meta": { }
}
Atto 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.
If the individual has connected their account using Atto Connect, you can use the GET /advanced-insights/v1/consents/{consentId}/consumer-financial-health
endpoint to verify an individual's financial health.
This API requires a bearer token using the api:advanced_insights
scope. Also bear in mind that this API works only when data storage is enabled
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.
consentId required | string The consent ID to fetch the Financial Health Results |
{- "data": [
- {
- "accountId": "string",
- "providerName": "string",
- "countryCode": "string",
- "currencyCode": "string",
- "accountHolderNames": [
- "string"
], - "identifiers": {
- "accountNumber": "string",
- "bankCode": "string",
- "iban": "string",
- "bic": "string",
- "secondaryIdentification": "string"
}, - "accountType": "Business",
- "accountSubType": "ChargeCard",
- "balances": {
- "current": {
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "creditLines": [
- {
- "amount": 0.1,
- "creditLineType": "NA",
- "included": true,
- "predicted": true
}
]
}, - "available": {
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "creditLines": [
- {
- "amount": 0.1,
- "creditLineType": "NA",
- "included": true,
- "predicted": true
}
]
}
}, - "lastThirtyDays": {
- "totalCreditsCount": 0,
- "totalDebitsCount": 0,
- "totalCreditsAmount": 0.1,
- "totalDebitsAmount": 0.1,
- "averageCreditsMinusDebits": 0.1,
- "endOfDayBalanceConsistency": 0.1,
- "endOfDayBalanceLowVal": 0.1,
- "endOfDayBalanceHighVal": 0.1,
- "endOfDayBalanceVariability": 0.1,
- "percentageOfDaysInNegativeBalance": 0.1
}, - "lastSixtyDays": {
- "totalCreditsCount": 0,
- "totalDebitsCount": 0,
- "totalCreditsAmount": 0.1,
- "totalDebitsAmount": 0.1,
- "averageCreditsMinusDebits": 0.1,
- "endOfDayBalanceConsistency": 0.1,
- "endOfDayBalanceLowVal": 0.1,
- "endOfDayBalanceHighVal": 0.1,
- "endOfDayBalanceVariability": 0.1,
- "percentageOfDaysInNegativeBalance": 0.1
}, - "lastNinetyDays": {
- "totalCreditsCount": 0,
- "totalDebitsCount": 0,
- "totalCreditsAmount": 0.1,
- "totalDebitsAmount": 0.1,
- "averageCreditsMinusDebits": 0.1,
- "endOfDayBalanceConsistency": 0.1,
- "endOfDayBalanceLowVal": 0.1,
- "endOfDayBalanceHighVal": 0.1,
- "endOfDayBalanceVariability": 0.1,
- "percentageOfDaysInNegativeBalance": 0.1
}, - "lastOneEightyDays": {
- "totalCreditsCount": 0,
- "totalDebitsCount": 0,
- "totalCreditsAmount": 0.1,
- "totalDebitsAmount": 0.1,
- "averageCreditsMinusDebits": 0.1,
- "endOfDayBalanceConsistency": 0.1,
- "endOfDayBalanceLowVal": 0.1,
- "endOfDayBalanceHighVal": 0.1,
- "endOfDayBalanceVariability": 0.1,
- "percentageOfDaysInNegativeBalance": 0.1
}, - "lastThreeSixtyDays": {
- "totalCreditsCount": 0,
- "totalDebitsCount": 0,
- "totalCreditsAmount": 0.1,
- "totalDebitsAmount": 0.1,
- "averageCreditsMinusDebits": 0.1,
- "endOfDayBalanceConsistency": 0.1,
- "endOfDayBalanceLowVal": 0.1,
- "endOfDayBalanceHighVal": 0.1,
- "endOfDayBalanceVariability": 0.1,
- "percentageOfDaysInNegativeBalance": 0.1
}
}
], - "meta": {
- "totalRecords": 0
}
}
Atto 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.
If the individual has connected their account using Atto Connect, you can use the GET /advanced-insights/v1/consents/{consentId}/business-financial-health
endpoint to verify a business' financial health.
This API requires a bearer token using the api:advanced_insights
scope. Also bear in mind that this API works only when data storage is enabled
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.
consentId required | string The consent ID to fetch the Financial Health Results |
{- "data": [
- {
- "accountId": "string",
- "providerName": "string",
- "countryCode": "string",
- "currencyCode": "string",
- "accountHolderNames": [
- "string"
], - "identifiers": {
- "accountNumber": "string",
- "bankCode": "string",
- "iban": "string",
- "bic": "string",
- "secondaryIdentification": "string"
}, - "accountType": "Business",
- "accountSubType": "ChargeCard",
- "balances": {
- "current": {
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "creditLines": [
- {
- "amount": 0.1,
- "creditLineType": "NA",
- "included": true,
- "predicted": true
}
]
}, - "available": {
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "creditLines": [
- {
- "amount": 0.1,
- "creditLineType": "NA",
- "included": true,
- "predicted": true
}
]
}
}, - "lastThirtyDays": {
- "totalCreditsCount": 0,
- "totalDebitsCount": 0,
- "totalCreditsAmount": 0.1,
- "totalDebitsAmount": 0.1,
- "averageCreditsMinusDebits": 0.1,
- "endOfDayBalanceConsistency": 0.1,
- "endOfDayBalanceLowVal": 0.1,
- "endOfDayBalanceHighVal": 0.1,
- "endOfDayBalanceVariability": 0.1,
- "percentageOfDaysInNegativeBalance": 0.1
}, - "lastSixtyDays": {
- "totalCreditsCount": 0,
- "totalDebitsCount": 0,
- "totalCreditsAmount": 0.1,
- "totalDebitsAmount": 0.1,
- "averageCreditsMinusDebits": 0.1,
- "endOfDayBalanceConsistency": 0.1,
- "endOfDayBalanceLowVal": 0.1,
- "endOfDayBalanceHighVal": 0.1,
- "endOfDayBalanceVariability": 0.1,
- "percentageOfDaysInNegativeBalance": 0.1
}, - "lastNinetyDays": {
- "totalCreditsCount": 0,
- "totalDebitsCount": 0,
- "totalCreditsAmount": 0.1,
- "totalDebitsAmount": 0.1,
- "averageCreditsMinusDebits": 0.1,
- "endOfDayBalanceConsistency": 0.1,
- "endOfDayBalanceLowVal": 0.1,
- "endOfDayBalanceHighVal": 0.1,
- "endOfDayBalanceVariability": 0.1,
- "percentageOfDaysInNegativeBalance": 0.1
}, - "lastOneEightyDays": {
- "totalCreditsCount": 0,
- "totalDebitsCount": 0,
- "totalCreditsAmount": 0.1,
- "totalDebitsAmount": 0.1,
- "averageCreditsMinusDebits": 0.1,
- "endOfDayBalanceConsistency": 0.1,
- "endOfDayBalanceLowVal": 0.1,
- "endOfDayBalanceHighVal": 0.1,
- "endOfDayBalanceVariability": 0.1,
- "percentageOfDaysInNegativeBalance": 0.1
}, - "lastThreeSixtyDays": {
- "totalCreditsCount": 0,
- "totalDebitsCount": 0,
- "totalCreditsAmount": 0.1,
- "totalDebitsAmount": 0.1,
- "averageCreditsMinusDebits": 0.1,
- "endOfDayBalanceConsistency": 0.1,
- "endOfDayBalanceLowVal": 0.1,
- "endOfDayBalanceHighVal": 0.1,
- "endOfDayBalanceVariability": 0.1,
- "percentageOfDaysInNegativeBalance": 0.1
}
}
], - "meta": {
- "totalRecords": 0
}
}
Obtain deeper insights from transaction data, providing you with accurate and automated transaction enrichment.
Atto’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.
If you wish to categorise any transactions that you have, you can 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.
This API requires a bearer token using the api:data
scope
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 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. |
{- "referenceId": "string",
- "countryCode": "string",
- "currencyCode": "string",
- "transactions": [
- {
- "transactionId": "string",
- "description": "string",
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "status": "Pending",
- "bookingDate": "string"
}
]
}
[- {
- "referenceId": "string",
- "countryCode": "string",
- "currencyCode": "string",
- "transactions": [
- {
- "transactionId": "string",
- "description": "string",
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "status": "Pending",
- "bookingDate": "string",
- "enrichedData": {
- "category": {
- "id": 0,
- "name": "string",
- "confidence": 0.1
}, - "class": {
- "id": 0,
- "name": "string",
- "confidence": 0.1
}, - "predictedMerchantName": "string"
}
}
]
}
]
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.
If you wish to verify an individual's income with your own transaction data, you can 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.
This API requires a bearer token using the api:data
scope
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) |
{- "accountId": "string",
- "includeFlags": true,
- "excludeBenefits": true,
- "currencyCode": "string",
- "transactions": [
- {
- "transactionId": "string",
- "description": "string",
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "status": "Pending",
- "bookingDate": "string"
}
]
}
[- {
- "accountId": "string",
- "incomeStreams": [
- {
- "month1": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month2": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month3": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month4": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month5": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month6": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month7": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month8": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month9": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month10": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month11": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "estimatedIncome": 0.1,
- "confidenceScore": 0.1,
- "confidenceScoreFlags": {
- "incomeForLast3Months": true,
- "varianceTolerance5Percent": true,
- "varianceTolerance10Percent": true,
- "mostRecentCheckValue": true,
- "stabilityOverall": 0.1,
- "stability6Months": 0.1
}, - "name": "string",
- "numberOfDeposits": 0,
- "isBenefit": true,
- "isSalary": true,
- "rank": "One"
}
], - "incomeStreamsSummary": {
- "month1": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month2": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month3": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month4": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month5": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month6": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month7": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month8": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month9": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month10": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "month11": {
- "income": 0.1,
- "month": 0,
- "year": 0
}, - "estimatedIncome": 0.1,
- "confidenceScore": 0.1,
- "confidenceScoreFlags": {
- "incomeForLast3Months": true,
- "varianceTolerance5Percent": true,
- "varianceTolerance10Percent": true,
- "mostRecentCheckValue": true,
- "stabilityOverall": 0.1,
- "stability6Months": 0.1
}
}
}
]
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.
If you wish to calculate affordability with any transactions that you have, you can 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.
This API requires a bearer token using the api:data
scope
Maximum of 12 months returned
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 |
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) |
{- "referenceId": "string",
- "includeFlexibleCosts": true,
- "currencyCode": "string",
- "countryCode": "string",
- "transactions": [
- {
- "transactionId": "string",
- "description": "string",
- "amount": 0.1,
- "creditDebitIndicator": "Credit",
- "status": "Pending",
- "bookingDate": "string"
}
]
}
{- "referenceId": "string",
- "countryCode": "string",
- "currencyCode": "string",
- "affordabilityMonths": [
- {
- "month": 0,
- "year": 0,
- "monthDateTime": "2019-08-24T14:15:22Z",
- "calculatedIncome": 0.1,
- "fixedCosts": 0.1,
- "flexibleCosts": 0.1,
- "debtFees": 0.1,
- "affordability": 0.1
}
], - "estimatedCalculatedIncome": 0.1,
- "estimatedFixedCosts": 0.1,
- "estimatedFlexibleCosts": 0.1,
- "estimatedDebtFees": 0.1,
- "estimatedAffordability": 0.1
}
This allows you to retrieve the statement of an account in PDF format. The statement is generated by Atto Stored Data API and not the bank.
Atto PDF statement contains account identifiers, balance, transactions, and period information.
If you wish to get the PDF statement of an account for a given consent, you can do so using the GET /stored-data/v1/consents/:consentId/accounts/:accountId/statement
endpoint.
This API requires a bearer token using the api:stored_data
scope.
Please note this statement is created by Atto and not the bank.
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 PDF statement |