Sayari Documentation

# API Reference v0 (Migration)

# Summary

API Version Update - Important Notice

Sunset Date: February 9th, 2024

Action Required: Sayari will officially sunset version v0 of our API. This means every endpoint detailed in the v0 documentation, will no longer be accessible.

What's Next?: We've prepared a guide to help you transition smoothly to v1 of the API. Please take a moment to review and ensure your integrations continue working seamlessly.

# Authentication

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

The old endpoint will be officially deprected 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:

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.

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.

Endpoints:

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

Detailed Information about how to paginate different endpoints can be found here

# Responses

We will now throw 429 errors when rate limits are hit

# Types

No Change:

  • Dates
  • Countries
  • Source
  • EmbeddedRecord
  • PossiblySameAsMatches

Updated:

# EmbeddedEntity

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

Additional fields 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

export type EmbeddedEntity = {
  id: string
  label: string
  degree: number
  entity_url: string
  pep: boolean
  psa_count: number
  sanctioned: boolean
  closed: boolean
  psa_sanctioned?: string
  translated_label?: string
  company_type?: string
  registration_date?: string
  latest_status?: { status: string; date?: string }
  shipment_arrival?: string
  shipment_departure?: string
  hs_code?: string
  type: string
  identifiers: { type: string; value: string; label: string }[]
  addresses: string[]
  date_of_birth?: string
  countries: string[]
  relationship_count: Record<string, number>
  source_count: Record<string, { count: number; label: string }>
  risk: Record<
    string,
    {
      value: string | boolean | number
      metadata: Record<string, (string | boolean | number)[]>
      level: "critical" | "high" | "elevated" | "relevant"
    }
  >
}

# PathSegment

type TraversalPath = {
  target: EmbeddedEntity
  path: {
    field: string
    entity: EmbeddedEntity
    relationship: RelationshipProperties
    relationships: RelationshipProperties[]
  }
  []:
}

type TraversalPath = {
  source: string
  target: EmbeddedEntity
  path: {
    field: string
    entity: EmbeddedEntity
    relationships: Record<
      string,
      {
        values: RelationshipProperties[]
        former?: true
        start_date?: string
        end_date?: string
        last_observed?: string
      }
    >
  }[]
}

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:

type RelationshipProperties = {
  record?: string
  attributes: Record<string, Record<string, Literal>[]>
  from_date?: Date
  date?: Date
  to_date?: Date
  acquisition_date?: Date
  publication_date?: Date
  former?: true
}

# 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, and can also be found here

  • 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.

See the entity section of our v1 docs for examples.

# 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.

{
 min_depth: number,
 max_depth: number,
 relationships: string[],
 countries: string[],
 types: string[],
 name: string,
 watchlist: boolean,
 psa: boolean,
 offset: number,
 limit: number,
 next: boolean,
 data: TraversalPath[],
 explored_count: number,
}

For more details see the docs here.

# 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. See documentation for it here

# Record

No Change

No Change, we have 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

The dob param has been renamed to date_of_birth, and all other previously supported params are still supported.

We no longer support the fuzziness.[field] or strict params.

Additionally we now support both GET and POST requests. More detail can be found here.

To migrate over to this endpoint the main changes that need to be accounted for are:

  • new endpoint name
  • dob renamed to date_of_birth.

The response has completely changed as well. New Response

# Source

No Change

# Sources

No Change

# Document Changelog

  • 11-27-23: Added more context regarding the EmbeddedEntity object.

API Walk-Through →