Create or Connect an Account

This endpoint is the single entry point for registering any account on Cobre. The behavior is driven by the action field in the request body:

`action`	What it does	Provider family
`connect`	Links an existing account at a supported financial institution.	Bank providers (e.g. `pr_mex_072`, `pr_col_1007`)
`create`	Provisions a new Cobre Balance account in Mexico, Colombia, or globally.	Cobre Balance providers (`pr_*_cobre`, `pr_global_cobre`)

The provider_id you choose determines which metadata shape is required and which response object you receive.

Connectivity Status Lifecycle

Status	Meaning	`action=create`	`action=connect`
`connecting`	Cobre is provisioning or linking the account	Yes (initial state)	Yes (initial state)
`connected`	Account is active and operational	Yes	Yes
`disconnected`	The live bank connection was lost or unlinked	—	Yes
`failed`	Provisioning or connection attempt failed	Yes	Yes
`closed`	Account was closed via Close a Cobre Balance — `pr_mex_cobre3` only	Yes (`pr_mex_cobre3` only)	—

When to use `action = create`

Use this flow to spin up a Cobre Balance — a Cobre-native account that holds funds for a given currency and powers real-time payments, R2P, Bre-B, and cross-border money movements.

When to use `action = connect`

Use this flow to integrate an account you already hold at a partner bank. Cobre keeps the connection live, polls intra-day balances, ingests transactions, and (where supported) lets you push money out of the account.

For more information refer to detailed guides below

Managing Cobre Balances guide

Managing Connect Accounts guide

Account Providers

Common Mistakes

Mixing action and provider_id intent (connect vs create) for the target provider.

Sending a metadata shape that does not match geo/provider (mex vs col connect metadata).

Assuming all providers support the same account_type/fields.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location 'https://api.cobre.co/v1/accounts' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "provider_id": "pr_col_cobre", "action": "create", "tags": [ "This is a tag" ], "alias": "My first Cobre Balance Colombia" }'

{ "id": "acc_1212534tdfgs", "provider_id": "pr_mex_cobre3", "provider_name": "Cobre Balance Mexico 3", "connectivity": { "status": "connected", "description": "string" }, "alias": "My first Cobre account!", "metadata": { "available_services": [ "mm_push_from_account" ], "primary_account": "acc_2NDkMRjA1o" }, "account_number": "646180303700100016", "account_type": "clabe", "obtained_balance": 10000, "obtained_balance_at": "2024-07-05T11:21:34Z", "geo": "mex", "tags": [ "accounting" ], "currency": "mxn", "created_at": "2024-06-17T17:34:50Z", "updated_at": "2024-07-05T11:21:34Z" }

Create or Connect an Account

Connectivity Status Lifecycle

When to use `action = create`

When to use `action = connect`

Common Mistakes

Request

Responses

Create or Connect an Account

Connectivity Status Lifecycle#

When to use action = create#

When to use action = connect#

Common Mistakes#

Request

Responses

Connectivity Status Lifecycle

When to use `action = create`

When to use `action = connect`

Common Mistakes