API for creating analyses from PDF bank statements using document extraction technology.

Server
https://api.algoan.com
Server Variables

Each requests must be set with an Authorization header using a Bearer JSON Web Token after authenticating with your client credentials.

Authentication

Algoan provides JSON Web Tokens based on the OAuth2 protocol to authenticate your organization. When you create a new project, you will need to use the service account shared by Algoan containing a client_id and a client_secret.

NOTE: this is the only API where request's parameters are formatted as snake case.

Create a new access token

Generates a new access token to use Algoan's APIs

Auth
Request Body

OAuth2 request body with two grant types - client_credentials and refresh_token

objectobject

Auth request body to generate a new access token

client_idstring

Your client ID

client_secretuuid

Your client secret

grant_typestring

Specify the type of grant access

Enum: client_credentials

POST /v1/oauth/token
Copy
Responses
201

Access Token instance

objectobject
access_tokenstring

The access token required for each API.

expires_innumber

Number of seconds until the access token expires

refresh_expires_innumber

Number of seconds until the refresh token expires

refresh_tokenstring

Refresh token used to generate a new access token

token_typestring

Type of access token (will always be set to bearer)

Response
Copy

Customer

represents a user able to connect/aggregate their bank accounts. It is unique per organization, project and custom identifier.

Create a customer

Creates a new customer instance

Auth
Request Body

New customer to create

objectobject

Information about a customer and its journey through Algoan.

customIdentifierstring

A custom identifier that will be attached to your customer. This can be used to identify a customer based on your internal reference.

aggregationDetails9 fieldsobject

Information about the AIS provider used for this report

personalDetails3 fieldsobject

Personal information about the customer

POST /v2/customers
Copy
Responses
201

New customer created

objectobject

Information about a customer and its journey through Algoan.

idstring

Algoan unique identifier

customIdentifierstring

A custom identifier that will be attached to your customer. This can be used to identify a customer based on your internal reference.

aggregationDetails9 fieldsobject

Information about the AIS provider used for this report

personalDetails3 fieldsobject

Personal information about the customer

reports3 fieldsobject

Reports about the customer

openBankingInformationobject

Information about the customer retrieved from the Open Banking process

ownersarray[object]

Owners of the accounts

Same names are merged.

namestring

Name of the owner

createdAtdate-time

Customer date of creation

updatedAtdate-time

Latest update of the customer

400

Bad request

401

Unauthorized, please make sure you are properly authenticated

403

Forbidden, please make sure you are allowed to use this route

422

Unprocessable Entity

Response
Copy

Analysis

An analysis is a snapshot of a customer's financial situation based on the connected bank accounts. It contains results from both products Score and Credit Insights.

NOTE: To get Credit Insights results or a Score, the analysis need to contain at least one CHECKING Account with a minimum of 20 transactions.

Create analysis from PDF bank statements

Triggers an analysis creation by extracting transaction and account data from PDF bank statements. This endpoint accepts one or more PDF files containing bank statements, extracts the financial data using document extraction technology, and automatically creates an analysis for the specified customer.

How it works

  1. Upload one or more PDF bank statements as base64-encoded files
  2. The system extracts accounts and transactions from the PDFs
  3. An analysis is automatically created with the extracted data
  4. The analysis processes the data to generate Score and Credit Insights results

Requirements

  • Files must be valid PDF documents containing bank statements
  • Each file must be base64-encoded
  • The customer must exist before calling this endpoint

Response

The endpoint returns immediately with a 202 Accepted status and the analysisId. The extraction and analysis computation happen asynchronously. You can poll the analysis status or use webhooks to be notified when the analysis is completed.

Auth
Request Body

Array of PDF bank statement files to extract and analyze

objectobject
filesarray[object]
fileNamestring

Name of the PDF bank statement file

base64Filestring

Base64-encoded PDF file content

POST /v2/customers/{id}/bank-statements
Copy
Responses
200

Analysis created and extraction in progress

objectobject
analysisIdstring

Unique identifier of the created analysis

400

Bad request - Invalid file format or missing required fields

401

Unauthorized, please make sure you are properly authenticated

403

Forbidden, please make sure you are allowed to use this route

404

Customer not found

Response
Copy

Get an analysis

Get a unique analysis

Auth
GET /v2/customers/{id}/analyses/{analysisId}
Copy
Responses
200

Analysis instance

objectobject

An analysis launched with open banking data

idstring

Unique analysis identifier

formatstring

Original format of the open banking data (default to ALGOAN). BUDGET_INSIGHT_V2 refers to the second version of Budget Insight API.

