Initiate with parameters | INFONITE

Start an execution: an engine logs into the source with the credentials you send and retrieves the features you asked for.

The call returns immediately with 202 Accepted and an execution_id. Nothing has run yet — the job is queued, and from here on you follow it with the state endpoints or with webhooks.

Choosing a `customer_id`

This is your identifier for the person or company the credentials belong to, and it is the thread that ties everything about them together: every execution, every event we deliver and every record we keep carries it. It is how a support conversation finds what happened to one customer, and what your usage figures are grouped by.

Recurring extractions

A monthly refresh of bank data, a periodic re-check of employment. Send the stable id of that customer in your own database: repeating the same value is precisely what makes successive executions read as one person, and what turns them into a history worth having.

One-shot verifications

A single check, a case opened and closed. The identifier of that operation does the job just as well — nothing on our side validates the value, so send whatever you can trace back later.

Never put personal data in it. No national id, no email, no phone number, no name.

It travels in the URL of the webhooks we deliver, it is quoted in support tickets and it is stored with the execution. An internal key or a UUID is the right shape; a DNI is not.

What to send

Field	What it is for
`engine_reference`	The engine to run, from List Engines.
`parameters`	The fields Show Engine Details declares for that engine. Values — or the whole object — may travel encrypted as `rsa::…` or `hybrid::…`.
`features`	What to retrieve, each with its own settings. Omit it and the engine runs its defaults.
`external_execution_id`	Optional, and entirely yours — we store it, echo it back and never read it. It reaches your webhook URL as `{external_execution_id}`, and a different value per run is what lets you execute the same engine twice for one customer at once.
`base_configurations`	How the execution behaves: see below.
`hooks_extra_data`	A flat dictionary appended to every webhook delivery as query parameters — the natural place for your case id. Never for secrets.

base_configurations.customer_interaction_available decides the shape of your integration.

true says somebody can answer a challenge from the source within minutes, so the execution pauses and waits for you. false says nobody is there: it runs at low priority, has up to three hours to find a good moment, and ends rather than waits if the source asks for a second factor.

Two more live here: execution_timeout (active processing, 60–1200 seconds) and tokenized_access, which asks for a ticket so these credentials can be reused later without storing them — see Getting a ticket back, just below.

Getting a ticket back

The 202 carries a ticket only when the request asked for one: set base_configurations.tokenized_access to true. Leave it at its default and the field is simply absent — it is never part of an ordinary answer.

A ticket is single-use and shown once. Exchange it at Exchange a Ticket for the token that runs this same access again, with no password on your side.

Your application has to be allowed to tokenize, and the request cannot decide that: credential tokenization is a capability granted per application, and it has to be enabled — requested is not yet enabled. Ask for tokenized_access without it and the call answers 400 with status_reason: T10N_FORBIDDEN, and no execution is created.

Credential Tokenization is the explanation: which half each side holds, how long a token lives, and how to have it turned on for an application.

What the answers mean

Status	Meaning
`202`	Accepted and queued — `status_reason` is `ACCEPTED`.
`400`	The execution was viable; one detail makes it impossible. The request is complete — a malformed one answers `422` — and we saw the impediment before initialising anything, so you get the answer now instead of an execution that could never have worked. `status_reason` says which, from the same vocabulary a finished execution uses, so the branch that handles a failure handles this too; there is no `execution_id`, because nothing was created. Two cases: `CUSTOMER_INTERVENTION_REQUIRED`, the engine needs a person at every run and you declared none, and `T10N_FORBIDDEN`, you asked for `tokenized_access` and your application may not tokenize.
`409`	An execution matching this one is already running, and the body names it — see below.
`503`	The engine is temporarily unavailable. Retry later; nothing is wrong with your request.

When one is already running

A 409 is less an error than a pointer, and that is the whole difference between the two refusals: a 400 never carries execution ids, because nothing was created; a 409 always does, and they name the run to follow. The platform refuses a second run against the same access — some institutions treat two simultaneous logins as an attack — and hands you the one already in flight:

409 — the run already in flight

{
  "execution_id": "6aa3d8b418d1c5dc9a8e3d36",
  "session_id": "5aa3dca503e37e6809539a58",
  "app_id": "4aa3dcbab3287e2385bb5cec",
  "auth_origin": "app-secret",
  "customer_id": "my-customer-1",
  "engine_reference": "DEMOBANKXXXXFIN100ES9999-mobile",
  "external_execution_id": "case-A-1029",
  "status_reason": "ALREADY_EXECUTING",
  "status_code": "TEMPORARY_ERROR"
}

