Hit the auth endpoint to get a bearer token

Get Token

Auth

Search for an entity. Please note, searches are limited to a maximum of 10,000 results.

A limit on the number of objects to be returned with a range between 1 and 100. Defaults to 100.

Number of results to skip before returning response. Defaults to 0.

Search Entity

Query term. The syntax for the query parameter follows elasticsearch simple query string syntax. The includes the ability to use search operators and to perform nested queries. Must be url encoded.

Record or entity fields to search against.

Whether or not to return search facets in results giving counts by field. Defaults to false.

Whether or not to return search geo bound facets in results giving counts by geo tile. Defaults to false.

Set to true to enable full elasticsearch query string syntax which allows for fielded search and more complex operators. Note that the syntax is more strict and can result in empty result-sets. Defaults to false.

Search Entity GET

Search for a record. Please note, searches are limited to a maximum of 10,000 results.

Search Record

Search Record GET

Search

The resolution endpoints allow users to search for matching entities against a provided list of attributes. The endpoint is similar to the search endpoint, except it's tuned to only return the best match so the client doesn't need to do as much or any post-processing work to filter down results.

A limit on the number of objects to be returned with a range between 1 and 10. Defaults to 10.

Resolution

Resolution POST

Search Shipments

Search Suppliers

Search Buyers

Trade

Retrieve an entity from the database based on the ID

The pagination token for the next page of relationship results

The pagination token for the previous page of relationship results

Limit total relationship values. Defaults to 50.

Sorts relationships by As Of date or Shareholder percentage, e.g. date or -shares

Filters relationships to greater than or equal to a Shareholder percentage

Filters shipment relationships to an arrival state

Filters shipment relationships to an arrival city

Filters shipment relationships to a departure state

Filters shipment relationships to a departure city

Filters shipment relationships to a trade partner name

Filters shipment relationships to an HS code

The pagination token for the next page of possibly same entities.

The pagination token for the previous page of possibly same entities.

Limit total possibly same as entities. Defaults to 100.

The pagination token for the next page of the entity's referencing records

The pagination token for the previous page of the entity's referencing records

Limit totals values returned for entity's referencing records. Defaults to 100.

Get Entity

The Entity Summary endpoint returns a smaller entity payload

Entity Summary

Entity

Limit total values for traversal. Defaults to 10. Max of 50.

Offset values for traversal. Defaults to 0. Max of 1000.

Set minimum depth for traversal. Defaults to 1.

Set maximum depth for traversal. Defaults to 4.

Set relationship type(s) to follow when traversing related entities. Defaults to following all relationship types.

Also traverse relationships from entities that are possibly the same as any entity that appears in the path. Defaults to traversing possibly same as relationships.

Filter paths to only those that end at an entity of the specified type(s). Defaults to returning paths that end at any type.

Filter paths to only those that end at an entity appearing on a watchlist. Defaults to not filtering paths by sanctioned status.

Filter paths to only those that end at an entity appearing on a pep list. Defaults to not filtering paths by pep status.

Set minimum percentage of share ownership for traversal. Defaults to 0.

Include relationships that were valid in the past but not at the present time. Defaults to true.

Include entities that existed in the past but not at the present time. Defaults to false.

Filter paths to only those that entity with an entity that we have flagged with this risk factor

Traversal

The UBO endpoint returns paths from a single target entity to up to 50 beneficial owners. The endpoint is a shorthand for the equivalent traversal query.

The Ownership endpoint returns paths from a single target entity to up to 50 entities directly or indirectly owned by that entity. The endpoint is a shorthand for the equivalent traversal query.

Filter paths to only those that end at an entity associated with the specified country(ies). Defaults to returning paths that end in any country.

Ownership

The Watchlist endpoint returns paths from a single target entity to up to 50 other entities that appear on a watchlist. The endpoint is a shorthand for the equivalent traversal query.

Set relationship type(s) to follow when traversing related entities. Defaults to following 31 relevant relationship types covering ownership, control, and trade.

Include relationships that were valid in the past but not at the present time. Defaults to false.

Watchlist

The Shortest Path endpoint returns a response identifying the shortest traversal path connecting each pair of entities.

Shortest Path

Retrieve a record from the database based on the ID

The unique identifier for a record in the database

A limit on the number of references to be returned. Defaults to 100.

