Devices representing any computer or physical device used to execute an event. Devices are most suitable when events can be traced back to a specific device fingerprint.

The /devices endpoint can create, list, and update devices.

ENDPOINT

DESCRIPTION

POST /devices/create

Creates a device.

PUT /devices/<unit21_id>/update

Updates an existing device.

GET /devices/<unit21_id>

Retrieves an existing devices.

POST /devices/list

Retrieves a list of all devices.

Batch Devices Requests

The /devices/create API accepts batch uploads:

  • each batch must contains no more than 250 devices,
  • and the total size of the POST body must be smaller than 100mb.
curl -X POST \
  https://<API_ENDPOINT>/v1/devices/create \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
        "devices": [
          {
            "device_id": "3234-sdghfdf-3332",
            "device_type": "mobile",
            "status": "active",
            "registered_at": 1572672326,
            "custom_data": {
            }
          },
          {
            "device_id": "3234-sdghfdf-3333",
            "device_type": "mobile",
            "status": "active",
            "registered_at": 1572672326,
            "custom_data": {
            }
          }
        ],
        "options": {
            "upsert_on_conflict": true,
            "resolve_geoip": false,
            "merge_custom_data": true,
            "list_merge_strategy": "union"
        }
      }'

When uploading a batch of devices, any device-level options will be ignored; only the top-level options provided will be used.

If there are any data validation errors in the data that is passed (such as missing required fields) the entire batch request will fail with a 400 response code.

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
{
    "error_code": "invalid_input",
    "message": "Unexpected field `device_idd`"
}

The response contains a count of all the devices processed in the batch along with a list of objects containing three fields. The list allows you to map the devices_id passed to our API with our internal unit21_id. The response also indicates whether this device previously existed or not.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "count": 2,
  "devices": [
    {
      "device_id": "3234-sdghfdf-3332",
      "unit21_id": "49073",
      "previously_existed": false
    },
    {
      "device_id": "3234-dfsasfr-3333",
      "unit21_id": "49074",
      "previously_existed": true
    }
  ]
}

For devices that previously already existed in our system, previously_existed will be true. Unlike the /devices/update API, Unit21 will not update the device with the newly provided fields, nor will it insert a new device into our system.

Placeholder Devices

Unit21's system creates placeholders for devices, entities, instruments, or events that we expect to eventually be inserted in the system but don't yet exist.

When the details are later provided through the /devices/create, /entities/create, /instruments/create, or /events/create APIs, the placeholder objects are populated with the newly provided information.

if a placeholder device is updated and there are any field value mismatches a 400 error code will be returned.

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
{
    "error_code": "invalid_input",
    "message": "Unexpected field `device_idd`"
}

It does not matter whether you insert events and devices before their corresponding entities or insert entities before their corresponding events and devices. It is more important that the object be populated with relevant information at some point in time so that your fraud investigators can be more effective.

Upsert Devices

If the /devices/create API is called for an device that already exists in the Unit21 system (i.e. has an existing device_id), we treat it as an upsert and perform an update on the existing device.

The response to the request will then contain the field previously_existed: true.

Note that we selectively ignore upserts if the request is identical to the last received update to that resource. The response to any upsert that is skipped will then contain the entry ignored: true:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "device_id": "11b72726-18d6-43b3-a0bf-b4adf6dfd2da",
    "ignored": true,
    "previously_existed": true,
    "unit21_id": "19"
}

If you wish for the API to perform strict validation and not perform an upsert on conflict, specifying options.upsert_on_conflict: false will result in the API responding with a 409 error code indicating that this device cannot be overwritten.

curl -X POST \
  https://<API_ENDPOINT>/v1/devices/create \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
    "device_id": "11b72726-18d6-43b3-a0bf-b4adf6dfd2da",
    "device_type": "mobile",
    "device_subtype": "android",
    "status": "active",
    "registered_at": 1572672326,
    "os_name": "Android",
    "os_version": "10",
    "app_version": "5.44.5",
    "device_manufacturer": "samsung",
    "device_model": "SM-N970U",
    "timezone": "America/Los_Angeles",
    "network_carrier": "T-Mobile",
    "network_cellular": true,
    "entities": [{
        "entity_id": "userA-11b72726-18d6-43b3-a0bf-b4adf6dfd2da",
        "entity_type": "user"
      }],
    "phone_numbers": ["+1234567890"],
    "digital_data": {
        "ip_addresses": ["43.250.192.0", "52.15.247.208"]
    },
    "tags": [
        "sector:europe"
    ],
    "options": {
      "upsert_on_conflict": false,
      "resolve_geoip": false,
      "merge_custom_data": true,
      "list_merge_strategy": "union"
    }
}'
HTTP/1.1 409 CONFLICT
Content-Type: application/json
{
    "error_code": "duplicate resource",
    "message": "Device with id 11b72726-18d6-43b3-a0bf-b4adf6dfd2da already exists",
    "unit21_id": "19"
}

Delete Devices

Deleting devices is not allowed.

Options for the Endpoint

curl -X POST \
  https://<API_ENDPOINT>/v1/devices/create \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
    "options": {
      "upsert_on_conflict": true,
      "resolve_geoip": false,
      "merge_custom_data": true,
      "list_merge_strategy": "union"
    }
  }'

The following fields are options for the endpoint:

Field

Type

Description

resolve_geoip

Boolean

Whether or not to resolve the geographic location from the provided IP address (in the digital data section). Defaults to true if at least one value of an ip_address is provided in digital_data.ip_addresses. If resolve_geoip is set to true but no values are provided in digital_data.ip_addresses, an exception will be thrown. If resolve_geo_ip is set to true but the IP address provided is invalid or cannot be resolved, no exception will be thrown.

list_merge_strategy

String

Only relevant for updates/upserts, ignored otherwise. Possible values are union, replace, difference. Default is union.

upsert_on_conflict

Boolean

If you wish for the API to perform strict validation and not perform an upsert on conflict, specifying options.upsert_on_conflict: false will result in the API responding with a 409 error code indicating that this device cannot be overwritten.

merge_custom_data

Boolean

Only relevant for updates/upserts, ignored otherwise.