Open a hosted consent session

POST 
/api/v1/workspaces/:workspace_id/companies/:company_id/bank_connections

Opens a consent session and returns the connection in pending with a consent_url. A 201 means a session exists, never that a bank is connected. A human must open consent_url in a browser; there is no headless bank connection. Poll GET /api/v1/bank_connections/{id} after the user returns - connected there means a webhook or a sync confirmed it, and the provider's redirect never does.

Request

Responses

201

A consent session was opened. The connection is pending and consent_url carries the page the user must visit.

202

The provider's answer did not establish whether a session was opened. The connection is returned so you can poll it, with no consent_url - there is none to give. Poll GET /api/v1/bank_connections/{id}; if it is still pending past consent_url_expires_at, open a new session with a fresh Idempotency-Key. Replaying this key returns this same response rather than opening a second session.

409

This Idempotency-Key cannot serve this request. code says which of two: idempotency_key_reuse - the key already served a different body, so send a fresh key or resend the original body to replay the stored response; idempotency_request_in_progress - an earlier call bearing this key is still running, or ended without establishing that nothing left the platform. Nothing was written by this call in either case.

422

The request was refused. code says which of four: validation_failed - the Idempotency-Key header or user_email is missing; invalid_argument - user_email is malformed, or redirect_url is not one of the URIs registered for your application; provider_quota_exceeded - the aggregator will not open one more connection for this account, so free a slot or move to another plan, because retrying unchanged is refused again; operation_failed - the aggregator refused the session for a transient reason, or another session is already being opened for the same company, so retry.