Enum: ALGOAN,BUDGET_INSIGHT_V2_0,LINXO_CONNECT_DIRECT_ACCOUNT_API_V3,LINXO_CONNECT_ACCOUNT_API_V2,TINK_V2,MASTERCARD_OPEN_BANKING,MASTERCARD_OPEN_BANKING_ENTERPRISE_V2,HYBRID

Default: ALGOAN

parameters5 fieldsobject

Optional parameters related to the analysis.

If disableScores and disableCreditInsights are both set to true, the analysis will be have to be triggered manually later by calling POST /analyses/{analysisId}/trigger with { disableScores: false, disableCreditInsights: false }.

statusstring

State of the analysis:

  • CREATED: you've just created the analysis. Algoan is waiting for accounts and transactions to be uploaded
  • FETCHING_DATA: accounts and transactions are being fetched by an asynchronous process (e.g. bank_details_required resthook event), you can force the emission of this event by calling the POST /analyses endpoint without accounts and transactions.
  • IN_PROGRESS: as soon as banking details are uploaded, the analysis is in "IN_PROGRESS" state. If you try to request Credit Insights or Score, the API will return a 202 HTTP status code.
  • COMPLETED: means that the analysis process is finished. Conditions:
    • If Credit Insights is disabled, the analysis is complete as soon as scores and metadata are defined
    • If Score is disabled, the analysis is complete as soon as creditInsights and metadata are defined
    • If you've launched both Score and Credit Insights, the analysis is completed as soon as all fields are defined
  • ERROR: the analysis is in an error state if Score or Credit Insights cannot be calculated. Therefore, an error property will be defined, giving you the reason for failure.

Enum: CREATED,FETCHING_DATA,ERROR,IN_PROGRESS,COMPLETED

sourcestring

Describes the origin of the analysis' launch:

  • INTERNAL: relaunched by Algoan if an internal error occurred (will not be billed)
  • CLIENT: created and launched by a client
  • CASH_FLOW_UPDATE: created and launched after a client cashflow update
  • ACCOUNT_SELECTION_UPDATE: created and launched after a client updated the list of selected accounts
  • REFRESH: created and launched after a client requested a refresh of the analysis
  • REFRESH_WITH_NEW_ACCOUNTS: created and launched after a client requested a refresh of the analysis with new accounts

Enum: INTERNAL,CLIENT,CASH_FLOW_UPDATE,ACCOUNT_SELECTION_UPDATE,REFRESH,REFRESH_WITH_NEW_ACCOUNTS

dataOriginstring

Describes the origin of the analysis' data:

  • OPEN_BANKING: Data fetched from an aggregator.
  • PDF: Data fetched from a PDF file
  • UNKNOWN: Default value

Enum: OPEN_BANKING,PDF,UNKNOWN

createdAtdate-time

Analysis date of creation

updatedAtdate-time

Latest update of the analysis

metadata15 fieldsobject

Indicators about the Open Banking data used to execute the Analysis. Deprecated properties correspond to Credit Insights indicators.

creditInsights6 fieldsobject

Object containing results from Credit Insights

scores2 fieldsobject

Scores assessing the probability of default Depending on your Score configuration you can have one or many scores computed. Each score will be billed independently.

errorobject

This property is defined if the analysis is in an ERROR state

codestring

Description :

  • NOT_ENOUGH_TRANSACTIONS: At least 20 transactions debited between YYYY-MM-DD and YYYY-MM-DD are required to compute the analysis.
  • CURRENCY_NOT_SUPPORTED: No checking or credit card accounts with currency EUR have been detected
  • USAGE_NOT_SUPPORTED: No personal checking or credit card accounts have been detected
  • NO_CHECKING_ACCOUNT: At least one PERSONAL checking account with currency EUR is required for an analysis
  • ACCOUNT_TYPE_NOT_SUPPORTED: At least one checking account is required to compute the analysis
  • OWNERSHIP_NOT_SUPPORTED: No checking or credit card accounts with ownership different than ATTORNEY have been detected
  • LOW_ACTIVITY_SCORE: The activity score is too low to compute the analysis. This error requires to be activated in the project configuration.
  • ZERO_INCOME: The income is equal to 0. This error requires to be activated in the project configuration.

Enum: INTERNAL_ERROR,NOT_ENOUGH_TRANSACTIONS,CURRENCY_NOT_SUPPORTED,USAGE_NOT_SUPPORTED,NO_CHECKING_ACCOUNT,ACCOUNT_TYPE_NOT_SUPPORTED,OWNERSHIP_NOT_SUPPORTED,LOW_ACTIVITY_SCORE,ZERO_INCOME

messagestring

A human readable error message

400

Bad request

401

Unauthorized, please make sure you are properly authenticated

403

Forbidden, please make sure you are allowed to use this route

404

Analysis not found

Response
Copy