Implementation Patterns

Project Entity Supply Chain Screening

Summary

The Sayari API helps you monitor and assess risks in your global supply chain by:

  • Matching your suppliers against Sayari’s knowledge graph
  • Mapping multi-tier supply chain relationships
  • Identifying potential risks (direct, and indirect via upstream network effects)
  • Tracking upstream product flows through HS codes and Sayari’s Product Blueprint technology
  • Monitoring risk changes over time with notifications for added or removed risks

5-Minute Quick Start

What You’ll Build

A simple supply chain monitor that checks a single supplier for risks.

Prerequisites

  • Your API credentials (client_id and client_secret)
  • A supplier to check (name, address, country)
1

Get Your Access Token

First, authenticate with the Sayari API to get a bearer token.

Request

client_idstringRequired
client_secretstringRequired
audience"sayari.com"Required
grant_type"client_credentials"Required

Response

access_tokenstringRequired
The bearer token you will pass in to subsequent API calls to authenticate.
expires_inintegerRequired
Tells you how long (in seconds) until your bearer token expires.
token_typestringRequired
Will always be "Bearer"
POST
/oauth/token
1from sayari import Sayari
2
3client = Sayari(
4    client_id="YOUR_CLIENT_ID",
5    client_secret="YOUR_CLIENT_SECRET",
6)
7client.auth.get_token(
8    client_id="your client_id here",
9    client_secret="your client_secret here",
10)
Response
1{
2  "access_token": "sk_test_4eC39HqLyjWDarjtT1zdp7dc",
3  "expires_in": 86400,
4  "token_type": "Bearer"
5}

Token expires in 24 hours - Store it securely and reuse it

2

Create a Project

Create a project container to organize your supplier entities.

Request

labelstringRequired
shareobjectOptional
Specifies access levels available to users in a project within an organization. For comprehensive access, the admin role is recommended.

Response

dataobjectRequired
POST
/v1/projects
1from sayari import Sayari
2from sayari.project import CreateProjectRequest, ProjectShareOnCreate
3
4client = Sayari(
5    client_id="YOUR_CLIENT_ID",
6    client_secret="YOUR_CLIENT_SECRET",
7)
8client.project.create_project(
9    request=CreateProjectRequest(
10        label="My First Project",
11        share=ProjectShareOnCreate(
12            org="admin",
13        ),
14    ),
15)
Response
1{
2  "data": {
3    "id": "0pjjaB",
4    "label": "My First Project",
5    "archived": false,
6    "created": "2025-08-26 03:17:58.70405+00",
7    "updated": "2025-08-26 03:17:58.70405+00",
8    "counts": {
9      "entity": 0,
10      "graph": 0,
11      "search": 0,
12      "record": 0
13    },
14    "is_scrm": false
15  }
16}

Key Response Fields:

  • id: this is the project_id we’ll reference this key in the following requests
3

Add Your First Supplier

Match your supplier against Sayari’s database to identify potential risks.

Read our Understanding Project Entity guide to familiarize yourself with the core concepts of Project Entities.

To retrieve additional risk metadata such as descriptions, utilize the Get Risk Factors endpoint.

Path parameters

project_idstringRequired

Request

identifierlist of strings or integers or doublesOptional
namelist of stringsOptional
countrylist of enumsOptional
addresslist of stringsOptional
date_of_birthlist of stringsOptional
contactlist of strings or integers or doublesOptional
typelist of enumsOptional
citylist of stringsOptional
statelist of stringsOptional
profileenumOptional
Allowed values:

Response