execution_id is the run that already exists, not the one you just asked for — nothing was created by this call. So the useful response is almost never to retry: follow that execution instead, answer its challenge if it is waiting for one, and read its results when it closes. A customer who double-submits your form gets one extraction and one answer, which is what you wanted anyway.

Three things collide, and knowing which tells you what to do:

What matched	What it means
The same customer and engine, still running	The obvious one. Follow it.
The same `external_execution_id` for that customer	Your own reference is already in flight. Follow it — or send a different reference if the two runs are genuinely different.
The same token	A tokenized run against those credentials is already going. Follow it.

If you meant them to run side by side, give each one a different external_execution_id. That is what the field is for, and it is the only way to have two executions of one engine for one customer at the same time.

Server to server only. This call is authorised with your application secret: it belongs in your backend, never in a browser, a mobile app or anything your customer can read. A leaked secret launches executions on your account.

Start an execution: an engine logs into the source with the credentials you send and retrieves the features you asked for. The call returns immediately with `202 Accepted` and an `execution_id`. Nothing has run yet — the job is queued, and from here on you follow it with the state endpoints or with [webhooks](/direct-executions/webhooks). ## Choosing a `customer_id` This is **your** identifier for the person or company the credentials belong to, and it is the thread that ties everything about them together: every execution, every event we deliver and every record we keep carries it. It is how a support conversation finds what happened to one customer, and what your usage figures are grouped by. <CardGroup cols={2}> <Card title="Recurring extractions" icon="fa-solid fa-repeat"> A monthly refresh of bank data, a periodic re-check of employment. Send the **stable id of that customer in your own database**: repeating the same value is precisely what makes successive executions read as one person, and what turns them into a history worth having. </Card> <Card title="One-shot verifications" icon="fa-solid fa-circle-check"> A single check, a case opened and closed. The **identifier of that operation** does the job just as well — nothing on our side validates the value, so send whatever you can trace back later. </Card> </CardGroup> <Warning> **Never put personal data in it.** No national id, no email, no phone number, no name. It travels in the URL of the webhooks we deliver, it is quoted in support tickets and it is stored with the execution. An internal key or a UUID is the right shape; a DNI is not. </Warning> ## What to send | Field | What it is for | | :--- | :--- | | `engine_reference` | The engine to run, from [List Engines](api:GET/config/engines/list). | | `parameters` | The fields [Show Engine Details](api:GET/config/engines/{engine_reference}) declares for that engine. Values — or the whole object — may travel encrypted as `rsa::…` or `hybrid::…`. | | `features` | What to retrieve, each with its own settings. Omit it and the engine runs its defaults. | | `external_execution_id` | Optional, and entirely yours — we store it, echo it back and never read it. It reaches your webhook URL as `{external_execution_id}`, and a different value per run is what lets you execute the same engine twice for one customer at once. | | `base_configurations` | How the execution behaves: see below. | | `hooks_extra_data` | A flat dictionary appended to every webhook delivery as query parameters — the natural place for your case id. **Never for secrets.** | <Note> **`base_configurations.customer_interaction_available` decides the shape of your integration.** `true` says somebody can answer a challenge from the source within minutes, so the execution pauses and waits for you. `false` says nobody is there: it runs at low priority, has up to three hours to find a good moment, and **ends** rather than waits if the source asks for a second factor. Two more live here: `execution_timeout` (active processing, 60–1200 seconds) and `tokenized_access`, which asks for a `ticket` so these credentials can be reused later without storing them — see **Getting a ticket back**, just below. </Note> ## Getting a ticket back The `202` carries a **`ticket`** only when the request asked for one: set `base_configurations.tokenized_access` to `true`. Leave it at its default and the field is simply absent — it is never part of an ordinary answer. A ticket is single-use and shown once. Exchange it at [Exchange a Ticket](api:PUT/executions/t10n) for the token that runs this same access again, with no password on your side. <Note> **Your application has to be allowed to tokenize**, and the request cannot decide that: credential tokenization is a capability granted **per application**, and it has to be enabled — requested is not yet enabled. Ask for `tokenized_access` without it and the call answers `400` with `status_reason: T10N_FORBIDDEN`, and no execution is created. [Credential Tokenization](/guides/credential-tokenization) is the explanation: which half each side holds, how long a token lives, and how to have it turned on for an application. </Note> ## What the answers mean | Status | Meaning | | :--- | :--- | | `202` | Accepted and queued — `status_reason` is `ACCEPTED`. | | `400` | **The execution was viable; one detail makes it impossible.** The request is complete — a malformed one answers `422` — and we saw the impediment before initialising anything, so you get the answer now instead of an execution that could never have worked. `status_reason` says which, **from the same vocabulary a finished execution uses**, so the branch that handles a failure handles this too; there is no `execution_id`, because nothing was created. Two cases: `CUSTOMER_INTERVENTION_REQUIRED`, the engine needs a person at every run and you declared none, and `T10N_FORBIDDEN`, you asked for `tokenized_access` and your application may not tokenize. | | `409` | **An execution matching this one is already running, and the body names it** — see below. | | `503` | The engine is temporarily unavailable. Retry later; nothing is wrong with your request. | ## When one is already running A `409` is **less an error than a pointer**, and that is the whole difference between the two refusals: a `400` never carries execution ids, because nothing was created; a `409` always does, and they name the run to follow. The platform refuses a second run against the same access — some institutions treat two simultaneous logins as an attack — and hands you the one already in flight: ```json title="409 — the run already in flight" { "execution_id": "6aa3d8b418d1c5dc9a8e3d36", "session_id": "5aa3dca503e37e6809539a58", "app_id": "4aa3dcbab3287e2385bb5cec", "auth_origin": "app-secret", "customer_id": "my-customer-1", "engine_reference": "DEMOBANKXXXXFIN100ES9999-mobile", "external_execution_id": "case-A-1029", "status_reason": "ALREADY_EXECUTING", "status_code": "TEMPORARY_ERROR" } ``` **`execution_id` is the run that already exists, not the one you just asked for** — nothing was created by this call. So the useful response is almost never to retry: [follow that execution](api:GET/executions/handler/v1/{execution_id}) instead, answer its challenge if it is waiting for one, and read its results when it closes. A customer who double-submits your form gets one extraction and one answer, which is what you wanted anyway. Three things collide, and knowing which tells you what to do: | What matched | What it means | | :--- | :--- | | The same **customer and engine**, still running | The obvious one. Follow it. | | The same **`external_execution_id`** for that customer | Your own reference is already in flight. Follow it — or send a different reference if the two runs are genuinely different. | | The same **token** | A tokenized run against those credentials is already going. Follow it. | <Tip> **If you meant them to run side by side**, give each one a different `external_execution_id`. That is what the field is for, and it is the only way to have two executions of one engine for one customer at the same time. </Tip> <Warning> **Server to server only.** This call is authorised with your application secret: it belongs in your backend, never in a browser, a mobile app or anything your customer can read. A leaked secret launches executions on your account. </Warning>

