Sayari Documentation

# API Reference

Sayari offers all graph related resources through a REST api, accepting either query-stings or JSON encoded request bodies returning the resource through standard HTTP verbs and content negotiation.

# Authentication

Authentication to the API is performed via JWT access tokens. To make API calls, you'll need to set the following variables in order to obtain a token.

  • CLIENT_ID
  • CLIENT_SECRET

The bearer token will then be granted by requesting the token resource.

curl --request POST \
  --url https://api.sayari.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id": $CLIENT_ID,
    "client_secret": $CLIENT_SECRET,
    "audience":"sayari.com",
    "grant_type":"client_credentials"
  }'

{
  "access_token": "sk_test_4eC39HqLyjWDarjtT1zdp7dc",
  "token_type": "Bearer"
}

This token will expire in 24 hours, at which point a new token should be requested.

To use the token to authenticate HTTP requests against the Sayari API, pass the bearer token in the request's Authorization header. For example, using the token retrieved above:

curl 'https://api.sayari.com/search/entity?q=china' -H"Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

# Requests

Sayari utilizes standard HTTP verbs to indicate request intent. All resources can be requested using GET requests with request parameters serialized in the url query string, e.g. /entity/:id?referenced_by.offset=50&attributes.address.limit=10.

# Pagination

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. Paginated requests take one of two forms: token pagination, for the entity endpoint, and offset pagination, for all other endpoints.

# Token Pagination

Token paginated requests specify optional next or prev parameters to retrieve the next or previous page of results. Omitting both token parameters will return the first page of results, which may contain a next token in the response body if there are more results to return. Result pages beyond the first will include a prev token in the response body, allowing for backwards pagination. The limit parameter will restrict the size of the page, up to whatever default is set for that result type.

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

# Offset Pagination

Offset paginated requests specify an optional offset and limit parameter for the paginatable list. The response data will include a next boolean field to indicate if the collection is fully paginated, and optionally may also include a size key with a count indicating the total length of the collection. Collections whose size is not feasible to compute, such as traversals, will not have a size key.

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

The search endpoint is paginated via offsets in cases where the search result size is greater than the page limit size. For very large result sets, the search count may be estimated.

GET /search/entity?q=china&offset=10&limit=5 HTTP/1.1
Accept: application/json

{
    "offset": 10,
    "limit": 5,
    "next": true,
    "size": {
        "count": 10000,
        "qualifier": "gte"
    },
    "data": [...]
}

# Paginating Entities

An Entity's attributes, relationships, possibly same as entities, and record references can all be paginated via tokens.

Pagination next or prev tokens are passed as query parameters with any combination of the following:

  • attributes.[field].['next' | 'prev']=[string], e.g. ?attributes.address.next=qr7bvn2
  • relationships.['next' | 'prev']=[string], e.g. ?relationships.next=qr7bvn2
  • possibly_same_as.['next' | 'prev']=[string], e.g. ?possibly_same_as.next=qr7bvn2
  • referenced_by.['next' | 'prev']=[string], e.g. ?referenced_by.next=qr7bvn2

For example, this HTTP request could return the following result:

GET /entity/abc?attributes.name.limit=10&relationships.next=qr7bvn2&relationships.limit=150 HTTP/1.1
Accept: application/json

{
    ...
    "attributes": {
        "name": {
            "next": "y4rkp09",
            "limit": 10,
            "size": {
                "count": 18,
                "qualifier": "eq"
            },
            "data": [...]
        }
    },
    "relationships": {
        "next": "w98vmfd",
        "prev": "myvc64l",
        "limit": 150,
        "size": {
            "count": 1201,
            "qualifier": "eq"
        },
        "data": [...]
    },
    "possibly_same_as": {
        "limit": 100,
        "size": {
            "count": 12,
            "qualifier": "eq"
        },

        "data": [...]
    },
    "referenced_by": {
        "next": "84ct7eb",
        "limit": 100,
        "size": {
            "count": 300,
            "qualifier": "eq"
        },
        "data": [...]
    }
}

# Paginating Records

A Record's entity references can paginated via offsets in cases where the record cites more entities than can be returned in a single request.

For example, this HTTP request could yield something like the following result:

GET /record/123?references.offset=100&references.limit=100 HTTP/1.1
Accept: application/json

{
    ...
    "references": {
        "next": false,
        "offset": 100,
        "limit": 100,
        "size": {
            "count": 140,
            "qualifier": "eq"
        },
        "data": [...]
    }
}

# Paginating Traversals

The traversal endpoints' response paths are paginated via offsets. Because the total number of potential matching paths is very expensive to compute, the response does not include size values. Instead, use the next boolean field to determine if there are more pages of results to return.

GET /traversal/123?offset=20&max_depth=8 HTTP/1.1
Accept: application/json

{
    "offset": 20,
    "limit": 20,
    "next": true,
    "data": [...]
}

# Responses

# Success

All successful requests will be indicated with 2xx status codes.

Code Response Description
200 OK Successful GET request.
201 Created Successful POST request.

# Errors

All errors will be returned with the corresponding HTTP response status indicating the reason for a failed request.

Code Response Description
400 Bad Request Incorrectly formatted request.
401 Unauthorized Request made without valid token.
404 Not Found Resource not found or does not exist.
405 Method Not Allowed Request made with an unsupported HTTP method. Currently only GET and POST supported.
406 Not Acceptable Request made in an unacceptable state. This is most commonly due to parameter validation errors.
415 Unsupported Media Type Accept header on request set to an unsupported media type. Currently only application/json and text/csv supported for indicated resources.
500 Internal Server Error Internal server error occurred.

The error will also be indicated as a JSON object in the body in the following format:

{
    "status": 500,
    "success": false,
    "messages": [
        "Internal Server Error"
    ]
}

Validation messages on request parameters will also displayed in the messages field to give more information on the failed request.

# Types

# Dates

Date strings are formatted as YYYY[-MM[-DD]], meaning 2000-10-02, 2000-10, and 2000 are all valid date formats. Dates without day or month-day segments appear where the day or month is either not known or not relevant.

Entity attributes and Entity relationships may all have either a from_date and/or to_date field to indicate when an attribute or relationship value started or ended, as well as an optional generic date field. Records also have date fields to indicate when the record was published (publication_date), and when it was acquired by Sayari (acquisition_date).

# Countries

Country Ids use the ISO 3166 Trigram country code.

# Source

{
    "id": "b9dc2ca839c318d04910a8a680131fdf",
    "label": "Albania Trade Register Extracts",
    "country": "ALB"
}

# EmbeddedEntity

{
    "id": "123",
    "label": "ACME Co.",
    "type": "company",
    "entity_url": "/entity/123",
    "identifiers": [{ "type": "uk_company_number", "value": "12345" }],
    "countries": ["GBR"],
    "closed": false,
    "pep": false,
    "sanctioned": false,
    "psa_sanctioned":"123456",
    "psa_count": 2,
    "source_count": {
        "some_source_id": {
            "count": 2,
            "label": "Some Source Label",
        }
    },
    "degree": 304,
    "addresses":["32535 31st Rd, Arkansas City, KS, 67005"],
    "date_of_birth":"1990-08-03",
    "relationship_count": {
        "has_shareholder": 300,
        "shareholder_of": 4
    }
}

