Sign in
latestOpenAPI 3.0.12026-08-20112309904.6 KB

466169815b78

Collections - Tier-N

Get tier-n collection supplier graph

Overview

Retrieve a stream of supplier relationship data for a tier-n enabled collection.

Effective tier = tier if provided, otherwise maxTier (request override, else collection setting, else 1). That value selects the response mode:

  • Effective tier = 1: Collection membership rows only — each supplier in the collection with the customer organization as customerTargetId. Edge/discovery fields (source, probability, mediaSources, nShipments, shipments) are null and omitted from JSON.
  • Effective tier ≥ 2: Membership rows first (same shape as tier 1), then suppliers discovered via tier-n traversal from collection members. Relative to each collection member: response tier 1 = that member's direct suppliers, tier 2+ = indirect (suppliers of suppliers). Distinguish membership from traversal "tier": 1 by customerTargetId = organization and source omitted/null.

Request tier vs response tier: In traversal rows, response tier is relative to each collection member — not a copy of the request parameter. Example: ?tier=3 can still return traversal rows with "tier": 1 (a collection member's direct supplier). Membership rows always use "tier": 1 with the organization as customerTargetId.

Examples

  • GET .../tier-n/data?tier=1 → membership only (see "Membership" example): [{ "tier": 1, "supplierTargetId": …, "customerTargetId": <organizationId> }, …]
  • GET .../tier-n/data?tier=3 → membership first, then traversal up to tier 3 relative to collection members (see "Traversal" example); e.g. membership "tier": 1 with organization as customerTargetId, then traversal "tier": 1 = that member's direct suppliers, "tier": 2 = indirect, and so on
  • Omitting tier uses maxTier (query override, else collection setting, else 1). If that resolves to 1, you get membership only — common when the collection's maxTier is 1

Response Format

  • JSON array of entries (tier, supplierTargetId, customerTargetId, and optional source / probability / media / shipment fields).
  • Null-valued fields are omitted. Optional edge fields appear based on query params only on traversal rows (e.g. includeMediaSources, includeShipmentDetails). Membership rows have no edge data.

Query Parameters

All optional. They override collection defaults from GET .../tier-n/settings.

  • At effective tier = 1, filter and include parameters (source, hsCodes, lastShipment, includeMediaSources, includeShipmentDetails, scope/source overrides, etc.) are ignored — the response is always unfiltered membership.
  • At effective tier ≥ 2, those parameters apply to discovered (traversal) relationships only; membership rows remain unfiltered.

Performance

  • For traversal, filter by source or hsCodes to reduce response size. Higher effective tier / maxTier increases data volume and response time.

Related Operations

  • Settings: GET /public/v1/collections/{collectionId}/tier-n/settings
  • Update settings: PUT /public/v1/collections/{collectionId}/tier-n/settings

Required Permission

access_public_supplier_graph, access_collection, and read on the collection.

get/public/v1/collections/{collectionId}/tier-n/data

Path parameters

collectionIdinteger required

Unique identifier of the tier-n collection. Same as the id from GET /public/v1/collections. The collection must have tiersEnabled=true.

Query parameters

includeCommodityFilterboolean

Include commodity filter metadata in the response. When true, adds commodity filter information to help understand data scope and filtering applied.

Example:true

Include commodity filter metadata in the response. When true, adds commodity filter information to help understand data scope and filtering applied.

includeMediaSourcesboolean

Include media source URLs for MEDIA-type relationships (traversal only; ignored when effective tier = 1). When true, adds mediaSources array with URLs used to derive the relationship from news/media sources.

Include media source URLs for MEDIA-type relationships (traversal only; ignored when effective tier = 1). When true, adds mediaSources array with URLs used to derive the relationship from news/media sources.

includeShipmentDetailsboolean

Include detailed shipment information per HS code (traversal only; ignored when effective tier = 1). When true, adds shipments array with shipment counts and dates broken down by product code.

Include detailed shipment information per HS code (traversal only; ignored when effective tier = 1). When true, adds shipments array with shipment counts and dates broken down by product code.

tierinteger

Sets the effective tier when provided (otherwise effective tier = maxTier). Effective tier 1 = collection membership only (edge fields omitted; other query filters ignored). Effective tier ≥ 2 = membership rows first, then traversal; traversal response tier is relative to each collection member (1 = that member's direct suppliers, 2+ = indirect), not a copy of this parameter. Range: 1-9.

Example:2

Sets the effective tier when provided (otherwise effective tier = maxTier). Effective tier 1 = collection membership only (edge fields omitted; other query filters ignored). Effective tier ≥ 2 = membership rows first, then traversal; traversal response tier is relative to each collection member (1 = that member's direct suppliers, 2+ = indirect), not a copy of this parameter. Range: 1-9.

source'Customer' | 'Media' | 'Customs' | 'PrewavePrediction'

Filter by data source type (traversal only; ignored when effective tier = 1). Valid values: Customs (shipment data), Media (news/media), Customer (customer data), PrewavePrediction (AI predictions). If not specified, uses all enabled sources.

lastShipmentstring

Only include suppliers with shipments since this date (traversal only; ignored when effective tier = 1). Format: YYYY-MM-DD.

Example:2024-01-01

Only include suppliers with shipments since this date (traversal only; ignored when effective tier = 1). Format: YYYY-MM-DD.

hsCodesstring

Filter by specific HS codes, comma-separated (traversal only; ignored when effective tier = 1). Example: 847330,940161

Example:847330,940161

Filter by specific HS codes, comma-separated (traversal only; ignored when effective tier = 1). Example: 847330,940161

maxTierinteger

Override the collection maxTier setting. When tier is omitted, this value is also the effective tier (1 = membership only with other filters ignored; ≥ 2 = membership plus traversal up to that tier relative to collection members). Higher values may increase response time and data volume. Range: 1-9.

Example:4

Override the collection maxTier setting. When tier is omitted, this value is also the effective tier (1 = membership only with other filters ignored; ≥ 2 = membership plus traversal up to that tier relative to collection members). Higher values may increase response time and data volume. Range: 1-9.

scopePrivateboolean

Override collection setting: include private targets in scope. When true, includes relationships involving private targets (typically internal company data).

Example:true

Override collection setting: include private targets in scope. When true, includes relationships involving private targets (typically internal company data).

scopeSharedboolean

Override collection setting: include shared targets in scope. When true, includes relationships involving shared targets (typically partner/team data).

Example:true

Override collection setting: include shared targets in scope. When true, includes relationships involving shared targets (typically partner/team data).

scopePublicboolean

Override collection setting: include public targets in scope. When true, includes relationships involving public targets (typically open/public data).

Override collection setting: include public targets in scope. When true, includes relationships involving public targets (typically open/public data).

sourceCustomerboolean

Override collection setting: include customer data sources. When true, includes relationships derived from customer-provided data.

Example:true

Override collection setting: include customer data sources. When true, includes relationships derived from customer-provided data.

sourceCustomsboolean

Override collection setting: include customs data sources. When true, includes relationships derived from customs/shipment data (most reliable source).

Example:true

Override collection setting: include customs data sources. When true, includes relationships derived from customs/shipment data (most reliable source).

sourceMediaboolean

Override collection setting: include media data sources. When true, includes relationships derived from media/news sources (may be less reliable).

Override collection setting: include media data sources. When true, includes relationships derived from media/news sources (may be less reliable).

sourcePrewavePredictionboolean

Override collection setting: include Prewave prediction data sources. When true, includes AI-predicted relationships with probability scores.

Example:true

Override collection setting: include Prewave prediction data sources. When true, includes AI-predicted relationships with probability scores.

minShipmentsinteger

Override collection setting: minimum number of shipments required for a relationship to be included. Higher values filter out less established relationships. Range: 0+.

Example:10

Override collection setting: minimum number of shipments required for a relationship to be included. Higher values filter out less established relationships. Range: 0+.

probabilityinteger

Override collection setting: minimum probability threshold for predicted relationships. Range: 0-100. Higher values return only high-confidence predictions.

Example:80

Override collection setting: minimum probability threshold for predicted relationships. Range: 0-100. Higher values return only high-confidence predictions.

shipmentsPeriodFromstring

Override collection setting: start date for shipment period analysis. Format: YYYY-MM-DD. Only relationships with shipments in this period are considered.

Example:2024-06-01

Override collection setting: start date for shipment period analysis. Format: YYYY-MM-DD. Only relationships with shipments in this period are considered.

shipmentsPeriodTostring

Override collection setting: end date for shipment period analysis. Format: YYYY-MM-DD. Only relationships with shipments in this period are considered.

Example:2024-11-30

Override collection setting: end date for shipment period analysis. Format: YYYY-MM-DD. Only relationships with shipments in this period are considered.

suspectedSuppliersboolean

Override collection setting: include suspected suppliers. When true, includes suppliers flagged as potentially risky or suspicious.

Override collection setting: include suspected suppliers. When true, includes suppliers flagged as potentially risky or suspicious.

logisticsProviderboolean

Override collection setting: include logistics providers. When true, includes companies that provide logistics services rather than direct suppliers.

Override collection setting: include logistics providers. When true, includes companies that provide logistics services rather than direct suppliers.

Response

Successfully retrieved tier-n collection supplier graph.

tierinteger required

Tier level. Membership rows: always 1. Traversal rows: relative to each collection member (1 = that member's direct suppliers, 2+ = indirect). For traversal rows this is not the same as the request tier parameter (which selects membership-only vs membership+traversal / max depth).

supplierTargetIdinteger required

Unique identifier of the supplier target in this relationship. Use this ID to look up additional supplier information via other APIs.

customerTargetIdinteger required

Unique identifier of the customer target in this relationship. The 'from' side of the relationship (customer organization for membership rows; upstream target for traversal rows).

source'Customer' | 'Media' | 'Customs' | 'PrewavePrediction'
probabilityinteger nullable

Confidence or probability score for the relationship (0-100). Only present for PREWAVE_PREDICTION sources. Higher values indicate more confident predictions.

mediaSourcesstring[] nullable

List of media source URLs used to derive this MEDIA-type relationship. Only present when source=MEDIA and includeMediaSources=true. These URLs provide evidence for the relationship.

nShipmentsinteger nullable

Number of shipments observed for this supplier/customer pair. Only present for CUSTOMS sources. Indicates the strength of the business relationship based on trade data.

nshipmentsinteger

Example response

[
  {
    "tier": 2,
    "supplierTargetId": 4567,
    "customerTargetId": 1234,
    "probability": 87,
    "mediaSources": [
      "https://example.com/article-1",
      "https://example.com/article-2"
    ],
    "nShipments": 3,
    "shipments": {
      "hscode": 847330,
      "nShipments": 5,
      "lastShipment": "2024-03-15"
    }
  }
]