Authentication

X-APP-SECRETstring

Application Secret

Request

This endpoint expects an object.

engine_referencestringRequiredformat: "engine-reference"

The engine to run, as List Engines publishes it — one source through one access channel, and the same string on every later event and record.

Read it from the catalogue rather than building it: which engines your application may run, and which of them are answering right now, is a question only the catalogue can answer. A reference that is unknown, disabled for you or out of service is refused before anything runs.

customer_idstringRequired1-64 characters

Your own identifier for the person or company these credentials belong to. Send the stable id you use in your system when the same access is run again over time — repeating a value is how successive executions read as the same customer — and for a one-off, the identifier of that operation does the job just as well.

It travels in every event we deliver and is stored with the execution, so keep personal data out of it: an internal key or a UUID, never a national id or an email. The endpoint description explains how to choose it.

parametersmap from strings to anyRequired

What the engine needs to log in — the fields Show Engine Details declares for it, under the names it declares them.

These are somebody else’s credentials, so they can travel encrypted end to end: send a value as rsa::… or hybrid::…, or the whole object as one encrypted string, and not even an intercepted request body reveals them. How to encrypt them.

external_execution_idstringOptional1-64 characters

Your own reference for this run — a case number, a job id, whatever your system calls it. We store it, echo it back on every state and event, and offer it as {external_execution_id} in the URL of the webhooks we deliver. We never interpret it.

It has one effect: a second execution with the same reference, for the same customer and still running, is refused with 409. That is also what lets you run one engine twice at once — give each run a different reference.

