Customs trade data API

The Customs API provides company discovery, company-name candidates, counterparties, product categories, trends, country distribution, and complete trade reports. Every endpoint is an asynchronous POST. Idempotency-Key is optional; send and reuse it when safe retries are needed.

Two independent dimensions control a query:

• company_role is the target company's role in the trade: importer or exporter.
• catalog is the record catalog to query: imports or exports.

They can be combined independently. Most requests use the first two common combinations; cross-combinations are useful when looking up a company from the opposite side's record catalog:

company_role answers “what role does the target company play?” while catalog answers “which side's record catalog should be queried?” They are not duplicate fields.

Find a queryable customs company name

POST/api/v2/customs/company-candidates

Company-name candidates identify exact name strings that have trade records in a date range. This is not a legal-entity resolution service. identity_status: unverified means that the exact name is queryable, not that the company's legal identity was verified.

cURLCopy
curl -X POST "https://revor.ai/api/v2/customs/company-candidates" \
  -H "Authorization: Bearer sk-revor-REPLACE_ME" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=20" \
  -d '{
    "company_name": "Banbros Commercial Inc.",
    "start_date": "2025-08-01",
    "end_date": "2026-07-31",
    "page": 1,
    "page_size": 20,
    "company_role": "exporter",
    "catalog": "imports",
    "country_codes": "IDN"
  }'

company_role and catalog are optional but should be provided together. If both are omitted, the endpoint checks the common importer/imports and exporter/exports combinations. If only one is supplied, the other is filled from its common pairing.

Discover companies by product and country

POST/api/v2/customs/companies/search

No company name is required. This endpoint returns importers or exporters from product, country, and date criteria in trade records. Use it to find potential buyers, suppliers, or peers in a market.

cURLCopy
curl -X POST "https://revor.ai/api/v2/customs/companies/search" \
  -H "Authorization: Bearer sk-revor-REPLACE_ME" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=20" \
  -d '{
    "company_role": "importer",
    "catalog": "imports",
    "start_date": "2025-09-01",
    "end_date": "2026-08-31",
    "hs_code": "8429",
    "product_description": "excavator",
    "origin_country_code": "CHN",
    "destination_country_code": "BRA",
    "page": 1,
    "page_size": 20,
    "sort_by": "trade_count",
    "sort_order": "desc"
  }'

Provide at least one of hs_code, product_description, origin_country_code, and destination_country_code to avoid an unscoped full-dataset query. Industry names are not a uniform customs classification; broad requests such as “machinery industry” should first be expressed as an appropriate HS Code or product keyword.

For a successful job, item.result.data.items contains normalized fields including company_name, country, country_code, trade_count, amount_usd, quantity, weight, and amount share. Some coverage does not provide every statistic. Credits are settled against the number of company rows actually returned; a zero-row result ultimately consumes 0 credits.

Query endpoints

These endpoints share one request format:

cURLCopy
curl -X POST "https://revor.ai/api/v2/customs/trade-reports" \
  -H "Authorization: Bearer sk-revor-REPLACE_ME" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=20" \
  -d '{
    "company_name": "BANBROS COMMERCIAL INC",
    "company_role": "importer",
    "catalog": "imports",
    "start_date": "2025-08-01",
    "end_date": "2026-07-31",
    "page": 1,
    "page_size": 20,
    "period_unit": "months",
    "filters": {
      "hs_code": "8429",
      "product_description": "excavator",
      "origin_country_code": "CHN",
      "destination_country_code": "USA"
    }
  }'

Shared request fields

The maximum query range is one year. Country and region codes use three letters; common examples include USA, CHN, IDN, PHL, and GBR. Invalid dates, company names, company_role, catalog, or country codes fail immediately without creating a job.

Single-section result

For a successful job, item.result contains the query scope and a paginated data object:

JSONCopy
{
  "company_name": "BANBROS COMMERCIAL INC",
  "company_role": "importer",
  "catalog": "imports",
  "date_range": { "start": "2025-08-01", "end": "2026-07-31" },
  "section": "counterparties",
  "data": {
    "total": 42,
    "page": 1,
    "page_size": 20,
    "returned_rows": 20,
    "items": [
      {
        "name": "Example Trading Co.",
        "country": "United States",
        "countryCode": "US",
        "tradeCount": 18,
        "sumOfUSD": 250000,
        "amountSharePct": 21.4
      }
    ]
  }
}

Public rows can contain only these stable fields: name, country, countryCode, date, hsCode, hsDescriptionCn, hsDescriptionEn, companyCount, weight, quantity, sumOfUSD, weightAvgPrice, quantityAvgPrice, tradeCount, and amountSharePct. Not every section returns every field.

Complete report result

item.result from trade-reports is grouped by section:

JSONCopy
{
  "company_name": "BANBROS COMMERCIAL INC",
  "company_role": "importer",
  "catalog": "imports",
  "date_range": { "start": "2025-08-01", "end": "2026-07-31" },
  "status": "partial",
  "sections": {
    "counterparties": {
      "status": "complete",
      "data": { "total": 42, "page": 1, "page_size": 20, "returned_rows": 20, "items": [] }
    },
    "categories": { "status": "complete", "data": {} },
    "trend": { "status": "failed", "error": { "code": "customs_section_failed" } },
    "countries": { "status": "complete", "data": {} }
  }
}

A complete report may partially succeed. Check each section's status; a succeeded job does not imply that all four sections succeeded.