> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecroma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contaduría CHIP

> Financial and budget reports of Colombian public entities: balances, budget execution and more, by entity, period and form, as each one reports them to the Contaduría General de la Nación through CHIP.

Every Colombian public entity (ministries, departments, municipalities, public
companies, hospitals, universities) reports its accounting and its budget to the
Contaduría General de la Nación through CHIP, the Consolidador de Hacienda e
Información Pública. Each report is a form for a period: the balance sheet accounts
with their opening balance, movements and closing balance; the budget's income and
expenditure as programmed and as executed; treasury, debt, royalties and more.

These endpoints return those reports as data: the entities that report, what each
one reported, and any one form with its whole account tree and amounts.

They also return the financial statements each entity files once a year, with
their notes: the document, its full text, and a search across the text of every one.

## Search entities

`POST /co/contaduria-chip/entities-search/v1` [Dataset](https://docs.usecroma.com/datasets.md)

Lists the entities that report to CHIP. Combine the filters.

| Field | Type | Notes |
| - | - | - |
| `query` | string | Optional. Words of the entity's name. Case and accents are ignored. |
| `entity_code` | string | Optional. A CHIP code, e.g. `210105001`: that one entity. |
| `tax_id` | string | Optional. NIT without its check digit, e.g. `890905211`. |
| `department` | string | Optional. Department, e.g. `ANTIOQUIA`. |
| `municipality` | string | Optional. Municipality, e.g. `MEDELLIN`. |
| `status` | enum | Optional. `active` or `inactive`. |
| `page` | integer | Optional. 1-based page. Default `1`. |
| `per_page` | integer | Optional. Results per page, 1-100. Default `20`. |

```bash theme={"dark"}
curl https://api.croma.run/co/contaduria-chip/entities-search/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "medellin", "department": "ANTIOQUIA" }'
```

Returns `as_of`, `query`, `total`, `page`, `per_page`, `total_pages`, `count` and `entities[]`: `entity_code`, `name`, `tax_id`, `tax_id_check_digit`, `address`, `phone`, `department`, `municipality`, `status`, `sector` and `nature`.

## Report index

`POST /co/contaduria-chip/report-index/v1` [Live](https://docs.usecroma.com/live-lookups.md)

Lists what an entity reported, one step at a time: categories, then periods, then forms.

| Field | Type | Notes |
| - | - | - |
| `entity_code` | string | **Required.** The entity's CHIP code, e.g. `210105001`. |
| `category_code` | string | Optional. A category code from `categories[]`, e.g. `K70`: also returns `periods[]`. |
| `period` | string | Optional, with `category_code`. A period from `periods[]`, e.g. `2026-07/2026-09`: also returns `forms[]`. |

```bash theme={"dark"}
curl https://api.croma.run/co/contaduria-chip/report-index/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entity_code": "210105001", "category_code": "K70" }'
```

Returns `found`, `entity`, `categories[]` (`category_code`, `name`, `retired`), `category_code`, `periods[]` (`period`, `label`, `start_date`, `end_date`), `period`, `forms[]` (`form_code`, `name`) and `checked_at`.

## Report

`POST /co/contaduria-chip/report/v1` [Live](https://docs.usecroma.com/live-lookups.md)

Returns one reported form with its rows.

| Field | Type | Notes |
| - | - | - |
| `entity_code` | string | **Required.** The entity's CHIP code, e.g. `210105001`. |
| `category_code` | string | **Required.** The category code, e.g. `K70`. |
| `period` | string | **Required.** First and last month of the period, `YYYY-MM/YYYY-MM`, e.g. `2026-07/2026-09`. |
| `form_code` | string | **Required.** The form's code, e.g. `168`. |
| `level` | integer,null | Optional. Depth of the tree to return: `1` is the top-level accounts only. Omit for every level. Default `null`. |
| `page` | integer | Optional. 1-based page of rows. Default `1`. |
| `per_page` | integer | Optional. Rows per page, 1-500. Default `100`. |

```bash theme={"dark"}
curl https://api.croma.run/co/contaduria-chip/report/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "entity_code": "210105001",
        "category_code": "K70",
        "period": "2026-07/2026-09",
        "form_code": "168",
        "level": 2
      }'
```

Returns `found`, `entity`, `category`, `form`, `period`, `scope`, `submission_number`, `received_at`, `columns[]`, `rows[]` with their paging (`total`, `page`, `per_page`, `total_pages`, `count`), `document_url`, `checked_at` and `served_from` (see below). `found` is `false`, never an error, when the entity has not reported that form for that period.

> [!NOTE]
>
> This read can take longer than a typical request. It's an
> [async job](https://docs.usecroma.com/async-jobs.md). By default the request waits inline and returns
> `{ data }`, or you can poll / use a `callback_url`. A report read recently
> answers at once: `served_from` says which, and `checked_at` when the
> source was last asked.

## Search financial statements

`POST /co/contaduria-chip/statements-search/v1` [Dataset](https://docs.usecroma.com/datasets.md)

Searches the full text of the financial statements and their notes. Combine the words with the filters.

| Field | Type | Notes |
| - | - | - |
| `query` | string | Optional. Words or a question, searched in the text of every document, e.g. `litigios y demandas provisión`. Without it, the statements the filters match are listed. |
| `entity_code` | string | Optional. A CHIP code, e.g. `210105001`: that entity's statements only. |
| `year` | integer,null | Optional. Fiscal year, e.g. `2025`. Default `null`. |
| `department` | string | Optional. The entity's department, e.g. `ANTIOQUIA`. |
| `municipality` | string | Optional. The entity's municipality, e.g. `MEDELLIN`. |
| `page` | integer | Optional. 1-based page of results. Default `1`. |
| `per_page` | integer | Optional. Results per page, 1-50. Default `10`. |

```bash theme={"dark"}
curl https://api.croma.run/co/contaduria-chip/statements-search/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "query": "litigios y demandas provisión",
        "entity_code": "210105001",
        "year": 2025
      }'
```

Returns `as_of`, the filters as read, `total`, `total_is_exact`, `page`, `per_page`, `total_pages`, `count` and `results[]`: each statement (`statement_id`, `entity_code`, `entity_name`, `tax_id`, `department`, `municipality`, `sector`, `category_code`, `category_name`, `year`, `start_date`, `end_date`, `scope`, `submission_number`, `document_name`, `document_url`, `document_bytes`, `pages`, `text_length`, `checked_at`) with `matches[]`: up to three passages, each with its `page_number`, `text`, `start` and `end`.

## Financial statements

`POST /co/contaduria-chip/statement/v1` [Dataset](https://docs.usecroma.com/datasets.md)

Returns one entity's statements for a year and the text of the document.

| Field | Type | Notes |
| - | - | - |
| `entity_code` | string | **Required.** The entity's CHIP code, e.g. `210105001`. |
| `year` | integer | **Required.** Fiscal year, e.g. `2025`. |
| `page_number` | integer,null | Optional. A page of the document to return whole, e.g. `12`. Default `null`. |
| `offset` | integer | Optional. First character of the range. Pass the previous `next_offset` to read on. Default `0`. |
| `limit` | integer | Optional. Maximum characters to return, 1000-1000000. Default `200000`. |

```bash theme={"dark"}
curl https://api.croma.run/co/contaduria-chip/statement/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entity_code": "210105001", "year": 2025, "page_number": 12 }'
```

Returns `as_of`, `found`, `entity_code`, `year` and `statement`: the fields of a search result plus `text_url`, `page_number` and `content` (`text`, `offset`, `total_length`, `has_more`, `next_offset`, `from_page`, `to_page`). `found` is `false`, never an error, when no statements of that entity are held for that year.

## How the three fit together

Start from the entity search to get a CHIP code. Ask the report index what that entity reported: its categories, then the periods of one category, then the forms of one period. Pass the four values (`entity_code`, `category_code`, `period`, `form_code`) to the report endpoint.

### `columns[]` and `rows[]`

Every form has its own columns, so a report describes them instead of fixing them:

| Field | Notes |
| - | - |
| `columns[].key` | The key of that column in each row's `values`. |
| `columns[].name` | The column's name, as the form prints it (`SALDO FINAL`). |
| `columns[].unit` | `pesos`, `thousands_of_pesos` or `unit` for an amount column; `null` for a text column. Older accounting periods are in thousands: always read the unit. |
| `columns[].type` | `amount` (numbers) or `text` (the form's own wording). |
| `rows[].code` | The row's code in the form's tree, dotted (`1.1.05.01`). |
| `rows[].name` | The account or concept. |
| `rows[].level` | Depth in the tree: `1` at the top, one more per dot. |
| `rows[].parent_code` | The code one level up, `null` at the top. |
| `rows[].values` | The cells by column key. |

A parent row already totals its children: add up rows of one level, never of several.

`submission_number` and `received_at` say which submission the report shows. An entity that corrects a period sends a new one, so a later read of the same period can carry a new number.

`document_url` is Croma's copy of the report as the source exports it, an Excel workbook with every row at every level.

> [card] [Full reference](https://docs.usecroma.com/api-reference/overview.md)
>
> Schemas, all response fields, and an interactive playground.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.