> ## 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.

# CCB: arbitral awards

> The arbitral awards of the CCB's Arbitration and Conciliation Center, about 2,150 since 1985, with their text and a copy of each one.

The awards that Colombia's largest arbitration center, at the Cámara de Comercio de Bogotá, publishes in its digital library: parties, arbitrators, secretary, case number, date, contract type, subjects, text and a byte-identical copy of the PDF.

Search by words, arbitrator, contract type, case number, collection or date, then read an award's text by its handle.

> [!NOTE]
>
> The whole source, organized and ready to query: every endpoint on this page answers in milliseconds. Every response carries `as_of`: how current the data is. [How datasets work](https://docs.usecroma.com/datasets.md).

## Search the awards

`POST /co/ccb-arbitration/awards-search/v1` [Dataset](https://docs.usecroma.com/datasets.md)

One search over every award, by words, arbitrator, contract type, case number, collection or date.

| Field | Type | Notes |
| - | - | - |
| `query` | string | Optional words matched against the whole text of each award, its title, case number, contract type and subjects, the best match first, e.g. `equilibrio económico`, `INVIAS` or `cláusula penal`. A result need not contain every word. |
| `collection` | enum | Optional collection: `national` (national arbitration) or `social` (social arbitration, the Center's low-cost tribunals for small claims). |
| `arbitrator` | string | Optional arbitrator surname, with or without accents, e.g. `Cárdenas` or `Cárdenas Mejía`. A filter, not searched by `query`. |
| `contract_type` | string | Optional type of the contract in dispute, matched by its words in any order, with or without accents: `Arrendamiento` finds `Arrendamiento de bienes inmuebles` and every other kind of lease; `Obra pública`, `Concesión`, `Prestación de servicios`. |
| `case_number` | string | Optional case number (radicado) the Center gave the arbitration, e.g. `145749`. |
| `from_date` | string | Optional: only awards on or after this date, `yyyy-mm-dd`. |
| `to_date` | string | Optional: only awards on or before this date, `yyyy-mm-dd`. |
| `page` | integer | 1-based page number. Default `1`. |
| `per_page` | integer | Results per page (1-50). Default `10`. |

```bash theme={"dark"}
curl https://api.croma.run/co/ccb-arbitration/awards-search/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "equilibrio económico", "contract_type": "Obra pública" }'
```

Returns `as_of` (how current the data is), the filters applied, `total` and `total_is_exact`, the paging fields (`page`, `per_page`, `total_pages`, `count`) and `results[]`, best match first (newest first without a `query`), one award each:

| Field | Notes |
| - | - |
| `id`, `handle_url` | The award's handle, e.g. `29654` (pass it to `award` for the text), and its permanent link. |
| `collection` | `national` (national arbitration) or `social` (social arbitration); `other` for a record filed in neither. |
| `title`, `case_number` | The title as filed and the Center's case number (radicado). |
| `claimants`, `respondents` | The parties, as the Center writes them. |
| `arbitrators`, `secretaries` | The tribunal's arbitrators and secretary, as `Surnames, Given names`. |
| `award_date`, `year` | The date of the award, `yyyy-mm-dd`, and its year; null on the few awards the Center filed without one. |
| `contract_types`, `subjects`, `sector` | The type of contract in dispute, the topics the Center indexed the award under, and the economic sector where recorded. |
| `city`, `language` | Where the tribunal sat and the language of the text, where recorded. |
| `document_url`, `source_document_url` | Croma's copy of the award, byte for byte as the Cámara de Comercio de Bogotá published it, and the source's own link. Give a reader `document_url`: it keeps working when the source moves its files. |
| `documents[]` | Every file published with the award, the award itself first, each with `name`, `content_type`, `bytes`, `md5`, `document_url` and `source_document_url`. |
| `text_status`, `text_length` | `ok` (Croma holds the whole text), `truncated` (only its first part) or `missing` (a scanned award not read yet), and the length of the text in characters. |
| `text_url`, `scanned` | The award's whole text as one plain-text file, and whether it was recognized from a scanned image. |
| `viewer_url` | Opens the award in Croma Viewer, a page for signed-in Croma users that shows the PDF with the cited passages highlighted: add `&cite=<start>-<end>` once per passage, up to 12. Null when Croma holds no PDF of it. |
| `source_updated_at` | When the source last changed the award's record. |

With a `query`, each result also carries `matches[]`, the passages of the award that answer the search, best first:

| Field | Notes |
| - | - |
| `matches[].section` | The part of the award the passage stands in: `ANTECEDENTES`, `CONSIDERACIONES` (the tribunal's reasoning), `COSTAS`, `PARTE RESOLUTIVA` (what it decided) or `SALVAMENTO DE VOTO`. Null before the first part. |
| `matches[].text` | The passage, verbatim. |
| `matches[].start`, `matches[].end` | Where it stands in the award's text, in characters: pass `start` as `offset` to `award` to read on from there. |
| `matches[].scanned` | True when the text was recognized from a scanned image. |
| `matches[].viewer_url` | The award opened in Croma Viewer on that passage, highlighted. |

> [!NOTE]
>
> To list every award of a contract type, send `contract_type` and no `query`: `query` ranks awards by what their text says, and an award about another contract can say a lot about leases.

## One award, with its text

`POST /co/ccb-arbitration/award/v1` [Dataset](https://docs.usecroma.com/datasets.md)

An award by its handle, with its text.

| Field | Type | Notes |
| - | - | - |
| `handle` | string | **Required.** The award's handle, the `id` of a search result (e.g. `29654`), or its `handle_url`. |
| `section` | enum | Optional: return only this part of the award. `decision` is what the tribunal decided (the `RESUELVE`); `consideraciones` its reasoning; `antecedentes` the claims and how the case went; `costas`; `salvamento` a dissenting vote. |
| `offset` | integer | First character of the text to return. Pass the previous response's `next_offset` to read on. Default `0`. |
| `limit` | integer | How many characters of the text to return. Default `200000`. |

```bash theme={"dark"}
curl https://api.croma.run/co/ccb-arbitration/award/v1 \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "handle": "29654" }'
```

Returns `as_of`, `found`, `handle` and `award`: every field of a search result plus `content`, a range of the award's text:

| Field | Notes |
| - | - |
| `content.text`, `content.offset` | A range of the award's text, and the character it starts at. |
| `content.total_length` | The length of the award's text, the same as `text_length`: the whole award when `text_status` is `ok`. |
| `content.has_more`, `content.next_offset` | Whether the text asked for continues (the award, or the part named by `section`), and the `offset` to send to read on. |
| `section` | The part `content` holds, when `section` was sent and the award has it. |
| `sections[]` | The award's parts in order (`ANTECEDENTES`, `CONSIDERACIONES`, `COSTAS`, `PARTE RESOLUTIVA`, `SALVAMENTO DE VOTO`), each with `section`, `start` and `end`. Empty when the award's parts carry no heading Croma recognizes. |

> [!NOTE]
>
> Croma holds the whole text of an award, however long: follow `next_offset` until `has_more` is false, or read it in one request from `text_url`. The few awards that say `text_status: truncated` hold only their first part, and `document_url` gives the whole award. `content` is null when `text_status` is `missing` (a scanned award not read yet).

> [!NOTE]
>
> A handle the library holds no award under returns `found: false` with HTTP 200, not an error.

> [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.