Skip to main content
POST
Create a portal session

Authorizations

Authorization
string
header
required

Username = your client id. Password = your client secret.

So the base64-encoded username:password described below is client_id:client_secret:

Most HTTP clients build that header for you:

Both values come from Developers → Apps → your app. The secret is shown once at creation and is prefixed oac_.

Path Parameters

userId
string
required

Body

application/json
return_url
string<uri> | null

Where "Continue to ‹App›" sends this user when they finish. Omit to use the app's configured portal return URL. With institution_id or connection_id, a successful bank flow also returns here directly, with status=completed and connection, even when the bank finishes in its own app and opens the return in another browser tab. Any https:// URL is accepted; it does not have to be registered on the app.

Maximum string length: 512
institution_id
integer | null

The institution the user already picked in your app. When set, the portal shows a short "‹App› uses Synci" interlude and then starts that institution's consent flow by itself, instead of asking the user to pick their bank a second time. Ids come from GET /finance/institutions. This always starts a new connection, even when the user already has one at that bank; connecting the same login twice gives the user a second connection with its own copy of the accounts, billed separately. To renew an existing connection, send connection_id instead. An institution this app may not connect is rejected with 422 when the session is minted.

Required range: 1 <= x <= 9007199254740991
connection_id
integer | null

One of this user's existing connections that needs renewing (an expiring consent, or a bank that asks the user to sign in again). The portal shows the same short interlude as for institution_id and then starts the renewal of THIS connection: it keeps its id, its accounts and their history, and a connection.reauthorized webhook follows. Send it as a string. Mutually exclusive with institution_id, which starts a new connection. Checked when the session is minted: a connection that is not this user's, or whose provider cannot renew, is a 422.

Required range: 1 <= x <= 9007199254740991

Response

data
object
required