---
title: "SECOP Contracts Search"
method: POST
path: "/co/secop/contracts-search/v1"
tags: ["Colombia", "SECOP"]
---

# SECOP Contracts Search

`POST /co/secop/contracts-search/v1`

## Request

- Base URL: `https://api.croma.run`
- URL: `https://api.croma.run/co/secop/contracts-search/v1`
- Auth: HTTP bearer

Search every contract the Colombian state has signed, across SECOP II (2015 onward) and SECOP I (2004 onward), in one shape. Full-text over the contract object and the parties, plus filters on the contractor's document (NIT or cédula, in any of the spellings SECOP prints), the cédula of the contractor's legal representative, the entity NIT, department, sector, contract type, modality, status, UNSPSC category, year, signature-date range and amount. This is the endpoint for "everything this company or person has contracted with the Colombian state".

**Dataset endpoint**: answers from the whole source in milliseconds and carries `as_of`.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `query` string: Optional search terms matched against the free text of the record (what is being bought, the entity and the supplier). Leave empty to filter without searching.
  - `platform` 'any' | 'secop_i' | 'secop_ii': Restrict to one system: `secop_ii` (the transactional platform, 2015 onward), `secop_i` (the publication register, 2004 onward), or `any` for both.
  - `entity_nit` string: Optional document filter: a NIT or a cédula, with or without dots and verification digit (`900195855`, `900.195.855-1` and `900195855-1` all match the same records).
  - `department` string: Optional department of the contracting entity, as SECOP writes it (`Antioquia`, `Bogotá D.C.`, ...). Empty for the whole country.
  - `modality` string: Optional modalidad de contratación, exactly as SECOP writes it (`Contratación directa`, `Licitación pública`, `Mínima cuantía`, ...). Empty for every modality.
  - `contract_type` string: Optional tipo de contrato, exactly as SECOP writes it (`Prestación de servicios`, `Obra`, `Suministros`, ...). Empty for every type.
  - `status` string: Optional estado, exactly as SECOP writes it (`Adjudicado`, `Celebrado`, `En ejecución`, `Terminado`, ...). Empty for every status.
  - `unspsc_code` string: Optional main UNSPSC category code of the purchase (`V1.80101500`). Empty for every category.
  - `year` integer: Optional calendar year. 0 searches every year.
  - `from_date` string, date: Optional date filter in yyyy-mm-dd format.
  - `to_date` string, date: Optional date filter in yyyy-mm-dd format.
  - `min_value` number: Optional lower bound on the amount, in COP. 0 means no lower bound.
  - `max_value` number: Optional upper bound on the amount, in COP. 0 means no upper bound.
  - `sort` 'recent' | 'oldest' | 'value_desc' | 'value_asc': Order of the results: `recent` (newest first, the default), `oldest`, `value_desc` (largest amount first) or `value_asc`.
  - `page` integer: 1-based page number for paginated results.
  - `per_page` integer: Results per page (1-100).
  - `provider_document` string: Optional document filter: a NIT or a cédula, with or without dots and verification digit (`900195855`, `900.195.855-1` and `900195855-1` all match the same records).
  - `legal_rep_document` string: Optional document filter: a NIT or a cédula, with or without dots and verification digit (`900195855`, `900.195.855-1` and `900195855-1` all match the same records).
  - `sector` string: Optional sector of the contracting entity (`Salud y Protección Social`, `Educación Nacional`, ...). Published on SECOP II contracts only. Empty for every sector.

## Response `200`

Successful response

