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:

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

EmbeddedEntity

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

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.

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.

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.

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
}