Getting Started

Make Your First Request

This guide will walk you through a series of steps to make your first request and subsequent calls. This is a great resource if you are a brand-new consumer of Sayari’s API. If you are brand new, consider utilizing our Postman Collection to familiarize yourself.

Authentication

This guide assumes that you have API credentials CLIENT_ID and CLIENT_SECRET, which are required to obtain a bearer token.

Interested and need credentials? Fill out this form and our team will get in touch.

Choose a Starting Point

Sayari has three endpoints that can be used to kick off a workflow, each tailored for specific use cases. Understanding when to use each is key to your success.

For the purpose of this guide, /resolution has been selected as the starting point.

Resolution

Use Case: Entity Screening and Validation

Resolution utilizes elastic search and natural language processing (NLP) techniques to provide the most accurate matches for your query. The response includes an entity attribute profile, Sayari entity_id, and explanation to help you understand how confident each match is.

Use Case: Investigations, Broad Searches, and Exploratory Lead Generation

Best suited for investigative purposes where your search terms might be broad. Sayari search takes the query term and returns an entity’s general profile, relationships, risks, and attributes. Overall, this endpoint is ideal for lead generation.

Use Case: Trade Data Searches and Investigations

Designed for searching global trade data, including shipments, buyers, and suppliers, with three specific endpoints: /shipments, /suppliers, and /buyers. The response provides key shipping data, including dates, departure and arrival destinations, risks associated with involved parties, Harmonized System (HS) codes, shipment descriptions, weight and other measures, and much more! Enable facets to return summarized trade activity.

Make a Request to Resolution

In this example, the entity of interest is:

  • name: VIKTOR ALEKSEEVICH OZEROV
  • address: Kab. 101, 19 Ul. Muravyova-Amurskogo, Khabarovsk, 680000
  • country: RUS
  • type: person
$curl --request GET \
>     --url 'https://api.sayari.com/v1/resolution?name=VIKTOR%20ALEKSEEVICH%20OZEROV&country=RUS&address=Kab.%20101%2C%2019%20Ul.%20Muravyova-Amurskogo%2C%20Khabarovsk%2C%20680000&type=person' \
>     --header 'accept: application/json' \
>     --header 'authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc'

If your environment is set up correctly and you’ve entered the above parameters, you should receive the following response:

