Bancolombia My Accounts

Bancolombia is Colombia’s largest bank. A customer’s Sucursal Virtual Personas holds their accounts, balances and movements. These endpoints read that online banking as the customer’s own connection.

Connect your account

Bancolombia answers only to a signed-in customer: their Sucursal Virtual Personas username and password. Each query runs as your organization’s own connection, so register one before your first query. Register the account once; Croma signs in for each query and never stores the credentials in the clear. POST /co/bancolombia/connections/v1 Register a connection once. Croma checks it with the source before saving it, and answers with its id and a masked name.

Field	Type	Notes
`username`	string	Required. The username (usuario) of that Bancolombia Sucursal Virtual Personas account.
`password`	string	Required. The password (clave) of that Bancolombia account.
`authorized`	boolean	Required. `true`: you confirm you are the account’s owner or have the owner’s authorization to use it.

curl https://api.croma.run/co/bancolombia/connections/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "username": "your-username",
        "password": "your-password",
        "authorized": true
      }'

{
  "data": {
    "id": "conn_2f8Kq1xVb7Lm0Pz9Rt4Wc3",
    "source": "bancolombia",
    "status": "active",
    "display_name": "J*** P*** G***",
    "usage": {
      "sign_ins_today": 1,
      "daily_limit": null,
      "resets_at": "2026-10-01T05:00:00.000Z"
    },
    "available_again_at": null,
    "created_at": "2026-09-30T20:00:00.000Z",
    "last_used_at": "2026-09-30T20:00:00.000Z"
  }
}

Every query then runs as one of your organization’s connections. Croma picks one, keeps its session open between queries, and moves to the next when one reaches its daily allowance. Register more than one to get more capacity a day. To run as a specific one, send its id as connection_id. How the flow works, step by step: Connections. List and delete them:

curl https://api.croma.run/co/bancolombia/connections/v1 -H "Authorization: Bearer $CROMA_API_KEY"
curl -X DELETE https://api.croma.run/co/bancolombia/connections/v1/conn_2f8Kq1xVb7Lm0Pz9Rt4Wc3 -H "Authorization: Bearer $CROMA_API_KEY"

Over MCP, the same verbs are the bancolombia_connect, bancolombia_list_connections, bancolombia_delete_connection tools. Connecting from an agent never passes the credentials through the conversation: the agent gets a secure link, and the user enters the account’s details in the Croma console. When a query cannot run as any connection:

Status	Code	Meaning
409	`connection_required`	The organization has no connection for this source yet.
422	`connection_rejected`	The source no longer accepts the connection’s credentials.
429	`connections_exhausted`	Every connection used its daily allowance. `Retry-After` says when one is available again.
409	`connection_exists`	The same account is already connected (on register).
422	`connection_limit_reached`	The organization already has 5 connections for this source (on register).

Credentials are encrypted as soon as they reach Croma, bound to your organization, and can only be opened by the isolated service that signs in to the source on your behalf. They are never returned by the API or shown to anyone. Deleting a connection destroys it permanently.

Accounts

POST /co/bancolombia/accounts/v1

Field	Type	Notes
`connection_id`	string	The connection to run as. Each Bancolombia connection reads its own account, so with more than one in your organization it is required; without it the call answers `409 connection_id_required`.

curl https://api.croma.run/co/bancolombia/accounts/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

Field	Notes
`count`	Number of accounts returned.
`accounts[]`	One per account (below).

Each account has its number, name and custom_name (the nickname the customer set), its type (savings, checking, credit_card or other) and type_raw (the bank’s own label), currency, status, plan_name, the three balances available_balance, current_balance and effective_balance, the allow_credit and allow_debit flags, holder_relation, joint_holder, opening_date and its office.

{
  "data": {
    "count": 1,
    "accounts": [
      {
        "number": "12345678901",
        "name": "JUAN PEREZ",
        "custom_name": "Mi ahorro",
        "type": "savings",
        "type_raw": "CUENTA_DE_AHORRO",
        "currency": "COP",
        "status": "ACTIVO",
        "plan_name": "PLAN PREMIUM",
        "available_balance": 4200000,
        "current_balance": 4200000,
        "effective_balance": 4200000,
        "allow_credit": true,
        "allow_debit": true,
        "holder_relation": "TITULAR",
        "joint_holder": false,
        "opening_date": "2020-01-15",
        "office": { "code": "698", "name": "CALLE 79" }
      }
    ]
  }
}

Every call reads Bancolombia live as your connection, so the answer is current and is never shared between organizations.

This lookup can take longer than a typical request. It is an async job. By default the request waits inline and returns { data }, or you can poll / use a callback_url.

Movements

POST /co/bancolombia/transactions/v1

Field	Type	Notes
`account_number`	string	Required. The account to read movements for, its number as it appears in the accounts list.
`date_from`	string	Required. First day of the window, inclusive, `yyyy-mm-dd`.
`date_to`	string	Required. Last day of the window, inclusive, `yyyy-mm-dd`.
`connection_id`	string	The connection to run as. Each Bancolombia connection reads its own account, so with more than one in your organization it is required; without it the call answers `409 connection_id_required`.

curl https://api.croma.run/co/bancolombia/transactions/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "account_number": "12345678901",
        "date_from": "2026-01-01",
        "date_to": "2026-03-31"
      }'

Response

Field	Notes
`account_number`	Echoes the account.
`from`, `to`	Echo the window, `yyyy-mm-dd`.
`count`	Number of movements returned.
`transactions[]`	One per movement (below).

Each movement has its date, description, amount (with the sign Bancolombia reports), movement_type (Bancolombia’s own label), reference and its office.

{
  "data": {
    "account_number": "12345678901",
    "from": "2026-01-01",
    "to": "2026-03-31",
    "count": 1,
    "transactions": [
      {
        "date": "2026-02-10",
        "description": "COMPRA ALMACENES EXITO",
        "amount": -120000,
        "movement_type": "DEBITO",
        "reference": "9912",
        "office": { "code": null, "name": "CALLE 79" }
      }
    ]
  }
}

Every call reads Bancolombia live as your connection, so the answer is current and is never shared between organizations.

This lookup can take longer than a typical request. It is an async job. By default the request waits inline and returns { data }, or you can poll / use a callback_url.

Full reference

Schemas, all response fields, and an interactive playground.

Get Started

Request types

Monitors

Countries

Bancolombia My Accounts

Connect your account

Accounts

Response

Movements

Response

Full reference

​Connect your account

​Accounts

​Response

​Movements

​Response

Full reference

Connect your account

Accounts

Response

Movements

Response