# EmbeddedRecord

{
    "id": "abc",
    "label": "Some Record - 1/14/2020",
    "source": "some_source_id",
    "publication_date": "2019-02-04",
    "acquisition_date": "2019-02-05",
    "references_count": 2,
    "record_url": "record/abc",
    "source_url": "https://entity.com/company/12345"
}

# PathSegment

{
    "field": "shareholder_of",
    "relationships": {
        "shareholder_of": [
            {
                "record": "ecdfb3f2ecc8c3797e77d5795a8066ef/123567",
                "attributes": {
                    "shares": [{ "percentage": 100, "monetary_value": 2100000, "currency": "USD" }]
                },
                "date": "2018-06-14",
            }
        ],
        "director_of": [
            {
                "record": "ecdfb3f2ecc8c3797e77d5795a8066ef/123567",
                "attributes": {
                    "position": [{ "value": "Director" }]
                },
                "from_date": "2007-12-01",
                "acquisition_date": "2021-04-14",
                "publication_date": "2021-04-14"
            }
        ],
    },
    "entity": EmbeddedEntity
}

# PossiblySameAsMatches

{
    "name": [
        {
            "target": "John Smith",
            "source": "John C Smith"
        }
    ],
    "date_of_birth": [
        {
            "target": "1970-05-02",
            "source": "1970-05"
        }
    ]
}

# Resource Endpoints

# Entity

GET /v1/entity/:id
Accept: application/json

An entity represents a single real-world thing such as a person or company or land property that has been extracted from one or more records. The entity response includes information on that entity's attributes, relationships, as well as the records that entity is sourced to. Entity requests includes paginated lists of attributes and relationships, with limit defaulting to 100. Paginate the lists of attributes and relationships using the next or prev token included in the response.

# Arguments

attributes.[field].next: string optional
The pagination token for the next page of attribute `[field]`, e.g. name, address, or country.
attributes.[field].prev: string optional
The pagination token for the previous page of attribute `[field]`, e.g. name, address, or country.
attributes.[field].limit: integer optional
Limit total values returned for attribute `[field]`. Defaults to 100.
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
possibly_same_as.next: integer optional
The pagination token for the next page of possibly same entities.
possibly_same_as.prev: integer optional
The pagination token for the previous page of possibly same entities.
possibly_same_as.limit: integer optional
Limit total possibly same as entities. Defaults to 100.
referenced_by.next: integer optional
The pagination token for the next page of the entity's referencing records
referenced_by.prev: integer optional
The pagination token for the previous page of the entity's referencing records
referenced_by.limit: integer optional
Limit totals values returned for entity's referencing records. Defaults to 100.

# Content Types

Supported content types include:

application/json
JSON response.
text/csv
CSV response.
application/pdf
PDF response.
application/vnd.ms-excel
Microsoft Excel XLSX response.

# Examples

GET /v1/entity/123?attributes.name.limit=10&relationships.next=wkdjtrsdre HTTP/1.1
Accept: application/json

{
    "id": "123",
    "label": "ACME Co.",
    "type": "company",
    "entity_url": "/v1/entity/123",
    "identifiers": [{ "type": "uk_company_number", "value": "12345" }],
    "countries": ["GBR"],
    "source_count": {
        "some_source_id": {
            "count": 2,
            "label": "UK Companies House",
        }
    },
    "relationship_count": {
        "has_shareholder": 300
    },
    "attributes": {
        "name": {
            "next": "b9dc2ca839c31",
            "limit": 100,
            "size": {
                "count": 4,
                "qualifier": "eq"
            },
            "data": [
                {
                    "properties": {
                        "value": "Acme Co."
                    },
                    "record": ["record_id"],
                    "record_count": 3
                },
                ...
            ]
        },
        ...
    },
    "relationships": {
        "next": "b9dc2ca839c31",
        "prev": "49dc2ca839c31",
        "limit": 100,
        "size": {
            "count": 300,
            "qualifier": "eq"
        },
        "data": [
            {
                "target": EmbeddedEntity,
                "types": {
                    "shareholder_of": [
                        {
                            "record": "record-id",
                            "attributes": {
                                "shares": [
                                    { "percentage": 100, "monetary_value": 2100000, "currency": "USD" }
                                ]
                            },
                            "date": "2018-06-14"
                        }
                    ]
                }
            },
            ...
        ]
    },
    "possibly_same_as": {
        "next": "b9dc2ca839c31",
        "limit": 100,
        "size": {
            "count": 2,
            "qualifier": "eq"
        },
        "data": [
            {
                "entity": EmbeddedEntity,
                "matches": PossiblySameAsMatches
            },
            ...
        ]
    },
    "referenced_by": {
        "next": "b9dc2ca839c31",
        "limit": 100,
        "size": {
            "count": 3,
            "qualifier": "eq"
        },
        "data": [
            {
                "record": EmbeddedRecord,
                "type": "about"
            },
            ...
        ]
    }
}

# Entity Summary

GET /v1/entity_summary/:id
Accept: application/json

The Entity Summary endpoint returns a smaller entity payload, including:

  • up to 50 values for each of the following attributes: name, address, identifier, weak_identifier, status, company_type, contact, business_purpose, country
  • up to 50 entities that are possibly the same as the target entity
  • up to 100 records the entity is sourced to

# Content Types

Supported content types include:

application/json
JSON encoded response.

# Examples

GET /record/123 HTTP/1.1
Accept: application/json

{
    "id": "123",
    "label": "ACME Corp.",
    "degree": 3,
    "pep": false,
    "sanctioned": false,
    "psa_count": 1,
    "type": "company",
    "entity_url": "/v1/entity/123",
    "identifiers": [{ "type": "uk_company_number", "value": "1234" }],
    "countries": ["GBR"],
    "source_count": {
        "ecdfb3f2ecc8c3797e77d5795a8066ef": {
            "count": 6,
            "label": "UK Corporate Registry"
        },
        "2a4fe9a14e332c8f9ded1f8a457c2b89": {
            "count": 12,
            "label": "UK Land Commercial and Corporate Ownership Data (CCOD)"
        },
    },
    "relationship_count": {
        "has_registered_agent": 1,
        "has_shareholder": 2,
        "linked_to": 2,
    },
    "attributes": {
        "identifier": {
            "offset": 0,
            "limit": 20,
            "next": false,
            "size": {
                "count": 1,
                "qualifier": "eq"
            },
            "data": [
                {
                    "properties": {
                        "value": "1234",
                        "type": "uk_company_number"
                    },
                    "record": ["abc"],
                    "record_count": 21
                }
            ]
        },
        ...
    }
}

# Traversal

GET /v1/traversal/:id
Accept: application/json

