Next Steps

For assistance migrating from v0 to v1, follow the below guide. Our API Reference and API Clients are useful resources to reference as well.

Authentication

• v0 : sayari.auth0.com/oauth/token
• v1 : api.sayari.com/oauth/token

The old endpoint will be officially deprecated on the sunset date. Previously, issued user credentials, CLIENT_ID and CLIENT_SECRET will still be valid via the new endpoint. For the new endpoint, Bearer tokens obtained from the resource remain valid for 24 hours. Ensure to include the token in the Authorization header for all subsequent API requests.

Pagination

In v0 all endpoints used offset pagination, but in v1 we have moved some endpoints to using token pagination. View our Pagination page for details.

Offset Pagination: Arguments

• limit: integer optional A limit on the number of objects to be returned. Defaults to 100.
• offset: integer optional Number of results to skip before returning response. Defaults to 0.

Impact Endpoints:

• Search
• Traversals
• Record
• Entity References

Token Pagination: Arguments:

• next: string optional Token to retrieve the next page of results
• prev: string optional Token to retrieve the previous page of results
• limit: integer optional A limit on the number of objects to be returned. Defaults to 100.

Impacted Endpoints:

• Entity
  • Relationships
  • Attributes
  • Possibly Same As entities
  • Record References

Responses

We will now throw 429 errors when rate limits are hit. View our Response Status Codes for details.

Types

No Change:

• Dates
• Countries
• Source
• EmbeddedRecord
• PossiblySameAsMatches

Updated:

• EmbeddedEntity

No breaking changes here, but wanted to highlight additional fields and enhancements in v1:

• translated_label: An optional string.
• company_type: An optional string.
• registration_date: An optional string.
• latest_status: An optional object with status as a string and an optional date.
• shipment_arrival: An optional string.
• shipment_departure: An optional string.
• hs_code: An optional string.
• risk: A complex object with a record structure, including value, metadata, and level.

Data Type & Structural Enhancements in v1:

• identifiers: In v1, each identifier includes an additional label string.
• relationship_count and source_count are defined as Record<string, number> and Record<string, { count: number; label: string }> respectively in v1, which is a more explicit and restrictive type than the more generic object definition in v0.

v1 full object

1
export type EmbeddedEntity = {
2
  id: string
3
  label: string
4
  degree: number
5
  entity_url: string
6
  pep: boolean
7
  psa_count: number
8
  sanctioned: boolean
9
  closed: boolean
10
  psa_sanctioned?: string
11
  translated_label?: string
12
  company_type?: string
13
  registration_date?: string
14
  latest_status?: { status: string; date?: string }
15
  shipment_arrival?: string
16
  shipment_departure?: string
17
  hs_code?: string
18
  type: string
19
  identifiers: { type: string; value: string; label: string }[]
20
  addresses: string[]
21
  date_of_birth?: string
22
  countries: string[]
23
  relationship_count: Record<string, number>
24
  source_count: Record<string, { count: number; label: string }>
25
  risk: Record<
26
    string,
27
    {
28
      value: string | boolean | number
29
      metadata: Record<string, (string | boolean | number)[]>
30
      level: "critical" | "high" | "elevated" | "relevant"
31
    }
32
  >
33
}

PathSegment

1
type TraversalPath = {
2
  target: EmbeddedEntity
3
  path: {
4
    field: string
5
    entity: EmbeddedEntity
6
    relationship: RelationshipProperties
7
    relationships: RelationshipProperties[]
8
  }
9
  []:
10
}
11
type TraversalPath = {
12
  source: string
13
  target: EmbeddedEntity
14
  path: {
15
    field: string
16
    entity: EmbeddedEntity
17
    relationships: Record<
18
      string,
19
      {
20
        values: RelationshipProperties[]
21
        former?: true
22
        start_date?: string
23
        end_date?: string
24
        last_observed?: string
25
      }
26
    >
27
  }[]
28
}