base_configurationsobjectOptional

The same settings, plus the one only a run WITH credentials can ask for: tokenized_access, which returns a ticket so this access can be repeated later without keeping the password.

featureslist of objectsOptional

What to retrieve. Every feature is a name — accounts_read, labor_check — and you may send it as the bare string, or as an object when you want to configure it: {"code": "accounts_read", "configurations": {…}}.

The features an engine offers, and the settings each one accepts, are in Show Engine Details. Ask for one it does not implement and it is ignored: no data, no error, and nothing in the results to say it was skipped — which is why the list is built from the catalogue. Ask only for what you will use: each feature is more time inside the source, and a slow one holds the whole execution.

hooks_extra_datamap from strings to stringsOptionalDefaults to {}

Your own context, carried into every webhook this execution delivers. Each key and value is appended to the delivery as a query parameter, so a handler reads it without opening the body.

A value may also be a template variable — {external_execution_id}, {event}, {status_reason}… — replaced with this execution’s own data at send time; anything else is sent verbatim. The full list, and the rest of the delivery contract, is in Webhooks.

Never put secrets here. Query strings end up in access logs and proxies; your endpoint’s authentication belongs in its header.

configurationsmap from strings to anyOptional

Engine-specific settings, and almost always empty. An engine takes what it needs through parameters and features; this is for the rare source that asks for something structural on top, and that engine declares exactly what in its own spec at Show Engine Details.

If you are wondering whether the engine you are integrating needs one: it does not. The handful that do are unmistakable about it.

Response

202 Accepted
Accepted, not finished. The execution is queued; what the source says comes later, in the state and in the events.

app_idstringformat: "object-id"

The application this execution was launched with — the one your secret belongs to. Worth keeping when your product uses more than one, a sandbox and a production app being the usual case: every record and every event we send carries it.

customer_idstring

The customer_id you supplied when the execution was initialised, returned as you sent it — so an answer can be routed to the right case with no lookup on your side.

auth_originenum

How the call that created the execution was authorised: an application secret for a server-to-server call, or a user session when it was launched from a console. An audit field — it says who started the run, not how it went.

engine_referencestringformat: "engine-reference"

The engine this execution runs, exactly as the catalogue publishes it. It is echoed on every event and every record, so a stored result says which source it came from with no lookup on your side.

status_reasonenum

The precise cause of the state. Every reason belongs to exactly one status_code family and its wording never changes, so it is safe to branch on — read status_code when the family is all you need, and see the lifecycle for what each one asks of you.

Reasons for ONGOING:
- ACCEPTED: queued, nothing has started yet.
- WAITING: picked up, the engine is warming up.
- RUNNING: logged in and extracting.
- ASYNC_WAIT: waiting on the source to produce something on its own schedule.
Reasons for ACTION_REQUIRED:
- MFA_REQUIRED: the source asked for a strong-authentication factor.
- INPUT_REQUIRED: the engine needs another field it could not know in advance.
Reasons for COMPLETED:
- COMPLETED: every requested feature answered.
Reasons for PARTIAL:
- PARTIAL: finished, with some features answered and others not.
Reasons for FAILED:
- FAILED: finished, and nothing could be retrieved.
Reasons for ABORTED:
- CLIENT_CANCELLED: you aborted it.
- USER_CANCELLED: your customer abandoned it.
- ACTION_TIMEOUT: nobody answered the challenge in time.
- TIMEOUT: the run exceeded its execution_timeout.
- CUSTOMER_INTERVENTION_REQUIRED: a person was needed and none was available.
- SYSTEM_CANCELLED: the platform stopped it.
Reasons for AUTH_ERROR — the source refused the login, and retrying the same values will not help:
- INCORRECT_CREDENTIALS: rejected. Ask your customer for them again.
- INCORRECT_MFA: the challenge was answered wrongly.
- BLOCKED_USER: the institution has blocked the access.
- FRIEZED_CREDENTIALS: the access is temporarily frozen.
- CHANGE_PASSWORD: the institution requires a password change first.
- MANUAL_INTERVENTION: the person must do something in the source’s own channel.
- INCOMPATIBLE_ACCESS: this access does not work through this engine’s channel.
- DUPLICATED_SESSION: another session is already open for that user.
Reasons for UNHANDLED_AUTH_ERROR:
- UNHANDLED_AUTH_ERROR: the login failed in a way we could not classify.
Reasons for CONFIGURATION_ERROR — the request itself, so retrying it unchanged fails the same way:
- BAD_CONFIGURATIONS: a feature configuration the engine does not accept.
- INCORRECT_PARAMETERS_FORMAT: the parameters did not match the engine’s form.
- INCORRECT_RESUME_FORMAT: the resume body did not match the published form.
- ENCRYPTION_ERROR: an encrypted value could not be opened.
- T10N_FORBIDDEN: your application may not tokenize.
- T10N_NOT_AVAILABLE: this engine does not support tokenization.
- T10N_REJECTED: the token is revoked or broken.
- T10N_EXCEPTION: the stored credentials could not be read.
- BAD_PROXY_CONFIGURATION: ours, not yours — contact support.
Reasons for TEMPORARY_ERROR — nothing is wrong with your request, retry later:
- OUT_OF_SERVICE: the source itself is unavailable.
- ENGINE_UNAVAILABLE: the engine is not serving right now.
- ALREADY_EXECUTING: another execution is already running for that access.
- ENGINE_BANNED, AUTO_CAPTCHA_ERROR, PROXY_ERROR, NETWORK_ERROR, INTERNAL_ERROR: the run could not be set up. Ours, and transient.

