Submit device data

Updated
  • Updated on Mar 9, 2026
  • Published on Mar 8, 2026
Prev Next
Post
/v1/sessions/{id}/collected-data

Uploads end-user's device data that has been collected to improve verification results and fight fraud

  • This endpoint is used to send detailed technical data about the end-user's device, network environment, and browser characteristics to enhance fraud detection and risk assessment capabilities
  • The data is collected by third-party fingerprinting services and submitted during or after the verification flow

When to use this endpoint

  • Use this endpoint when you need to submit device intelligence data from third-party fingerprinting providers

Common use cases include:

  • Enhancing fraud detection by submitting comprehensive device fingerprints
  • Providing network telemetry for risk scoring and geolocation verification
  • Submitting browser characteristics and environment data for device intelligence
  • Integrating with third-party fraud prevention services that collect device data

Request body content

  • In this request, only the following fields are mandatory:

    • providerName: string Name of the fingerprinting service provider, max 255 characters
    • network.ip: string Either IPv4 or IPv6 data needs be present
    • device.fingerprint: string Device fingerprint, max 255 characters

  • The rest of the parameters listed below are optional If there is no data to provide, the parameter should not be included in the payload

Response data

  • The response confirms successful data submission and returns:

    • Request status confirmation
    • sessionId that received the collected data
    • attemptId associated with this data submission (see the List attempts endpoint for more info about attempts)

  • This data becomes part of the verification session's fraud detection signals and risk assessment

Implementation notes

  • The session must be in created or started status
  • Device fingerprint is the only required field in the device object
  • At least one IP address (IPv4 or IPv6) must be provided in network.ip
  • The person object is optional and used only if additional contact data was collected
  • This endpoint requires session-level HMAC signature authentication
  • Data submitted through this endpoint enhances fraud detection but is not required for basic verification
  • Always ensure that you use the correct API URL to send requests See the API URL section for more info.
  • The order of parameters in the real API response can differ from the order you see in this documentation. This is expected and part of the Backwards compatible changes requirements.
Header parameters
x-auth-client
stringRequired

Your integration's API key (occasionally referred to as the "Token", "API public key" or "Publishable key"). Required for all API requests.

You can find your API key in the Veriff Customer Portal > Settings > API keys.

Exampleyour-api-key
x-hmac-signature
stringRequired

Request body signed with the shared secret key. Required to authenticate the request sender.

Examplea3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a2b4
Content-Type
stringRequired

Request content type. Must be application/json.

Valid values[ "application/json" ]
Exampleapplication/json
Path parameters
id
string (uuid) Required

Verification session ID.

Examplef04bdb47-d3be-4b28-b028-a652feb060b5
Body parameters
minimal_payload

Minimum required fields to submit device fingerprinting data. Only includes the three mandatory parameters.

{
  "providerName": "SampleFingerprint",
  "network": {
    "ip": {
      "addressV4": "192.168.1.100"
    }
  },
  "device": {
    "fingerprint": "123456asdfg7890hijkl123456asdfg7890hijkl123456asdfg7890hijkl"
  }
}
comprehensive_payload

Complete device fingerprinting data including all optional fields such as person data, network details, browser characteristics, and device specifications.

{
  "providerName": "SampleFingerprint",
  "person": {
    "email": "firstname.lastname@domain.com",
    "phoneNumber": "+11 222 333 44"
  },
  "network": {
    "mobileCarrier": "RandomTeleCom Inc",
    "ssid": "MyWiFiNetwork",
    "hostname": "examplehostname.amazonaws.com",
    "location": {},
    "ip": {
      "addressV4": "192.168.1.100",
      "addressV6": "2001:DB8:0000:XXXX:XXX:17FF:FEB6:XXXX/64"
    },
    "asn": {
      "number": "AS12345",
      "organisation": "AWS"
    }
  },
  "device": {
    "fingerprint": "123456asdfg7890hijkl123456asdfg7890hijkl123456asdfg7890hijkl",
    "androidId": "ab1357cd-a1b2-c3d4-f5g6",
    "model": "Samsung Galaxy S23 Ultra",
    "vendor": "Samsung",
    "type": "mobile",
    "browser": {
      "languages": [
        "en-gb"
      ],
      "userAgent": "Mozilla/5.0 (Linux; Android 13) AppleWebKit/537.36",
      "timezoneOffsetMinutes": -240,
      "isIncognito": false
    },
    "audio": {
      "devices": [
        {
          "name": "Built-in Speaker"
        }
      ]
    },
    "screen": {
      "heightPixels": 3088,
      "widthPixels": 1440,
      "dpi": 500
    },
    "battery": {
      "level": 0.43,
      "charging": true
    },
    "os": {
      "family": "Android",
      "name": "Android",
      "platform": "ARM",
      "version": "13"
    }
  }
}
Expand All
object
providerName
string Required

Name of the company providing the fingerprinting service, max 255 characters.

ExampleSampleName
person
object

Data about the person being verified.

email
string

Person's email address entered during the validation.

Examplefirstname.lastname@domain.com
phoneNumber
string

Person's phone number.

Can include numbers, whitespaces and the "+" sign in front.

Example+11 222 333 44
network
object Required

Data about the network used.

mobileCarrier
string

Name of the service provider.

ExampleRandomTeleCom Inc
ssid
string

Service Set Identifier (SSID) value.

Example12345
hostname
string

Service host name.

Exampleexamplehostname.amazonaws.com
location
object

Additional data about the location.

ip
object Required