The Traversal endpoint returns paths from a single target entity to up to 50 directly or indirectly-related entities. Each path includes information on the 0 to 10 intermediary entities, as well as their connecting relationships. The response's explored_count field indicates the size of the graph subset the application searched. Running a traversal on a highly connected entity with a restrictive set of argument filters and a high max depth will require the application to explore a higher number of traversal paths, which may affect performance.

# Arguments

offset: integer optional
Offset values for traversal. Defaults to 0.
limit: integer optional
Limit total values for traversal. Defaults to 50.
min_depth: integer optional
Set minimum depth for traversal. Defaults to 0.
max_depth: integer optional
Set maximum depth for traversal. Defaults to 10.
relationships: string, string[] optional
Set relationship type(s) to follow when traversing related entities. Defaults to following all relationship types.
psa: boolean optional
Also traverse relationships from entities that are possibly the same as any entity that appears in the path. Defaults to not traversing possibly same as relationships.
countries: string, string[] optional
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.
types: string, string[] optional
Filter paths to only those that end at an entity of the specified type(s). Defaults to returning paths that end at any type.
name: string optional
Filter paths to only those that end at an entity with a name that includes the specified substring. Defaults to not filtering paths by name.
watchlist: boolean optional
Filter paths to only those that end at an entity appearing on a watchlist or pep list. Defaults to not filtering paths by watchlist or pep status.

# Examples

GET /v1/traversal/123?max_depth=6&relationships=has_shareholder&relationships=branch_of&psa HTTP/1.1
Accept: application/json

{
    "min_depth": 1,
    "max_depth": 6,
    "relationships": ["has_shareholder", "branch_of"],
    "countries": [],
    "types": [],
    "name": "",
    "watchlist": false,
    "psa": true,
    "offset": 0,
    "limit": 50,
    "next": true,
    "data": [
        {
            "target": EmbeddedEntity,
            "path": PathSegment[]
        },
        ...
    ],
    "explored_count": 1201
}

# UBO

GET /v1/ubo/:id
Accept: application/json

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:

GET /v1/traversal/:id?relationships=has_shareholder&relationships=has_beneficial_owner&relationships=has_owner&relationships=subsidiary_of&relationships=branch_of

# Arguments

See Traversal

# Examples

See Traversal

# Ownership

GET /v1/downstream/:id
Accept: application/json

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:

GET /v1/traversal/:id?relationships=shareholder_of&relationships=beneficial_owner_of&relationships=owner_of&relationships=has_subsidiary&relationships=has_branch

# Arguments

See Traversal

# Examples

See Traversal

# Watchlist

GET /v1/watchlist/:id
Accept: application/json

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

GET /v1/traversal/:id?watchlist

# Arguments

See Traversal

# Examples

See Traversal

# Shortest Path

GET /v1/shortest_path
Accept: application/json

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

# Arguments

entities: string[]
Entity ids

# Examples

GET /v1/shortest_path?entities=123&entities=345 HTTP/1.1
Accept: application/json

{
    "entities": [
        "123",
        "345"
    ],
    "data": [
        {
            "target": EmbeddedEntity,
            "path": PathSegment[]
        }
    ]
}

# Record

GET /v1/record/:id
Accept: application/json

Records represent the documents used to source entities. The record resource includes metadata about the document itself as well as the entities extracted from the document.

# Arguments

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

# Content Types

Supported content types include:

application/json
JSON encoded response.

# Examples

GET /v1/record/:id HTTP/1.1
Accept: application/json

{
    "id": "1",
    "label": "foo",
    "source_url": "/source/1",
    "publication_date": "2018-02-29",
    "acquisition_date": "2018-06-13",
    "references_count": 3,
    "record_url": "/record/1",
    "document_urls": [
        "/document/1/file/company-html.html",
    ],
    "references": {
        "next": false,
        "offset": 0,
        "limit": 100,
        "size": {
            "count": 1,
            "qualifier": "eq"
        },
        "data": EmbeddedEntity[]
    }
}

# Fields

id: string
Internal ID of the associated record.
label: string
Human readable label for the record.
source_url: string
Url to the source associated with the record.
publication_date: date
Date of record publication.
acquisition_date: date
The date Sayari acquired the source document.
references_count: integer
Count of entities referenced in source document.
record_url: string
Url to current record.
document_urls: string array optional
A list of document urls for downloading the underlying source document. If omitted then source document is not able to be downloaded.
references: paginated search entity
A list of embedded entity references with meta indicating the type of reference.

# Reference Types

An about reference gives a list of entities that the record is specifically about. In most cases there will be a single entity of this type.

The mentions reference is the other reference type and corresponds to another entity mentioned in the record.

GET /v1/search/[entity|record]
Accept: application/json

The search endpoint allows for the ability to search Sayari internal data using text queries. Both entity and records have associated search endpoints with common arguments.

# Arguments

q: string
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.
filter: Filter array optional
Filters to be applied to search query to limit the result-set. Set as an object {"filter_key": "value"} where filter_key can be one of source, country, or entity_type. Serialized to query string if not sent in POST request.
fields: string array
Record or entity fields to search against.
facets: boolean optional
Whether or not to return search facets in results giving counts by field. Defaults to false.
advanced: boolean optional
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.
limit: integer optional
A limit on the number of objects to be returned with a range between 1 and 100. Defaults to 100.
offset: integer optional
Number of results to skip before returning response. Defaults to 0.

# Content Types

Supported content types include:

application/json
JSON encoded response.
text/csv
CSV string representation of response.

# Examples

To make a simple request use the q parameter to search against a query. The following are equivalent:

GET /v1/search/record?q=test HTTP/1.1
Accept: application/json

POST /v1/search/record HTTP/1.1
Accept: application/json

{
  "q": "test"
}

WARNING

All search arguments passed through the query string of the GET request must be url encoded. For example foo OR (bar~5) becomes foo%20OR%20(bar~5).

# Fields

To search against a specific field, use the fields parameter in the request. This request will search addresses and names for apple.

GET /v1/search/record?q=apple&fields=address&fields=name HTTP/1.1
Accept: application/json

POST /v1/search/record HTTP/1.1
Accept: application/json

{
  "q": "test",
  "fields": ["address", "name"]
}

The following fields are supported:

  • name
  • identifier
  • address
  • business_purpose
  • date_of_birth
  • contact

# Filters

Filters are parameters that limit the result-set post query. They can have different representations depending on request type. If using a GET request, filters can be added to the query string as an array with the format filter=id. For example, a filter against sources for UK Corporate Registry which has the id ecdfb3f2ecc8c3797e77d5795a8066ef would look like filters=source%3Decdfb3f2ecc8c3797e77d5795a8066ef. Alternatively, the filter can be expressed in the body of the request as a Filter object which looks like the following:

{
  "filters": {
      "source": [ "ecdfb3f2ecc8c3797e77d5795a8066ef" ]
  }
}

Notice the array type indicating that the query can be filtered by multiple sources. An example filtered request by multiple sources would appear as follows:

GET /v1/search/entity?filters=source=ecdfb3f2ecc8c3797e77d5795a8066ef&filters=source=4ea8bac1bed868e1510ffd21842e9551&q=example HTTP/1.1
Accept: application/json