- SecopContractsSearchResponse
  - `data` SecopContractsSearchData, required
    - `as_of` string, nullable, required: How current the data is: the moment this dataset was last brought up to date, as an ISO timestamp. Null before the first sync.
    - `total` number, required: Records matching the filters, regardless of the page size, counted up to 1000.
    - `total_is_exact` boolean, required: False when more than 1000 match: `total` is then 1000, and the pages go on.
    - `page` number, required
    - `per_page` number, required
    - `total_pages` number, required: Pages over `total`; there are more when `total_is_exact` is false.
    - `count` number, required: Records returned on this page.
    - `query` string, required
    - `platform` string, nullable, required
    - `entity_nit` string, nullable, required
    - `department` string, nullable, required
    - `modality` string, nullable, required
    - `contract_type` string, nullable, required
    - `status` string, nullable, required
    - `unspsc_code` string, nullable, required
    - `year` number, nullable, required
    - `from_date` string, nullable, required
    - `to_date` string, nullable, required
    - `min_value` number, nullable, required
    - `max_value` number, nullable, required
    - `sort` string, required
    - `provider_document` string, nullable, required
    - `legal_rep_document` string, nullable, required
    - `sector` string, nullable, required
    - `results` object[], required
      - `id` string, required: Stable identifier, `<platform>:<contract id>` (e.g. `secop_ii:CO1.PCCNTR.4168447`).
      - `platform` 'secop_i' | 'secop_ii', required: Which system published the row: `secop_ii` (the transactional platform, 2015 onward) or `secop_i` (the publication register, 2004 onward).
      - `contract_id` string, nullable, required: The contract id as its own platform numbers it.
      - `reference` string, nullable, required: The entity's own reference for the contract.
      - `process_id` string, nullable, required: Id of the process the contract came out of, prefixed like `id`, so it joins the processes dataset.
      - `portfolio_id` string, nullable, required: SECOP II proceso de compra (`CO1.BDOS.*`) the contract belongs to.
      - `award_id` string, nullable, required: Id of the adjudicación the contract implements (SECOP I).
      - `entity` string, nullable, required: Name of the contracting entity.
      - `entity_nit` string, nullable, required: NIT of the contracting entity, digits only, no verification digit.
      - `entity_code` string, nullable, required: The entity's internal SECOP code.
      - `entity_level` string, nullable, required: Nivel: `NACIONAL` or `TERRITORIAL`.
      - `entity_order` string, nullable, required: Orden of the entity within the state.
      - `entity_sector` string, nullable, required: Sector the entity belongs to (salud, educación, defensa, ...).
      - `entity_branch` string, nullable, required: Rama of the state the entity belongs to.
      - `entity_centralized` string, nullable, required: `Centralizada` or `Descentralizada`; a label upstream, not a boolean.
      - `entity_department` string, nullable, required: Department the entity sits in.
      - `entity_city` string, nullable, required: Municipality the entity sits in.
      - `sub_unit` string, nullable, required: Sub unidad ejecutora (SECOP I).
      - `provider` string, nullable, required: Name or razón social of the contractor.
      - `provider_document` string, nullable, required: Contractor's document, digits only: a NIT for a company, a cédula when the contractor is a natural person. The one field to filter by to see everything a person or company has contracted with the state.
      - `provider_document_type` string, nullable, required: Kind of document `provider_document` is (NIT, cédula de ciudadanía, ...).
      - `provider_code` string, nullable, required: The provider's internal SECOP code.
      - `provider_department` string, nullable, required: Department of the contractor.
      - `provider_city` string, nullable, required: Municipality of the contractor.
      - `provider_is_group` boolean, nullable, required: True when the contractor is a plural structure: a consorcio or a unión temporal.
      - `provider_is_sme` boolean, nullable, required: True when the contractor is registered as a PyME / MiPyme.
      - `provider_size` string, nullable, required: Tamaño MiPyme as SECOP I states it (micro, pequeña, mediana).
      - `legal_rep_name` string, nullable, required: Name of the contractor's legal representative.
      - `legal_rep_document` string, nullable, required: Document of the contractor's legal representative, digits only. Filter by it to see every contract a person signed on behalf of a company.
      - `legal_rep_document_type` string, nullable, required: Kind of document the legal representative holds.
      - `legal_rep_nationality` string, nullable, required: Nationality of the legal representative.
      - `legal_rep_domicile` string, nullable, required: Domicile of the legal representative.
      - `legal_rep_gender` string, nullable, required: Gender of the legal representative, as the platform records it.
      - `object` string, nullable, required: Objeto del contrato: what the contract is for, at signature.
      - `description` string, nullable, required: Descripción del proceso the contract came out of.
      - `unspsc_code` string, nullable, required: Main UNSPSC category code.
      - `contract_type` string, nullable, required: Tipo de contrato (obra, prestación de servicios, suministro, consultoría, ...).
      - `modality` string, nullable, required: Modalidad the contract was procured under.
      - `modality_justification` string, nullable, required: The legal ground given for the modality.
      - `status` string, nullable, required: Estado del contrato in the platform's own words.
      - `delivery_conditions` string, nullable, required: Condiciones de entrega.
      - `location` string, nullable, required: Localización recorded for the contract.
      - `execution_address` string, nullable, required: Address the contract is executed at (SECOP II).
      - `execution_locations` string, nullable, required: Municipalities of execution (SECOP I).
      - `value` number, nullable, required: Value of the contract in COP at signature, before additions.
      - `additions_value` number, nullable, required: Total added to the contract afterwards, in COP.
      - `value_with_additions` number, nullable, required: Value including every addition, in COP. The number to rank spending by.
      - `invoiced_value` number, nullable, required: Invoiced to date, in COP (SECOP II).
      - `paid_value` number, nullable, required: Paid to date, in COP (SECOP II).
      - `pending_payment_value` number, nullable, required: Still to be paid, in COP (SECOP II).
      - `pending_execution_value` number, nullable, required: Still to be executed, in COP (SECOP II).
      - `advance_payment_enabled` boolean, nullable, required: Whether the contract allows an advance payment.
      - `advance_payment_value` number, nullable, required: Advance payment agreed, in COP.
      - `amortized_value` number, nullable, required: Advance amortized to date, in COP.
      - `pending_amortization_value` number, nullable, required: Advance still to be amortized, in COP.
      - `cdp_balance` number, nullable, required: Saldo CDP (certificado de disponibilidad presupuestal), in COP.
      - `vigencia_balance` number, nullable, required: Saldo vigencia, in COP.
      - `funding_origin` string, nullable, required: Origen de los recursos, as the platform labels it.
      - `funding_national_budget` number, nullable, required: Share funded by the Presupuesto General de la Nación, in COP.
      - `funding_participations` number, nullable, required: Share funded by the Sistema General de Participaciones, in COP.
      - `funding_royalties` number, nullable, required: Share funded by the Sistema General de Regalías, in COP.
      - `funding_own_territorial` number, nullable, required: Share funded by a mayor's or governor's own resources, in COP.
      - `funding_credit` number, nullable, required: Share funded by credit, in COP.
      - `funding_other` number, nullable, required: Share funded from other sources (in kind, private, cooperation), in COP.
      - `expense_destination` string, nullable, required: Destino del gasto: `Inversión` or `Funcionamiento`.
      - `budget_position` string, nullable, required: Posición del rubro presupuestal (SECOP I).
      - `budget_name` string, nullable, required: Nombre del rubro presupuestal (SECOP I).
      - `budget_value` number, nullable, required: Value charged to that rubro, in COP (SECOP I).
      - `bpin_code` string, nullable, required: BPIN code of the investment project the contract belongs to.
      - `sign_date` string, nullable, required: When the contract was signed, `yyyy-mm-dd`.
      - `start_date` string, nullable, required: When execution starts, `yyyy-mm-dd`.
      - `end_date` string, nullable, required: When execution ends, `yyyy-mm-dd`.
      - `liquidation_start_date` string, nullable, required: Start of the liquidation stage, `yyyy-mm-dd`.
      - `liquidation_end_date` string, nullable, required: End of the liquidation stage, `yyyy-mm-dd`.
      - `liquidation_date` string, nullable, required: Fecha de liquidación, `yyyy-mm-dd` (SECOP I).
      - `extension_notice_date` string, nullable, required: When the entity gave notice of an extension.
      - `updated_date` string, nullable, required: When the source last touched the row, `yyyy-mm-dd`. Null on 42% of SECOP II contracts, so never treat it as complete.
      - `year` number, nullable, required: Calendar year of `sign_date`.
      - `duration` string, nullable, required: Stated duration of the contract.
      - `duration_days` number, nullable, required: Plazo de ejecución in days (SECOP I).
      - `added_days` number, nullable, required: Days added to the contract by its modifications.
      - `can_be_extended` boolean, nullable, required: Whether the contract may be extended.
      - `requires_liquidation` boolean, nullable, required: Whether the contract carries a liquidation stage.
      - `has_environmental_obligation` boolean, nullable, required: Whether the contract carries an environmental obligation.
      - `has_post_consumption_obligations` boolean, nullable, required: Whether it carries post-consumption obligations.
      - `has_reversion` boolean, nullable, required: Whether assets revert to the state at the end.
      - `is_post_conflict` boolean, nullable, required: Whether the contract is marked as post-conflict spending.
      - `peace_pillar` string, nullable, required: Pilar del Acuerdo de Paz the spending is attributed to.
      - `peace_point` string, nullable, required: Punto del Acuerdo de Paz the spending is attributed to.
      - `standard_documents` string, nullable, required: Documentos tipo / pliegos tipo applied to the process.
      - `standard_documents_sector` string, nullable, required: Sector of the pliegos tipo applied.
      - `supervisor` string, nullable, required: Name of the contract's supervisor.
      - `supervisor_document` string, nullable, required: Document of the supervisor.
      - `expense_orderer` string, nullable, required: Name of the ordenador del gasto.
      - `expense_orderer_document` string, nullable, required: Document of the ordenador del gasto.
      - `payment_orderer` string, nullable, required: Name of the ordenador de pago.
      - `payment_orderer_document` string, nullable, required: Document of the ordenador de pago.
      - `url` string, nullable, required: Public page for the contract or its process.

## Other responses

- `400`: Invalid request body
- `401`: Missing or invalid API key
- `429`: Rate limit exceeded
- `500`: Internal error

---

[API](https://skmtc.dev/usecroma/apis/croma-marketplace-api.md) · [All operations](https://skmtc.dev/usecroma/apis/croma-marketplace-api/llms.txt) · [OpenAPI document](https://skmtc.dev/usecroma/apis/croma-marketplace-api/revisions/df016cdb29d7?raw)