dataobjectRequired
POST
/v1/projects/:project_id/entities/create
1from sayari import Sayari
2from sayari.project_entity import CreateResolvedProjectEntityRequest
3
4client = Sayari(
5    client_id="YOUR_CLIENT_ID",
6    client_secret="YOUR_CLIENT_SECRET",
7)
8client.project_entity.create_project_entity(
9    project_id="0n4473",
10    request=CreateResolvedProjectEntityRequest(
11        name=["Marvel Garment"],
12        country=["KHM"],
13        address=[
14            "Beung Thom 3 Village, Sangkat Beung Thom, Posenchey, Phnom Penh"
15        ],
16    ),
17)
Response
1{
2  "data": {
3    "project_entity_id": "R3BEv8",
4    "project_id": "0n4473",
5    "label": "Marvel Garment",
6    "upload_ids": [],
7    "strength": "strong",
8    "created_at": "2025-08-26 00:29:10.514803+00",
9    "attributes": {
10      "name": {
11        "resolve": true,
12        "values": [
13          "Marvel Garment"
14        ]
15      },
16      "country": {
17        "resolve": true,
18        "values": [
19          "KHM"
20        ]
21      },
22      "address": {
23        "resolve": true,
24        "values": [
25          "Beung Thom 3 Village, Sangkat Beung Thom, Posenchey, Phnom Penh"
26        ]
27      }
28    },
29    "countries": [
30      "MAC",
31      "KHM",
32      "USA",
33      "COL",
34      "HKG",
35      "CAN"
36    ],
37    "risk_categories": [
38      {
39        "id": "forced_labor",
40        "label": "Forced labor",
41        "risk_factors": [
42          "psa_forced_labor_uflpa_origin_subtier",
43          "psa_forced_labor_xinjiang_origin_subtier",
44          "forced_labor_sheffield_hallam_university_reports_origin_subtier",
45          "psa_forced_labor_wro_origin_subtier",
46          "psa_forced_labor_sheffield_hallam_university_reports_origin_subtier",
47          "forced_labor_uflpa_origin_subtier",
48          "forced_labor_xinjiang_origin_subtier",
49          "psa_forced_labor_aspi_origin_subtier",
50          "exports_ilab_forced_labor",
51          "psa_exports_ilab_child_labor",
52          "exports_ilab_child_labor",
53          "psa_exports_ilab_forced_labor"
54        ]
55      },
56      {
57        "id": "environmental_risk",
58        "label": "Environmental risk",
59        "risk_factors": [
60          "psa_exports_eudr_shipment_wood",
61          "exports_eudr_shipment_wood"
62        ]
63      }
64    ],
65    "risk_factors": [
66      {
67        "id": "psa_forced_labor_uflpa_origin_subtier"
68      },
69      {
70        "id": "psa_forced_labor_xinjiang_origin_subtier"
71      },
72      {
73        "id": "forced_labor_sheffield_hallam_university_reports_origin_subtier"
74      },
75      {
76        "id": "psa_exports_eudr_shipment_wood"
77      },
78      {
79        "id": "exports_eudr_shipment_wood"
80      },
81      {
82        "id": "psa_forced_labor_wro_origin_subtier"
83      },
84      {
85        "id": "psa_forced_labor_sheffield_hallam_university_reports_origin_subtier"
86      },
87      {
88        "id": "forced_labor_uflpa_origin_subtier"
89      },
90      {
91        "id": "forced_labor_xinjiang_origin_subtier"
92      },
93      {
94        "id": "psa_forced_labor_aspi_origin_subtier"
95      },
96      {
97        "id": "exports_ilab_forced_labor"
98      },
99      {
100        "id": "psa_exports_ilab_child_labor"
101      },
102      {
103        "id": "exports_ilab_child_labor"
104      },
105      {
106        "id": "psa_exports_ilab_forced_labor"
107      }
108    ],
109    "upstream": {
110      "risk_factors": [],
111      "countries": [],
112      "trade_counts": {
113        "receiver_of": 34,
114        "shipper_of": 58
115      },
116      "has_upstream": true,
117      "products": [
118        "6006",
119        "5808",
120        "9607",
121        "6117",
122        "6004",
123        "3506",
124        "5806",
125        "3215",
126        "6001",
127        "3926",
128        "5407",
129        "8451",
130        "9406",
131        "8308",
132        "5607",
133        "6205",
134        "2905",
135        "6105",
136        "6109",
137        "6110",
138        "4202",
139        "6203",
140        "6104",
141        "6114",
142        "6101",
143        "6111",
144        "6204",
145        "8537",
146        "6103",
147        "8452",
148        "6112",
149        "4908",
150        "6202",
151        "9506",
152        "6307",
153        "4015",
154        "6102",
155        "5515",
156        "6108",
157        "4911",
158        "4820"
159      ]
160    },
161    "tags": [],
162    "matches": [],
163    "case": "not_assigned"
164  }
165}

Key Response Fields:

  • project_entity_id: Use for supply chain queries and to reference the project entity in other API calls
  • strength: Match confidence (strong/partial/no_match)
  • risk_categories: Array of risk categories
  • risk_factors: Detailed risk identifiers
  • upstream.products: HS codes of products handled by supplier
  • has_upstream: Boolean indicating whether the supplier has upstream data
4

View Supply Chain Summary

Get a high-level overview of your supplier’s entire supply chain, including countries, risks, and products.

Path parameters

project_idstringRequired
The project Identifier
project_entity_idstringRequired
The project entity Identifier

Query parameters

productlist of stringsOptional
Product root edge filter. Filters results to include only trade relationships where the associated component is part of the specified product's blueprint or is a sub-component of that product.
-productlist of stringsOptional
Product root edge filter. Filters results to exclude any trade relationships where the associated component is part of the specified product's blueprint or is a sub-component of that product.
risk_factorslist of enumsOptional
Risk leaf node filter. Only return supply chains that end with a supplier that has 1+ of the specified risk factors.
-risk_factorslist of enumsOptional
Risk leaf node filter. Only return supply chains that end with a supplier that has none of the specified risk factors.
countrieslist of enumsOptional
Country leaf node filter. Only return supply chains that end with a supplier in 1+ of the specified countries.
-countrieslist of enumsOptional
Country leaf node filter. Only return supply chains that end with a supplier in none of the specified countries.
componentlist of stringsOptional
Component edge filter. Only return supply chains that contain at least one edge with 1+ of the specified HS codes.
-componentlist of stringsOptional
Component edge filter. Only return supply chains that contain no edges with any of the specified HS codes.
min_datestringOptional
Minimum date edge filter in <YYYY-MM-DD> format. Only return supply chains with edge dates that are greater than or equal to this date.
max_datestringOptional
Maximum date edge filter in <YYYY-MM-DD> format. Only return supply chains with edge dates that are less than or equal to this date.
max_depthintegerOptional
The maximum depth of the traversal, from 1 to 4 inclusive. Default is 4. Reduce if query is timing out.
limitintegerOptional
The maximum number of results to return. Default is no limit.

Response