AUTH_OK belongs to this vocabulary too, but it only ever appears in authentication_status: a login that succeeds leaves the execution ONGOING.

status_codeenumRead-only

The family a state belongs to, and the value to branch on: it is always present, and every status_reason belongs to exactly one of these. The precise cause lives in the reason — read it when the family is not specific enough to decide. Allowed values are:

ONGOING: The execution is ongoing
ACTION_REQUIRED: The execution is waiting for an input
COMPLETED: The execution has been completed
ABORTED: The execution has been aborted
CONFIGURATION_ERROR: The execution has been rejected due to a configuration error
PARTIAL: The execution has been completed with errors
TEMPORARY_ERROR: The execution cannot be processed due to a temporary error
AUTH_ERROR: The execution failed due to an authentication error
UNHANDLED_AUTH_ERROR: The execution failed during the login because of an unhandled error
FAILED: The execution has failed

execution_idstringOptionalformat: "object-id"

The handle to this execution, and the one value worth storing from this response: you poll it for the state, you match it against the webhooks we deliver, and every results endpoint is addressed by it.

Present only when the execution was created. A request refused before that — a collision, an invalid configuration — answers without it.

session_idstringOptionalformat: "object-id"

The session this execution belongs to. An execution launched on its own is its own session, so today the two values usually match — treat them as two independent identifiers anyway: an execution can be one step of a wider journey, and a run you are pointed at is not always the one you asked for.

Address results and state by execution_id. Like it, this is only present when an execution was created.

external_execution_idstringOptional

The reference you attached when the execution was started, if you sent one — echoed so your own identifier travels beside ours, on this response and on every event.

status_messagestringOptional

A human-readable note, when there is one to add. It is diagnostic and never a contract: do not parse it and do not show it to your end user as it comes — branch on status_reason and write your own copy.

session_tokenstringOptional

A short-lived token that authorises acting on this execution and nothing else: it cannot read a single extracted record, and it stops working when the execution ends.

Resolving a pause through this API needs none of it — collect the value and send it to the resume endpoint. The token is for the other option, which is coming: handing that moment to a minimal hosted interface instead of building the screens yourself. Not a flow — no journey, no consent step, no branding, just what a pause needs over the execution you already started. Until it ships there is nothing to present this token to, so you can safely ignore it.

The prefix says which kind of run issued it: st_test_ when the run is a rehearsal — a sandbox application, or a sandbox engine under a production one — and st_live_ otherwise.

ticketstringOptional=64 characters

A single-use ticket for the credentials this execution just used. It is returned only when the execution asked for tokenized access and your application is allowed to use it.

You see it here and nowhere else. Exchange it for a token and it is spent: what we keep afterwards is the sealed credentials and a verifier — never the key that opens them, which is the half you hold. Keep it out of your logs, and read the Credential Tokenization guide for the shared-custody model behind it.

Errors

400

Bad Request Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

503

Service Unavailable Error

Choosing a customer_id

What to send

Getting a ticket back

What the answers mean

When one is already running

Authentication

Request

Response

Errors

Choosing a customer_id

What to send

Getting a ticket back

What the answers mean

When one is already running

Choosing a `customer_id`

Choosing a `customer_id`