How to read this reference
Every page under this heading is generated from the running service: the schemas are the real ones and the explorer sends a real call. What a generated page cannot tell you is which call comes first — so this one does, in about a minute.
New here? Read what a direct execution is and your first execution instead. This page assumes you have decided to integrate and want the map.
The happy path
Find the engine
List the engines you can run and take the reference of the one you want. Read what it needs to know which parameters its login takes and which features it can retrieve — that is the contract your request is checked against.
Start the execution
Initiate with parameters with the credentials in hand, or Initiate with a token when you have run this access before and would rather not hold the password.
You get 202 and an execution_id. That is the only value worth storing: everything below is addressed by it.
Wait for something to happen
Two ways, and one of them is better. Register a webhook and we tell you; or poll the state, which answers with a status code and no body at all.
Answer, if you are asked
A source can stop mid-run to ask your customer for a code. Read the state — it answers 423 with the form to render — and send the values back to Answer and resume. Challenges & MFA is the long version.
Read what came back
When the run is closed, the results are readable by family — the customer profile to begin with, or, better, the Financial Position — the same records in one call instead of ten.
Delete it
Delete the execution as soon as you have stored what you need. The less of somebody’s financial data sits anywhere, the better — including here.
What is in this reference
The catalogue: what your application may run today, what each engine needs to log in, and which features it can retrieve. Two endpoints, and the place every integration starts.
The two ways in — with credentials, or with a token that stands in for credentials you ran once before. Everything else about a run is decided here.
Following a run: poll it, read it, answer what it asks, stop it, and delete it when you are done. Five endpoints, used in that order.
Exchange the ticket a first execution issued for a reusable token, check what it may do, and revoke it. The guide explains the custody model.
Financial Position and Public Position return a whole side in one call, and that is the read to build on; underneath them there is an endpoint per family — identity, financial, public administration, commercial — plus the original documents.
The four calls we make to YOUR server: started, action required, authentication ended, ended. They carry the state, never the data.
A results endpoint answers as soon as ITS feature is finished, not when the whole execution is. A slow source — the credit registry is the usual one — does not hold up the families that already came back: 202 means this family, and a family nobody asked for answers 204.
Two things worth knowing before you build
An execution takes as long as an institution takes. Polling asks a question whose answer is “not yet” almost every time. Subscribe to ended even if you subscribe to nothing else — it is the only event we re-deliver.
customer_interaction_available says whether anybody can answer a challenge. With false the source is never allowed to contact your customer — no SMS at three in the morning — and the run ends instead of waiting.
Everything that holds for every endpoint — the X-APP-SECRET header, the base URLs, the error shape and the rate limits — is stated once in Using the API, not repeated on each page.