Number of references to skip before returning response. Defaults to 0.

Get Record

Record

Returns metadata for all sources that Sayari collects data from

List Sources

Returns metadata for a source that Sayari collects data from

The unique identifier for a source in the database

Get Source

Source

Create Project

The pagination token for the next page of projects.

The pagination token for the previous page of projects.

Limit total values returned for projects. Defaults to 100. Max 100.

Toggle between projects that have been archived (true) or not (false). Defaults to false.

Get Projects

The response format. Defaults to application/json.

The pagination token for the next page of entities.

The pagination token for the previous page of entities.

Limit total entities returned. Defaults to 1,000. Max 10,000.

Whether to include geo facets in the response. Defaults to false.

Only return entities with the specified HS code(s).

Only return entities that received the specified HS code(s).

Only return entities that shipped the specified HS code(s).

The language code to translate the entity labels to. Defaults to the user's preferred language.

Only return entities that match the specified filters.

Get Project Entities

Delete Project

Project

Save Entity

Deletes an existing saved resource from a project.

Delete Resource

Resource

Post Attribute

Patch Attribute

Delete Attribute

Attributes

Limit total notifications in the response. Defaults to 100.

Offset which notifications are returned. Defaults to 0.

Project Notifications

Resource Notifications

Deletes all notifications from a project.

Delete Project Notifications

Deletes notifications for saved resources of an entity.

Delete Entity Notifications

Deletes notifications for a saved resource.

Delete Resource Notifications

Notifications

The usage endpoint provides a simple interface to retrieve information on usage made by your API account. This includes both views per API path and credits consumed. The time period for the usage query is also specified in the response and whether or not this includes total usage.

An ISO 8601 encoded date string indicating the starting time period to obtain usage stats. In the format YYYY-MM-DD

An ISO 8601 encoded date string indicating the ending time period to obtain usage stats. In the format YYYY-MM-DD

Get Usage

The history endpoint return a user's event history.

An ISO 8601 encoded date string indicating the starting time period for the events. In the format YYYY-MM-DD

An ISO 8601 encoded date string indicating the ending time period for the events. In the format YYYY-MM-DD

Pagination token to retrieve the next page of results

Get History

Info

Country leaf node filter. Only return supply chains that end with a supplier in 1+ of the specified countries.

Country leaf node filter. Only return supply chains that end with a supplier in none of the specified countries.

Risk leaf node filter. Only return supply chains that end with a supplier that has 1+ of the specified risk factors.

Risk leaf node filter. Only return supply chains that end with a supplier that has none of the specified risk factors.

Product root edge filter. Only return supply chains that start with an edge that has 1+ of the specified HS codes.

Product root edge filter. Only return supply chains that start with an edge that has none of the specified HS codes.

Component node filter. Only return supply chains that contain at least one edge with 1+ of the specified HS codes.

Component node filter. Only return supply chains that contain no edges with any of the specified HS codes.

The maximum depth of the traversal, from 1 to 4 inclusive. Default is 4. Reduce if query is timing out.

The date range to filter the supply chain by by only considering shipments within the specified date range, inclusive. The date range is formatted as "YYYY-MM-DD|YYYY-MM-DD", where the first date is the start date and the second date is the end date. Both dates are optional, e.g. "|2022-01-01" will return all shipments up to and including 2022-01-01.

Upstream Trade Traversal

Supply Chain

AddAttribute

value of additional information in JSON format

AttributeProperties

AttributeResponse

AttributeResponseData

UpdateAttribute

AuthResponse

The bearer token you will pass in to subsequent API calls to authenticate.

Tells you how long (in seconds) until your bearer token expires.

CountQualifier

Response fields that represent unbounded collections, such as a search result or an entity's attributes or relationships, or a record's references, can all be paginated in cases where the collection is larger than can be efficiently returned in a single request.

PaginatedResponse

QualifiedCount

EntitySummaryResponse

GetEntityResponse

AdditionalInformationData

This is a generic attribute used to hold miscellaneous information not covered by any other attribute. Includes "value" (for the attribute itself), "type" (a name: e.g., "Real property description"), and "extra" (a miscellaneous field to hold any other details).

AdditionalInformationInfo

AdditionalInformationProperties

The type of additional information being conveyed

AddressData

AddressInfo

AddressProperties

For category queries like "restaurants", etc.

