Skip to content

Start the statement-sharing consent step (create a consent Link token)

POST
/plaid/items/{id}/statement-consent
curl --request POST \
--url https://api.tovarifinancial.com/plaid/items/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/statement-consent \
--header 'Authorization: Bearer <token>'

KAN-4170. Mints an update-mode Plaid Link token that asks an EXISTING bank connection for Liabilities consent (additional_consented_products: ['liabilities'], no account selection), so a credit card linked before the consent ask can share statements without being removed and re-added. The repair token (POST /plaid/items/{id}/relink) is unchanged. Writes nothing; the request body is ignored and X-Idempotency-Key is not read (a duplicate only mints a second short-lived token). Every refusal comes before any Plaid call, in this order: 404 for a malformed id; the tenant gates; 409 STATEMENT_CONSENT_UNAVAILABLE with details.reason ‘flag_off’ when the consent ask is not armed in this environment; 403 CAPABILITY_REQUIRED without debt_planning; 404 for an unknown, unlinked or other household’s connection; 409 STATEMENT_CONSENT_UNAVAILABLE ‘no_credit_card’ when the connection holds no live credit card; 409 STATEMENT_CONSENT_UNAVAILABLE ‘not_enabled’ when the household has not turned statement details on; 409 STATEMENT_CONSENT_REAUTH_REQUIRED when the connection needs an ordinary reconnect first. A connection whose consent is already recorded answers { status: 'already_granted' } with no Plaid call. A Plaid refusal of the token is a 502 STATEMENT_CONSENT_REJECTED (the connection is untouched); a Plaid outage is a 503.

id
required
string format: uuid

Plaid item id

A consent Link token, or nothing to do

Media typeapplication/json
object
data
required
One of:
object
status
string
Allowed values: link
linkToken
string
expiration
string format: date-time
message
string
requestId
required
string
timestamp
required
string format: date-time
Example
{
"data": {
"status": "link"
}
}

Missing, invalid, or expired bearer token

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
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. This operation can ALSO answer 403 with errorCode CAPABILITY_REQUIRED and no details, a refusal by the HANDLER rather than by the tenant gate: the request needs the debt_planning capability (the Premier plan or Founder access) — turning statement details on (enabled: true; turning it off needs no capability), or (KAN-4134) saving a non-null card payment field on a bill (clearing the mode needs none) or reading the card payment preview. It fails closed: a capability read that errors is refused the same way. Nothing is written, nothing is queued and no idempotency record is kept. It does NOT depend on CAPABILITY_FENCE_ENABLED or BILLING_ENABLED. The errorCode enum on this operation’s response schema is the complete, machine-readable list.

Media typeapplication/json
object
errorCode
required

Which condition refused the request, evaluated in this order (CCR-1). SUBSCRIPTION_REQUIRED is unreachable while BILLING_ENABLED is not exactly true; CAPABILITY_REQUIRED is unreachable while CAPABILITY_FENCE_ENABLED is not exactly true. The two switches are independent, so CAPABILITY_REQUIRED is reachable with the subscription paywall off. CAPABILITY_REQUIRED carries no details.

string
Allowed values: EMAIL_NOT_VERIFIED POLICY_ACCEPTANCE_REQUIRED SUBSCRIPTION_REQUIRED CAPABILITY_REQUIRED
message
required
string
details
object
outstanding
required

Active policy versions the user has not yet accepted.

Array<object>
object
id
required
string format: uuid
policyType
required
string
version
required
integer
title
required
string
firstAcceptance
required

True when the user has accepted no policy before — the client renders the new-signup screen rather than the re-acceptance one.

boolean
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "EMAIL_NOT_VERIFIED"
}

Resource not found or not owned by the caller org

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
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).

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "INVALID_EMAIL_FORMAT"
}

Internal error (no internal detail leaked)

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
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.

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "INVALID_EMAIL_FORMAT"
}