---
title: "DIAN Importers and Exporters Search"
method: POST
path: "/co/dian-trade/directory-search/v1"
tags: ["Colombia", "DIAN Importers and Exporters"]
---

# DIAN Importers and Exporters Search

`POST /co/dian-trade/directory-search/v1`

## Request

- Base URL: `https://api.croma.run`
- URL: `https://api.croma.run/co/dian-trade/directory-search/v1`
- Auth: HTTP bearer

Search DIAN's directories of importers and exporters of goods, every year since 2017 and both directories at once: by company name (`query`), `flow` (`import` or `export`), `year`, and `tariff_code` (a 4-digit heading, 6-digit HS subheading or 10-digit subpartida among each company's five main ones). Each result is one company's row in one year's directory: NIT, name, rank, CIF (imports) or FOB (exports) value in US dollars, net weight, declarations or declaration items, and its main subpartidas arancelarias. Newest year first, then by value. Served by Croma (`as_of` says how current the data is), brought up to date weekly.

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

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `query` string: Optional words matched against the name (razón social) as DIAN prints it.
  - `flow` 'any' | 'import' | 'export': Which directory: `import` (importers, valued CIF), `export` (exporters, valued FOB), or `any`.
  - `year` integer: Optional directory year (2017 or later). 0 searches every year.
  - `tariff_code` string: Optional tariff code, digits only, matched against the five main subpartidas of each row: a 4-digit heading (`8703`), a 6-digit HS subheading (`870323`) or a full 10-digit subpartida (`8703239090`).
  - `page` integer: 1-based page number for paginated results.
  - `per_page` integer: Results per page (1-100).

## Response `200`

Successful response

- DianTradeDirectorySearchResponse
  - `data` DianTradeDirectorySearchData, required
    - `as_of` string, nullable, required: How current the data in this response is.
    - `query` string, required
    - `flow` string, nullable, required
    - `year` number, nullable, required
    - `tariff_code` string, nullable, required
    - `total` number, required: Matches across every page, 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: Results on this page.
    - `results` object[], required: Newest year first, then by value, largest first.
      - `id` string, required: Stable identifier: flow, year and NIT, e.g. `import-2025-899999068`. A natural person, whom DIAN publishes without a NIT, is identified by its rank instead: `import-2025-pn-34409`.
      - `flow` 'import' | 'export', required: `import` (the directorio de importadores) or `export` (the directorio de exportadores).
      - `year` integer, required: Year the directory covers, 2017 or later.
      - `through_month` integer, nullable, required: Last month the figures accumulate to (1-12). `12` for a closed year; the current year's directory is cumulative and republished as months close. Null when the directory does not state it.
      - `rank` integer, required: Position in that year's directory (Consecutivo), 1 for the largest value.
      - `document_number` string, nullable, required: The company's NIT, numeric, no verification digit. Null for a natural person, whose identification DIAN does not publish.
      - `name` string, nullable, required: Razón social as DIAN prints it that year. `PERSONA NATURAL` for a natural person.
      - `natural_person` boolean, required: True when DIAN recategorized the row as a natural person and published neither the identification nor the name.
      - `value_usd` number, required: Total value in US dollars for the year to `through_month`: CIF for imports, FOB for exports.
      - `value_basis` 'CIF' | 'FOB', required: How `value_usd` is valued: `CIF` for imports, `FOB` for exports.
      - `net_weight_kg` number, required: Total net weight in kilograms.
      - `declarations` integer, nullable, required: Imports only: number of import declarations filed. Null on exports.
      - `declaration_items` integer, nullable, required: Exports only: number of registros, the series or items listed across the export declarations (not the number of declarations). Null on imports.
      - `top_tariff_codes` string[], required: The main subpartidas arancelarias imported or exported, up to five, in DIAN's order (Primera to Quinta), as 10-digit codes.
      - `top_tariff_headings` string[], required: The 4-digit headings (partidas) of `top_tariff_codes`, in order, without repeats.
      - `top_tariff_subheadings` string[], required: The 6-digit HS subheadings of `top_tariff_codes`, in order, without repeats.
      - `updated_at` string, nullable, required: `yyyy-mm-dd` DIAN last updated that year's directory, as the directory states it. Null when it does not.

## Other responses

- `400`: Invalid request body
- `401`: Missing or invalid API key
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream source returned an 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)