POST /v1/search/entity HTTP/1.1
Accept: application/json
{
    "q": "test",
     "filters": {
         "source": [
             "ecdfb3f2ecc8c3797e77d5795a8066ef",
             "4ea8bac1bed868e1510ffd21842e9551"
         ]
     }
}

The following fields support filtering:

  • entity_type
  • source
  • country

# Facets

A search response can display the facet results for filtering fields depending on the request. If the facets argument is applied then they will be provided in the response. For example, using the following request:

GET /v1/search/record?q=example&facets=true HTTP/1.1
Accept: application/json

The responses will look like:

{
    "offset": 0,
    "limit": 1,
    "next": true,
    "size": {
        "count": 10000,
        "qualifier": "gte"
    },
    "data": [
        {
            "id": "1",
            "label": "Foo Bar",
            "source_url": "/source/1",
            "publication_date": "2018-05-23",
            "acquisition_date": "2018-02-12",
            "references_count": 3,
            "record_url": "/record/1",
            "matches": {
                "address": [
                    "Foo <em>example</em> Bar",
                ],
            }
        }
    ],
    "facets": {
        "country": [
            {
                "key": "TUR",
                "label":"Turkey",
                "doc_count": 37701
            },
            {
                "key": "GBR",
                "label":"United Kingdom",
                "doc_count": 26706
            },
            {
            
                "key": "USA",
                "label":"United States",
                "doc_count": 10813
            }
        ],
        "entity_type": [
            {
                "key": "company",
                "doc_count": 36720
            },
            {
                "key": "property",
                "doc_count": 22484
            }
        ],
         "source": [
              {
                "key": "123465646464",
                "doc_count": 435631
            },
            {
                "key": "999596322424",
                "doc_count": 21078
            },
        ],
        "source_type": [
            {
                "key": "Company data",
                "doc_count": 441718
            },
            {
                "key": "Litigation data",
                "doc_count": 28980
            },
            {
                "key": "Other",
                "doc_count": 169
            },
        ],
        "region": [
            {
                "key": "USA & Canada",
                "doc_count": 435980
            },
            {
                "key": "Asia Pacific",
                "doc_count": 26014
            },
            {
                "key": "Latin America & Caribbean",
                "doc_count": 4099
            }
        ]
    }
}

The search endpoint gives the ability for users to specify their query in full elasticsearch query string syntax. This allows for fielded search with more advanced operators than available with the default query syntax. The following advanced query for name = foo, identifier = bar can be expressed in the following request with the advanced parameter is set to true and the query set to the uri-encoded equivalent of (name.value:foo OR identifier.value:bar).

GET /v1/search/entity?q=(name.value%3Afoo%20OR%20identifier.value%3Abar)&advanced=true HTTP/1.1
Accept: application/json, text/javascript

Alternatively, to search for an identifier of a specific type, use the url-encoded equivalent of (identifier.value:123 AND identifier.type:uk_company_number). The list of available fields is as follows:

  • name.value
  • identifier.value, identifier.type. For a list of possible identifier types, see the ontology documentation for identifier types
  • address.value
  • business_purpose.value
  • date_of_birth.value
  • contact.value, contact.type. For a list of possible contact types, see the ontology documentation for contact types

To search against sayari entities use the /search/entity endpoint. The will give a paginated response of Embedded Entities along with the fields that the search matched against.

Request:

GET /v1/search/entity?q=example&limit=1 HTTP/1.1
Accept: application/json, text/javascript

Response:

{
    "offset": 0,
    "limit": 1,
    "next": true,
    "size": {
        "count": 10000,
        "qualifier": "gte"
    },
    "data": [
        {
            "id": "1",
            "label": "example company",
            "type": "company",
            "entity_url": "/entity/1",
            "identifiers": [
                {
                    "type": "test_identifier",
                    "value": "1"
                }
            ],
            "countries": [
                "VEN"
            ],
            "source_count": {
                "1122": {
                    "count": 63,
                    "label": "UK Companies House",
                }
            },
            "relationship_count": {
                "has_employee": 63
            },
            "matches": {
                "name": [
                    "<em>example company</em>"
                ]
            }
        }
    ]
}

To search against sayari records and documents use the /v1/search/record endpoint. The will give a paginated response of Embedded Records along with the fields that the search matched against.

Request:

GET /v1/search/record?q=test&limit=1 HTTP/1.1
Accept: application/json, text/javascript

Response:

{
    "offset": 0,
    "limit": 1,
    "next": true,
    "size": {
        "count": 10000,
        "qualifier": "gte"
    },
    "data": [
        {
            "id": "1",
            "label": "Foo Bar",
            "source_url": "/source/1",
            "publication_date": "2018-05-23",
            "crawl_date": "2018-02-12",
            "acquisition_date": 3,
            "record_url": "/record/1",
            "matches": {
                "address": [
                    "Foo <em>example</em> Bar",
                ],
            }
        }
    ],
}

# Sources

The sources endpoint returns metadata for all sources that Sayari collects data from.

GET /v1/source/:id
Accept: application/json

GET /v1/sources
Accept: application/json

# Arguments

limit: integer optional
A limit on the number of objects to be returned with a range between 1 and 100. Defaults to 100.
offset: integer optional
Number of results to skip before returning response. Defaults to 0.

# Content Types

Supported content types include:

application/json
JSON encoded response.

# Source by ID

GET /v1/source/b9dc2ca839c318d04910a8a680131fdf HTTP/1.1
Accept: application/json, text/javascript

{
    "id": "b9dc2ca839c318d04910a8a680131fdf",
    "label": "Albania Trade Register Extracts",
    "country": "ALB"
}

# List all Sources

GET /v1/sources?limit=10 HTTP/1.1
Accept: application/json, text/javascript

{
    "offset": 0,
    "limit": 2,
    "size": {
        "count": 124,
        "qualifier": "eq"
    },
    "next": true,
    "data": [
        {
            "id": "b9dc2ca839c318d04910a8a680131fdf",
            "label": "Albania Trade Register Extracts",
            "country": "ALB"
        },
        {
            "id": "4ea8bac1bed868e1510ffd21842e9551",
            "label": "Albania Trade Register Bulletins",
            "country": "ALB"
        }
    ]
}

# Workspace Endpoints

# Projects

Projects are user/group scoped resources that allow users to store saved entities, records, searches, graphs and directories within them.

# Create Project

The create endpoint expects a POST request including a body that contains the project label.

Request

POST /v1/projects HTTP/1.1
Accept: application/json
{
  "label": "New Project"
}

Response

{
  "data": {
	  "id": "JGlwYl",
	  "label": "Test Project",
	  "archived": false,
	  "created": "2022-02-28 16:21:25.28231+00",
	  "updated": "2022-02-28 16:21:25.28231+00"
  }
}

# List Projects

Fetch a token paginated list of all the projects that the user has access to.

GET /v1/projects HTTP/1.1
Accept: application/json

Arguments

