API reference

The complete v1 reference: base URL, conventions, and every resource object. Each resource has its own page with request, response, and error details.

This reference documents every endpoint of the Caibo Global v1 API. Start with the conventions below, then jump to a resource. If you're new, read the guides first — the quickstart walks you through your first payout end to end.

Base URL

bash

https://api.caiboglobal.com/v1

All endpoints are relative to this URL and served over HTTPS only.

Authentication

Every endpoint except POST /organizations authenticates with an API key sent as X-API-Key (or Authorization: Bearer). Each endpoint also requires a specific scope, noted on its page.

bash

-H "X-API-Key: ck_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

Conventions

Money is strings. Amounts (e.g. amount) are decimal strings like "100.50".
Timestamps are ISO 8601 UTC, e.g. 2026-07-23T14:03:00Z.
IDs are prefixed: org_, po_, key_, whe_, kyb_.
Objects carry an object field naming their type (e.g. "payout").
Lists return { object: "list", data, has_more, next_cursor } — see Pagination.
Errors return { error: { type, code, message, param, request_id } } — see Errors.
Idempotency: POST /payouts requires an Idempotency-Key header — see Idempotency.

Endpoints

Method & path	Scope	Reference
`POST /payouts`	`payouts:write`	Payouts
`GET /payouts`	`payouts:read`	Payouts
`GET /payouts/{id}`	`payouts:read`	Payouts
`POST /payouts/{id}/cancel`	`payouts:write`	Payouts
`GET /balances`	`balances:read`	Balances & rates
`GET /rates`	`balances:read`	Balances & rates
`GET /countries`	`organization:read`	Catalog
`GET /payment-methods`	`organization:read`	Catalog
`POST /webhooks`	`webhooks:write`	Webhooks
`GET /webhooks`	`webhooks:read`	Webhooks
`DELETE /webhooks/{id}`	`webhooks:write`	Webhooks
`POST /api-keys`	`organization:write`	API keys
`GET /api-keys`	`organization:read`	API keys
`DELETE /api-keys/{id}`	`organization:write`	API keys
`GET /organization`	`organization:read`	Organization & KYB
`POST /organizations`	Firebase (no API key)	Organization & KYB
`POST /kyb`	`organization:write`	Organization & KYB
`GET /kyb`	`organization:read`	Organization & KYB

The objects

Payout

Field	Type	Description
`id`	string	Payout id, e.g. `po_9f8e7d6c5b4a`.
`object`	string	Always `"payout"`.
`status`	enum	`pending`, `screening`, `approved`, `processing`, `completed`, `failed`, `blocked`, `cancelled`, `pending_approval`. See Payout lifecycle.
`mode`	enum	`test` or `live`.
`amount`	string	Decimal amount, e.g. `"25.00"`.
`currency`	string	Asset: `USDC`, `USDT`, or `ETH`.
`rail`	string	Always `"stablecoin"`.
`destination`	object	`{ network, address }`.
`screening_status`	enum	`pending`, `clear`, or `blocked`.
`tx_hash`	string \| null	On-chain transaction hash once `completed`; otherwise `null`.
`failure_reason`	string	Present when `status` is `failed`.
`metadata`	object	Your key/value data, echoed back. Present if you set it.
`created_at`	string	ISO 8601 UTC.

Organization

Field	Type	Description
`id`	string	`org_...`
`object`	string	Always `"organization"`.
`legal_name`	string	Registered legal name.
`display_name`	string	Display name.
`country`	string	ISO-3166 alpha-2.
`status`	enum	`pending`, `active`, `suspended`, `closed`.
`kyb_status`	enum	`unverified`, `pending`, `verified`, `rejected`.
`created_at`	string	ISO 8601 UTC.

APIKey

Field	Type	Description
`id`	string	`key_...`
`object`	string	Always `"api_key"`.
`prefix`	string	Visible prefix, e.g. `ck_live_a1b2`.
`mode`	enum	`test` or `live`.
`name`	string \| null	Optional label.
`scopes`	string[]	Granted scopes.
`revoked`	boolean	Whether the key has been revoked.
`created_at`	string	ISO 8601 UTC.
`last_used_at`	string \| null	Last time the key authenticated a request.
`key`	string	The full secret. Returned only in the create response, once.

WebhookEndpoint

Field	Type	Description
`id`	string	`whe_...`
`object`	string	Always `"webhook_endpoint"`.
`url`	string	Your HTTPS endpoint.
`events`	string[]	Subscribed event names.
`active`	boolean	Whether deliveries are enabled.
`created_at`	string	ISO 8601 UTC.
`secret`	string	Signing secret (`whsec_...`). Returned only in the create response, once.

KybSubmission

Field	Type	Description
`id`	string	`kyb_...`
`object`	string	Always `"kyb_submission"`.
`org_id`	string	Owning organization.
`status`	enum	`pending`, `in_review`, `verified`, `rejected`.
`legal_name`	string	Legal name.
`registration_no`	string	Business registration number.
`incorporation_country`	string	ISO-3166 alpha-2.
`beneficial_owners`	object[]	Each `{ name, dob, ownership_pct, country }`.
`documents`	object[]	Each `{ type, reference }`.
`review_notes`	string	Present when `rejected`.
`created_at`	string	ISO 8601 UTC.
`reviewed_at`	string	Present once reviewed.