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 }.
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.