Skip to content
Tovari Docs

Delete (deactivate) a payee

DELETE
/payees/{id}
curl --request DELETE \
  --url 'https://api.tovarifinancial.com/payees/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0?confirm=1' \
  --header 'Authorization: Bearer <token>'

Soft-deletes the payee and releases every reference to it: bills detach (name preserved), learned payee_mappings are deleted, matching rules (payee_rules) are deleted, staged import resolutions are nulled. When bills reference the payee the call returns 409 with the blocker list unless ?confirm=1 is supplied; the gate fails closed on any other value (true, yes, …).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

Payee id

Query Parameters

Section titled “Query Parameters”
confirm
string
Allowed values: 1

Set to ‘1’ to confirm unlinking bills

Header Parameters

Section titled “Header Parameters”
X-Idempotency-Key
string

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.

Responses

Section titled “Responses”

200

Section titled “200”

Deactivated + references released

Media typeapplication/json
object
data
required
object
id
required
string format: uuid
deactivated
required

Soft delete — the payee row is preserved so history keeps resolving.

boolean
detachedBillCount
required

Bills whose payee_id was set NULL (name preserved).

integer
releasedMappingCount
required

Learned payee_mappings rows deleted.

integer
releasedStagedRowCount
required

Staged import rows whose resolved_payee_id was nulled.

integer
releasedRuleCount
required

Payee_rules rows deleted (all rules on this explicit, confirm-gated delete).

integer
message
string
requestId
required
string
timestamp
required
string format: date-time
Example
{
  "data": {
    "deactivated": true
  }
}

401

Section titled “401”

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 ORG_NAME_TAKEN 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"
}

403

Section titled “403”

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.

Media typeapplication/json
object
errorCode
required

Which precondition refused the request. Evaluated in this order (CCR-1); SUBSCRIPTION_REQUIRED is unreachable while BILLING_ENABLED is not exactly true.

string
Allowed values: EMAIL_NOT_VERIFIED POLICY_ACCEPTANCE_REQUIRED SUBSCRIPTION_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"
}

404

Section titled “404”

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 ORG_NAME_TAKEN 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"
}

409

Section titled “409”

Bills reference this payee and ?confirm=1 was not supplied. Nothing was written.

Media typeapplication/json
object
errorCode
required

Reuses VALIDATION_ERROR — there is no dedicated needs-confirmation code.

string
Allowed values: VALIDATION_ERROR
message
required
string
details
required
object
billCount
required

Exact number of bills referencing the payee.

integer
bills
required

Sample of blocking bills, capped at 20, id + name ONLY (data minimization — no amounts, no account ids).

Array<object>
object
id
required
string format: uuid
name
required
string
requestId
required
string
timestamp
required
string format: date-time
Example
{
  "errorCode": "VALIDATION_ERROR"
}

500

Section titled “500”

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 ORG_NAME_TAKEN 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"
}

503

Section titled “503”

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 ORG_NAME_TAKEN 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"
}