{ "item": [ { "name": "Connections", "description": "Bank connection lifecycle and consent management", "item": [ { "id": "812230c7-f7fc-469d-8c2b-3fa56954266b", "name": "Initialize connection (direct integration)", "request": { "name": "Initialize connection (direct integration)", "description": { "content": "Initializes the bank connection and returns a URL for user redirection. This is the direct integration path where the partner renders their own bank picker; for the hosted flow use `POST /v1/connect-sessions`. After the bank journey, the user is redirected to `returnUrl` with `connectionId`, `resultCode` (`Ok`|`Error`) and optional `error` appended. Authoritative completion signal is the webhook stream, not the redirect. Auth windows (additive): about 2 minutes to initiate bank authentication, then completion is checked ~20 minutes later (≈ 22 minutes from start). `expiresAt` reflects the initiate window; note that `directRedirect` providers return `expiresAt = now`, so it is not universally a \"time to reach the bank\".\n", "type": "text/plain" }, "url": { "path": [ "v1", "connections" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": { "content": "Name of the partner application the end user is connecting from. Analytics metadata only — attached to the resulting connection's tracking events; omitting it has no functional effect.\n", "type": "text/plain" }, "key": "X-Application-Name", "value": "" }, { "disabled": true, "description": { "content": "Version of the partner application. Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-App-Version", "value": "" }, { "disabled": true, "description": { "content": "Operating-system version of the end user's device. Analytics metadata only. Note the header spelling — `OSVersion` without a hyphen.\n", "type": "text/plain" }, "key": "X-Client-OSVersion", "value": "" }, { "disabled": true, "description": { "content": "Platform of the end user's device (e.g. `iOS`, `Android`, `Web`). Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-Platform", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"providerId\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\",\n \"ownershipType\": \"Personal\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "ce53daba-f43c-47a1-9fc3-893a6c4a3ebc", "name": "Connection initialized; redirect the user to `redirectUrl`.", "originalRequest": { "url": { "path": [ "v1", "connections" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": { "content": "Name of the partner application the end user is connecting from. Analytics metadata only — attached to the resulting connection's tracking events; omitting it has no functional effect.\n", "type": "text/plain" }, "key": "X-Application-Name", "value": "" }, { "disabled": true, "description": { "content": "Version of the partner application. Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-App-Version", "value": "" }, { "disabled": true, "description": { "content": "Operating-system version of the end user's device. Analytics metadata only. Note the header spelling — `OSVersion` without a hyphen.\n", "type": "text/plain" }, "key": "X-Client-OSVersion", "value": "" }, { "disabled": true, "description": { "content": "Platform of the end user's device (e.g. `iOS`, `Android`, `Web`). Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-Platform", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"providerId\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\",\n \"ownershipType\": \"Personal\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "Idempotent-Replayed", "value": "" } ], "body": "{\n \"connectionId\": \"\",\n \"redirectUrl\": \"\",\n \"expiresAt\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "62c0b8f2-3e8a-409b-92e7-69aac16473f2", "name": "Invalid request — malformed body, missing required fields, or missing/malformed headers.", "originalRequest": { "url": { "path": [ "v1", "connections" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": { "content": "Name of the partner application the end user is connecting from. Analytics metadata only — attached to the resulting connection's tracking events; omitting it has no functional effect.\n", "type": "text/plain" }, "key": "X-Application-Name", "value": "" }, { "disabled": true, "description": { "content": "Version of the partner application. Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-App-Version", "value": "" }, { "disabled": true, "description": { "content": "Operating-system version of the end user's device. Analytics metadata only. Note the header spelling — `OSVersion` without a hyphen.\n", "type": "text/plain" }, "key": "X-Client-OSVersion", "value": "" }, { "disabled": true, "description": { "content": "Platform of the end user's device (e.g. `iOS`, `Android`, `Web`). Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-Platform", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"providerId\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\",\n \"ownershipType\": \"Personal\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "3e533ba8-652e-4a73-b6e6-80debfbee712", "name": "Invalid or missing X-Api-Key, or API access blocked because the spending cap was reached. Raise the cap or settle payment in the partner portal.", "originalRequest": { "url": { "path": [ "v1", "connections" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": { "content": "Name of the partner application the end user is connecting from. Analytics metadata only — attached to the resulting connection's tracking events; omitting it has no functional effect.\n", "type": "text/plain" }, "key": "X-Application-Name", "value": "" }, { "disabled": true, "description": { "content": "Version of the partner application. Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-App-Version", "value": "" }, { "disabled": true, "description": { "content": "Operating-system version of the end user's device. Analytics metadata only. Note the header spelling — `OSVersion` without a hyphen.\n", "type": "text/plain" }, "key": "X-Client-OSVersion", "value": "" }, { "disabled": true, "description": { "content": "Platform of the end user's device (e.g. `iOS`, `Android`, `Web`). Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-Platform", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"providerId\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\",\n \"ownershipType\": \"Personal\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "0ccc8502-5ac8-479b-9eb1-1f82c293fab2", "name": "`pilot_provider_not_allowed` - the provider is not reachable with a sandbox key: sandbox keys reach sandbox providers (`*_xf`); use a live key for the real bank catalog. `sandbox_provider_not_allowed` - the provider is a sandbox provider (`*_xf`), which a live key never reaches; use a sandbox key to test against it. `application_not_active` - the application is not activated, so it cannot open bank connections.", "originalRequest": { "url": { "path": [ "v1", "connections" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": { "content": "Name of the partner application the end user is connecting from. Analytics metadata only — attached to the resulting connection's tracking events; omitting it has no functional effect.\n", "type": "text/plain" }, "key": "X-Application-Name", "value": "" }, { "disabled": true, "description": { "content": "Version of the partner application. Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-App-Version", "value": "" }, { "disabled": true, "description": { "content": "Operating-system version of the end user's device. Analytics metadata only. Note the header spelling — `OSVersion` without a hyphen.\n", "type": "text/plain" }, "key": "X-Client-OSVersion", "value": "" }, { "disabled": true, "description": { "content": "Platform of the end user's device (e.g. `iOS`, `Android`, `Web`). Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-Platform", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"providerId\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\",\n \"ownershipType\": \"Personal\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "18c9c074-33a0-4f97-a46f-e55438845544", "name": "`pilot_connection_cap_reached` - the cap on concurrently active real-bank connections made with sandbox keys is full. Revoke one of those connections or use a live key. `idempotency_key_in_use` - the first request with this `Idempotency-Key` is still in flight. Wait for it to answer, then retry; the retry replays its response.", "originalRequest": { "url": { "path": [ "v1", "connections" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": { "content": "Name of the partner application the end user is connecting from. Analytics metadata only — attached to the resulting connection's tracking events; omitting it has no functional effect.\n", "type": "text/plain" }, "key": "X-Application-Name", "value": "" }, { "disabled": true, "description": { "content": "Version of the partner application. Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-App-Version", "value": "" }, { "disabled": true, "description": { "content": "Operating-system version of the end user's device. Analytics metadata only. Note the header spelling — `OSVersion` without a hyphen.\n", "type": "text/plain" }, "key": "X-Client-OSVersion", "value": "" }, { "disabled": true, "description": { "content": "Platform of the end user's device (e.g. `iOS`, `Android`, `Web`). Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-Platform", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"providerId\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\",\n \"ownershipType\": \"Personal\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6bf04fbb-d329-4db0-a5da-0b239d7e0fb2", "name": "`idempotency_key_reused` - the `Idempotency-Key` was replayed with a different request body or a different `X-Client-Id`. Reuse a key only to retry the identical request; send a fresh key for a new one.", "originalRequest": { "url": { "path": [ "v1", "connections" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": { "content": "Name of the partner application the end user is connecting from. Analytics metadata only — attached to the resulting connection's tracking events; omitting it has no functional effect.\n", "type": "text/plain" }, "key": "X-Application-Name", "value": "" }, { "disabled": true, "description": { "content": "Version of the partner application. Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-App-Version", "value": "" }, { "disabled": true, "description": { "content": "Operating-system version of the end user's device. Analytics metadata only. Note the header spelling — `OSVersion` without a hyphen.\n", "type": "text/plain" }, "key": "X-Client-OSVersion", "value": "" }, { "disabled": true, "description": { "content": "Platform of the end user's device (e.g. `iOS`, `Android`, `Web`). Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-Platform", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"providerId\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\",\n \"ownershipType\": \"Personal\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c3627582-9f77-45fd-a788-085e59fcf54b", "name": "Rate limit exceeded. Retry with exponential backoff and honor Retry-After.", "originalRequest": { "url": { "path": [ "v1", "connections" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": { "content": "Name of the partner application the end user is connecting from. Analytics metadata only — attached to the resulting connection's tracking events; omitting it has no functional effect.\n", "type": "text/plain" }, "key": "X-Application-Name", "value": "" }, { "disabled": true, "description": { "content": "Version of the partner application. Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-App-Version", "value": "" }, { "disabled": true, "description": { "content": "Operating-system version of the end user's device. Analytics metadata only. Note the header spelling — `OSVersion` without a hyphen.\n", "type": "text/plain" }, "key": "X-Client-OSVersion", "value": "" }, { "disabled": true, "description": { "content": "Platform of the end user's device (e.g. `iOS`, `Android`, `Web`). Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-Platform", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"providerId\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\",\n \"ownershipType\": \"Personal\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c36629a9-1782-4b04-a4fd-b8c9bf0d7f0e", "name": "Connection service temporarily unavailable.", "originalRequest": { "url": { "path": [ "v1", "connections" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": { "content": "Name of the partner application the end user is connecting from. Analytics metadata only — attached to the resulting connection's tracking events; omitting it has no functional effect.\n", "type": "text/plain" }, "key": "X-Application-Name", "value": "" }, { "disabled": true, "description": { "content": "Version of the partner application. Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-App-Version", "value": "" }, { "disabled": true, "description": { "content": "Operating-system version of the end user's device. Analytics metadata only. Note the header spelling — `OSVersion` without a hyphen.\n", "type": "text/plain" }, "key": "X-Client-OSVersion", "value": "" }, { "disabled": true, "description": { "content": "Platform of the end user's device (e.g. `iOS`, `Android`, `Web`). Analytics metadata only.", "type": "text/plain" }, "key": "X-Client-Platform", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"providerId\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\",\n \"ownershipType\": \"Personal\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Service Unavailable", "code": 503, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "3d635ca3-a6da-48a6-b8e2-79287fbeb7bc", "name": "Delete connection", "request": { "name": "Delete connection", "description": {}, "url": { "path": [ "v1", "connections", ":connectionId" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "connectionId", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "body": {}, "auth": null }, "response": [ { "id": "20046816-34ed-42d3-b2cf-c5986c97e380", "name": "Connection deleted. A `ConnectionDeleted` webhook follows.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" } ], "method": "DELETE", "body": {} }, "status": "OK", "code": 200, "header": [ { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "cookie": [], "_postman_previewlanguage": "text" }, { "id": "8ccd03e7-b0b2-4477-a935-b4ddf8ff7b46", "name": "Invalid request — malformed body, missing required fields, or missing/malformed headers.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "24fa37f0-b6ce-440d-a5cb-16f9c0ef9d37", "name": "Invalid or missing X-Api-Key, or API access blocked because the spending cap was reached. Raise the cap or settle payment in the partner portal.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a341e8c6-1eb0-42f2-9cf2-459c17eeba7f", "name": "Resource not found.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "043ec960-d255-4740-8c78-c28cf2ae1e41", "name": "Rate limit exceeded. Retry with exponential backoff and honor Retry-After.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "DELETE", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "fb84cc58-4fee-4bfd-806f-58a4beedf581", "name": "Refresh connection (capability-gated)", "request": { "name": "Refresh connection (capability-gated)", "description": { "content": "Fetches new transactions for an existing `Active` connection in the background. **Refresh never redirects the user** — if the bank requires re-authentication, the refresh fails, the connection becomes `Inactive`, and the recovery path is `reconnect`. Completion is signalled by `ConnectionRefreshSuccess` / `ConnectionRefreshFailed` webhooks (`TransactionsFetching*` progress events are reused; `AccountsFetching*` are not sent on refresh). Guards: concurrent call → `refresh_in_progress`; 10-minute cooldown after a successful manual refresh and per-provider daily quotas → `refresh_cooldown` / `refresh_quota_exceeded` with `nextRefreshPossibleAt`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "connections", ":connectionId", "refresh" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "connectionId", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"locale\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "6ec7288a-e82d-4a94-a7b9-fb93683587f2", "name": "Refresh accepted and running in the background.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "refresh" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"locale\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Accepted", "code": 202, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"status\": \"Accepted\",\n \"nextRefreshPossibleAt\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "57abe96e-caa4-41cc-b2d8-08f7e054edb9", "name": "Guard rejection - `refresh_in_progress`, `refresh_cooldown`, or `refresh_quota_exceeded`. `refresh_cooldown` (the 10-minute wait after a manual refresh) and `refresh_quota_exceeded` (the per-provider daily allowance) are resolved separately at the rejection, and both carry `nextRefreshPossibleAt`.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "refresh" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"locale\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "cb72e475-8b97-4b29-b44a-071004b38bec", "name": "Invalid or missing X-Api-Key, or API access blocked because the spending cap was reached. Raise the cap or settle payment in the partner portal.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "refresh" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"locale\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8e9ce025-6753-4d63-b7d0-970b1e7c0e7e", "name": "`capability_disabled` (refresh not enabled for this partner), `operation_temporarily_unavailable` (the operation is temporarily not allowed for this connection; retry later), or `consent_inactive` (consent revoked/expired — reconnect required).", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "refresh" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"locale\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "9681bb5a-1c7c-49ba-a804-8eff84d582b3", "name": "Resource not found.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "refresh" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"locale\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "87a2ac98-4ee2-42df-832b-1198f4906425", "name": "`background_refresh_not_allowed` — the bank rejects unattended (background) access. **Side effects:** the connection is inactivated and the partner also receives an asynchronous `ConnectionConsentRevoked`/`ConnectionConsentExpired` webhook. Recovery is `reconnect`. (Today's raw body carries no machine signal; the `error.code` is synthesized in v1.1.)", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "refresh" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"locale\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Not Acceptable", "code": 406, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ff8636ed-51a9-4b5d-a924-cf875259a66e", "name": "Rate limit exceeded. Retry with exponential backoff and honor Retry-After.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "refresh" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"locale\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "fa26101e-778f-45b0-95a5-8c9c4c37d142", "name": "Reconnect connection (capability-gated)", "request": { "name": "Reconnect connection (capability-gated)", "description": { "content": "Renews consent for an `Inactive` connection via a new bank authorization. Always redirects the user — behaves like create but keeps the same `connectionId`. Rejected for `Disabled` connections (`connection_not_recoverable`). For the hosted flow, create a connect session with `connectionId` instead of calling this endpoint: the user then gets the same hosted screens (including the account picker) as on a create.\n", "type": "text/plain" }, "url": { "path": [ "v1", "connections", ":connectionId", "reconnect" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "connectionId", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } }, "auth": null }, "response": [ { "id": "0be69c88-42f4-467b-8f71-f755b14c119e", "name": "Reconnect initialized; redirect the user to `redirectUrl`.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "reconnect" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "Idempotent-Replayed", "value": "" } ], "body": "{\n \"connectionId\": \"\",\n \"redirectUrl\": \"\",\n \"expiresAt\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7029c600-80f1-4390-9b1a-e5a9e258a7d0", "name": "Invalid request, or connection is `Disabled` (`connection_not_recoverable`).", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "reconnect" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "56d46e17-3dc5-49f9-bd67-e4021cc705cf", "name": "Invalid or missing X-Api-Key, or API access blocked because the spending cap was reached. Raise the cap or settle payment in the partner portal.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "reconnect" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "4f75dbd2-3ded-4c1c-b47e-2be0ecfe3aa1", "name": "`capability_disabled` — reconnect not enabled for this partner. `sandbox_provider_not_allowed` - the reconnect would migrate the connection to a sandbox provider (`*_xf`), which a live key never reaches. `application_not_active` - the application is not activated, so it cannot open bank connections.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "reconnect" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "e461a7b5-b380-404d-99ff-0497f9c5444f", "name": "Resource not found.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "reconnect" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "a1f70c16-6ce5-4c20-aca9-85e5bd500893", "name": "`idempotency_key_in_use` - the first request with this `Idempotency-Key` is still in flight. Wait for it to answer, then retry; the retry replays its response.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "reconnect" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "7f36d29b-f9f1-4f10-a004-77704b0ea2b8", "name": "`idempotency_key_reused` - the `Idempotency-Key` was replayed with a different request body or a different `X-Client-Id`. Reuse a key only to retry the identical request; send a fresh key for a new one.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "reconnect" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "95c68df7-5212-407b-9954-471739eaffb7", "name": "Rate limit exceeded. Retry with exponential backoff and honor Retry-After.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "reconnect" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "disabled": true, "description": { "content": "Unique key (UUID recommended) making the request idempotent for 24 hours, scoped per partner. A replay with the same key returns the original response.\n", "type": "text/plain" }, "key": "Idempotency-Key", "value": "" }, { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"returnUrl\": \"\",\n \"locale\": \"en\",\n \"subscribeToAllAccounts\": \"\",\n \"skipConsentScreen\": \"\"\n}", "options": { "raw": { "headerFamily": "json", "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "cc1458cf-0914-400a-9b43-2b1420972ce8", "name": "Revoke consent", "request": { "name": "Revoke consent", "description": { "content": "Revokes consent for the connection; the connection becomes `Inactive`. BudgetBakers also auto-revokes after successful data retrieval for one-shot partners (`autoRevokeAfterCreate`). **Idempotent:** revoking an already-`Inactive` connection succeeds with 200 and no callback (no-op). It keys off the connection status, not consent, so there is no `403 consent_inactive` here.\n", "type": "text/plain" }, "url": { "path": [ "v1", "connections", ":connectionId", "revoke" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "type": "any", "value": "", "key": "connectionId", "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" } } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "PATCH", "body": {}, "auth": null }, "response": [ { "id": "46d237db-2163-4f15-92c6-8e5d9c1ed5fe", "name": "Consent revoked (or already revoked — idempotent no-op).", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "revoke" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" } ], "method": "PATCH", "body": {} }, "status": "OK", "code": 200, "header": [ { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "cookie": [], "_postman_previewlanguage": "text" }, { "id": "2b75542b-2e27-401a-971f-f93fb4d3125d", "name": "The connection is `Disabled` (consent never obtained), which cannot be revoked (`connection_not_recoverable`), or the request is invalid.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "revoke" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "PATCH", "body": {} }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "abae6575-a6fa-42c1-8686-e0b04713f4ff", "name": "Invalid or missing X-Api-Key, or API access blocked because the spending cap was reached. Raise the cap or settle payment in the partner portal.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "revoke" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "PATCH", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "1d9c7542-2711-49c3-8686-f5602703326e", "name": "Resource not found.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "revoke" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "PATCH", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "27b05cb0-5e4c-484e-a405-ebc829da4ad9", "name": "Rate limit exceeded. Retry with exponential backoff and honor Retry-After.", "originalRequest": { "url": { "path": [ "v1", "connections", ":connectionId", "revoke" ], "host": [ "{{PARTNER_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "description": { "content": "(Required) ", "type": "text/plain" }, "type": "any", "value": "", "key": "connectionId" } ] }, "header": [ { "disabled": false, "description": { "content": "(Required) Client ID obtained from `POST /v1/clients`. Required on all client-scoped endpoints.", "type": "text/plain" }, "key": "X-Client-Id", "value": "" }, { "key": "Accept", "value": "application/json" } ], "method": "PATCH", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "key": "Content-Type", "value": "application/json" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "X-Request-Id", "value": "" }, { "disabled": true, "description": { "content": "", "type": "text/plain" }, "key": "Retry-After", "value": "" } ], "body": "{\n \"error\": {\n \"code\": \"idempotency_key_reused\",\n \"message\": \"\",\n \"nextRefreshPossibleAt\": \"\"\n },\n \"requestId\": \"\",\n \"errorDesc\": \"\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ] } ], "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-Api-Key", "type": "string" }, { "key": "value", "value": "{{BB_API_KEY}}", "type": "string" }, { "key": "in", "value": "header", "type": "string" } ] }, "event": [], "variable": [ { "key": "PARTNER_API_URL", "value": "https://aisp-partner.bbapi.io" } ], "info": { "_postman_id": "4b775f29-93bb-4fde-a223-6ddefc67530f", "name": "BudgetBakers Partner AISP API v1.1 lifecycle actions", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": { "content": "AISP API for contracted partners: create a client, connect to a bank (directly\nor via the hosted connect flow), retrieve accounts and transactions, refresh or\nreconnect (capability-gated), and revoke consent.\n\nThis version is current for the connection lifecycle actions - create,\nrefresh, reconnect, revoke and delete - which exist only on `/v1`. Connect\nsessions, partner config, providers, clients and all reads have their home on\n`/v2` (see the Partner API v2 reference); the `/v1` connect-session and\npartner-config paths are transitional aliases.\n\nSandbox and live mode are selected by the API key prefix (`bb_test_…` /\n`bb_live_…`), never by the host. Guides:\nhttps://aisp-docs.bbapi.io/guide/getting-started\n\nThe contract evolves additively: new endpoints, optional fields, envelope\nfields and enum values may be added without notice, and clients must ignore\nwhat they do not recognize.\n\n## Versioning\nVersioning is selective and applied **per path** — the `/v1/` segment belongs to\neach individual path, not to the base URL. Individual endpoints may advance to\n`/v2/` independently; do not hardcode `/v1/` as a shared client-side prefix.\n\n## Authentication\nEvery request requires `X-Api-Key`. Client-scoped endpoints additionally require\nthe `X-Client-Id` header. Production traffic passes our API gateway with\nper-partner rate limits; optional enterprise hardening (mTLS, IP allowlisting)\nis configured at the infrastructure level, not in this API.\n\n## Errors (v1.1)\nEvery error response carries a stable machine-readable `error.code` (see the\n`ErrorCode` schema) alongside an informational `errorDesc` string. Clients and\nSDKs MUST branch on `error.code` only and MUST NOT parse `errorDesc`. Every\nresponse includes an `X-Request-Id` correlation header. `401` and `429` are\nproduced by the API gateway and may not carry the full envelope.\n\n## Idempotency (v1.1)\n`POST /v1/connections`, `POST /v1/connections/{connectionId}/reconnect` and\n`POST /v1/connect-sessions` accept an `Idempotency-Key` header (24 h window,\nscoped per partner): a replay with the same key returns the original\nresponse. They differ on a key replayed with a *different* request.\n`POST /v1/connections` and\n`POST /v1/connections/{connectionId}/reconnect` fingerprint the request body\nand `X-Client-Id` and answer `422 idempotency_key_reused` when either differs,\nso one key can never stand for two different connections. Their replays\ncarry `Idempotent-Replayed: true`; a first-time response never has the\nheader. While the first request with a key is still in flight, a second\nrequest with the same key is refused with `409 idempotency_key_in_use`\nrather than run twice - retry it after the first one has answered, and it\nreplays. `POST /v1/connect-sessions` does not fingerprint: it returns the\noriginal session whatever the body says. `POST /v1/clients` supports upsert\nsemantics via `externalId`.\n\n## Webhooks\nConnection lifecycle events are delivered as HTTP callbacks — see the companion\nWebhooks v2 reference.\n\n\nContact Support:\n Email: integration@budgetbakers.com", "type": "text/plain" } } }