Sample data

1. Bulk resolve companies

Post 1–50 company names or tickers. More than one input requires a bulk-enabled key; otherwise the request returns HTTP 403 with code: bulk_access_required. Results preserve input order.

{
  "entities": ["NVDA", "META"]
}

Example response:

{
  "data": [
    {
      "inputIndex": 0,
      "input": "NVDA",
      "status": "resolved",
      "entity": {
        "entityId": "ent_7f5f3525efbe865ab42c",
        "name": "NVIDIA Corp",
        "symbol": "NVDA",
        "country": "US",
        "type": "public"
      }
    },
    {
      "inputIndex": 1,
      "input": "META",
      "status": "review",
      "reason": "context_required",
      "candidates": [
        { "entityId": "ent_78d628c7c94a14d0e024", "name": "META PLATFORMS INC", "symbol": "META", "country": "US", "type": "public", "match": { "kind": "exact_primary_ticker" } },
        { "entityId": "ent_34e96b993210dffc39bd", "name": "METATECH TRADING LTD", "symbol": "META", "country": "PK", "type": "public", "match": { "kind": "exact_primary_ticker" } }
      ]
    }
  ],
  "summary": {
    "requested": 2, "resolved": 1, "review": 1,
    "notFound": 0, "failed": 0, "invalid": 0
  }
}

A resolved row contains entity and optional alternatives. A review row contains reason and candidates. Each entity has entityId, name, symbol, country, and type; symbol, country, and type can be null. Candidates and alternatives also have match.kind.

To confirm or correct a mapping, send the chosen entityId with your original query. You can send only the rows you want to correct, then reuse those IDs in subsequent requests.

{
  "entities": [
    { "query": "META", "entityId": "ent_78d628c7c94a14d0e024" }
  ]
}

{
  "entities": [
    { "query": "Samsung", "name": "Samsung Electronics Co Ltd", "country": "KR", "reference": "row-17" }
  ]
}

A malformed entity entry rejects the entire request with HTTP 400 and code: invalid_entity_input. Queries must be nonempty strings of up to 128 characters; unsupported query content can instead produce an invalid result row.

Every result row has inputIndex, input, and status. Rows with status: not_found, invalid, or error also have code. Error rows have retryable: true and count as summary.failed. Valid batches return HTTP 200 with a status on every row, or HTTP 503 if every row has status: error. Retry failed rows after Retry-After.

2. Request relationships and metrics

Send up to 25 confirmed IDs in entityIds with a bulk-enabled key. For one company, use entityId instead. Request suppliers, customers, or both, and the metrics you want.

{
  "entityIds": [
    "ent_7f5f3525efbe865ab42c",
    "ent_78d628c7c94a14d0e024"
  ],
  "direction": "suppliers",
  "asOf": "2026-08-19",
  "limit": 25,
  "offset": 0,
  "metrics": [
    "relationshipSize",
    "supplierRevenuePercent",
    "customerCostPercent"
  ]
}

Example response:

{
  "data": [
    {
      "inputIndex": 0,
      "entityId": "ent_7f5f3525efbe865ab42c",
      "status": "ok",
      "date": "2026-08-19",
      "relationships": [
        {
          "supplier": { "entityId": "ent_f74279c03e4680276410", "name": "Micron Technology Inc", "symbol": "MU", "country": "US" },
          "customer": { "entityId": "ent_7f5f3525efbe865ab42c", "name": "NVIDIA Corp", "symbol": "NVDA", "country": "US" },
          "metrics": {
            "relationshipSize": { "value": 9800000000, "currency": "USD" },
            "supplierRevenuePercent": { "value": 17.62 },
            "customerCostPercent": { "value": 14 }
          }
        }
      ]
    },
    {
      "inputIndex": 1,
      "entityId": "ent_78d628c7c94a14d0e024",
      "status": "ok",
      "date": "2026-08-19",
      "relationships": []
    }
  ],
  "summary": { "requested": 2, "succeeded": 2, "failed": 0 },
  "usage": {
    "periodStart": "2026-10-01",
    "usedPercent": 12.5,
    "metered": true
  }
}

Single-company and batch requests use the same response envelope: data, summary, and usage. Each result has inputIndex, entityId, and status. An ok result also has date and relationships. An error result has an error object with code and message, and sometimes retryable. Keep successful rows when a batch partially fails.

Each relationship has supplier and customer, each with entityId, name, symbol, and country. The entityId, symbol, and country fields can be null. Relationships without metrics are included; unavailable metric fields and an empty metrics object are omitted. An empty relationships array means no relationships were returned for that company.

An ok result can also contain errors: an array of objects with supplier and customer names, code, and an optional metric name. Check this array for partial relationship or metric failures. The summary counts company results, not individual relationships or metrics. Multi-company batches return HTTP 200 unless every company fails with a server error, in which case they return HTTP 503. Single-company failures retain their HTTP error status.

The direction defaults to both. The limit applies per company: 25 by default, capped by the service limit (100 by default) and your plan. With both, the limit covers suppliers and customers together. Omit metrics or send an empty array for relationships alone.

The offset defaults to 0 and must be a nonnegative safe integer. It skips that many relationships per company. Request later pages with the same filters and a higher offset. Responses do not include a total count or next-page cursor.

The relationshipSize metric is an absolute USD amount. The supplierRevenuePercent metric is the supplier’s revenue dependence on the customer; customerCostPercent is the customer’s cost dependence on the supplier. Percentages use 0–100 units, so 17.62 means 17.62%.

3. Historical relationships

Include asOf in every relationships request as an exact YYYY-MM-DD calendar date. The date on each result is the exact date you requested. Estimates update periodically, so different dates can have the same values.

{
  "entityId": "ent_7f5f3525efbe865ab42c",
  "direction": "suppliers",
  "metrics": ["relationshipSize"],
  "asOf": "2026-08-19"
}

Future dates are rejected. History is subject to your plan and available coverage: Builder includes a rolling three years; Architect includes a rolling ten years. Enterprise history access is defined by the applicable Order Form. Missing values are never substituted with zero.