archived: boolean optional
Determines if the list returned contains active or archived projects.
For pagination arguments see [Token Pagination](#pagination)

Example Request:

GET /v1/projects?limit=2&next=MjAyMi0wMi0yOCAxNjoyMjo0MS4yNDEzMTMrMDB8OGdqYTBC HTTP/1.1

Response:

{
	"prev": "MjAyMi0wMi0yOCAxNjoyMjozOC4wMjE3MjkrMDB8eTBuRFll",
	"next": "MjAyMi0wMi0yOCAxNjoyMjozNC43MDc0NyswMHxtR0pCR2E",
	"limit": 2,
	"data": [{
		"project": {
			"id": "y0nDYe",
			"label": "Test Project 8",
			"archived": false,
			"created": "2022-02-28 16:22:38.021729+00",
			"updated": "2022-02-28 16:22:38.021729+00"
		},
		"members": [{
			"type": "user",
			"id": "test-user",
			"role": "admin"
		}]
	},{
		"project": {
			"id": "mGJBGa",
			"label": "Test Project 7",
			"archived": false,
			"created": "2022-02-28 16:22:34.70747+00",
			"updated": "2022-02-28 16:22:34.70747+00"
		},
		"members": [{
			"type": "user",
			"id": "test-user",
			"role": "admin"
		}]
	}]
}

# Get Project

Retrieve a project and all its metadata.

GET /v1/project/:id HTTP/1.1
Accept: application/json

Response:

{
	"data": {
		"id": "y0nDYe",
		"label": "Test Project 8",
		"archived": false,
		"created": "2022-02-28 16:22:38.021729+00",
		"updated": "2022-02-28 16:22:38.021729+00"
	}
}

# List Project Contents

Fetch a token paginated list of all the resources within a project, note that this will not include resources saved within directories in the project.

GET /v1/project/:id/contents HTTP/1.1
Accept: application/json

Arguments

  For pagination arguments see Token Pagination

Example

Request:

GET /v1/project/eG6rGE/contents?limit=2&next=MjAyMi0wMi0yOCAxNzo1MzowOC41MDU5NzQrMDB8OGdqYTBC HTTP/1.1

Response:

{
	"prev": "MjAyMi0wMi0yOCAxNzo1MzowNi4xNTQxMzErMDB8eTBuRFll",
	"next": "MjAyMi0wMi0yOCAxNzo1MzowNC4xNDU1MjQrMDB8bUdKQkdh",
	"limit": 2,
	"data": [{
		"id": "y0nDYe",
		"project": "eG6rGE",
		"label": "SPICE GIRLS LLP",
		"type": "entity",
		"resourceId": "Fl7N9OvAJ3AkOwHphEBapA",
		"resourceGraph": "sayari",
		"created": "2022-02-28 17:53:06.154131+00",
		"updated": "2022-02-28 17:53:06.154131+00"
	},{
		"id": "mGJBGa",
		"project": "eG6rGE",
		"label": "SPICE GIRLS LIMITED",
		"type": "entity",
		"resourceId": "iWnrIqMeSKd2zsQ0xjkgdw",
		"resourceGraph": "sayari",
		"created": "2022-02-28 17:53:04.145524+00",
		"updated": "2022-02-28 17:53:04.145524+00"
	}]
}

# Update Project

Users with the correct permissions can update a project’s label or if the project is archived. In the PATCH request body you should specify both the field you wish to update and the value to update it with.

PATCH /v1/project/:id HTTP/1.1
Accept: application/json

Arguments

field: can either be “label” or “archived”

value: should be string when field is “label” and boolean when field is “archived”

Example Request:

PATCH /v1/project/y0nDYe HTTP/1.1
Accept: application/json

{
	"field": "label",
	"value": "New Project Label"
}

Response:

{
	"data": {
		"id": "y0nDYe",
		"label": "New Project Label",
		"archived": false,
		"created": "2022-02-28 16:22:38.021729+00",
		"updated": "2022-02-28 16:45:06.214944+00"
	}
}

# Delete Project

DELETE /v1/projects/:id HTTP/1.1
Accept: application/json

If a user does not have the correct permissions to delete a project making a request to this endpoint will result in a 403.

On success this endpoint will return the deleted project and all its metadata.

# Export Project

There are 3 endpoints available to retrieve all the saved resources within a project. Both json and excel spreadsheet exports are available.

Content Types

Supported content types include:

application/json
    JSON encoded response.
application/vnd.ms-excel
    Microsoft Excel spreadsheet.

All exports are token paginated with a default limit of 1000 resources. See Token Pagination.

Export Entities

GET /v1/project/:id/entity HTTP/1.1

Export Records

GET /v1/project/:id/record HTTP/1.1

Export All Saved Resources

GET /v1/project/:id/resource HTTP/1.1

Example

Request:

GET /v1/project/eG6rGE/entity?limit=2 HTTP/1.1
Accept: application/json

Response:

{
  "next": "MjAyMi0wMi0yOCAxNzo1MzowOC41MDU5NzQrMDB8OGdqYTBC",
  "limit": 2,
  "data": [{
    "entity": {
      "id": "6VRqD0P5l2mqyXH_7dR87w",
      "label": "SPICE GIRLS MERCHANDISING LIMITED",
      "degree": 5,
      "entity_url": "/v1/entity/6VRqD0P5l2mqyXH_7dR87w",
      "pep": false,
      "psa_count": 0,
      "sanctioned": false,
      "type": "company",
      "identifiers": [{
        "value": "03333376",
        "type": "uk_company_number",
        "label": "Uk Company Number"
      }],
      "addresses": [],
      "countries": ["GBR"],
      "relationship_count": {
        "has_registered_agent": 1,
        "has_director": 4
      },
      "source_count": {
        "ecdfb3f2ecc8c3797e77d5795a8066ef": {
          "count": 9,
          "label": "UK Corporate Registry"
        }
      }
    },
    "created": "2022-02-28 17:53:21.02577+00",
    "updated": "2022-02-28 17:53:21.02577+00",
    "label": "SPICE GIRLS MERCHANDISING LIMITED"
  }, {
    "entity": {
      "id": "FskQdZnoj2olAOG9MkBEeA",
      "label": "SPICE GIRLS TOURING LIMITED",
      "degree": 6,
      "entity_url": "/v1/entity/FskQdZnoj2olAOG9MkBEeA",
      "pep": false,
      "psa_count": 0,
      "sanctioned": false,
      "type": "company",
      "identifiers": [{
        "value": "03333358",
        "type": "uk_company_number",
        "label": "Uk Company Number"
      }],
      "addresses": [],
      "countries": ["GBR"],
      "relationship_count": {
        "has_registered_agent": 1,
        "has_director": 5
      },
      "source_count": {
        "ecdfb3f2ecc8c3797e77d5795a8066ef": {
          "count": 9,
          "label": "UK Corporate Registry"
        }
      }
    },
    "created": "2022-02-28 17:53:08.505974+00",
    "updated": "2022-02-28 17:53:08.505974+00",
    "label": "SPICE GIRLS TOURING LIMITED"
  }]
}

# Saved Resources

Users can add Sayari entities and records as saved resources to their projects. Users with the admin/editor roles can update/add/delete resources to a project.

# Create Saved Resource

POST /v1/resource HTTP/1.1
Accept: application/json

# Create Saved Entity

{
  "type": "entity"
  "project": string,
  "directory": string | undefined,
  "label": string,
  "resource_graph": "sayari",
  "resource_id": string
}

# Create Saved Record

{
  "type": "record"
  "project": string,
  "directory": string | undefined,
  "label": string,
  "resource_graph": "sayari",
  "resource_id": string
}

Example

Request:

POST /v1/resource HTTP/1.1
Accept: application/json

{
  "type": "entity",
  "project": "DgEVYa",
  "label": "test entity 1",
  "resource_graph": "sayari",
  "resource_id": "Ct5ciOlXLRqYC6NCW1Ivxw"
}

Response:

{
  "data": {
    "id": "eG6rGE",
    "project": "DgEVYa",
    "label": "test entity 1",
    "type": "entity",
    "resourceId": "Ct5ciOlXLRqYC6NCW1Ivxw",
    "resourceGraph": "sayari",
    "created": "2022-03-04 16:42:20.960509+00",
    "updated": "2022-03-04 16:42:20.960509+00"
  }
}

# Get Saved Resource

The following endpoint can be used to retrieve a saved resource and all its metadata.

GET /v1/resource/:id HTTP/1.1
Accept: application/json

Response:

{
  "data": {
    "id": "eG6rGE",
    "project": "DgEVYa",
    "label": "test entity 1",
    "type": "entity",
    "resourceId": "Ct5ciOlXLRqYC6NCW1Ivxw",
    "resourceGraph": "sayari",
    "created": "2022-03-04 16:42:20.960509+00",
    "updated": "2022-03-04 16:42:20.960509+00"
  }
}

# Update Saved Resource

Users with the admin or editor role have the ability to update a saved resource label.

PATCH /v1/resource/:id HTTP/1.1
Accept: application/json

This endpoint expects the request body to contain the the field to be updated (which should always be "label") and the new value.

{
  "field": "label",
  "value": string
}

Example Request:

PATCH /v1/resource/eG6rGE HTTP/1.1
Accept: application/json

{
  "field": "label",
  "value": "New Label"
}

Response:

{
  "data": {
    "id": "eG6rGE",
    "project": "DgEVYa",
    "label": "New Label",
    "type": "entity",
    "resourceId": "Ct5ciOlXLRqYC6NCW1Ivxw",
    "resourceGraph": "sayari",
    "created": "2022-03-04 16:42:20.960509+00",
    "updated": "2022-03-04 16:46:30.710394+00"
  }
}

# Delete Saved Resource

DELETE /v1/resource/:id HTTP/1.1
Accept: application/json

If a user does not have the correct permissions to delete a saved resource within the specified project then making a request to this endpoint will result in a 403.

Response:

{
  "data": {
    "id": "eG6rGE",
    "project": "DgEVYa",
    "label": "New Label",
    "type": "entity",
    "resourceId": "Ct5ciOlXLRqYC6NCW1Ivxw",
    "resourceGraph": "sayari",
    "created": "2022-03-04 16:42:20.960509+00",
    "updated": "2022-03-04 16:46:30.710394+00"
  }
}

# Change Notifications

Change notifications include updated data about an entity that is saved to a user’s project. Each new data release there will be a new batch of notifications for users to view. For each new release the previous release’s notifications will be deleted (if the user has not already done so).

# List all Change Notifications for resources within a project

This endpoint can be used to retrieve an offset paginated list of the resources within a project that have change notifications. Each item in the list will contain the saved resource id, the Sayari entity id of that saved resource and the counts for each type of change notification that is available for that resource.

GET /v1/project/:id/change_notifications HTTP/1.1
Accept: application/json

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.

Example

Request:

GET /v1/project/DgEVYa/change_notifications?limit=2 HTTP/1.1

Response:

{
  "limit": 2,
  "next": true,
  "data": [{
    "id": "eG6rGE",
    "resourceId": "Ct5ciOlXLRqYC6NCW1Ivxw",
    "counts": [
      [ "address", 2 ],
      [ "business_purpose", 1 ],
      [ "director_of", 1 ],
      [ "name", 5 ],
      [ "shareholder_of", 1 ]
    ]
  }, {
    "id": "VGylY4",
    "resourceId": "Ct5ciOlXLRqYC6NCW1Ivxw",
    "counts": [ [ "address", 1 ] ]
  }]
}

# List all Change Notifications for a specific saved resource

This endpoint can be used to retrieve an offset paginated list of the change notification for a specific saved resource. Each item in the list will contain the following:

  • resourceId: For attribute change notifications this will correspond to the Sayari record id. For relationship change notification this will be the id of the related entity.
  • value: For attribute change notifications this will be the new/updated attribute value. For relationship change notifications this will be the related entity's label.
  • qualifier: For attribute change notifications this will be the id of the source that contained the record from which the new attribute was parsed. For relationship change notifications this will either be the type of the related entity.
  • date The date this change notification was created.
GET /v1/resource/:id/change_notifications HTTP/1.1
Accept: application/json

Arguments

type: string optional
The specific type of notifications you wish to filter by. Possible values can be any of the attributes or relationships listed in our ontology.
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.

Example

Request:

GET /v1/resource/eG6rGE/change_notifications?type=name&limit=2 HTTP/1.1
Accept: application/json

Response:

{
  "limit": 2,
  "next": true,
  "data": [{
    "resourceId": "record123",
    "value": "New Name 1",
    "qualifier": null,
    "date": "2021-05-19T04:00:00.000Z"
  }, {
    "resourceId": "record123",
    "value": "New Name 2",
    "qualifier": null,
    "date": "2021-05-19T04:00:00.000Z"
  }]
}

# Get Change Notifications counts for a specific saved resource

GET /v1/resource/:id/change_notifications/count HTTP/1.1
Accept: application/json

Response:

{
  "address": 2,
  "business_purpose": 1,
  "director_of": 1,
  "name": 5,
  "shareholder_of": 1
}

# Delete all Change Notifications for resources within a project

DELETE /v1/project/:id/change_notifications HTTP/1.1

A successful request will result in a 204

# Delete all Change Notifications for a specific saved resource

DELETE /v1/resource/:id/change_notifications HTTP/1.1

A successful request will result in a 204

# Resolutions

The resolutions endpoints allow users to upload a list of identifying information for entities they are interested in and would like to match against Sayari data. We currently support 3 formats for uploads:

  1. mulitpart/form-data
  2. text/csv
  3. application/json

For more details on what each of those uploads should look like see the Upload Resolutions section.

Two terms that will be referenced in the below documentation:

  • Resolved Entity: An entity that was parsed from the upload and we were able to match against Sayari data
  • Unresolved Entity: An entity that was parsed from the upload and we were not able to match against Sayari data

# Upload Resolutions

When uploading a CSV for resolutions the CSV must meet the following criteria:

  • The first row should contain headers. Label each column header based on the identifier type you want to run that data against. Simply put, if the data in the first column will be entity names, name that column header “name.” Column headers can be name, country, address, date_of_birth, contact, identifier, and any identifiers here. If you have an identifier but don't know the type, use the column header identifier. Note that the headers must match how they are written above exactly otherwise the request will result in an error.
  • For each subsequent row, add the data for a single entity you want to upload and resolve.
  • Only enter one attribute per cell. If an entity has multiple attributes of the same type, for example multiple countries, you need to create multiple country column headers.
  • You are not required to add values for every column. E.g., if you have two name columns and an address column, but some entities you are resolving have one known name, you can leave the second name column empty

# multipart/form-data

Users can upload a CSV file in form-data format for resolutions. The file must be a CSV, uploading an Excel or Numbers spreadsheet will result in an error.

POST /v1/project/:id/resolutions HTTP/1.1
Content-Type: mulitpart/form-data
Accept: application/json

{
  "file": /* file as form-data goes here */
}

Response:

{
  "file": "test_file.csv",
  "uploaded": "2022-03-08T16:55:28.224Z",
  "count": 38
}

# text/csv

POST /v1/project/:id/resolutions HTTP/1.1
Content-Type: text/csv
Accept: application/json

Response:

{
  "file": "csv-body-upload",
  "uploaded": "2022-03-08T20:11:04.371Z"
  "count": 38
}

# application/json

When uploading using json the expected type for the body data is as follows:

{
  "identifier"?: { "type"?: string, "value": string }[],
  "name"?: string[],
  "country"?: string[],
  "address"?: string[],
  "date_of_birth"?: string[],
  "contact"?: string[],
}[]

Example

Request:

POST /v1/project/DgEVYa/resolutions HTTP/1.1
Content-Type: application/json
Accept: application/json

[{
  "name": [ "Institute of the Russian Diaspora (AKA Institute of Russian Abroad)", "ИНСТИТУТ РУССКОГО ЗАРУБЕЖЬЯ"],
  "identifier": [{ "type": "ru_inn", "value": "7727536630" }, { "type": "run_ogrn", "value": "1057746409379" }]
},{
  "name": ["Sergey Yurevich Panteleev", "Сергей Юрьевич Пантелеев"],
  "identifier": [{ "type": "ru_inn", "value": "772916129659" }]
},{
  "name": ["Aleksandr Gennadyevich Starunskiy", "Александр Геннадьевич Старунский"],
  "identifier": [{ "type": "ru_inn", "value": "771989171763" }]
},{
  "name": ["Denis Valyerevich Tyurin", "Денис Валерьевич Тюрин"],
  "identifier": [{ "type": "ru_inn", "value": "772807385405" }]
}, {
  "name": ["Diana Sergeevna Voronchikhina", "Диана Сергеевна Ворончихина"],
  "identifier": [ { "type": "ru_inn", "value": "434587652282" }]
},{
  "name": ["Russkiy Mir Foundation", "ФОНД \"РУССКИЙ МИР\""],
  "identifier": [{ "type": "ru_inn", "value": "7731281960" }, { "type": "run_ogrn", "value": "1077799019253" }]
},{
  "name": ["LIMITED LIABILITY COMPANY INFORMATION AGENCY \"INFOROS\"","ООО ИНФОРМАЦИОННОЕ АГЕНСТВО\"ИНФОРОС\""],
  "identifier": [{ "type": "ru_inn", "value": "7727214569" },{ "type": "run_ogrn", "value": "1037739468084" }]
},{
  "name": ["Nina Viktorovna Dorokhova", "Нина Викторовна Дорохова"],
  "identifier": [{ "type": "ru_inn", "value": "505202442068" }]
},{
  "name": ["Anastasiya Sergeevna Kirillova", "Анастасия Сергеевна Кириллова"],
  "identifier": [{ "type": "ru_inn", "value": "771674318370" }]
},{
  "name": ["Shanghai Cooperation Organization Business Club", "Ассоциация \"Деловой Клуб ШОС\""],
  "identifier": [{ "type": "ru_inn", "value": "7727289028" }, { "type": "run_ogrn", "value": "1097799029052" }]
},{
  "name": ["Georgiy Alekseevich Zuev", "Георгий Алексеевич Зуев"],
  "identifier": [{ "type": "ru_inn", "value": "772403421577" }]
},{
  "name": ["Georgiy Alekseevich Zuev", "Андрей Витальевич Ильяшенко"],
  "identifier": [{ "type": "ru_inn", "value": "771706200945" }]
}]

Response:

{
  "file": "json-body-upload",
  "uploaded": "2022-03-08T20:13:21.825Z",
  "count": 12
}

# Get Resolution Progress

Once a resolution has been uploaded users will be able to check the progress of the resolution via this endpoint.

GET /v1/project/:id/resolutions/progress
Accept: application/json

Response:

{
  "id": "DgEVYa",
  "remaining": 300,
  "total": 500,
  "started": "2022-03-08 17:45:07.945529+00",
  "updated": "2022-03-08 17:48:34.789976+00"
}

# Get Resolved Entities

Using this endpoint users can retrieve a token paginated list of the entities that we were able to resolve against Sayari data.

Resolved Entity Type:

{
  id: string //the id of the uploaded entity, can be used for deleting the entity
  count: number //number of Sayari entities that the uploaded entity matched
  // the attributes parsed from the upload
  attributes: {
    identifier?: { type?: string, value: string }[],
    name?: string[],
    country?: string[],
    address?: string[],
    date_of_birth?: string[],
    contact?: string[],
  }
  // key/value pairs for Sayari entities that were matched against and the attributes that matched.
  hits: {
    version: 1,
    values: {
      [entityId]: {
        identifier?: string[],
        name?: string[],
        country?: string[],
        address?: string[],
        date_of_birth?: string[],
        contact?: string[],
      }
    }
  }
  updated: string //the date on which the uploaded entity was last checked against Sayari data
  created: string //the date this entity was uploaded
}

For arguments see Token Pagination

GET /v1/project/:id/resolutions/resolved
Accept: application/json

Example

Request:

GET /v1/project/DgEVYa/resolutions/resolved?limit=2&next=MjAyMi0wMy0wOCAxNjo1NToyOC4xNzkrMDB8ZWE5MTdiODkxYmNjZjJlZTFhNjcyM2Q0MmM2YzAwNWY HTTP/1.1

Response:

{
  "prev": "MjAyMi0wMy0wOCAxNjo1NToyOC4xNzkrMDB8ZTQwNzllMjFlZjJmMTNiNTFhZjBhZDEwZjYzMDVjMzM",
  "next": "MjAyMi0wMy0wOCAxNjo1NToyOC4xNzkrMDB8ZGU0MzNkNTU4ZDExNTc2NWZjYmJhMDk2Nzc2MjJmOWY",
  "limit": 2,
  "size": {
    "count": 21,
    "qualifier": "eq"
  },
  "data": [{
    "id": "e4079e21ef2f13b51af0ad10f6305c33",
    "count": 1,
    "attributes": {
      "name": [
        "LIMITED LIABILITY COMPANY \"INFORMATION AGENCY INFOROS\"",
        "ООО \"ИНФОРМАЦИОННОЕ АГЕНТСТВО ИНФОРОС\""
      ],
      "identifier": [{
        "type": "ru_inn",
        "value": "5025021509",
        "label": "Ru Inn"
      }, {
        "type": "ru_ogrn",
        "value": "1045004804888",
        "label": "Ru Ogrn"
      }]
    },
    "hits": {
      "values": {
        "AEZO6OE06LvZONqlo1AznA": {
          "name": ["Limited Liability Company <em>Information</em> <em>Agency</em> <em>Inforos</em>"],
          "identifier": [
            "<em>1045004804888</em>",
            "<em>5025021509</em>",
            "<em>5025021509</em>"
          ]
        }
      },
      "version": 1
    },
    "updated": "2022-03-08 16:55:28.179+00",
    "created": "2022-03-08 16:55:28.179+00"
  }, {
    "id": "de433d558d115765fcbba09677622f9f",
    "count": 1,
    "attributes": {
      "name": [
        "Foundation for the Support of Innovative International Research",
        "Фонд поддержки инновационных международных исследований"
      ],
      "identifier": [{
        "type": "ru_inn",
        "value": "7704279288",
        "label": "Ru Inn"
      }, {
        "type": "ru_ogrn",
        "value": "1127799004277",
        "label": "Ru Ogrn"
      }]
    },
    "hits": {
      "values": {
        "H5nRqfY5KKDU1sChIvwD5g": {
          "name": ["<em>Fund</em> <em>For</em> <em>Innovative</em> <em>International</em> <em>Research</em>"],
          "identifier": [
            "<em>7704279288</em>",
            "<em>1127799004277</em>"
          ]
        }
      },
      "version": 1
    },
    "updated": "2022-03-08 16:55:28.179+00",
    "created": "2022-03-08 16:55:28.179+00"
  }]
}

# Get Unresolved Entities

Using this endpoint users can retrieve a token paginated list of the entities that we were not able to resolve against Sayari data.

Unresolved Entity Type:

{
  id: string //the id of the uploaded entity, can be used for deleting the entity
  count: number //number of Sayari entities that the uploaded entity matched
  // the attributes parsed from the upload
  attributes: {
    identifier?: { type?: string, value: string }[],
    name?: string[],
    country?: string[],
    address?: string[],
    date_of_birth?: string[],
    contact?: string[],
  }
  updated: string //the date on which the uploaded entity was last checked against Sayari data
  created: string //the date this entity was uploaded
}

For arguments see Token Pagination

GET /v1/project/:id/resolutions/unresolved
Accept: application/json

Example

Request:

GET /v1/project/DgEVYa/resolutions/unresolved?limit=2&next=MjAyMi0wMy0wOCAxNjo1NToyOC4xNzkrMDB8ZjA4YzVmMWI2N2JiZmIzODY3MDBlNTkxNDJiNmZiZmI HTTP/1.1
Accept: application/json

Response:

{
  "prev": "MjAyMi0wMy0wOCAxNjo1NToyOC4xNzkrMDB8ZDkxNWI4YjYxNzQ1NGUxMjhiMTAyMjliNjZmZmRjNWM",
  "next": "MjAyMi0wMy0wOCAxNjo1NToyOC4xNzkrMDB8Y2M4NjZiZWUxMDExM2ZkOGY3M2NhZTFiOTJjZjNlNTM",
  "limit": 2,
  "size": {
    "count": 17,
    "qualifier": "eq"
  },
  "data": [{
    "id": "d915b8b617454e128b10229b66ffdc5c",
    "attributes": {
      "name": [
        "Aleksandr Gennadyevich Starunskiy",
        "Александр Геннадьевич Старунский"
      ],
      "identifier": [{
        "type": "ru_inn",
        "value": "771989171763",
        "label": "Ru Inn"
      }, {
        "type": "ru_ogrn",
        "value": "",
        "label": "Ru Ogrn"
      }]
    },
    "updated": "2022-03-08 16:55:28.179+00",
    "created": "2022-03-08 16:55:28.179+00"
  }, {
    "id": "cc866bee10113fd8f73cae1b92cf3e53",
    "attributes": {
      "name": [
        "Mikhail Andreevich Panin",
        "Михаил Андреевич Панин"
      ],
      "identifier": [{
        "type": "ru_inn",
        "value": "774394493826",
        "label": "Ru Inn"
      },{
        "type": "ru_ogrn",
        "value": "",
        "label": "Ru Ogrn"
      }]
    },
    "updated": "2022-03-08 16:55:28.179+00",
    "created": "2022-03-08 16:55:28.179+00"
  }]
}

# Delete Resolved/Unresolved Entity

DELETE /v1/project/:id/resolutions/resolved/:resolutionId
Accept: application/json

DELETE /v1/project/:id/resolutions/unresolved/:resolutionId
Accept: application/json

# Delete All Resolved/Unresolved Entities

DELETE /v1/project/:id/resolutions/resolved
Accept: application/json

DELETE /v1/project/:id/resolutions/unresolved
Accept: application/json

# Info Endpoints

# Usage

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.

GET /usage
Accept: application/json

# Arguments

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

# Content Types

Supported content types include:

application/json
JSON encoded response.

# Examples

GET /usage

{
  "usage": {
    "get_entity": 1,
    "search": 1,
    "search_entities": 1,
    "search_records": 1
  },
  "from": "2020-05-22T22:22:22.222Z",
  "to": "2020-06-02T12:22:22.222Z"
}

Note: If usage states were not aggregated on the specified date the next closest date will be provided.

GET /usage?from=2020-05-21&to=2021-05-28

{
  "usage": {
    "get_entity": 5,
    "search": 2,
    "search_entities": 4,
    "search_records": 5
  },
  "from": "2020-05-21T00:00:00Z",
  "to": "2021-05-28T00:00:00Z"
}

# History

The history endpoint return a user's event history

GET /history
Accept: application/json

# Arguments

events: string[] optional
The type of events to filter on.
from: date optional
An ISO 8601 encoded date string indicating the starting time period for the events. In the format YYYY-MM-DD
to: date optional
An ISO 8601 encoded date string indicating the ending time period for the events. In the format YYYY-MM-DD
size: integer optional
Size to limit number of events returned
token: string optional
Pagination token to retrieve the next page of results

# Content Types

Supported content types include:

application/json
JSON encoded response.

# Examples

GET /history?from=2020-02-22&to=2021-05-29

{
    "events": [
         {
            "user": "auth0|abcd",
            "environment": "production",
            "event": "add_to_graph",
            "data": {
                "countries": [
                    "UKR"
                ],
                "email": "ab@gmail.com",
                "groups": [
                    "Group-A"
                ],
                "ip": 0,
                "level": "info",
                "message": "add_to_graph",
                "size": 51,
                "sources": [
                    "defddbef5048d6"
                ]
            },
            "timestamp": "2021-05-20T00:13:14.307Z"
        },
        ...
    ]
}

API Walk-Through →