Merge Accounts
POST /api/v1/accounts/:id/merge
Merges another account (delete_account_id) into this one (:id, the account that is retained). This is destructive and irreversible:
- Unions the
identifier arrays of both accounts onto the retained account.
- Permanently deletes all transactions belonging to the losing account.
- Relinks the losing account's statements to the retained account.
- Re-queues processing (
read_file) for each relinked statement — this regenerates their transactions on the retained account from scratch.
- Permanently deletes the losing account.
Because of step 2, requires confirm: true in the body or the request is rejected before anything is touched.
Path Parameters
| Parameter | Type | Description |
|---|
| id | string | Account ID to retain |
Body Parameters
| Parameter | Type | Required | Description |
|---|
| delete_account_id | string | Yes | Account ID to merge away and delete |
| confirm | boolean | Yes | Must be true — acknowledges the transactions on delete_account_id will be permanently deleted |
Example Request
curl -X POST "https://statements.finopsbricks.com/api/v1/accounts/acc_retain/merge" \
-H "api-key: fob_stm_xxxxxxxxxxxx" \
-H "api-secret: xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"delete_account_id": "acc_delete",
"confirm": true
}'
Response
{
"data": {
"retained_account_id": "acc_retain",
"deleted_account_id": "acc_delete",
"transactions_deleted": 128,
"statements_requeued": 6,
"merged_identifiers": ["1234567890", "0987654321"]
}
}
Response Fields
| Field | Type | Description |
|---|
| retained_account_id | string | The account that survives (same as :id) |
| deleted_account_id | string | The account that was merged away and deleted |
| transactions_deleted | number | Transactions permanently deleted from the losing account |
| statements_requeued | number | Statements relinked to the retained account and re-queued for processing |
| merged_identifiers | string[] | The union of both accounts' identifier arrays, now on the retained account |
Errors
| Code | Description |
|---|
| 400 | delete_account_id missing, equal to :id, or confirm is not true |
| 401 | Invalid or missing API credentials |
| 403 | API key lacks accounts:delete permission |
| 404 | Either account not found |
400 Response (missing confirmation)
{
"error": {
"code": "CONFIRMATION_REQUIRED",
"message": "Set confirm: true to proceed — this permanently deletes the merged-away account's transactions and re-processes its statements."
}
}