API reference

List institutions

GET/v1/institutions

Every institution this key may connect. A sandbox key sees the sandbox institutions and nothing else; a live key never sees them. sync_mode and runs_on say how each institution stays current and where its sign-in happens, so you know before anybody connects.

Returns

200 The institutions this key may connect. array of Institution

Errors

Example

curl "https://api.alkirai.com/v1/institutions" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET"

Start a Connect session

POST/v1/connect/sessions

Mints a link_token and the link_url to open in the person's browser or web view. Connect takes their sign-in details and any one-time code, then sends the browser to your redirect_uri with public_token and, if you sent one, state. The redirect_uri must be registered for your key and is matched exactly. The session lasts 10 minutes. Not for an institution whose runs_on is client, which answers 400. With connection_id, Connect signs the person in again to a connection you already hold instead of making a new one; a connection that is not yours answers 404.

Request body

JSON, a LinkSessionRequest. At most 64 KiB.

Returns

200 The token and the address to open. LinkSessionResponse

Errors

Example

curl -X POST "https://api.alkirai.com/v1/connect/sessions" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "institution_id": "sandbox_bank",
    "redirect_uri": "https://example.com/connected",
    "state": "person-42"
  }'

Exchange a public token

POST/v1/connect/exchange

Trades the public_token from your redirect for the connection_id you keep. A public token lasts 60 seconds and works once, so exchange it as soon as your redirect is called: a connection nobody exchanges is deleted after 5 minutes. After a sign-in again, it is the connection you sent, and an exchange that never happens deletes nothing.

Request body

JSON, a ExchangeRequest. At most 64 KiB.

Returns

200 The new connection. ExchangeResponse

Errors

Example

curl -X POST "https://api.alkirai.com/v1/connect/exchange" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET" \
  -H "Content-Type: application/json" \
  -d "{\"public_token\": \"$PUBLIC_TOKEN\"}"

List connections

GET/v1/connections

Every connection this key made, with each one's state. Read without signing in to any institution, so it costs no sign-ins.

Returns

200 This key's connections. ConnectionList

Errors

Example

curl "https://api.alkirai.com/v1/connections" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET"

Get a connection

GET/v1/connections/{connection_id}

One connection's state and sign-in budget, read without signing in. active: a sync would sign in now. stopped: syncs are refused until something changes, and error says what. at_limit: the sign-in budget is spent until sign_ins.next_at.

Path parameters

Returns

200 The connection's state. ConnectionStatus

Errors

Example

curl "https://api.alkirai.com/v1/connections/$CONNECTION_ID" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET"

Remove a connection

DELETE/v1/connections/{connection_id}

Deletes the connection and the sign-in details AlkiraiLink stored for it. Safe to repeat: removing an unknown connection still answers removed: true. When action_required is not empty, show it to the person, because something is left at the institution that only they can clear.

Path parameters

Returns

200 What the removal did. RemovalOutcome

Errors

Example

curl -X DELETE "https://api.alkirai.com/v1/connections/$CONNECTION_ID" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET"

List accounts

GET/v1/connections/{connection_id}/accounts

The connection's accounts and balances. Signs in to the institution, so it spends one of the connection's sign-ins; to read accounts and transactions together, use Refresh a connection. For 15 minutes after a connect, reads are answered from the connect's own sign-in.

Path parameters

Returns

200 The accounts. array of Account

Errors

Example

curl "https://api.alkirai.com/v1/connections/$CONNECTION_ID/accounts" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET"

Sync transactions

POST/v1/connections/{connection_id}/sync

Transactions added, modified and removed since cursor. Send no cursor the first time; store the one returned and send it next time. History can arrive over several syncs, so keep syncing with the cursor returned. When partial_failure is set, the diff is real but incomplete: store what arrived, keep the new cursor and sync again later. Signs in, as List accounts does.

Path parameters

Query parameters

Returns

200 What changed, and the next cursor. SyncResult

Errors

Example

curl -X POST "https://api.alkirai.com/v1/connections/$CONNECTION_ID/sync?cursor=$CURSOR" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET"

Refresh a connection

POST/v1/connections/{connection_id}/refresh

Accounts and a transaction sync from one sign-in. Prefer it to List accounts followed by Sync transactions, which signs in twice. transactions is exactly what Sync transactions returns for the same cursor.

Path parameters

Query parameters

Returns

200 The accounts, and what changed. RefreshResult

Errors

Example

curl -X POST "https://api.alkirai.com/v1/connections/$CONNECTION_ID/refresh?cursor=$CURSOR" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET"

Get an export recipe

GET/v1/institutions/{institution_id}/export-recipe

What the mobile SDK needs to run a sign-in sync at this institution. Fetch it from your server and pass it to the SDK unchanged: its fields are the SDK's to read, and they change when the institution's site does. Only for an institution whose runs_on is client; any other answers 404.

Path parameters

Returns

200 The recipe, for the SDK. ExportRecipe

Errors

Example

curl "https://api.alkirai.com/v1/institutions/sandbox_statements/export-recipe" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET"

Get a signed manifest

GET/v1/institutions/{institution_id}/manifest

The address the SDK opens for this institution's sign-in and its export recipe, signed by AlkiraiLink, so the SDK can check that neither was changed on the way. Fetch it from your server and pass it to the SDK byte for byte: do not parse, re-encode or reorder it. Only for an institution whose runs_on is client; any other answers 404.

Path parameters

Returns

200 The signed manifest: payload and signature, both base64url. any

Errors

Example

curl "https://api.alkirai.com/v1/institutions/sandbox_statements/manifest" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET"

Read a statement

POST/v1/institutions/{institution_id}/statements

Reads one exported statement file into accounts and transactions, and returns your cursor with the file's months added. AlkiraiLink keeps nothing it is sent: not the file, not its rows, not the cursor. transactions is every row in the file, not a diff, so upsert by transaction_id, which is the same for the same row in overlapping files. Send a sign-in's files one at a time, each with the cursor the one before returned.

Path parameters

Request body

JSON, a StatementUpload. At most 1.5 MiB.

Returns

200 The file's accounts, rows and coverage, and the new cursor. StatementRead

Errors

Example

curl -X POST "https://api.alkirai.com/v1/institutions/sandbox_statements/statements" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "statement_base64": "<the exported file, base64>",
    "cursor": "<the cursor you stored, or empty>"
  }'

Plan which months to export

POST/v1/institutions/{institution_id}/statement-plan

Which months to export for each account, from your cursor and the months the institution's page offers. The newest month on offer is always included, because it is the one a late transaction lands in. Writes nothing.

Path parameters

Request body

JSON, a StatementPlanRequest. At most 128 KiB.

Returns

200 The months to fetch, per account. StatementPlan

Errors

Example

curl -X POST "https://api.alkirai.com/v1/institutions/sandbox_statements/statement-plan" \
  -H "X-Client-Id: $ALKIRAILINK_CLIENT_ID" \
  -H "X-API-Key: $ALKIRAILINK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "cursor": "<the cursor you stored, or empty>",
    "accounts": [
      {
        "account": "0001",
        "currency": "USD"
      }
    ],
    "offered_months": [
      "2026-09",
      "2026-10"
    ]
  }'