Data Types

The Sayari API uses specific data types to structure the information returned in API responses.

Dates

  • Format: YYYY[-MM[-DD]]
  • Description: Dates are formatted as year-month-day, though partial dates (for example, just year **2000** or year-month **2000-10**) are acceptable. This flexibility accommodates data where full date details might not be available.
  • Usage: Dates are common in fields indicating time frames, like from_date, to_date, or publication_date.

Countries

  • Format: ISO 3166-1 alpha-3 codes
  • Description: Countries are represented using three-letter codes as defined by the International Organization for Standardization (ISO). This ensures consistency and ease of understanding across international datasets.
  • Usage: This data type is useful in filtering or identifying the geographical context of entities or records.

Source

  • Description: This type provides metadata about the data source, including its unique identifier, a human-readable label, and the associated country.
  • Usage: Source information is essential for understanding the origin of the data, which can be critical for verification or compliance purposes.

Example:

Sample Source Object
1{
2 "id": "b9dc2ca839c318d04910a8a680131fdf",
3 "label": "Albania Trade Register Extracts",
4 "country": "ALB"
5}

EmbeddedEntity

After June 25th, 2024, use the trade_count object, to understand if an entity has related shipments.
  • Description: This data type represents a summarized view of an entity, such as a company or person, within the dataset. It includes identifiers, basic attributes, and links to detailed information.
  • Usage: This type is used to provide a snapshot of an entity, often in the context of relationships or search results.
Sample Embedded Entity Object
1{
2 "id": "123",
3 "label": "ACME Co.",
4 "type": "company",
5 "entity_url": "/entity/123",
6 "identifiers": [{ "type": "uk_company_number", "value": "12345" }],
7 "countries": ["GBR"],
8 "closed": false,
9 "trade_count": {
10 "sent": 969,
11 "received": 109
12 },
13 "pep": false,
14 "sanctioned": false,
15 "psa_sanctioned": "123456",
16 "psa_count": 2,
17 "source_count": {
18 "some_source_id": {
19 "count": 2,
20 "label": "Some Source Label"
21 }
22 },
23 "degree": 304,
24 "addresses": ["32535 31st Rd, Arkansas City, KS, 67005"],
25 "date_of_birth": "1990-08-03",
26 "relationship_count": {
27 "has_shareholder": 300,
28 "shareholder_of": 4
29 }
30}

EmbeddedRecord

  • Description: This is a concise representation of a record, typically a document or filing, including its source, publication and acquisition dates, and a reference count.
  • Usage: This is useful for making quick reference to official records or documents linked to an entity.
Sample Embedded Record Object
1{
2 "id": "abc",
3 "label": "Some Record - 1/14/2020",
4 "source": "some_source_id",
5 "publication_date": "2019-02-04",
6 "acquisition_date": "2019-02-05",
7 "references_count": 2,
8 "record_url": "record/abc",
9 "source_url": "https://entity.com/company/12345"
10}

PathSegment

  • Description: This type details a segment of a relationship path in the data, showing how different entities are connected through various relationships.
  • Usage: Often used in network analysis or due diligence, this type is key in understanding complex inter-entity relationships.
Sample Path Segment Object
1{
2 "field": "shareholder_of",
3 "relationships": {
4 "shareholder_of": {
5 "values": [
6 {
7 "record": "ecdfb3f2ecc8c3797e77d5795a8066ef/123567",
8 "attributes": {
9 "shares": [
10 {
11 "percentage": 100,
12 "monetary_value": 2100000,
13 "currency": "USD"
14 }
15 ]
16 },
17 "date": "2018-06-14"
18 }
19 ]
20 },
21 "director_of": {
22 "values": [
23 {
24 "record": "ecdfb3f2ecc8c3797e77d5795a8066ef/123567",
25 "attributes": {
26 "position": [{ "value": "Director" }]
27 },
28 "from_date": "2007-12-01",
29 "to_date": "2015-05-01",
30 "acquisition_date": "2021-04-14",
31 "publication_date": "2021-04-14"
32 }
33 ],
34 "former": true
35 }
36 },
37 "entity": EmbeddedEntity
38}

PossiblySameAsMatches

  • Description: This type indicates potential matches for an entity based on similarity in attributes or relationships. It’s used to suggest possible connections or identity overlaps.
  • Usage: Entities are grouped as possibly the same and may qualify as potentially duplicate or related entities. This data type is important for risk and entity assessment.
Sample PSA Object
1{
2 "name": [
3 {
4 "target": "John Smith",
5 "source": "John C Smith"
6 }
7 ],
8 "date_of_birth": [
9 {
10 "target": "1970-05-02",
11 "source": "1970-05"
12 }
13 ]
14}