How fields are shared between objects

Some data models can be added to multiple objects sent from the customer system. For example, the location_data data fields could be added to any entity, event, instrument, or object.

Whenever possible, it is advisable to include these fields whenever the data is available about an object. The same model can be associated with multiple objects, e.g. an entity and an instrument may share the exact same digital_data fields. These cross associations make the detection model more robust.

While you can associate multiple location_data and digital_data objects with entities and instruments, events only allow for associations with single locations, IP addresses, and client fingerprints.

Location data

Sample location_data object for entity and instrument APIs:

"location_data": [
  {
    "type": "SHIPPING",
    "building_number": "712",
    "street_name": "California Ave",
    "city": "Redmond",
    "state": "WA",
    "postal_code": "98008",
    "country": "US"
  },
  {
    "type": "BILLING",
    "building_number": "217",
    "street_name": "Oregon Ave",
    "city": "Redmond",
    "state": "WA",
    "postal_code": "98010",
    "country": "US"
  }
]

Sample location_data object for event APIs:

"location_data": 
{
  "type": "SHIPPING",
  "building_number": "712",
  "street_name": "California Ave",
  "city": "Redmond",
  "state": "WA",
  "postal_code": "98008",
  "country": "US"
}

Field Name	Type	Description
type	string	A string field indicating the type of address e.g. `SHIPPING`, `BILLING` (max 24 characters)
building_number	string	Building number of the primary residence (max 24 characters)
unit_number	string	Flat/unit/apartment number of the associated residence (max 24 characters)
street_name	string	Street name of primary residence (max 128 characters)
city	string	City of the primary residence (max 128 characters)
state	string	For a residence within the United States, use the two letter state codes (CA, TX, FL, etc). Otherwise, use the country and regional subdivision codes. Codes are based on the ISO 3166-1 alpha-2 standard
postal_code	string	ZIP code or postal code of primary residence. Can provide either 5-digit ZIP Code (99999) or ZIP+4 Code (99999-9999) formats for US addresses
country	string	Country of the primary residence─provided in 2 character form ISO 3166-1 alpha-2 abbreviated form

Digital data

Sample digital_data object for entity and instrument APIs:

"digital_data": {
    "ip_addresses": [
      "164.22.53.244",
      "164.22.53.245"
    ],
    "client_fingerprints": [
      "4908hsdfknkd90432nj3k2kj2jk23kj2k3jk2j3",
      "kj2jk23kj2k3jk2j34908hsdfknkd90432nj3"
    ]
}

Sample digital_data object for event APIs:

"digital_data": {
  "ip_address": "164.22.53.244",
  "client_fingerprint": "4908hsdfknkd90432nj3k2kj2jk23kj2k3jk2j3"
}

Field Name	Type	Description
ip_address	string	List of IP addresses. MUST be in either IPv4 or IPv6 format. Used for geolocating
first_seen	int	Date in seconds since 1 Jan 1970 00:00:00 UTC (i.e. in Unix time) when first seen
last_seen	int	Date in seconds since 1 Jan 1970 00:00:00 UTC (i.e. in Unix time) when last seen

client_fingerprint	string	Fingerprints associated with this entity (unique identifying number
first_seen	int	Date in seconds since 1 Jan 1970 00:00:00 UTC (i.e. in Unix time) when first seen
last_seen	int	Date in seconds since 1 Jan 1970 00:00:00 UTC (i.e. in Unix time) when last seen