> ## 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. # DIAN Company Trade Profile > A Colombian company's foreign trade history by NIT, from DIAN's yearly directories of importers and exporters since 2017: its row in each year's importers directory (rank, CIF value in US dollars, net weight, declarations, main subpartidas arancelarias) and in each year's exporters directory (rank, FOB value, net weight, declaration items, main subpartidas), newest first. `found: false` when the NIT appears in no directory. 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`. ## OpenAPI ````yaml /api-reference/openapi.json post /co/dian-trade/profile/v1 openapi: 3.1.0 info: title: Croma Marketplace API version: 1.0.0 description: >- Government-data APIs for Colombia, Peru, Mexico, and global web search. Croma normalizes public-sector data into structured JSON for product teams and AI agents. Every operation is a POST with a JSON body and an organization API key as a bearer token; every operation is an idempotent lookup and accepts an optional `Idempotency-Key` header. Paths carry their major version (`/v1`); the versioning and deprecation policy, including the `Deprecation` and `Sunset` headers a retiring endpoint sends, is at https://docs.usecroma.com/versioning. Rate limits are per organization and reported on every response (`RateLimit-Policy`, `X-RateLimit-*`): https://docs.usecroma.com/rate-limits. termsOfService: https://usecroma.com/en/terms contact: name: Croma support url: https://usecroma.com/en/support email: tomas@usecroma.com servers: - url: https://api.croma.run security: [] paths: /co/dian-trade/profile/v1: post: tags: - Colombia - DIAN Importers and Exporters summary: DIAN Company Trade Profile description: >- A Colombian company's foreign trade history by NIT, from DIAN's yearly directories of importers and exporters since 2017: its row in each year's importers directory (rank, CIF value in US dollars, net weight, declarations, main subpartidas arancelarias) and in each year's exporters directory (rank, FOB value, net weight, declaration items, main subpartidas), newest first. `found: false` when the NIT appears in no directory. 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`. operationId: dian_trade_profile parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object required: - document_number properties: document_number: type: string minLength: 4 maxLength: 15 pattern: ^\d{4,15}$ description: Colombian NIT (numeric, no verification digit). 4-15 digits. additionalProperties: false example: document_number: '899999068' responses: '200': description: Successful response headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Idempotency-Key: $ref: '#/components/headers/Idempotency-Key' Deprecation: $ref: '#/components/headers/Deprecation' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-Cache: $ref: '#/components/headers/X-Cache' content: application/json: schema: $ref: '#/components/schemas/DianTradeProfileResponse' '400': description: Invalid request body headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Idempotency-Key: $ref: '#/components/headers/Idempotency-Key' Deprecation: $ref: '#/components/headers/Deprecation' Sunset: $ref: '#/components/headers/Sunset' content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: Missing or invalid API key headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Idempotency-Key: $ref: '#/components/headers/Idempotency-Key' Deprecation: $ref: '#/components/headers/Deprecation' Sunset: $ref: '#/components/headers/Sunset' content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: Rate limit exceeded headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Idempotency-Key: $ref: '#/components/headers/Idempotency-Key' Deprecation: $ref: '#/components/headers/Deprecation' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': description: Internal error headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Idempotency-Key: $ref: '#/components/headers/Idempotency-Key' Deprecation: $ref: '#/components/headers/Deprecation' Sunset: $ref: '#/components/headers/Sunset' content: application/json: schema: $ref: '#/components/schemas/ApiError' '502': description: Upstream source returned an error headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Idempotency-Key: $ref: '#/components/headers/Idempotency-Key' Deprecation: $ref: '#/components/headers/Deprecation' Sunset: $ref: '#/components/headers/Sunset' content: application/json: schema: $ref: '#/components/schemas/ApiError' security: - bearerAuth: [] externalDocs: description: Interactive documentation and examples url: https://docs.usecroma.com/guides/colombia/dian-trade components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Optional client-chosen key for this request (any string up to 255 characters, e.g. a UUID). Every Croma operation is an idempotent lookup: repeating a request with the same body returns the same result and creates nothing, so retrying after a timeout or network failure is always safe. The key is echoed back in the `Idempotency-Key` response header so you can correlate a retry with its first attempt. Each attempt that reaches the API counts against the rate limit. schema: type: string maxLength: 255 example: 0f8e9a42-6b7c-4d1e-9a3f-2c5d7e8f9a0b headers: X-Request-Id: description: Unique id for the request (req_…). Include it in support reports. schema: type: string RateLimit-Policy: description: >- Quota policy for this endpoint as an IETF RateLimit-Policy structured field, e.g. `"default";q=100;w=86400` (100 requests per 86400-second window per organization). Endpoints with an extra hourly ceiling list both policies, e.g. `"webSearch";q=10;w=3600, "default";q=100;w=86400`. Present on every response, including 401 and 429. schema: type: string example: '"default";q=100;w=86400' Idempotency-Key: description: >- The `Idempotency-Key` the request carried, echoed back unchanged. Absent when the request sent none. schema: type: string Deprecation: description: >- Present only on an endpoint version scheduled for removal: the date the deprecation took effect (RFC 9745). A `Sunset` header and a `Link` with `rel="successor-version"` accompany it. Policy: https://docs.usecroma.com/versioning schema: type: string example: '@1767225600' Sunset: description: >- Present only on an endpoint version scheduled for removal: the date after which it answers 410 (RFC 8594). Announced in the changelog at least 90 days ahead. schema: type: string format: date-time example: Wed, 01 Apr 2026 00:00:00 GMT X-RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer X-RateLimit-Remaining: description: Requests left before you are throttled. schema: type: integer X-RateLimit-Reset: description: ISO 8601 timestamp when the window resets. schema: type: string format: date-time X-Cache: description: >- HIT or MISS. Cached hits spend no credits, but still count toward an hourly ceiling. schema: type: string enum: - HIT - MISS Retry-After: description: Seconds to wait before retrying. schema: type: integer schemas: DianTradeProfileResponse: type: object required: - data properties: data: $ref: '#/components/schemas/DianTradeProfileData' ApiError: type: object required: - error properties: error: type: object required: - type - code - message properties: type: type: string description: >- Broad category: invalid_request_error, authentication_error, not_found_error, rate_limit_error, upstream_error, api_error. code: type: string description: Machine-readable specific code. message: type: string description: Human-readable explanation, safe to surface in UI. param: type: string description: Field that triggered the error. Present on validation errors. details: type: object description: Free-form structured detail. DianTradeProfileData: type: object properties: as_of: anyOf: - type: string - type: 'null' description: How current the data in this response is. found: type: boolean description: >- False when the NIT appears in no importers or exporters directory since 2017. document_number: type: string description: Echoes the request's `document_number`. name: anyOf: - type: string - type: 'null' description: The name in the most recent directory the company appears in. years: type: array items: type: number description: Every year the company appears in either directory, newest first. imports: type: array items: type: object properties: id: type: string description: >- 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: type: string enum: - import - export description: >- `import` (the directorio de importadores) or `export` (the directorio de exportadores). year: type: integer description: Year the directory covers, 2017 or later. through_month: anyOf: - type: integer - type: 'null' description: >- 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: type: integer description: >- Position in that year's directory (Consecutivo), 1 for the largest value. document_number: anyOf: - type: string - type: 'null' description: >- The company's NIT, numeric, no verification digit. Null for a natural person, whose identification DIAN does not publish. name: anyOf: - type: string - type: 'null' description: >- Razón social as DIAN prints it that year. `PERSONA NATURAL` for a natural person. natural_person: type: boolean description: >- True when DIAN recategorized the row as a natural person and published neither the identification nor the name. value_usd: type: number description: >- Total value in US dollars for the year to `through_month`: CIF for imports, FOB for exports. value_basis: type: string enum: - CIF - FOB description: >- How `value_usd` is valued: `CIF` for imports, `FOB` for exports. net_weight_kg: type: number description: Total net weight in kilograms. declarations: anyOf: - type: integer - type: 'null' description: >- Imports only: number of import declarations filed. Null on exports. declaration_items: anyOf: - type: integer - type: 'null' description: >- 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: type: array items: type: string description: >- The main subpartidas arancelarias imported or exported, up to five, in DIAN's order (Primera to Quinta), as 10-digit codes. top_tariff_headings: type: array items: type: string description: >- The 4-digit headings (partidas) of `top_tariff_codes`, in order, without repeats. top_tariff_subheadings: type: array items: type: string description: >- The 6-digit HS subheadings of `top_tariff_codes`, in order, without repeats. updated_at: anyOf: - type: string - type: 'null' description: >- `yyyy-mm-dd` DIAN last updated that year's directory, as the directory states it. Null when it does not. required: - id - flow - year - through_month - rank - document_number - name - natural_person - value_usd - value_basis - net_weight_kg - declarations - declaration_items - top_tariff_codes - top_tariff_headings - top_tariff_subheadings - updated_at description: The company's row in each year's importers directory, newest first. exports: type: array items: type: object properties: id: type: string description: >- 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: type: string enum: - import - export description: >- `import` (the directorio de importadores) or `export` (the directorio de exportadores). year: type: integer description: Year the directory covers, 2017 or later. through_month: anyOf: - type: integer - type: 'null' description: >- 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: type: integer description: >- Position in that year's directory (Consecutivo), 1 for the largest value. document_number: anyOf: - type: string - type: 'null' description: >- The company's NIT, numeric, no verification digit. Null for a natural person, whose identification DIAN does not publish. name: anyOf: - type: string - type: 'null' description: >- Razón social as DIAN prints it that year. `PERSONA NATURAL` for a natural person. natural_person: type: boolean description: >- True when DIAN recategorized the row as a natural person and published neither the identification nor the name. value_usd: type: number description: >- Total value in US dollars for the year to `through_month`: CIF for imports, FOB for exports. value_basis: type: string enum: - CIF - FOB description: >- How `value_usd` is valued: `CIF` for imports, `FOB` for exports. net_weight_kg: type: number description: Total net weight in kilograms. declarations: anyOf: - type: integer - type: 'null' description: >- Imports only: number of import declarations filed. Null on exports. declaration_items: anyOf: - type: integer - type: 'null' description: >- 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: type: array items: type: string description: >- The main subpartidas arancelarias imported or exported, up to five, in DIAN's order (Primera to Quinta), as 10-digit codes. top_tariff_headings: type: array items: type: string description: >- The 4-digit headings (partidas) of `top_tariff_codes`, in order, without repeats. top_tariff_subheadings: type: array items: type: string description: >- The 6-digit HS subheadings of `top_tariff_codes`, in order, without repeats. updated_at: anyOf: - type: string - type: 'null' description: >- `yyyy-mm-dd` DIAN last updated that year's directory, as the directory states it. Null when it does not. required: - id - flow - year - through_month - rank - document_number - name - natural_person - value_usd - value_basis - net_weight_kg - declarations - declaration_items - top_tariff_codes - top_tariff_headings - top_tariff_subheadings - updated_at description: The company's row in each year's exporters directory, newest first. required: - as_of - found - document_number - name - years - imports - exports securitySchemes: bearerAuth: type: http scheme: bearer description: 'Use Authorization: Bearer YOUR_API_KEY' ````