filtersobjectRequired
dataobjectRequired
GET
/v1/projects/:project_id/entities/:project_entity_id/supply_chain/upstream_summary
1from sayari import Sayari
2
3client = Sayari(
4    client_id="YOUR_CLIENT_ID",
5    client_secret="YOUR_CLIENT_SECRET",
6)
7client.project_entity.project_entity_supply_chain_summary(
8    project_id="0n4473",
9    project_entity_id="yebNPJ",
10    max_depth=4,
11)
Response
1{
2  "filters": {
3    "max_depth": 4
4  },
5  "data": {
6    "project_id": "0n4473",
7    "project_entity_id": "yebNPJ",
8    "upstream": {
9      "components": [
10        "2710",
11        "5806",
12        "7320",
13        "5205",
14        "5206",
15        "5401",
16        "8507",
17        "5402",
18        "5807",
19        "9607",
20        "6004",
21        "3809",
22        "6006",
23        "9606",
24        "5509",
25        "5208",
26        "5202",
27        "2933",
28        "3215",
29        "3204",
30        "3506",
31        "3905",
32        "5201",
33        "3907"
34      ],
35      "countries": [
36        "JPN",
37        "VNM",
38        "IND",
39        "CHN",
40        "HKG",
41        "IDN",
42        "TWN",
43        "TUR",
44        "DEU",
45        "BGD",
46        "KOR",
47        "NLD",
48        "THA",
49        "BRA",
50        "LKA",
51        "MEX",
52        "TZA",
53        "PAK",
54        "ESP",
55        "USA",
56        "CIV",
57        "SGP",
58        "BEL",
59        "PHL",
60        "KHM",
61        "ITA",
62        "CHE",
63        "ISR",
64        "AUS",
65        "ZAF",
66        "CMR",
67        "MYS",
68        "SWZ",
69        "LIE",
70        "FRA",
71        "GBR",
72        "ROU",
73        "PRT",
74        "TKL",
75        "AUT",
76        "HUN",
77        "NOR",
78        "PER",
79        "CZE",
80        "ARG",
81        "NZL",
82        "BEN",
83        "BFA",
84        "PNG",
85        "LUX",
86        "RUS",
87        "FIN"
88      ],
89      "risk_categories": [
90        {
91          "id": "forced_labor",
92          "label": "Forced labor",
93          "risk_factors": [
94            "psa_forced_labor_uflpa_origin_subtier",
95            "exports_ilab_forced_labor",
96            "psa_forced_labor_xinjiang_origin_subtier",
97            "forced_labor_sheffield_hallam_university_reports_origin_subtier",
98            "psa_forced_labor_sheffield_hallam_university_reports_origin_subtier",
99            "psa_exports_ilab_forced_labor",
100            "forced_labor_uflpa_origin_subtier",
101            "psa_exports_ilab_child_labor",
102            "exports_ilab_child_labor",
103            "psa_owner_of_forced_labor_xinjiang_entity",
104            "owner_of_forced_labor_xinjiang_entity",
105            "sheffield_hallam_university_forced_labor_entity",
106            "forced_labor_xinjiang_origin_subtier",
107            "psa_forced_labor_aspi_origin_subtier",
108            "forced_labor_aspi_origin_subtier",
109            "psa_forced_labor_wro_origin_subtier",
110            "psa_owned_by_xinjiang_entity",
111            "owned_by_xinjiang_entity",
112            "psa_owner_of_sheffield_hallam_university_reports_forced_labor_entity",
113            "sheffield_hallam_university_forced_labor_reports_intermediary_entity",
114            "forced_labor_wro_origin_subtier",
115            "owned_by_sheffield_hallam_university_reports_forced_labor_entity",
116            "psa_owned_by_sheffield_hallam_university_reports_forced_labor_entity"
117          ]
118        },
119        {
120          "id": "environmental_risk",
121          "label": "Environmental risk",
122          "risk_factors": [
123            "psa_exports_eudr_shipment_wood",
124            "exports_eudr_shipment_wood",
125            "psa_exports_eudr_shipment_rubber",
126            "exports_eudr_shipment_rubber",
127            "exports_eudr_shipment_soya",
128            "psa_exports_eudr_shipment_soya",
129            "exports_eudr_shipment_palm_oil",
130            "psa_exports_eudr_shipment_palm_oil",
131            "exports_eudr_shipment_coffee",
132            "psa_exports_eudr_shipment_coffee"
133          ]
134        },
135        {
136          "id": "export_controls",
137          "label": "Export controls",
138          "risk_factors": [
139            "exports_bis_high_priority_items_indirect",
140            "psa_exports_bis_high_priority_items_indirect",
141            "exports_to_usa_bis_entity",
142            "psa_exports_to_usa_bis_entity",
143            "psa_exports_bis_high_priority_items_direct",
144            "exports_bis_high_priority_items_direct",
145            "military_end_use_china_keywords",
146            "exports_bis_high_priority_items_critical_components_direct",
147            "psa_exports_bis_high_priority_items_critical_components_direct",
148            "owner_of_export_controls_entity",
149            "owner_of_usa_bis_entity",
150            "psa_owner_of_usa_bis_entity",
151            "psa_owner_of_export_controls_entity",
152            "psa_owned_by_usa_section_1260h_entity",
153            "owned_by_usa_section_1260h_entity",
154            "meu_list_contractors",
155            "bis_boycott_requester_list",
156            "exports_bis_high_priority_items_critical_components_indirect",
157            "psa_exports_bis_high_priority_items_critical_components_indirect"
158          ]
159        },
160        {
161          "id": "sanctions",
162          "label": "Sanctions",
163          "risk_factors": [
164            "psa_exports_to_sanctioned_isr_mod_nbctf_entity",
165            "psa_exports_to_sanctioned_fra_dgt_mefids_entity",
166            "psa_exports_to_sanctioned_usa_ofac_sdn_entity",
167            "psa_exports_to_sanctioned_eu_dg_fisma_ec_entity",
168            "psa_exports_to_sanctioned_aus_dfat_entity",
169            "psa_exports_to_sanctioned_gbr_fcdo_entity",
170            "psa_exports_to_sanctioned_un_sc_entity",
171            "psa_exports_to_sanctioned_eu_ec_sanctions_map_entity",
172            "psa_exports_to_sanctioned_ukr_sfms_entity",
173            "psa_export_to_sanctioned",
174            "psa_exports_to_sanctioned_eu_ec_regulation_833_2014_entity",
175            "exports_to_sanctioned_che_seco_entity",
176            "exports_to_sanctioned_usa_ofac_sdn_entity",
177            "export_to_sanctioned",
178            "exports_to_sanctioned_ukr_nsdc_entity",
179            "exports_to_sanctioned_eu_ec_regulation_833_2014_entity",
180            "psa_exports_to_sanctioned_ukr_nsdc_entity",
181            "psa_exports_to_sanctioned_che_seco_entity",
182            "owner_of_sanctioned_entity",
183            "psa_owner_of_sanctioned_entity",
184            "owner_of_sanctioned_ukr_nsdc_entity",
185            "owner_of_sanctioned_usa_ofac_non_sdn_entity",
186            "psa_owner_of_sanctioned_ukr_nsdc_entity",
187            "psa_exports_to_sanctioned_mys_moha_entity",
188            "psa_owner_of_sanctioned_usa_ofac_non_sdn_entity",
189            "exports_to_sanctioned_xxx_ebrd_entity",
190            "psa_exports_to_sanctioned_xxx_ebrd_entity",
191            "psa_exports_to_sanctioned_jpn_mof_entity",
192            "exports_to_sanctioned_eu_dg_fisma_ec_entity",
193            "exports_to_sanctioned_can_gac_entity",
194            "psa_exports_to_sanctioned_can_gac_entity",
195            "exports_to_sanctioned_gbr_fcdo_entity",
196            "exports_to_sanctioned_fra_dgt_mefids_entity",
197            "exports_to_sanctioned_jpn_mof_entity",
198            "exports_to_sanctioned_eu_ec_sanctions_map_entity"
199          ]
200        },
201        {
202          "id": "political_exposure",
203          "label": "Political exposure",
204          "risk_factors": [
205            "psa_export_to_soe",
206            "export_to_soe",
207            "owned_by_chinese_soe",
208            "psa_owned_by_soe",
209            "psa_owned_by_chinese_soe",
210            "owned_by_soe",
211            "psa_owner_of_soe",
212            "psa_export_to_chinese_soe",
213            "owner_of_soe",
214            "export_to_chinese_soe",
215            "owner_of_chinese_soe",
216            "psa_owner_of_chinese_soe"
217          ]
218        },
219        {
220          "id": "adverse_media",
221          "label": "Adverse media",
222          "risk_factors": [
223            "reputational_risk_other",
224            "law_enforcement_action",
225            "reputational_risk_financial_crime"
226          ]
227        },
228        {
229          "id": "regulatory_action",
230          "label": "Regulatory action",
231          "risk_factors": [
232            "law_enforcement_action",
233            "regulatory_action",
234            "psa_owner_of_regulatory_action_entity",
235            "owner_of_regulatory_action_entity"
236          ]
237        }
238      ]
239    }
240  }
241}

