Complete an update-mode Link session (reconcile, or a targeted attach)
const url = 'https://api.tovarifinancial.com/plaid/items/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/relink/complete';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"purpose":"reconcile"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.tovarifinancial.com/plaid/items/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/relink/complete \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "purpose": "reconcile" }'One route, three purposes, discriminated on the optional body field purpose.
THE IDEMPOTENCY CONTRACT IS SPLIT ACROSS THEM, deliberately.
- purpose absent or
reconcile: X-Idempotency-Key is OPTIONAL and IS honored, through the shared store under the operation namePOST /plaid/items/{id}/relink/complete— a distinct name from the bind phase below, so a key reused across the two purposes is a 409 IDEMPOTENCY_CONFLICT rather than a cross-purpose replay. A request with no key behaves exactly as before and touches the store not at all. A replayed delivery returns the recorded status and bytes, makes NO second Plaid call and enqueues NO second sync job. An absentpurposeand an explicitreconcilefingerprint identically, so frontend bundles cached across a deploy replay against fresh ones instead of conflicting. Only a fully successful delivery is recorded: if the re-auth succeeds but the account reconcile fails, the response is still 200 with an empty reconcile summary and the key is left usable so a retry re-runs the reconcile. No non-2xx outcome is ever recorded. - purpose
attach-target, phaseplan: strictly read-only (zero writes, no health check, no status repair) and takes NO idempotency key.item.statusis the STORED status, so a requires_reauth item legitimately plans as requires_reauth. An empty or all-unbindable candidate set is a legitimate 200. - purpose
attach-target, phasebind: X-Idempotency-Key is REQUIRED and IS honored through the shared store under the operation namePOST /plaid/items/{id}/relink/complete#attach-target— a replayed delivery returns the recorded bytes and makes no second Plaid call. It writes exactly ONE plaid_accounts row, on the EXISTING item; no plaid_items row is created anywhere on this path. For a non-active item it first verifies the connection via Plaid and repairs the stored status. 409 ACCOUNT_ALREADY_LINKED carries details.conflict oftarget(the local account already has a live linkage) orplaid-account(the chosen Plaid account already feeds a different local account, with details.accountId naming it). BOTH conflicts are also detected inside the bind transaction, not only by the pre-checks, so a concurrent duplicate delivery gets the same 409 rather than a 500: a unique violation on idx_plaid_accounts_active_uniq maps to details.conflicttarget, and a zero-row RETURNING from the guarded insert (the (item, Plaid account) row already exists and is live) maps to details.conflictplaid-accountwith details.accountId naming the local account that holds it. 404 covers an unknown item, an unknown or inactive target account, and a plaidAccountId the institution no longer shares. A request body that is present but is not valid JSON is a 400 VALIDATION_ERROR; only an absent or empty body defaults to the reconcile purpose.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Plaid item id
Header Parameters
Section titled “Header Parameters”Optional idempotency key for safe write retries. Every operation that declares this header reads it. Two cases, told apart per operation: (1) where the operation also documents a 409, replaying this key with a different payload returns 409 IDEMPOTENCY_CONFLICT and replaying it with the same payload returns the original response; (2) where it documents no 409, a replay is reconciled optimistically against a unique key column and answers the original 200.
Request Body
Section titled “Request Body”Responses
Section titled “Responses”Reconcile summary, attach-target plan, or attach-target bind result
object
object
object
object
object
object
object
Why the candidate is not bindable. An OPEN set — today ‘already-linked-on-this-item’ or ‘already-linked-elsewhere’.
The LOCAL account id already fed by this Plaid account. Present only when reason is ‘already-linked-elsewhere’.
object
object
object
Calendar date, ‘YYYY-MM-DD’
Example
{ "data": { "item": { "status": "active" } }}Validation failed — see errorCode / fieldErrors
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Missing, invalid, or expired bearer token
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Authenticated, but the tenant gate refuses the request until the caller resolves a precondition. errorCode is one of EMAIL_NOT_VERIFIED, POLICY_ACCEPTANCE_REQUIRED, or SUBSCRIPTION_REQUIRED, evaluated in exactly that order (contract term CCR-1: email verification first, then policy acceptance, then subscription — so a subscriber who has merely not re-accepted the current policies always sees POLICY_ACCEPTANCE_REQUIRED). A POLICY_ACCEPTANCE_REQUIRED body additionally carries details.outstanding (the policy versions still to accept) and details.firstAcceptance. The SUBSCRIPTION_REQUIRED arm is INERT unless the server-side BILLING_ENABLED flag is exactly the string true; while it is off, only the first two codes are reachable. Not retryable as sent — resolve the named condition, then resend.
object
Which precondition refused the request. Evaluated in this order (CCR-1); SUBSCRIPTION_REQUIRED is unreachable while BILLING_ENABLED is not exactly true.
object
Active policy versions the user has not yet accepted.
object
True when the user has accepted no policy before — the client renders the new-signup screen rather than the re-acceptance one.
Example
{ "errorCode": "EMAIL_NOT_VERIFIED"}Resource not found or not owned by the caller org
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Conflict. errorCode is IDEMPOTENCY_CONFLICT when an X-Idempotency-Key was replayed with a different request payload; where the operation instead detects a resource-state conflict it carries that endpoint’s own errorCode (a duplicate name, an import that is no longer committable, an account already linked to a bank connection).
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Internal error (no internal detail leaked)
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Service temporarily unavailable — errorCode is SERVICE_UNAVAILABLE. A TRANSIENT, RETRYABLE condition rather than a defect in the request: a query that exceeded its time budget, a lost or refused database connection, a saturated connection pool, or an outage at an upstream provider the request depends on (the authentication provider, or the bank data provider on a bank-connection operation). The identical request may succeed on retry — back off briefly and, on a write, resend the same X-Idempotency-Key where the operation accepts one.
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}