API Overview

A comprehensive reference of Algoan's endpoints and models.

Glossary

Resource	Definition
Organization	As a client, you are part of an Organization which represents your company.
Project	Your Organization can own several Algoan projects. Each of them represents a discrete set of products and configurations.
Aggregator	An aggregator is an AISP (Account Information Service Provider) able to fetch banking data from financial institutions.

Today, Algoan's API are based on semantic versioning and the major version number is included in the URL path (/v2). If a backward-incompatible change is made to the API, a new version will be released in the URL path.

API Environments

Sandbox

Use a sandbox to test our APIs and build your integration. You can use one of our free sets of sample data to test our endpoints.

Production

Once you are ready to launch your project into production, contact our Customer Success team and fill out a form to describe your project.

Model

Customer: represents a user who is able to connect/aggregate their bank accounts. It is unique to your organization, your project and your "custom identifier" (it can represent your internal reference). Each Customer has:

zero, one or many Analysis. One Analysis contains a score and a creditInsights results.
zero, one or many Accounts attached to an Analysis. Each Account has zero, one or many Transaction.

Response structure and pagination

API methods that are returning more than one document share the same structure:

resources: contains the list (or a subset) of requested documents
pagination:
- first: contains the first page URL
- last: contains the last page URL
- next: contains the next page URL
- previous: contains the previous page URL
- totalPages: represents the total number of pages
- totalResources: represents the total number of resources

Our APIs use a page-based pagination system and accept two query parameters:

limit: maximum number of resources returned. The default value is set to 200
page: number of the page

JSON
    
 
{    "resources": [{ ... }],    "pagination": {      "next": "/v2/customers?page=3&limit=20",      "previous": "/v2/customers?page=1&limit=20",      "first": "/v2/customers?page=1&limit=20",      "last": "/v2/customers?page=11&limit=20",      "totalPages": 11,      "totalResources": 206    }  }
Copy

NOTE: If the total number of pages is equal to one or if the total number of resources is empty, then first, last, next and previous parameters will be set to null:

JSON
    
 
{    "resources": [],    "pagination": {      "next": null,      "previous": null,      "first": null,      "last": null,      "totalPages": 1,      "totalResources": 0    }  }
Copy

API Errors

The list below describes all possible errors. It is always returned as a JSON:

code: a machine readable code.
message: a human readable error message.
status: the HTTP status code.

Example:

JSON
    
 
{    "code": "MISSING_PARAM",    "message": "Transaction 'id_1' has no amount",    "status": 400}
Copy

HTTP Status	Code	Description
400	`MISSING_PARAM`	A required param is missing
400	`BAD_REQUEST`	A param is not respecting the correct format
401	`UNAUTHORIZED`	The `Authorization` header is wrong or missing
403	`FORBIDDEN`	You cannot access the API
404	`NOT_FOUND`	The called API does not exist
404	`UNKNOWN_ENTITY`	The provided identifier has not been found
422	`ALREADY_EXISTS`	The entity you are trying to create already exists
500	`INTERNAL_SERVER_ERROR`	An internal error occurred. Please contact support@algoan.com.

Analysis Errors

The list below describes all possible errors when creating an analysis. It is always returned as a JSON:

code: a machine readable code.
message: a human readable error message.
status: the HTTP status code.

Example:

JSON
    
 
{    "error": {    "message": "At least one checking account is required for an analysis",    "code": "NO_CHECKING_ACCOUNT",      }    "status": 200}
Copy

HTTP Status	Code	Description
200	`CURRENCY_NOT_SUPPORTED`	No checking accounts with the project's currency have been detected
200	`NO_CHECKING_ACCOUNT`	At least one checking account is required for an analysis
200	`ACCOUNT_TYPE_NOT_SUPPORTED`	All accounts have `type`equals to "UNKNOWN"
200	`OWNERSHIP_NOT_SUPPORTED`	No checking or credit card accounts with ownership different than `ATTORNEY` have been detected
200	`USAGE_NOT_SUPPORTED`	Our API does not accept Business accounts
200	`NOT_ENOUGH_TRANSACTIONS`	We require at least 1 transaction debited in a CHECKING or CREDIT_CARD account

Errors examples

1st example

Two accounts sent in our API :

an account with usage equals to "PRO"
an account with type equals to "UNKNOWN"

API error = USAGE_NOT_SUPPORTED

2nd example

A single account sent in our API :

an account with account type equals to "SAVINGS"

API error = NO_CHECKING_ACCOUNT

3rd example

Three accounts sent in our API :

an account with type equals to "UNKNOWN"
an account with usage equals to "PRO"
an account with type equals to "CHECKING"

Response : No error, but only the checking account will be included in the analysis

Authentication

Algoan uses the OAuth 2.0 protocol to authorize your application to communicate with Algoan's endpoints. To make requests, you must generate an access token.

Access tokens are encoded as JSON Web Tokens. They can be used as OAuth 2.0 Bearer tokens.

To authenticate your service, use the client_credentials registration flow:

Bash (cURL)
    
 
curl --request POST \  --url https://api.algoan.com/v1/oauth/token \  --header 'Content-Type: application/x-www-form-urlencoded' \  --data grant_type=client_credentials \  --data client_id=your_client_id \  --data client_secret=your_client_secret
Copy

Last updated on May 23, 2024

Was this page helpful?