Response contains:

  • upstream.countries: All countries in supply chain
  • upstream.risk_categories: Categorized risks with factors
  • upstream.components: Product HS codes present
5

Get Detailed Supply Chain Paths

Retrieve specific supply chain paths with detailed trade relationships, dates, and locations.

Path parameters

project_idstringRequired
The project Identifier
project_entity_idstringRequired
The project entity Identifier

Query parameters

productlist of stringsOptional
Product root edge filter. Filters results to include only trade relationships where the associated component is part of the specified product's blueprint or is a sub-component of that product.
-productlist of stringsOptional
Product root edge filter. Filters results to exclude any trade relationships where the associated component is part of the specified product's blueprint or is a sub-component of that product.
risklist of enumsOptional
Risk leaf node filter. Only return supply chains that end with a supplier that has 1+ of the specified risk factors.
-risklist of enumsOptional
Risk leaf node filter. Only return supply chains that end with a supplier that has none of the specified risk factors.
countrieslist of enumsOptional
Country leaf node filter. Only return supply chains that end with a supplier in 1+ of the specified countries.
-countrieslist of enumsOptional
Country leaf node filter. Only return supply chains that end with a supplier in none of the specified countries.
shipment_countrylist of enumsOptional
Filters supply chain paths where 1+ shipment country from any tier matches the provided values.
-shipment_countrylist of enumsOptional
Filters supply chain paths where none of the shipment countries from any tier matches the provided values.
tier1_shipment_countrylist of enumsOptional
Filters supply chain paths where 1+ shipment country from tier 1 matches the provided values.
tier2_shipment_countrylist of enumsOptional
Filters supply chain paths where 1+ shipment country from tier 2 matches the provided values.
tier3_shipment_countrylist of enumsOptional
Filters supply chain paths where 1+ shipment country from tier 3 matches the provided values.
tier4_shipment_countrylist of enumsOptional
Filters supply chain paths where 1+ shipment country from tier 4 matches the provided values.
tier5_shipment_countrylist of enumsOptional
Filters supply chain paths where 1+ shipment country from tier 5 matches the provided values.
componentlist of stringsOptional
Component edge filter. Only return supply chains that contain at least one edge with 1+ of the specified HS codes.
-componentlist of stringsOptional
Component edge filter. Only return supply chains that contain no edges with any of the specified HS codes.
min_datestringOptional
Minimum date edge filter in <YYYY-MM-DD> format. Only return supply chains with edge dates that are greater than or equal to this date.
max_datestringOptional
Maximum date edge filter in <YYYY-MM-DD> format. Only return supply chains with edge dates that are less than or equal to this date.
max_depthintegerOptional
The maximum depth of the traversal, from 1 to 4 inclusive. Default is 4. Reduce if query is timing out.
limitintegerOptional
The maximum number of results to return. Default is no limit.

Response

