---
title: "SECOP Annual Procurement Plans Search"
method: POST
path: "/co/secop/plans-search/v1"
tags: ["Colombia", "SECOP"]
---

# SECOP Annual Procurement Plans Search

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

## Request

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

Search the Plan Anual de Adquisiciones each Colombian public entity publishes: the budget it expects to spend that year and the thresholds it will buy under, published before it buys any of it. Filter by entity NIT, department, year or platform to see what an entity intends to procure rather than what it already has.

**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.
  - `department` string: Optional department of the contracting entity, as SECOP writes it (`Antioquia`, `Bogotá D.C.`, ...). Empty for the whole country.
  - `year` integer: Optional calendar year. 0 searches every year.
  - `page` integer: 1-based page number for paginated results.
  - `per_page` integer: Results per page (1-100).

## Response `200`

Successful response

- SecopPlansSearchResponse
  - `data` SecopPlansSearchData, 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
    - `department` string, nullable, required
    - `year` number, nullable, required
    - `results` object[], required
      - `id` string, required: Stable identifier, `<platform>:<plan id>`.
      - `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).
      - `plan_id` string, nullable, required: The plan's id as its own platform numbers it.
      - `year` number, nullable, required: Year the plan covers.
      - `entity` string, nullable, required: Name of the entity.
      - `entity_nit` string, nullable, required: NIT of the entity, digits only.
      - `entity_code` string, nullable, required: The entity's internal SECOP code.
      - `mission` string, nullable, required: Misión y visión the entity states in the plan.
      - `strategy` string, nullable, required: Perspectiva estratégica the entity states in the plan.
      - `total_budget` number, nullable, required: Total budget the plan announces, in COP.
      - `lesser_amount_threshold` number, nullable, required: Menor cuantía threshold for the entity that year, in COP.
      - `minimum_amount_threshold` number, nullable, required: Mínima cuantía threshold for the entity that year, in COP.
      - `status` string, nullable, required: Estado of the plan (SECOP II).
      - `version` number, nullable, required: Version of the plan (SECOP II republishes on every change).
      - `department` string, nullable, required: Department of the entity.
      - `city` string, nullable, required: Municipality of the entity.
      - `contact_name` string, nullable, required: Contact named on the plan.
      - `contact_phone` string, nullable, required: Contact telephone.
      - `contact_email` string, nullable, required: Contact email.
      - `published_date` string, nullable, required: When the plan was published, `yyyy-mm-dd`.
      - `updated_date` string, nullable, required: When the plan was last modified, `yyyy-mm-dd`.

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