Any human settlement, including cities, towns, villages, hamlets, localities, etc.

Boroughs or districts within a city that serve some official purpose (e.g., "Brooklyn", "Hackney", or "Bratislava IV")

Sovereign nations and their dependent territories; anything with an ISO 3166 code

Informal subdivision of a country without any political status

Building/site name (e.g., "Brooklyn Academy of Music", "Empire State Building")

Usually refers to the external (street-facing) building number. In some jurisdictions, this may be a compound number that also includes an apartment/block number.

The language in which the address was provided in the record

Expressions indicating a floor number (e.g., "3rd Floor", "Ground Floor")

Phrases like "in", "near", etc. used after a category phrase, to help with parsing queries like "restaurants in Brooklyn"

Typically found in non-physical (mail-only) addresses

A code describing the precision of the X and Y coordinates

A first-level administrative division, including provinces and departments. Scotland, Northern Ireland, Wales, and England in the UK are also mapped to "state" (convention commonly used in geocoding tools).

A second-level administrative division or county

Usually an unofficial neighborhood name, like "Harlem", "South Bronx", or "Crown Heights"

The address value transliterated to English

Indicates what the address is referring to. For example, it could be a physical address, mailing address, or other address type.

An apartment, unit, office, lot, or other secondary unit designator

Currently only used for appending “West Indies” after the country name, a pattern frequently used in the English-speaking Caribbean (e.g., “Jamaica, West Indies”)

The X coordinate (longitude) of the address

The Y coordinate (latitude) of the address

This enumerated type indicates the kind of location an address is referring to.

AddressType

An address at which an entity receives mail

An address at which an entity has a physical presence

An address an entity has listed for its registration

An address at which an entity conducts its operations

AttributeData

AttributeDetails

BothIdentifierTypes

BusinessPurposeData

Text and/or a code (NAICS, NACE, ISIC, etc.) that describes what a company is legally allowed to do or produce

BusinessPurposeInfo

BusinessPurposeProperties

The type of code (e.g., "ISIC4", "NACE1")

1	{
2	"offset": 0,
3	"limit": 20,
4	"next": false,
5	"data": [
6	{
7	"id": "dlOL1cZzEkIEZcRUcrBZCQ",
8	"resource_id": "0eZQ43",
9	"entity_id": "dlOL1cZzEkIEZcRUcrBZCQ",
10	"notifications": [
11	{
12	"type": "risk",
13	"field": "forced_labor_xinjiang_origin_subtier",
14	"values": [
15	"false"
16	],
17	"date": "2024-02-06T00:00:00.000Z"
18	}
19	]
20	},
21	{
22	"id": "wxwqZshCF4trlrmOa2eu9w",
23	"resource_id": "03ePyj",
24	"entity_id": "wxwqZshCF4trlrmOa2eu9w",
25	"notifications": [
26	{
27	"type": "risk",
28	"field": "forced_labor_sheffield_hallam_university_reports_origin_subtier",
29	"values": [
30	"3"
31	],
32	"date": "2024-02-15T00:00:00.000Z"
33	}
34	]
35	},
36	{
37	"id": "dX9cfM3FPefIp8VAuBKgIQ",
38	"resource_id": "0XEQaX",
39	"entity_id": "dX9cfM3FPefIp8VAuBKgIQ",
40	"notifications": [
41	{
42	"type": "risk",
43	"field": "forced_labor_sheffield_hallam_university_reports_origin_direct",
44	"values": [
45	"1"
46	],
47	"date": "2024-02-15T00:00:00.000Z"
48	},
49	{
50	"type": "risk",
51	"field": "forced_labor_sheffield_hallam_university_reports_origin_subtier",
52	"values": [
53	"false"
54	],
55	"date": "2024-02-15T00:00:00.000Z"
56	},
57	{
58	"type": "risk",
59	"field": "owner_of_regulatory_action_entity",
60	"values": [
61	"1"
62	],
63	"date": "2024-02-06T00:00:00.000Z"
64	}
65	]
66	}
67	]
68	}

Key Concepts

API Clients

API Reference

Guides

Use Cases

Project Notifications

Path parameters

Query parameters

Response

1	curl -G https://api.sayari.com/v1/notifications/projects/0oZnoG \
2	-H "Authorization: Bearer <token>" \
3	-d limit=20