filtersobjectRequired
dataobjectRequired
explored_countintegerRequired
Number of hops explored in the traversal
partial_resultsbooleanRequired
True if the traversal returned partial results
statusintegerOptional
successbooleanOptional
messagestringOptional
GET
/v1/projects/:project_id/entities/:project_entity_id/supply_chain/upstream
1from sayari import Sayari
2
3client = Sayari(
4    client_id="YOUR_CLIENT_ID",
5    client_secret="YOUR_CLIENT_SECRET",
6)
7client.project_entity.project_entity_supply_chain(
8    project_id="0n4473",
9    project_entity_id="yebNPJ",
10    product=["6004"],
11    limit=1,
12)
Response
1{
2  "filters": {
3    "product": [
4      "6004"
5    ],
6    "limit": 1
7  },
8  "data": {
9    "paths": [
10      {
11        "source_entity_id": "e0WEtIhAvDUjWs-hg12jSA",
12        "path": [
13          {
14            "tier": 2,
15            "entity_id": "bWbImzpaFHN-4tj9n8JXzg",
16            "components": [
17              {
18                "hs_code": "6004",
19                "arrival_countries": [
20                  "KHM"
21                ],
22                "departure_countries": [
23                  "VNM"
24                ],
25                "min_date": "2023-01-01",
26                "max_date": "2024-12-31"
27              }
28            ]
29          },
30          {
31            "tier": 3,
32            "entity_id": "_jCU70ygP5Vx0kheGGxniw",
33            "components": [
34              {
35                "hs_code": "5402",
36                "arrival_countries": [
37                  "VNM"
38                ],
39                "departure_countries": [
40                  "VNM"
41                ],
42                "min_date": "2023-01-01",
43                "max_date": "2025-01-17"
44              }
45            ]
46          },
47          {
48            "tier": 4,
49            "entity_id": "dRvTdx1af-XrFqh9L3Y4-Q",
50            "components": [
51              {
52                "hs_code": "3907",
53                "arrival_countries": [
54                  "VNM"
55                ],
56                "departure_countries": [
57                  "JPN"
58                ],
59                "min_date": "2023-01-16",
60                "max_date": "2025-01-24"
61              }
62            ]
63          },
64          {
65            "tier": 5,
66            "entity_id": "FFXyR4N57IZuQDTH2pzYTQ",
67            "components": [
68              {
69                "hs_code": "2909",
70                "arrival_countries": [
71                  "JPN"
72                ],
73                "departure_countries": [
74                  "USA"
75                ],
76                "min_date": "2023-06-24",
77                "max_date": "2023-08-11"
78              }
79            ]
80          }
81        ]
82      }
83    ],
84    "entities": {
85      "FFXyR4N57IZuQDTH2pzYTQ": {
86        "id": "FFXyR4N57IZuQDTH2pzYTQ",
87        "type": "company",
88        "label": "Dow Chemical Co",
89        "risk_factors": [
90          "law_enforcement_action",
91          "psa_forced_labor_xinjiang_origin_subtier",
92          "reputational_risk_other",
93          "reputational_risk_financial_crime",
94          "forced_labor_xinjiang_origin_subtier",
95          "regulatory_action",
96          "psa_forced_labor_aspi_origin_subtier"
97        ],
98        "countries": [
99          "BEL",
100          "CAN",
101          "ECU",
102          "USA"
103        ]
104      },
105      "dRvTdx1af-XrFqh9L3Y4-Q": {
106        "id": "dRvTdx1af-XrFqh9L3Y4-Q",
107        "type": "company",
108        "label": "NAGASE & CO LTD",
109        "risk_factors": [
110          "psa_forced_labor_uflpa_origin_subtier",
111          "exports_ilab_forced_labor",
112          "psa_forced_labor_xinjiang_origin_subtier",
113          "psa_export_to_soe",
114          "forced_labor_sheffield_hallam_university_reports_origin_subtier",
115          "psa_forced_labor_sheffield_hallam_university_reports_origin_subtier",
116          "psa_exports_ilab_forced_labor",
117          "forced_labor_uflpa_origin_subtier",
118          "forced_labor_xinjiang_origin_subtier",
119          "psa_forced_labor_aspi_origin_subtier"
120        ],
121        "countries": [
122          "BRA",
123          "CAN",
124          "CHN",
125          "DEU",
126          "ESP",
127          "GBR",
128          "ISR",
129          "JPN",
130          "KOR",
131          "NLD",
132          "SGP",
133          "TCD",
134          "THA",
135          "TUR",
136          "TWN",
137          "USA",
138          "VNM"
139        ]
140      },
141      "_jCU70ygP5Vx0kheGGxniw": {
142        "id": "_jCU70ygP5Vx0kheGGxniw",
143        "type": "company",
144        "label": "CôNG TY TRáCH NHIệM HữU HạN HYOSUNG VIệT NAM",
145        "risk_factors": [
146          "psa_forced_labor_uflpa_origin_subtier",
147          "exports_ilab_forced_labor",
148          "psa_forced_labor_xinjiang_origin_subtier",
149          "eu_high_risk_third",
150          "psa_export_to_soe",
151          "forced_labor_sheffield_hallam_university_reports_origin_subtier",
152          "psa_exports_ilab_child_labor",
153          "psa_exports_eudr_shipment_wood",
154          "exports_eudr_shipment_wood",
155          "psa_exports_eudr_shipment_rubber",
156          "exports_ilab_child_labor",
157          "psa_forced_labor_sheffield_hallam_university_reports_origin_subtier",
158          "psa_exports_ilab_forced_labor",
159          "exports_eudr_shipment_rubber",
160          "forced_labor_uflpa_origin_subtier",
161          "export_to_soe",
162          "forced_labor_xinjiang_origin_subtier",
163          "psa_forced_labor_aspi_origin_subtier"
164        ],
165        "countries": [
166          "ARE",
167          "ARG",
168          "AUT",
169          "BEL",
170          "BRA",
171          "CHE",
172          "CHN",
173          "CYP",
174          "CZE",
175          "DEU",
176          "ECU",
177          "ESP",
178          "FIN",
179          "FRA",
180          "GBR",
181          "GEO",
182          "GRC",
183          "HKG",
184          "HUN",
185          "IDN",
186          "IND",
187          "ITA",
188          "JPN",
189          "KHM",
190          "KOR",
191          "LTU",
192          "LUX",
193          "LVA",
194          "MEX",
195          "MYS",
196          "NAM",
197          "PHL",
198          "POL",
199          "PRT",
200          "ROU",
201          "SAU",
202          "SEN",
203          "SGP",
204          "SRB",
205          "SVN",
206          "SWE",
207          "THA",
208          "TUR",
209          "TWN",
210          "USA",
211          "VIR",
212          "VNM"
213        ]
214      },
215      "bWbImzpaFHN-4tj9n8JXzg": {
216        "id": "bWbImzpaFHN-4tj9n8JXzg",
217        "type": "company",
218        "label": "Công ty TNHH GAIN LUCKY (Việt Nam)",
219        "risk_factors": [
220          "psa_forced_labor_uflpa_origin_subtier",
221          "exports_ilab_forced_labor",
222          "psa_forced_labor_xinjiang_origin_subtier",
223          "eu_high_risk_third",
224          "sheffield_hallam_university_forced_labor_reports_intermediary_entity",
225          "forced_labor_sheffield_hallam_university_reports_origin_subtier",
226          "psa_exports_ilab_child_labor",
227          "psa_exports_eudr_shipment_wood",
228          "exports_eudr_shipment_wood",
229          "exports_ilab_child_labor",
230          "psa_forced_labor_sheffield_hallam_university_reports_origin_subtier",
231          "psa_exports_ilab_forced_labor",
232          "forced_labor_uflpa_origin_subtier",
233          "forced_labor_xinjiang_origin_subtier",
234          "psa_forced_labor_aspi_origin_subtier"
235        ],
236        "countries": [
237          "CHE",
238          "CHN",
239          "DEU",
240          "GEO",
241          "HKG",
242          "JPN",
243          "KHM",
244          "KOR",
245          "THA",
246          "VIR",
247          "VNM"
248        ]
249      },
250      "e0WEtIhAvDUjWs-hg12jSA": {
251        "id": "e0WEtIhAvDUjWs-hg12jSA",
252        "type": "company",
253        "label": "MARVEL GARMENT CO LTD",
254        "risk_factors": [
255          "psa_forced_labor_uflpa_origin_subtier",
256          "exports_ilab_forced_labor",
257          "psa_forced_labor_xinjiang_origin_subtier",
258          "eu_high_risk_third",
259          "forced_labor_sheffield_hallam_university_reports_origin_subtier",
260          "psa_exports_ilab_child_labor",
261          "psa_exports_eudr_shipment_wood",
262          "exports_eudr_shipment_wood",
263          "exports_ilab_child_labor",
264          "psa_forced_labor_wro_origin_subtier",
265          "psa_forced_labor_sheffield_hallam_university_reports_origin_subtier",
266          "psa_exports_ilab_forced_labor",
267          "forced_labor_uflpa_origin_subtier",
268          "forced_labor_xinjiang_origin_subtier",
269          "psa_forced_labor_aspi_origin_subtier"
270        ],
271        "countries": [
272          "CAN",
273          "COL",
274          "HKG",
275          "KHM",
276          "MAC",
277          "USA"
278        ]
279      }
280    }
281  },
282  "explored_count": 70357,
283  "partial_results": false
284}
6

