Cowdidocs
API ReferencePayees

Combine two payees

POST
/v1/user/payees/{payeeId}/combine

Merge the source payee's accounts into the target payee named in the path, then delete the source payee. Both payees must belong to the caller. Any destination the target already has is skipped. Returns 400 when the source and target are the same payee. Requires an authenticated, active user. Returns 404 when the target or the source payee does not exist.

Authorization

oauth2
AuthorizationBearer <token>

Create a client with POST /v1/oauth/clients, then exchange its credentials for an access token. AUTHORIZATION_CODE clients act on behalf of a signed-in user and always use PKCE; CLIENT_CREDENTIALS clients act as themselves. A client may only be granted scopes its creator already holds — read the grantable list from GET /v1/oauth/clients/scopes.

In: header

Path Parameters

payeeId*string

Unique identifier of the payee that survives the combination.

Formatuuid

Request Body

application/json

Combine another payee into the payee named in the path. source_payee_id identifies the payee to merge in: its accounts move onto the path payee, and it is then deleted.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/user/payees/550e8400-e29b-41d4-a716-446655440000/combine" \  -H "Content-Type: application/json" \  -d '{    "source_payee_id": "550e8400-e29b-41d4-a716-446655440000"  }'
{  "id": "550e8400-e29b-41d4-a716-446655440000",  "label": "string",  "display_name": "string",  "is_favorite": false,  "is_blocked": false,  "block_reasons": [    "UNWANTED_PAYMENTS"  ],  "block_details": "string",  "is_cowdi_user": false,  "cowdi_user_id": "660e8400-e29b-41d4-a716-446655440111",  "cowdi_user_tag": "@johnd123456",  "accounts": [    {      "resource_id": "string",      "id": "660e8400-e29b-41d4-a716-446655440001",      "type": "SEND_MONEY",      "account_holder_name": "string",      "linked_user_id": "660e8400-e29b-41d4-a716-446655440111",      "linked_user_tag": "@johnd123456",      "mobile_number": "254712345678",      "transaction_count": 15,      "last_used_at": "2026-02-10T14:00:00Z",      "verification_status": "VERIFIED",      "verified_at": "2026-02-01T08:00:00Z",      "verification": {        "resolved_name": "John Doe",        "account_valid": true,        "requires_confirmation": false,        "message": "string"      }    }  ],  "created_at": "2026-01-15T10:30:00Z",  "updated_at": "2026-02-01T08:00:00Z",  "resource_id": "string"}
{  "code": "BAD_REQUEST",  "description": "Bad Request"}
{  "code": "UNAUTHORISED",  "description": "Unauthorised"}
{  "code": "FORBIDDEN",  "description": "Forbidden"}
{  "code": "BAD_REQUEST",  "description": "Invalid input"}
{  "code": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

Block a payee POST

Block one of the caller's payees so payments to its accounts are rejected. The request body is optional. When supplied, it records one or more `reasons` and a free-text `details` note. Requires an authenticated, active user. Returns 404 when the payee does not exist or does not belong to the caller.

Unblock a payee POST

Unblock one of the caller's payees so payments to its accounts proceed again. Clears any recorded block reasons and details. Requires an authenticated, active user. Returns 404 when the payee does not exist or does not belong to the caller.