IP info. At least one is mandatory (IPv4 or IPv6).

addressV4
string

IPv4 info. Optional if IPv6 info is included.

Example192.168.XXX.XXX
addressV6
string

IPv6 info. Optional if IPv4 info is included.

Example2001:DB8:0000:XXXX:XXX:17FF:FEB6:XXXX/64
asn
object

Autonomous System Number (ASN) info.

number
string

Autonomous System Number (ASN).

ExampleAS12345
organisation
string

Name of the organization owning the ASN.

ExampleAWS
device
object Required

Data related to the device used for verification.

fingerprint
string Required

Device fingerprint, max 255 characters.

Example123456asdfg7890hijkl123456asdfg7890hijkl123456asdfg7890hijkl
androidId
string

The Android unique device ID is a combination of 8 digits and letters, followed by a dash and three sets of 4 digits and letters, all letters are lowercase.

Exampleab1357cd-a1b2-c3d4-f5g6
idfv
string

The Identifier for Vendors (IDFV) code.

ExampleF325G3GB-12FC-352F-C6C3-DZ52F0F690D8
model
string

Device model.

ExampleSamsung Galaxy S23 Ultra
vendor
string

Device supplier.

ExampleSamsung
type
string

Device type.

Valid values[ "desktop", "mobile", "tablet", "other" ]
Examplemobile
browser
object

Data related to the browser used for verification.

languages
Array of string

IETF language tag, for example "es-419", "en-gb", "pl".

Example[ "en-gb" ]
string
userAgent
string

Browser user agent, max 255 characters.

timezoneOffsetMinutes
integer

An integer for the time offset from the UTC, in range from -1440 to +1440 minutes.

Example-240
isIncognito
boolean

Data about whether the incognito mode is on.

Examplefalse
audio
object

Data related to the audio of the device used for verification.

devices
Array of string

Array of data strings about the audio of the device used for verification, in format of name : string.

string
screen
object

Data related to the screen of the device used for verification.

heightPixels
integer

An integer in range of 1-100000.

Example3088
widthPixels
integer

An integer in range of 1-100000

Example1440
dpi
integer

An integer in range of 1-100000.

Example500
battery
object

Data related to the battery of the device used for verification.

level
number (float)

A float in range of 0.0-1.0.

Example0.43
charging
boolean

Data about whether the device is charging.

Exampletrue
os
object

Data related to the operating system (OS) of the device used for verification.

family
string

OS family.

ExampleAndroid
name
string

OS name.

ExampleAndroid
platform
string

OS platform type, for example "x64", "ARM", "OS/390".

version
string

OS version.

Example13
Responses
200

Collected data posted successfully

Headers
Content-Type
string
Response content type.
Valid values[ "application/json" ]
x-auth-client
string
API key echoed back in response.
x-hmac-signature
string
Response body signed with the shared secret key. Required to authenticate the response sender.
successful_submission

Successful data submission

Confirmation that device fingerprinting data was successfully received and associated with the verification session and attempt.

{
  "status": "success",
  "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
  "attemptId": "f5c68aea-7f4d-478d-80ab-ca9356074f69"
}
object
status
string

API request status

Examplesuccess
sessionId
string

UUID v4 which identifies the verification session

Examplef04bdb47-d3be-4b28-b028-a652feb060b5
attemptId
string

UUID v4 which identifies the attempt

Examplef5c68aea-7f4d-478d-80ab-ca9356074f69
400

Bad request

Headers
Content-Type
string
Response content type.
x-auth-client
string
API key echoed back in response.
x-hmac-signature
string
Response body signed with the shared secret key. Required to authenticate the response sender.
missing_required_field

Missing required field

{
  "status": "fail",
  "code": "1101",
  "message": "Validation failed"
}
invalid_data_format

Invalid data format

{
  "status": "fail",
  "code": "1101",
  "message": "Validation failed"
}
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleValidation failed
401

Unauthorized

Headers
Content-Type
string
Response content type.
x-auth-client
string
API key echoed back in response.
x-hmac-signature
string
Response body signed with the shared secret key. Required to authenticate the response sender.
missing_api_key

Missing API key

{
  "status": "fail",
  "code": "1101",
  "message": "Mandatory X-AUTH-CLIENT header containing the API key is missing from the request."
}
invalid_hmac_signature

Invalid HMAC signature

{
  "status": "fail",
  "code": "1101",
  "message": "X-HMAC-SIGNATURE validation failed"
}
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleMandatory X-AUTH-CLIENT header containing the API key is missing from the request.
404

Session not found

Headers
Content-Type
string
Response content type.
x-auth-client
string
API key echoed back in response.
x-hmac-signature
string
Response body signed with the shared secret key. Required to authenticate the response sender.
session_not_found

Session does not exist

{
  "status": "fail",
  "code": "1101",
  "message": "Resource not found"
}
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleResource not found
500

Internal server error

Headers
Content-Type
string
Response content type.
x-auth-client
string
API key echoed back in response.
x-hmac-signature
string
Response body signed with the shared secret key. Required to authenticate the response sender.
server_error

Server processing error

{
  "status": "fail",
  "code": "1101",
  "message": "Something went wrong"
}
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleSomething went wrong



Document Versioning

Changelog

Date

Description

Mar 9, 2026

Documentation updated: parent categories rearranged, intro section expanded, request and response examples added

Oct 2, 2025

vrf- headers removed from response headers

Aug 6, 2025

Response headers added

Mar 12, 2025

Documentation published