Monitor Risk Changes

Track risk changes on your monitored entities by polling the notifications endpoint.

Path parameters

idstringRequired
Unique identifier of the project

Query parameters

limitintegerOptional
Limit total notifications in the response. Defaults to 100.
offsetintegerOptional
Offset which notifications are returned. Defaults to 0.
sortenumOptional
Defines a sort order on a field. The value should begin with a '-' to indicate a descending sort, followed by a field name to sort on.
Allowed values:

Response

nextbooleanRequired
datalist of objectsRequired
sizeobjectRequired
GET
/v1/notifications/projects/:id
1from sayari import Sayari
2
3client = Sayari(
4    client_id="YOUR_CLIENT_ID",
5    client_secret="YOUR_CLIENT_SECRET",
6)
7client.notifications.project_notifications(
8    id="0dLeO0",
9    limit=20,
10)
Response
1{
2  "next": false,
3  "data": [
4    {
5      "resource_id": "olxQPZ",
6      "entity_id": "IoKwj2-82wwzZRlFA1htGQ",
7      "notifications": [
8        {
9          "type": "risk",
10          "field": "exports_ilab_child_labor",
11          "values": [
12            "false"
13          ],
14          "date": "2025-06-04T00:00:00.000Z"
15        },
16        {
17          "type": "risk",
18          "field": "exports_ilab_forced_labor",
19          "values": [
20            "false"
21          ],
22          "date": "2025-06-04T00:00:00.000Z"
23        },
24        {
25          "type": "risk",
26          "field": "forced_labor_xinjiang_origin_subtier",
27          "values": [
28            "3"
29          ],
30          "date": "2025-06-04T00:00:00.000Z"
31        },
32        {
33          "type": "risk",
34          "field": "psa_exports_ilab_child_labor",
35          "values": [
36            "false"
37          ],
38          "date": "2025-06-04T00:00:00.000Z"
39        },
40        {
41          "type": "risk",
42          "field": "psa_exports_ilab_forced_labor",
43          "values": [
44            "false"
45          ],
46          "date": "2025-06-04T00:00:00.000Z"
47        }
48      ],
49      "risk_notifications": {
50        "added": [
51          "exports_ilab_child_labor",
52          "exports_ilab_forced_labor",
53          "psa_exports_ilab_child_labor",
54          "psa_exports_ilab_forced_labor"
55        ],
56        "removed": [
57          "forced_labor_xinjiang_origin_subtier"
58        ],
59        "date": "2025-06-04T00:00:00.000Z"
60      },
61      "custom_fields": {}
62    },
63    {
64      "resource_id": "Kx1w34",
65      "entity_id": "3oKp0fp1UE-W8BG5crAFIw",
66      "notifications": [
67        {
68          "type": "risk",
69          "field": "exports_ilab_child_labor",
70          "values": [
71            "true"
72          ],
73          "date": "2025-06-04T00:00:00.000Z"
74        },
75        {
76          "type": "risk",
77          "field": "exports_ilab_forced_labor",
78          "values": [
79            "true"
80          ],
81          "date": "2025-06-04T00:00:00.000Z"
82        },
83        {
84          "type": "risk",
85          "field": "psa_exports_ilab_child_labor",
86          "values": [
87            "true"
88          ],
89          "date": "2025-06-04T00:00:00.000Z"
90        },
91        {
92          "type": "risk",
93          "field": "psa_exports_ilab_forced_labor",
94          "values": [
95            "true"
96          ],
97          "date": "2025-06-04T00:00:00.000Z"
98        }
99      ],
100      "risk_notifications": {
101        "added": [],
102        "removed": [
103          "exports_ilab_child_labor",
104          "exports_ilab_forced_labor",
105          "psa_exports_ilab_child_labor",
106          "psa_exports_ilab_forced_labor"
107        ],
108        "date": "2025-06-04T00:00:00.000Z"
109      },
110      "custom_fields": {}
111    },
112    {
113      "resource_id": "BOMrB9",
114      "entity_id": "PF0ehzmptuJ2VJr2J5u0nw",
115      "notifications": [
116        {
117          "type": "risk",
118          "field": "export_controls_adjacent",
119          "values": [
120            "true"
121          ],
122          "date": "2025-06-14T00:00:00.000Z"
123        },
124        {
125          "type": "risk",
126          "field": "exports_bis_high_priority_items_critical_components_indirect",
127          "values": [
128            "3"
129          ],
130          "date": "2025-06-14T00:00:00.000Z"
131        }
132      ],
133      "risk_notifications": {
134        "added": [
135          "exports_ilab_child_labor",
136          "exports_ilab_forced_labor",
137          "psa_exports_ilab_child_labor",
138          "psa_exports_ilab_forced_labor"
139        ],
140        "removed": [
141          "export_controls_adjacent",
142          "exports_bis_high_priority_items_critical_components_indirect",
143          "psa_exports_bis_high_priority_items_critical_components_indirect",
144          "psa_forced_labor_uflpa_origin_subtier",
145          "psa_regulatory_action"
146        ],
147        "date": "2025-06-04T00:00:00.000Z"
148      },
149      "custom_fields": {}
150    }
151  ],
152  "size": {
153    "count": 73,
154    "qualifier": "eq"
155  }
156}