1{
2    "fields": {
3        "name": [
4            "VIKTOR ALEKSEEVICH OZEROV"
5        ],
6        "address": [
7            "Kab. 101, 19 Ul. Muravyova-Amurskogo, Khabarovsk, 680000"
8        ],
9        "country": [
10            "RUS"
11        ],
12        "type": [
13            "person"
14        ]
15    },
16    "data": [
17        {
18            "score": 371.43286,
19            "entity_id": "5eXI5D1vfHoj7ohDoW59Vw",
20            "label": "VIKTOR ALEKSEEVICH OZEROV",
21            "type": "person",
22            "identifiers": [
23                {
24                    "type": "xxx_acuris_id",
25                    "value": "I1351720",
26                    "label": "Xxx Acuris Id"
27                },
28                {
29                    "type": "usa_ofac_sdn_number",
30                    "value": "16664",
31                    "label": "Usa Ofac Sdn Number"
32                },
33                {
34                    "type": "xxx_intel_internal_id",
35                    "value": "5c4880c2a18bbce4b8f16eaf",
36                    "label": "Xxx Intel Internal Id"
37                },
38                {
39                    "type": "gbr_hm_treasury_sanction_group_id",
40                    "value": "12912",
41                    "label": "Gbr Hm Treasury Sanction Group Id"
42                },
43                {
44                    "type": "che_seco_sanction_number",
45                    "value": "27325",
46                    "label": "Che Seco Sanction Number"
47                },
48                {
49                    "type": "eu_sanction_rn",
50                    "value": "EU.3505.38",
51                    "label": "Eu Sanction Rn"
52                },
53                {
54                    "type": "aus_consolidated_sanctions_reference",
55                    "value": "2709",
56                    "label": "Aus Consolidated Sanctions Reference"
57                },
58                {
59                    "type": "gbr_uk_sanctions_id",
60                    "value": "RUS0046",
61                    "label": "Gbr Uk Sanctions Id"
62                },
63                {
64                    "type": "unknown",
65                    "value": "Ukraine-/Russia-Related Sanctions Regulations, 31 CFR 589.201 and/or 589.209",
66                    "label": "Unknown"
67                }
68            ],
69            "addresses": [
70                "Kab. 101, 19 Ul. Muravyova-Amurskogo, Khabarovsk, 680000, Russia",
71                "680000, г. Хабаровск, ул. Муравьева-Амурского, д. 19, каб. 101",
72                "101 Cabinet, 19 Muravyeva-Amurskogo Str., Khabarovsk, 680000, RU",
73                "Abakan, Republic of Khakasia, RU",
74                "Абакан, Хакасія, Російська Федерація"
75            ],
76            "countries": [
77                "RUS",
78                "XXX",
79                "CAN",
80                "AUS",
81                "UKR",
82                "GBR",
83                "USA",
84                "CHE"
85            ],
86            "sources": [
87                "a8c6ee1cd4dfc952105ee8c0e4836f08",
88                "93de05b55a68cc964f34bbfc7ec7bc86",
89                "fdfedf11a5122e2aef9dc3f176c7427d",
90                "bef2f30139ea37c723ecb0f953b5f024",
91                "e85d865943ee6d8369307569d2ad9de0",
92                "e6e4acebdea4e9e71af8d3586d34fcdd",
93                "f4ce10ac8bdc0bd9bcb31cb868b4b539",
94                "c10d482320f207d92aa814519c3bd686",
95                "fdfedf11a5122e2aef9dc3f176c7427d",
96                "92edb8fe6615498f6e3e7b0e220f74e6",
97                "10a889609ddae6cc31773feebe48166b",
98                "417400a1ac439843fda5bb2f05fb4161"
99            ],
100            "typed_matched_queries": [
101                "type|1",
102                "strictAddressNormalNameCombo",
103                "type|0",
104                "name|StrictV2|0",
105                "address|StrictV2|0",
106                "address|NormalV2|0",
107                "country|0",
108                "name|NormalV2|0",
109                "strictNameNormalAddressCombo"
110            ],
111            "matched_queries": [
112                "type",
113                "strictAddressNormalNameCombo",
114                "name",
115                "address",
116                "country",
117                "strictNameNormalAddressCombo"
118            ],
119            "highlight": {
120                "type": [
121                    "<em>PERSON</em>"
122                ],
123                "name": [
124                    "<em>VIKTOR</em> <em>ALEKSEEVICH</em> <em>OZEROV</em>",
125                    "<em>OZEROV</em> <em>Viktor</em> <em>Alekseevich</em>",
126                    "<em>Viktor</em> <em>Aleekseevich</em> <em>Ozerov</em>",
127                    "<em>Viktor</em> <em>Alekseyevich</em> <em>Ozerov</em>",
128                    "<em>ВИКТОР</em> АЛЕКСЕЕВИЧ <em>ОЗЕРОВ</em>"
129                ],
130                "address": [
131                    "<em>Kab</em>. <em>101</em>, <em>19</em> <em>Ul</em>. <em>Muravyova</em>-<em>Amurskogo</em>, <em>Khabarovsk</em>, <em>680000</em>, Russia",
132                    "<em>101</em> Cabinet, <em>19</em> <em>Muravyeva</em>-<em>Amurskogo</em> Str., <em>Khabarovsk</em>, <em>680000</em>, RU",
133                    "<em>680000</em>, г. Хабаровск, ул. Муравьева-Амурского, д. <em>19</em>, каб. <em>101</em>"
134                ],
135                "country": [
136                    "<em>RUS</em>"
137                ]
138            },
139            "explanation": {
140                "type": [
141                    {
142                        "matched": "<em>PERSON</em>",
143                        "uploaded": "person"
144                    }
145                ],
146                "name": [
147                    {
148                        "matched": "<em>VIKTOR</em> <em>ALEKSEEVICH</em> <em>OZEROV</em>",
149                        "uploaded": "VIKTOR ALEKSEEVICH OZEROV",
150                        "nameCustomTfIdfScore": 0.3925957819262012,
151                        "highQualityMatchName": true
152                    },
153                    {
154                        "matched": "<em>OZEROV</em> <em>Viktor</em> <em>Alekseevich</em>",
155                        "uploaded": "VIKTOR ALEKSEEVICH OZEROV",
156                        "nameCustomTfIdfScore": 0.3925957819262012,
157                        "highQualityMatchName": true
158                    },
159                    {
160                        "matched": "<em>Viktor</em> <em>Aleekseevich</em> <em>Ozerov</em>",
161                        "uploaded": "VIKTOR ALEKSEEVICH OZEROV",
162                        "nameCustomTfIdfScore": 0.6955376691631864,
163                        "highQualityMatchName": true
164                    },
165                    {
166                        "matched": "<em>Viktor</em> <em>Alekseyevich</em> <em>Ozerov</em>",
167                        "uploaded": "VIKTOR ALEKSEEVICH OZEROV",
168                        "nameCustomTfIdfScore": 0.6955376691631864,
169                        "highQualityMatchName": true
170                    },
171                    {
172                        "matched": "<em>ВИКТОР</em> АЛЕКСЕЕВИЧ <em>ОЗЕРОВ</em>",
173                        "uploaded": "VIKTOR ALEKSEEVICH OZEROV",
174                        "nameCustomTfIdfScore": 0.6666666666666665,
175                        "highQualityMatchName": true
176                    }
177                ],
178                "address": [
179                    {
180                        "matched": "<em>Kab</em>. <em>101</em>, <em>19</em> <em>Ul</em>. <em>Muravyova</em>-<em>Amurskogo</em>, <em>Khabarovsk</em>, <em>680000</em>, Russia",
181                        "uploaded": "Kab. 101, 19 Ul. Muravyova-Amurskogo, Khabarovsk, 680000"
182                    },
183                    {
184                        "matched": "<em>101</em> Cabinet, <em>19</em> <em>Muravyeva</em>-<em>Amurskogo</em> Str., <em>Khabarovsk</em>, <em>680000</em>, RU",
185                        "uploaded": "Kab. 101, 19 Ul. Muravyova-Amurskogo, Khabarovsk, 680000"
186                    },
187                    {
188                        "matched": "<em>680000</em>, г. Хабаровск, ул. Муравьева-Амурского, д. <em>19</em>, каб. <em>101</em>",
189                        "uploaded": "Kab. 101, 19 Ul. Muravyova-Amurskogo, Khabarovsk, 680000"
190                    }
191                ],
192                "country": [
193                    {
194                        "matched": "<em>RUS</em>",
195                        "uploaded": "RUS"
196                    }
197                ]
198            },
199            "match_strength": {
200                "value": "strong"
201            }
202        }
203    ]
204}

Congratulations! You’ve successfully made your first call to Sayari and completed our version of Hello World! In the response, you’ll see a Sayari "entity_id": "5eXI5D1vfHoj7ohDoW59Vw", which is the vital object to progress to the other endpoints.