Cowdidocs
API ReferencePayees

Get payees by id

POST
/v1/user/payees/batch

Get the caller's payees for a list of ids, in the order requested. The response omits any id that does not exist or does not belong to the caller. It never returns 404 for a missing id. Accepts 1 to 100 ids per request. Requires an authenticated, active user.

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

Request Body

application/json

Request to fetch several payees by id in one call

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/user/payees/batch" \  -H "Content-Type: application/json" \  -d '{    "ids": [      "550e8400-e29b-41d4-a716-446655440000"    ]  }'
{  "data": [    {      "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": "RATE_LIMIT_EXCEEDED",  "description": "Too Many Requests"}
{  "code": "INTERNAL_ERROR",  "description": "Internal Server Error"}

Create a payee POST

Create a payee with one initial account for the caller, verified inline against Confirmation of Payee. The required destination fields depend on `type` (`SEND_MONEY`, `POCHI`, `PAY_BILL`, `BUY_GOODS`, or `BANK_ACCOUNT`), and an unlinked destination needs an `account_holder_name`. Saving a destination the caller already has returns that existing payee instead of a duplicate. A partial or no name match, or a provider outage, returns 422 `PAYEE_ACCOUNT_CONFIRMATION_REQUIRED`. Resubmit with `confirm=true` to save the account anyway. Requires an authenticated, active user.

Look up contacts on Cowdi POST

Match the caller's address-book phone numbers against Cowdi users in the acting organization. Returns only the numbers that belong to a Cowdi user in that organization. Other numbers are omitted from the response. Requires an authenticated, active user.