Key Response Fields:

  • resource_id: This is your project_entity_id
  • risk_notifications.added: New risks detected for the entity
  • risk_notifications.removed: Risks that have been resolved or removed
  • risk_notifications.date: When the risk change occurred

Important Notes:

  • Parse the risk_notifications array, not the notifications array
  • The resource_id field corresponds to your project_entity_id
  • Poll this endpoint on a 24-hour cadence for optimal results
  • The notifications endpoint is being enhanced but remains fully functional for production use

Complete API Workflow

UML sequence diagram showing the complete supply chain screening workflow
Complete API Workflow
1

Get Bearer Token

POST /oauth/token - Authenticate and get 24-hour access token

  • Input: client_id, client_secret, audience, grant_type
  • Output: Bearer token for API authentication
  • Expires: 24 hours (cache and reuse)
2

Create Project Container

POST /v1/projects - Create organizational container for suppliers

  • Input: Project name and sharing settings
  • Output: project_id for organizing entities
  • Purpose: Groups related supplier entities together
1

Match & Resolve Suppliers

POST /v1/projects/{project_id}/entities/create - Find and match suppliers in Sayari’s knowledge graph

Input Requirements:

  • name - Company name
  • address - Physical address
  • country - ISO country code (e.g., KHM)
  • identifier (optional) - Tax ID, registration number

Key Outputs:

  • project_entity_id - Unique identifier for API calls
  • strength - Match confidence (strong/partial/no_match)
  • risk_categories - Categorized risk factors
  • upstream.products - HS codes of products handled
1

Get Supply Chain Overview

GET /v1/projects/{project_id}/entities/{project_entity_id}/supply_chain/upstream_summary

Returns:

  • upstream.countries - All countries across supply tiers
  • upstream.risk_categories - Risk factors by category
  • upstream.components - Product HS codes present
  • Aggregated view perfect for dashboards and reporting
2

Get Detailed Trade Paths

GET /v1/projects/{project_id}/entities/{project_entity_id}/supply_chain/upstream

Returns:

  • Specific supplier-to-supplier relationships
  • Trade dates and shipment countries by tier
  • Component-level HS code flows
  • Entity details with risk factors
1

Poll for Risk Changes

GET /v1/notifications/projects/{project_id} - Check for risk changes on monitored entities

Polling Cadence:

  • Recommended: Every 24 hours
  • Maximum: Every hour (respect rate limits)

Response Processing:

  • resource_id maps to project_entity_id
  • risk_notifications.added contains new risks
  • risk_notifications.removed contains resolved risks
  • risk_notifications.date shows when changes occurred

Integration Tips:

  • Set up scheduled jobs/cron for automated polling
  • Send alerts to compliance teams for new critical risks
  • Update internal risk dashboards automatically
  • Log all risk changes for audit trails

Understanding the Response Data

Match Confidence Levels

StrengthMeaning
strongHigh confidence match
partialMedium confidence match
no_matchNo suitable match found

Risk Categories Explained

For a complete list of risk factors and their definitions, see the Risk Factor Table in our library documentation.

