API reference
Every v1 endpoint, rendered from the public contract the API and SDK are built on.
The Unirail API is REST over JSON at https://api.unirail.dev, with every path under /v1. The endpoints below are rendered from @unirail/contract, the same contract the API serves and the SDK is typed by, and the machine-readable spec is at https://api.unirail.dev/v1/openapi.json.
Conventions
| Topic | Rule |
|---|---|
| Authentication | Authorization: Bearer ur_test_sk_…. The key's environment decides where the call runs. |
| Versioning | Unirail-Version: 2026-10-08. The SDK sends it for you. |
| Idempotency | Idempotency-Key on every write (idempotency). |
| Amounts | { value, asset }: integer minor units as a string, and iso4217:GBP or a CAIP-19 asset id. |
| Timestamps | ISO 8601 strings with an offset. |
| Ids | Prefixed: cus_, acct_, lnk_, ins_, qt_, pi_, leg_, evt_, con_. |
| Lists | limit (1–100, default 25) and after (the last id you saw). Responses are { data, hasMore, next }. |
| Errors | One envelope with a stable data.code (errors). |
Parameters marked * are required. With the SDK, call the method shown on the right of each endpoint, for example unirail.routeQuotes.create({ … }).
Rails
/v1/railsrails.list()The provider catalogue: integrated and listed rails.
| Parameter | In | Type | Notes |
|---|---|---|---|
| country | query | string | ISO 3166-1 alpha-2 |
| status | query | "listed" | "in-development" | "integrated" | "certified" | Only listings with this status. |
Returns { data }.
Addresses
/v1/addresses/parseaddresses.parse()Validate and mask a payto:// address without storing it.
| Parameter | In | Type | Notes |
|---|---|---|---|
| payto* | body | string | A payto:// URI, for example payto://scan/040004/12345678?receiver-name=Ada%20Lovelace. (max 2048 chars) |
Returns { scheme, known, masked, country, receiverName }.
Institutions
/v1/institutionsinstitutions.list()Banks reachable through this environment's connections.
| Parameter | In | Type | Notes |
|---|---|---|---|
| country* | query | string | ISO 3166-1 alpha-2 |
| q | query | string | Search by bank name. (max 80 chars) |
| limit | query | integer | Page size. (default 25, 1–100) |
Returns { data }.
Customers
/v1/customerscustomers.create()Create or return the customer for your user id.
| Parameter | In | Type | Notes |
|---|---|---|---|
| externalId* | body | string | Your user id. Unique per environment; creating twice returns the same customer. (max 128 chars) |
| name | body | string | (max 140 chars) |
| body | string (email) | ||
| country | body | string | ISO 3166-1 alpha-2 |
| metadata | body | Record<string, string> | Up to 20 keys you can use to find objects again. |
Returns a customer object with HTTP 201.
/v1/customers/{id}customers.retrieve()| Parameter | In | Type | Notes |
|---|---|---|---|
| id* | path | string | cus_… identifier |
Returns a customer object.
/v1/customerscustomers.list()| Parameter | In | Type | Notes |
|---|---|---|---|
| externalId | query | string | Your user id. Unique per environment; creating twice returns the same customer. |
| after | query | string | Cursor: the id of the last object you received. Returns the objects after it. |
| limit | query | integer | Page size. (default 25, 1–100) |
Returns a page of customer objects: { data, hasMore, next }.
Link sessions
/v1/link_sessionslinkSessions.create()Start linking a customer's bank account.
| Parameter | In | Type | Notes |
|---|---|---|---|
| customer* | body | string | The customer (cus_…). |
| country* | body | string | ISO 3166-1 alpha-2 |
| institution | body | string | An institution from GET /v1/institutions. |
| rail | body | string | Force a rail. Otherwise the environment’s policy picks one for the institution. |
| channel | body | "web" | "native" | Where your user is: web or native. (default "web") |
| returnUri* | body | string (uri) | Where the user lands after the provider step; your app's URL or universal link |
| psu | body | { ip, userAgent, deviceId, psuType } | Context from your user’s device (IP, user agent, device id, personal or business). Some banks require it. |
Returns a link_session object with HTTP 201.
/v1/link_sessions/{id}/advancelinkSessions.advance()Continue after the user returns from the provider.
| Parameter | In | Type | Notes |
|---|---|---|---|
| id* | path | string | lnk_… identifier |
| returnParams | body | Record<string, string> | The query parameters your return URI received, verbatim. |
| sdkResult | body | Record<string, string> | For sdk actions, what the provider SDK handed back (for example Plaid’s public token). |
Returns a link_session object.
/v1/link_sessions/{id}linkSessions.retrieve()| Parameter | In | Type | Notes |
|---|---|---|---|
| id* | path | string | lnk_… identifier |
Returns a link_session object.
Accounts
/v1/accountsaccounts.create()Register account details a payee gave you (not linked through a provider).
| Parameter | In | Type | Notes |
|---|---|---|---|
| customer | body | string | The customer (cus_…). |
| holderName* | body | string | The account holder’s name, as the payee gave it to you. (max 140 chars) |
| payto* | body | string | A payto:// URI, for example payto://scan/040004/12345678?receiver-name=Ada%20Lovelace. (max 2048 chars) |
| metadata | body | Record<string, string> | Up to 20 keys you can use to find objects again. |
Returns an account object with HTTP 201.
/v1/accounts/{id}accounts.retrieve()| Parameter | In | Type | Notes |
|---|---|---|---|
| id* | path | string | acct_… identifier |
Returns an account object.
/v1/accountsaccounts.list()| Parameter | In | Type | Notes |
|---|---|---|---|
| customer | query | string | The customer (cus_…). |
| after | query | string | Cursor: the id of the last object you received. Returns the objects after it. |
| limit | query | integer | Page size. (default 25, 1–100) |
Returns a page of account objects: { data, hasMore, next }.
Route quotes
/v1/route_quotesrouteQuotes.create()Find and price the routes between two accounts.
| Parameter | In | Type | Notes |
|---|---|---|---|
| from* | body | string | acct_… identifier |
| to* | body | string | acct_… identifier |
| amount* | body | { value, asset } | Integer minor units as a decimal string, plus an asset such as iso4217:GBP. |
| preference | body | "cheapest" | "fastest" | "recommended" | Which label to rank first. Defaults to the environment’s routing policy. |
| preferRail | body | string | Rank routes through this rail first when several are feasible. |
| channel | body | "web" | "native" | Where your user is: web or native. (default "web") |
Returns { quotes, infeasible, suggestion }.
Payment intents
/v1/payment_intentspaymentIntents.create()Pay along an accepted quote.
| Parameter | In | Type | Notes |
|---|---|---|---|
| quote* | body | string | The quote (qt_…) your user approved. |
| digest* | body | string | The digest of the quote your user approved. |
| returnUri* | body | string (uri) | Where the user lands after the provider step; your app's URL or universal link |
| reference | body | string | Payment reference, up to 140 characters. (max 140 chars) |
| psu | body | { ip, userAgent, deviceId, psuType } | Context from your user’s device (IP, user agent, device id, personal or business). Some banks require it. |
| metadata | body | Record<string, string> | Up to 20 keys you can use to find objects again. |
Returns a payment_intent object with HTTP 201.
/v1/payment_intents/{id}paymentIntents.retrieve()| Parameter | In | Type | Notes |
|---|---|---|---|
| id* | path | string | pi_… identifier |
Returns a payment_intent object.
/v1/payment_intents/{id}/advancepaymentIntents.advance()Continue after the user returns from approving.
| Parameter | In | Type | Notes |
|---|---|---|---|
| id* | path | string | pi_… identifier |
| returnParams | body | Record<string, string> | The query parameters your return URI received, verbatim. |
| sdkResult | body | Record<string, string> | For sdk actions, what the provider SDK handed back (for example Plaid’s public token). |
Returns a payment_intent object.
/v1/payment_intents/{id}/cancelpaymentIntents.cancel()| Parameter | In | Type | Notes |
|---|---|---|---|
| id* | path | string | pi_… identifier |
Returns a payment_intent object.
/v1/payment_intentspaymentIntents.list()| Parameter | In | Type | Notes |
|---|---|---|---|
| customer | query | string | The customer (cus_…). |
| after | query | string | Cursor: the id of the last object you received. Returns the objects after it. |
| limit | query | integer | Page size. (default 25, 1–100) |
Returns a page of payment_intent objects: { data, hasMore, next }.
Route decisions
Decide mode: a routing decision from masked metadata, for when your backend calls the provider itself. See Decide mode.
/v1/route_decisionsrouteDecisions.create()Decide the rail and cost for an operation from masked metadata (no personal data).
| Parameter | In | Type | Notes |
|---|---|---|---|
| operation* | body | "banking.ais.account-details" | "banking.ais.balances" | "banking.ais.transactions" | "banking.ais.insights" | "banking.pis.single" | "banking.pis.scheduled" | "banking.pis.vrp-sweeping" | "banking.pis.vrp-commercial" | "banking.pis.bulk" | "banking.payouts" | "banking.pay-ins.virtual-accounts" | "banking.pay-ins.debit" | "verification.cop" | "verification.vop" | "verification.ownership" | "verification.micro-deposits" | "identity.kyc.document" | "identity.kyc.biometric" | "identity.kyc.database" | "identity.kyc.eid" | "identity.kyb" | "identity.prefill" | "compliance.screening.sanctions" | "compliance.screening.pep" | "compliance.screening.adverse-media" | "compliance.screening.payments" | "compliance.transaction-monitoring" | "compliance.travel-rule" | "risk.payment-return" | "risk.fraud-signals" | "money.fx" | "money.cross-border" | "money.stablecoin-ramp" | A capability id, for example banking.pis.single. |
| amount | body | { value, asset } | { asset, band } | Minor units, or { asset, band: { min, max } } to keep the exact figure to yourself. Required for payments. |
| payer* | body | { country, institution, scheme, accountRef, linkedRails } | Metadata only: country, and optionally institution, scheme (a payto scheme name), accountRef (from maskAccount) and linkedRails. Any other field is refused. |
| payee | body | { country, institution, scheme, accountRef, linkedRails } | Like payer. Required for payments. |
| preference | body | "cheapest" | "fastest" | "recommended" | Which label to rank first. Defaults to the environment’s routing policy. |
| channel | body | "web" | "native" | Where your user is: web or native. (default "web") |
| constraints | body | { excludeRails, custodyAdmitted } | excludeRails, and custodyAdmitted to narrow what your policy admits. |
Returns a route_decision object.
Outcomes
/v1/outcomesoutcomes.create()Report how a decided operation went; feeds reliability and contract usage.
| Parameter | In | Type | Notes |
|---|---|---|---|
| decision* | body | string | The decision (dec_…) this outcome is for. |
| rail* | body | string | The rail you actually used, which may be one of the alternatives. |
| status* | body | "succeeded" | "failed" | "cancelled" | succeeded, failed or cancelled. Reporting the same status twice returns the first record. |
| latencyMs* | body | integer | From sending the request to the provider until this status. (0–2592000000) |
| providerFee | body | { amount, currency } | What the provider charged, in decimal major units, if you know it. |
| failureCode | body | string | A short code such as rejected. Never the provider’s message. |
| context | body | { operation, country, institution } | Only for decisions your own @unirail/router made, which Unirail never saw: the operation, country and optional institution. |
Returns an outcome object with HTTP 201.
Routing snapshot
/v1/routing_snapshotroutingSnapshot.get()Everything the decision engine reads, to run @unirail/router yourself (no secrets).
Returns a routing_snapshot object.
Events
/v1/eventsevents.list()Events in order; walk with `after` to replay anything a webhook missed.
| Parameter | In | Type | Notes |
|---|---|---|---|
| after | query | string | Cursor: the id of the last object you received. Returns the objects after it. |
| type | query | "link_session.completed" | "link_session.failed" | "account.updated" | "account.reauth_required" | "payment_intent.requires_action" | "payment_intent.processing" | "payment_intent.succeeded" | "payment_intent.failed" | "payment_intent.cancelled" | "leg.updated" | "connection.degraded" | Only events of this type. |
| limit | query | integer | Page size. (default 25, 1–100) |
Returns a page of event objects: { data, hasMore, next }.
/v1/events/{id}events.retrieve()| Parameter | In | Type | Notes |
|---|---|---|---|
| id* | path | string | evt_… identifier |
Returns an event object.