API

2026

March-16

• Added risk factors changelog
• Updated rate limits

2025

August-27

Deprecation: /v1/sources endpoints

• The GET /v1/sources/ endpoint has been deprecated and replaced by GET /v1/ontology/sources endpoint

June-17

Deprecation: Relationship former field

The boolean former field on relationship objects is being deprecated in favor of the new relationship_status enum field (active, inactive, unknown). Both fields will be returned during the deprecation period for backwards compatibility. The former field will be removed on or after October 17, 2025.

June-13

Q2.5 Release - Supply Chain Enhancements

Supply Chain Traversal Response Format Update

We’ve redesigned the supply chain traversal response format to improve clarity, reduce payload size, and enhance developer experience based on user feedback.

Affected Endpoints

• GET Project Entity Supply Chain
• GET Upstream Trade Traversal

What’s Changed

1. Intuitive Path Structure - Path segments now show the supplier entity and components they ship, following a logical supplier → buyer flow

2. Clearer Terminology - Renamed products → components throughout the response to eliminate confusion

3. Optimized Payload Structure - Entity data moved to a separate entities lookup object, significantly reducing response size and duplication

4. New Tier-Specific Filtering - Added granular shipment country filters for each tier level:

   • tier1_shipment_country - Filter by tier 1 shipment countries
   • tier2_shipment_country - Filter by tier 2 shipment countries
   • tier3_shipment_country - Filter by tier 3 shipment countries
   • tier4_shipment_country - Filter by tier 4 shipment countries
   • tier5_shipment_country - Filter by tier 5 shipment countries

   Each filter accepts a list of country codes to match shipments at the specified tier level. These filters are only supported for the GET Project Entity Supply Chain.

New Supply Chain Summary Endpoint

• GET Project Entity Supply Chain Summary

This endpoint provides aggregated summaries of upstream supply chain data, designed for simplified integration and analysis without requiring complex post-processing.

Key Features

• Aggregated Risk Analysis - Risk factors grouped by Risk Categories, with factors appearing in multiple categories included in all relevant groups
• Departure Country Summary - De-duplicated list of all departure countries from upstream supply chain edges, focusing on origin countries where goods are shipped from
• Component Overview - Complete list of unique HS codes present in the upstream supply chain

Project Entity Response Object Update

The project entity response object now includes summary level information for the project entity match group:

Affected Endpoints

• POST Create Project Entity
• GET Project Entities
• GET Project Entity

Summary Fields

• countries - Countries associated with the entity
• direct_risk_factors - Direct risk factors for the entity
• upstream_countries - Countries in the upstream supply chain
• upstream_risk_factors - Risk factors from upstream entities
• upstream_products - Products/components in the upstream supply chain

This summary level information enables developers to get a comprehensive understanding of Project Entities’ risk and upstream supply chain profile.

May-01

Project and Notification Endpoints Updates

We’ve deprecated project content endpoints including all notification endpoints, and will release a replacement for these with a more friendly and powerful interface.

We will continue supporting these endpoints for a period of 30 days of deprecation. Upon reaching the sunset date of June 1 2025, we may stop accepting requests made to them.

Deprecated endpoints:

• /v1/projects/{id}/contents/entity
• /v1/notifications/*

April-03

Traversal Response Updates

We’ve deprecated the watchlist field on the response of the traversal endpoints (v1/traversal/*). This field no longer provides value because its value is always false. We will continue including it in responses for a period of 30 days of deprecation. Upon reaching the sunset date of May 15 2025, we will stop including it in responses.

2024

November-06

Match Resolution Updates

Overview

We’ve enhanced our resolution endpoint with improved address matching capabilities and introduced configurable parameters that allow developers to fine-tune matching behavior for specific client requirements. See our Resolution API Reference for details.

Address Matching Improvements

• Added match_quality enum field (high/medium/low) in response
• Implemented new geocoding-based matching logic:
  • Input addresses are geocoded to (x,y) coordinates
  • Spatial analysis used to identify and rank potential matches
  • Provides more accurate location-based validation

Match Tuning Parameters

minimum_score_threshold

• Controls match strictness.
• When to use: Adjust this parameter when you need to balance between match precision and recall. Increase when accuracy is critical, decrease when you want to capture more potential matches.

search_fallback

• Falls back to name-only entity search when the corporate or supplier profile matching fails to find a match.
• When to use: Enable this feature when dealing with incomplete or varying quality data sources, or when maximizing match coverage is more important than strict profile matching.

cutoff_threshold

• Controls similar results window in match groups.
• When to use: Adjust this when dealing with ambiguous entities or when you need to control the trade-off between match precision and recall. Lower the threshold when seeing more potential matches is valuable.

skip_post_processing

• Bypasses the post-processing setps and re-ranking.
• When to use: Enable this during development and testing phases to understand raw match results, useful for debugging results.

August-27

Added new filter parameters to trade/search

• product_origin
• supplier_city
• supplier_state
• buyer_city
• buyer state
• transit_country

August-06

Added entity resolution documentation to the Sayari Library.

July-24

We’ve enhanced the project notifications with a new risk_notifications object. This object provides a clear view of changes in risk notifications for each entity.

• added: Array of newly added risk notifications
• removed: Array of risk notifications no longer applicable
• date: Timestamp of the notification change

1
{
2
  "entity_id": "vnOScfTpsCFA-CH3X1ME0w",
3
  "resource_id": "0kJNw8",
4
  "custom_fields": {},
5
  "risk_notifications": {
6
    "added": [
7
      "exports_bis_high_priority_items_indirect",
8
      "meu_list_contractors"
9
    ],
10
    "removed": [
11
      "forced_labor_xinjiang_origin_subtier"
12
    ],
13
    "date": "2024-07-23T00:00:00.000Z"
14
  }
15
}

July-19

New Product Blueprint Sub-Tier Trade History Risk Factors

We are excited to announce the release of five new beta trade history risk factors for API & Bulk Data users. These risk factors are precomputed utilizing our proprietary product blueprints to more accurately identify relevant sub-tier supplier forced labor risk. The new risk factors will be available in addition to the legacy ones, operating as a subset.

Compared to their legacy ones, the new risk factors backed by product blueprints offer:

• Increased relevance by identifying sub-tier suppliers that received the same or similar goods originally shipped from an entity associated with forced labor risk
• Reduced noise via ~80% fewer false positives
• Risk information (called origin_shipment_product) indicating the type of good initially shipped from the origin entity associated with risk

For more details visit our Risk Factor Documentation

Rate Limits Updated

We have shifted to a tiered rate limiting system — see Rate Limit Documentation for details.

June-25

Q2.2024 Release

Beta Updates

• Updated the upstream supply chain mapping endpoint, which can be used to access Sayari Map functionality via API. It is now /supply_chain/upstream, and the response structure, is similar to that of a traversal.
• Released /resolution/persisted. And endpoint to support a single request to resolve, save and assign attributes to entities in projects for the purposes of notifications.
• Updated project notifications to allowing sorting in descending order.

Deprecation & Sunset Updates

• shipment entities sunset from Entity Search. Utilize Trade Search - Shipments going forward.
• shipper_of and receiver_of sunset from the relationship_type object within the EmbeddedEntity data type. Utilize the trade_count object going forward.

May-07

Deprecation Notice: Shipments - EmbeddedEntity & Entity Search

Effective: June 25th, 2024, the following changes will occur:

EmbeddedEntity Modifications

• The relationship_type object within EmbeddedEntity will no longer include shipper_of and receiver_of relationship types.
• Instead, API users should reference the new trade_count object within EmbeddedEntity to analyze the volume of shipments sent and received by an entity.

Affected Endpoints (with EmbeddedEntity in the response)

• Entity Search
• Entity
• Entity Summary
• Traversals

1
{
2
    "relationship_count": {
3
        "shipper_of": 969,
4
        "receiver_of": 109,
5
        "ships_to": 75,
6
        "receives_from": 26,
7
        "notify_party_of": 59
8
    },
9
}

1
{
2
    "trade_count": {
3
        "sent": 969,
4
        "received": 109
5
    },
6
}

Entity Search Endpoint Changes

Entity Search will no longer return entity type shipment in the response. Instead, if the desire is to search for and return shipments, we encourage API users to adopt the new Trade Endpoints, which are designed to offer enhanced capabilities for searching and analyzing trade data, suitable for both investigative and supply-chain use cases.

Trade Endpoints:

• Trade Search - Shipments
• Trade Search - Suppliers
• Trade Search - Buyers

For detailed guidance on how to transition and take advantage of the new Trade Endpoints, we recommend visiting our guides:

• Guide: Trade Search - Shipments
• Guide: Trade Search - Suppliers & Buyers

Beta Documentation Update

Added API Reference documentation for the following beta endpoints:

Save to Projects and Notifications

• Attributes
• Project
• Resource
• Notifications

Upstream Supply Chain

• Upstream

Additional Documentation Updates

• Rate Limits updated.
• Risk Factors documentation updated to improve the developer experience.
• Added limit as a query-parameter for the Resolution endpoint. Default is set to the max of 10. Requesting a lower limit, will reduce the number of matched entities.

March-08

Fern developer documentation launch

• We’re proud to announce the launch of our new developer documentation with Fern 🌱! Check out our new API reference documentation, client libraries and more. We’ll be sun setting our previous docs site docs.sayari.com on April 5th, 2024. If you have any feedback, let us know by clicking on Was this page helpful? At the bottom of the page.

March-01

Traversal Limit Update

• In our ongoing effort to maintain optimal performance and stability for our API clients, we have set the maximum offset limit to 1,000 paths. Per request, the default limit remains the same 20, with a max of 50.

February-09

Sunset Notice - v0 Endpoints

• v0 endpoints are officially sunset. See v0 Migration Guide for details.

2023

November-11

Trade Search Beta

• We’re excited to announce the launch of our Beta program for the Trade Search API. To gain early access and help shape its development, please get in touch with your account representative.

October-10

Deprecation Notice - v0 Endpoints**

• v0 endpoints are now deprecated and will be sunset on 2024-02-09. See v0 Migration Guide for details. Please contact your account representative if you have any questions.g