The main difference is that we have combined the relationship and relationship properties into one object. The object keys are the relationship type and the value can be seen above.

The RelationshipProperties type looks as follows:

1
type RelationshipProperties = {
2
  record?: string
3
  attributes: Record<string, Record<string, Literal>[]>
4
  from_date?: Date
5
  date?: Date
6
  to_date?: Date
7
  acquisition_date?: Date
8
  publication_date?: Date
9
  former?: true
10
}

Endpoints

All v1 endpoints are prepended with a v1 in the path.

Entity

New token pagination for:

• Relationships
• Attributes
• Possibly Same As entities
• Record References
• Relationships API has changed:

Previously you would request relationships: /entity/:id?relationships.[field].offset=0&relationships.[field].limit=10

Now we use the type param to determine with relationships type to fetch (leave undefined for relationships of all types). We have also added some new params that can be used to filter and sort relationships v1/entity/:id?relationships.type=[field]&relationships.limit=10

All new params for relationships are listed below. Visit our API Reference for details.

• relationships.next: integer optional The pagination token for the next page of relationship results
• relationships.prev: integer optional The pagination token for the previous page of relationship results
• relationships.limit: integer optional Limit total relationship values. Defaults to 100.
• relationships.type: integer optional Filter relationships to relationship type, e.g. director_of or has_shareholder
• relationships.sort: string optional Sorts relationships by As Of date or Shareholder percentage, e.g. date or -shares
• relationships.startDate: date optional Filters relationships to after a date
• relationships.endDate: date optional Filters relationships to before a date
• relationships.minShares: integer optional Filters relationships to greater than or equal to a Shareholder percentage
• relationships.country: string[] optional Filters relationships to a list of countries

Additionally we now support an additional Content Type

• application/vnd.ms-excel Microsoft Excel XLSX response. All previously supported content types are supported as well.

Entity Summary

No Change

Traversal

We have added additional params that you can now use to filter traversals. Note that we no longer support the watchlist boolean param and have instead replaced it with the sanctioned param.

• sanctioned: boolean optional Filter paths to only those that end at an entity appearing on a watchlist. Defaults to not filtering paths by sanctioned status.
• pep: boolean optional Filter paths to only those that end at an entity appearing on a pep list. Defaults to not filtering paths by pep status.
• min_shares: integer optional Set minimum percentage of share ownership for traversal. Defaults to 0.
• include_unknown_shares: boolean optional Also traverse relationships when share percentages are unknown. Only useful when min_shares is set greater than 0. Defaults to true.
• exclude_former_relationships: boolean optional Include relationships that were valid in the past but not at the present time. Defaults to false.
• exclude_closed_entities: boolean optional Include entities that existed in the past but not at the present time. Defaults to false. The response has changed significantly, see the updated PathSegment type above.

1
{
2
 min_depth: number,
3
 max_depth: number,
4
 relationships: string[],
5
 countries: string[],
6
 types: string[],
7
 name: string,
8
 watchlist: boolean,
9
 psa: boolean,
10
 offset: number,
11
 limit: number,
12
 next: boolean,
13
 data: TraversalPath[],
14
 explored_count: number,
15
}

UBO / Ownership / Watchlist

• All still supported but again the traversal response has changed slightly, see PathSegment update above.

Shortest Path

• The Shortest Path endpoint returns a response identifying the shortest traversal path connecting each pair of entities.
• New endpoint in v1. Visit our API Reference for details.

Record

No Change

Search

• added a geo_facets param that allows you to return search geo bound facets in results giving counts by geo tile.

Resolution

• The resolution endpoint has been renamed.
• v0: /resolve/entity
• v1: /v1/resolution
• dob renamed to date_of_birth
• We no longer support the fuzziness.[field] or strict params.
• Support both GET and POST requests. Visit our API Reference for details.

Source

No Change

Sources

No Change