Risk CategoryWhat It Means
forced_laborUFLPA, Xinjiang, WRO associations
environmentalEUDR violations, deforestation
sanctionsOFAC, EU, UN sanctions
export_controlsDual-use, military end-use
regulatory_actionRegulatory violations
political_exposurePEP connections, SOE links
adverse_mediaNegative news coverage

Understanding HS Codes

HS Codes are classifications used in international trade to identify specific products and materials. For more details, see the HS Codes endpoint. The endpoint currently accepts HS Codes up to 4 digits at the sub-chapter level.

  • 6004: Knitted fabrics with elastane
  • 5201: Raw cotton
  • 3907: Polyacetals and polyesters
  • 5402: Synthetic filament yarn
  • 6001: Pile fabrics, knitted or crocheted

Interpreting Supply Chain Paths

Supply chain paths show the specific trade relationships and flow of goods from your supplier up through multiple tiers. Here’s how to read the path structure:

Each path represents a complete supply chain route from your matched supplier to upstream entities:

1{
2  "source_entity_id": "e0WEtIhAvDUjWs-hg12jSA",  // Your matched supplier
3  "path": [                      // Array of upstream connections
4    {
5      "tier": 2,                 // Supply chain tier (2-5)
6      "entity_id": "bWbImzpaFHN-4tj9n8JXzg",     // Upstream supplier ID
7      "components": [...]        // Products/materials traded
8    },
9    {
10      "tier": 3,                 // Next tier upstream
11      "entity_id": "_jCU70ygP5Vx0kheGGxniw",     // Another upstream supplier
12      "components": [...]        // Different products/materials
13    }
14  ]
15}

Supply chain tiers represent the distance from your supplier:

  • Tier 1: Your matched supplier (source_entity_id)
  • Tier 2: Direct Suppliers to your matched supplier
  • Tier 3: Suppliers to your Tier 2 suppliers
  • Tier 4: Suppliers to your Tier 3 suppliers
  • Tier 5: Suppliers to your Tier 4 suppliers

Each component represents a traded product or material:

1{
2  "hs_code": "6004",           // Product classification
3  "arrival_countries": ["KHM"], // Where goods arrived
4  "departure_countries": ["CHN"], // Where goods originated
5  "min_date": "2023-01-01",    // Earliest trade date
6  "max_date": "2024-12-31"     // Latest trade date
7}

Key Points:

  • hs_code identifies the specific product (e.g., “6004” = knitted fabrics)
  • arrival_countries shows arrival countries / areas of import
  • departure_countries shows departure countries / areas of export
  • Date range shows when these trades occurred

Example Path Interpretation:

1{
2  "source_entity_id": "e0WEtIhAvDUjWs-hg12jSA",    // Marvel Garment (Cambodia)
3  "path": [
4    {
5      "tier": 2,
6      "entity_id": "bWbImzpaFHN-4tj9n8JXzg",       // Vietnamese textile supplier
7      "components": [
8        {
9          "hs_code": "6004",       // Knitted fabrics with elastane
10          "arrival_countries": ["KHM"],  // Shipped TO Cambodia
11          "departure_countries": ["VNM"], // Shipped FROM Vietnam
12          "min_date": "2023-01-01",
13          "max_date": "2024-12-31"
14        }
15      ]
16    },
17    {
18      "tier": 3,
19      "entity_id": "_jCU70ygP5Vx0kheGGxniw",       // Vietnamese yarn supplier
20      "components": [
21        {
22          "hs_code": "5402",       // Synthetic filament yarn
23          "arrival_countries": ["VNM"],  // Shipped TO Vietnam
24          "departure_countries": ["VNM"], // Shipped FROM Vietnam (domestic)
25          "min_date": "2023-01-01",
26          "max_date": "2025-01-17"
27        }
28      ]
29    },
30    {
31      "tier": 4,
32      "entity_id": "dRvTdx1af-XrFqh9L3Y4-Q",       // Japanese chemical supplier
33      "components": [
34        {
35          "hs_code": "3907",       // Polyacetals and polyesters
36          "arrival_countries": ["VNM"],  // Shipped TO Vietnam
37          "departure_countries": ["JPN"], // Shipped FROM Japan
38          "min_date": "2023-01-16",
39          "max_date": "2025-01-24"
40        }
41      ]
42    },
43    {
44      "tier": 5,
45      "entity_id": "FFXyR4N57IZuQDTH2pzYTQ",       // US chemical company
46      "components": [
47        {
48          "hs_code": "2909",       // Chemical compounds
49          "arrival_countries": ["JPN"],  // Shipped TO Japan
50          "departure_countries": ["USA"], // Shipped FROM USA
51          "min_date": "2023-06-24",
52          "max_date": "2023-08-11"
53        }
54      ]
55    }
56  ]
57}

This tells us:

  • Marvel Garment (e0WEtIhAvDUjWs-hg12jSA) has a complex 5-tier supply chain
  • Tier 2: Sources knitted fabrics (HS 6004) from Vietnam to Cambodia
  • Tier 3: Vietnamese supplier sources synthetic yarn (HS 5402) domestically
  • Tier 4: Japanese supplier provides polyester materials (HS 3907) to Vietnam
  • Tier 5: US chemical company supplies raw chemicals (HS 2909) to Japan
  • Supply chain spans multiple countries: USA → Japan → Vietnam → Cambodia

Best Practices

  • Batch suppliers - Add multiple suppliers per project
  • Filter early - Use parameters to reduce response size
  • Store project Entity IDs - Store Project Entity Ids, they are reliable and stable
  • Be mindful of rate limits - Utilize rate limiting strategies such as exponential backoff and retry mechanisms
  • Provide identifiers - When possible, provide identifiers to return more accurate, precise matches
  • Use ISO country codes - KHM not Cambodia

Additional Resources

Last Updated: August 2025