Version: v6

Onboarding

The Incognia Onboarding API delivers frictionless identity verification that reduces time to verify and onboard trusted users, and detects application fraud. It compares the address provided in an application with the current and past location behavior of the device to assess whether the new user actually lives at that address and delivers a risk assessment and supporting evidence.

When a device is new to the Incognia network, Incognia determines whether the new user is currently at the address claimed during onboarding and if not, how far away they are. At the same time, it continues to collect location data and provides an updated risk assessment. If the information provided during the onboarding process does not match the device's location behavior pattern, Incognia delivers a high risk score.

In order to assess a new sign-up, Incognia needs to receive an Installation ID to identify the device from which it originates. It also may optionally receive the address declared by the user.

POST

https://api.incognia.com/api/v2/onboarding/signups

This endpoint registers a new signup for the given device with the available information, returning a risk assessment and supporting evidence.

Even though the declared address is an optional parameter, the risk assessment quality is greatly enhanced by its addition. We recommend informing one of address_line or structured_address(the latter is the preferred option). Also, informing the address_coordinates of the declared address drastically improves the accuracy of the results.

Request
Response

Headers

Content-Type	string	Required	application/JSON
Authorization	string	Required	Bearer token generated in Authenticating section.

Body Parameters

address_coordinates	object	Optional	Object containing the latitude and longitude of the declared address.
structured_address	object	Optional	Object containing the individual address fields.
address_line	string	Optional	Complete address declared by the user. It takes precedence over structured_address if both are informed.
installation_id	string	Required	Installation ID of the device from which the signup originates.

200: OK

The submission is successful.

{
  "id": "5e76a7ca-577c-4f47-a752-9e1e0cee9e49",
  "request_id": "8afc84a7-f1d4-488d-bd69-36d9a37168b7",
  "risk_assessment": "high_risk",
  "reasons": [
    {
      "code": "multiple_accounts",
      "source": "local"
    },
    {
      "code": "multiple_installations",
      "source": "local"
    }
  ],
  "evidence": {
    // For a complete explanation of this part of the response,
    // please refer to the evidence page in the docs.
    "device_model": "Moto Z2 Play",
    "geocode_quality": "good",
    "address_quality": "good",
    "address_match": "street",
    "location_events_near_address": 38,
    "location_events_quantity": 288,
    "location_services": {
      "location_permission_enabled": true,
      "location_sensors_enabled": true
    },
    "device_integrity": {
      "probable_root": false,
      "emulator": false,
      "gps_spoofing": false,
      "from_official_store": true 
    },
    "device_fraud_reputation": "unknown",
    "device_behavior_reputation": "suspect",
    "activity_evidence": {
      "first_known_address_activity": "2021-11-22T19:16:13.591Z",
      "last_known_address_activity": "2021-11-22T19:16:13.591Z",
      "first_address_verification": "2022-01-03T21:09:13.924118Z"
    },
    "accessed_accounts": 10,
    "app_reinstallations": 5,
    "different_declared_addresses": 3,
    "distance_from_last_location_to_declared_address": 10,
    "distance_from_nearest_location_to_declared_address": 7
  },
  "device_id": "HcXQff4DRBtyIaTaYBat_SxP6fOzp_48V_oEaGm84g3LC7c4mg4JOcE0rYUT7He5QY6uZZcLfNRcphQVmfC6CA"
}

400: Bad Request

Invalid installation_id.

Empty.

403: Forbidden

The provided token does not have the required permissions.

Empty.

404: Not Found

Your request is correctly formatted but our service was unable to find device related information (Installation ID). It usually occurs when there are issues with your SDK integration, so please check it on the Apps Page.

Unable to find user device information. Please try again later and check your SDK integration

500: Internal Server Error

Some internal error happened. Try again or, if the problem persists, contact us.

Empty.

Body with structured address
Body with address line
Body with address coordinates

{
  "installation_id": "LX2K9uIfkPIL2UIXxQCqSXDTPKkG8gLG2heKnlMrwAaCLV2KHxuji1WLElDrFBlWYJLCwbkghZVmp5WVb6UAjfxlgcExS3W1fgQ4j0ikcp7Z8x9dGTaYcVFXVf0fupbcvhI8Nh0RO9oy+3NavbBX7Q",
  "structured_address": {
    "locale": "pt-BR",
    "country_name": "Brasil",
    "country_code": "BR",
    "state": "SP",
    "city": "São Paulo",
    "borough": "",
    "neighborhood": "Bela Vista",
    "street": "Av. Paulista",
    "number": "1578",
    "complements" : "Andar 2",
    "postal_code": "01310-200"
  }
}

{
  "installation_id": "LX2K9uIfkPIL2UIXxQCqSXDTPKkG8gLG2heKnlMrwAaCLV2KHxuji1WLElDrFBlWYJLCwbkghZVmp5WVb6UAjfxlgcExS3W1fgQ4j0ikcp7Z8x9dGTaYcVFXVf0fupbcvhI8Nh0RO9oy+3NavbBX7Q",
  "address_line": "Av. Paulista, 1578 - Bela Vista, São Paulo - SP, 01310-200"
}

{
  "installation_id": "LX2K9uIfkPIL2UIXxQCqSXDTPKkG8gLG2heKnlMrwAaCLV2KHxuji1WLElDrFBlWYJLCwbkghZVmp5WVb6UAjfxlgcExS3W1fgQ4j0ikcp7Z8x9dGTaYcVFXVf0fupbcvhI8Nh0RO9oy+3NavbBX7Q",
  "address_line": "Av. Paulista, 1578 - Bela Vista, São Paulo - SP, 01310-200",
  "address_coordinates": {
     "lat": -23.561414,
     "lng": -46.6558819
  }
}

Sample cURL request

curl -XPOST -H "Content-type: application/json" -H "Authorization: Bearer <token>" -d @body.json "https://api.incognia.com/api/v2/onboarding/signups"

Response body

For a 200-OK response, these are the fields you should expect as a result:

Response field	Type	Description
id	string	Unique identifier for the signup event.
request_id	string	Unique identifier for the request. Can be used for audit purposes.
risk_assessment	enum	The risk assessment result. One of `high_risk`, `low_risk` or `unknown_risk`. For more information refer to Understanding risk assessments.
reasons	array	The reasons for the risk assessment. For more information refer to Understanding risk assessments.
evidence	object	The supporting evidence for the risk assessment. For more information refer to Understanding risk assessments.
device_id	string	Unique identifier for the user's device.

GET

https://api.incognia.com/api/v2/onboarding/signups/{id}

This method allows you to query the latest assessment for a given signup event, identified by its id. Refer to Webhooks in case you want to receive assessment changes as soon as they occur.

Request
Response

Path Parameters

string

Required

Signup ID of the event whose assessment is being queried.

Headers

Authorization

string

Required

Bearer token generated in Authenticating section.

200: OK

The submission is successful.

{
  "id": "5e76a7ca-577c-4f47-a752-9e1e0cee9e49",
  "request_id": "8afc84a7-f1d4-488d-bd69-36d9a37168b7",
  "risk_assessment": "high_risk",
  "reasons": [
    {
      "code": "multiple_accounts",
      "source": "local"
    },
    {
      "code": "multiple_installations",
      "source": "local"
    }
  ],
  "evidence": {
    // For a complete explanation of this part of the response,
    // please refer to the evidence page in the docs.
    "device_model": "Moto Z2 Play",
    "geocode_quality": "good",
    "address_quality": "good",
    "address_match": "street",
    "location_events_near_address": 38,
    "location_events_quantity": 288,
    "location_services": {
      "location_permission_enabled": true,
      "location_sensors_enabled": true
    },
    "device_integrity": {
      "probable_root": false,
      "emulator": false,
      "gps_spoofing": false,
      "from_official_store": true 
    },
    "device_fraud_reputation": "unknown",
    "device_behavior_reputation": "suspect",
    "activity_evidence": {
      "first_known_address_activity": "2021-11-22T19:16:13.591Z",
      "last_known_address_activity": "2021-11-22T19:16:13.591Z",
      "first_address_verification": "2022-01-03T21:09:13.924118Z"
    },
    "accessed_accounts": 10,
    "app_reinstallations": 5,
    "different_declared_addresses": 3,
    "distance_from_last_location_to_declared_address": 10,
    "distance_from_nearest_location_to_declared_address": 7
  },
  "device_id": "HcXQff4DRBtyIaTaYBat_SxP6fOzp_48V_oEaGm84g3LC7c4mg4JOcE0rYUT7He5QY6uZZcLfNRcphQVmfC6CA",
}

403: Forbidden

The provided token does not have the required permissions.

Empty.

404: Not Found

We were unable to find the given Sign Up event assessment in our database. Please check the given id.

Unable to find the given sign up id.

500: Internal Server Error

Some internal error happened. Try again or, if the problem persists, contact us.

Empty.

Sample cURL request

curl -H "Authorization: Bearer <token>" "https://api.incognia.com/api/v2/onboarding/signups/<id>"

Response body

For a 200-OK response, these are the fields you should expect as a result:

Response field	Type	Description
id	string	Unique identifier for the signup event.
request_id	string	Unique identifier for the request. Can be used for audit purposes.
risk_assessment	enum	The risk assessment result. One of `high_risk`, `low_risk` or `unknown_risk`. For more information refer to Understanding risk assessments.
reasons	array	The reasons for the risk assessment. For more information refer to Understanding risk assessments.
evidence	object	The supporting evidence for the risk assessment. For more information refer to Understanding risk assessments.
device_id	string	Unique identifier for the user's device.

PUT

https://api.incognia.com/api/v2/onboarding/signups/{id}

This method allows you to update the address of a given signup event referenced by its id, returning a risk assessment and the evidence behind it.

Even though the declared address is an optional parameter, the risk assessment quality is greatly enhanced by its addition. We recommend informing one of address_line or structured_address. Also, informing the address_coordinates drastically improves the accuracy of the results.

Warning: this is under construction. Please consult Incognia's team before using this endpoint.

Request
Response

Path Parameters

string

Required

Signup ID of the event being updated.

Headers

Content-Type	string	Optional	application/json
Authorization	string	Required	Bearer token generated in Authenticating section.

Body Parameters

address_coordinates	object	Optional	Object containing the latitude and longitude of the declared address.
structured_address	object	Optional	Object containing the individual address fields.
address_line	string	Optional	Complete address declared by the user. It takes precedence over structured_address if both are informed.

200: OK

The submission is successful.

{
  "id": "5e76a7ca-577c-4f47-a752-9e1e0cee9e49",
  "request_id": "8afc84a7-f1d4-488d-bd69-36d9a37168b7",
  "risk_assessment": "high_risk",
  "reasons": [
    {
      "code": "multiple_accounts",
      "source": "local"
    },
    {
      "code": "multiple_installations",
      "source": "local"
    }
  ],
  "evidence": {
    // For a complete explanation of this part of the response,
    // please refer to the evidence page in the docs.
    "device_model": "Moto Z2 Play",
    "geocode_quality": "good",
    "address_quality": "good",
    "address_match": "street",
    "location_events_near_address": 38,
    "location_events_quantity": 288,
    "location_services": {
      "location_permission_enabled": true,
      "location_sensors_enabled": true
    },
    "device_integrity": {
      "probable_root": false,
      "emulator": false,
      "gps_spoofing": false,
      "from_official_store": true 
    },
    "device_fraud_reputation": "unknown",
    "device_behavior_reputation": "suspect",
    "activity_evidence": {
      "first_known_address_activity": "2021-11-22T19:16:13.591Z",
      "last_known_address_activity": "2021-11-22T19:16:13.591Z",
      "first_address_verification": "2022-01-03T21:09:13.924118Z"
    },
    "accessed_accounts": 10,
    "app_reinstallations": 5,
    "different_declared_addresses": 3,
    "distance_from_last_location_to_declared_address": 10,
    "distance_from_nearest_location_to_declared_address": 7
  },
  "device_id": "HcXQff4DRBtyIaTaYBat_SxP6fOzp_48V_oEaGm84g3LC7c4mg4JOcE0rYUT7He5QY6uZZcLfNRcphQVmfC6CA"
}

403: Forbidden

The provided token does not have the required permissions.

Empty.

404: Not Found

Your request is correctly formatted, but our service was unable to find the related sign-up information. Please check your sign-up id.

Unable to find the given sign up id.

500: Internal Server Error

Some internal error happened. Try again or, if the problem persists, contact us.

Empty.

Body with structured address
Body with address line
Body with address coordinates

{
  "installation_id": "LX2K9uIfkPIL2UIXxQCqSXDTPKkG8gLG2heKnlMrwAaCLV2KHxuji1WLElDrFBlWYJLCwbkghZVmp5WVb6UAjfxlgcExS3W1fgQ4j0ikcp7Z8x9dGTaYcVFXVf0fupbcvhI8Nh0RO9oy+3NavbBX7Q",
  "structured_address": {
    "locale": "pt-BR",
    "country_name": "Brasil",
    "country_code": "BR",
    "state": "SP",
    "city": "São Paulo",
    "borough": "",
    "neighborhood": "Bela Vista",
    "street": "Av. Paulista",
    "number": "1578",
    "complements" : "Andar 2",
    "postal_code": "01310-200"
  }
}

{
  "installation_id": "LX2K9uIfkPIL2UIXxQCqSXDTPKkG8gLG2heKnlMrwAaCLV2KHxuji1WLElDrFBlWYJLCwbkghZVmp5WVb6UAjfxlgcExS3W1fgQ4j0ikcp7Z8x9dGTaYcVFXVf0fupbcvhI8Nh0RO9oy+3NavbBX7Q",
  "address_line": "Av. Paulista, 1578 - Bela Vista, São Paulo - SP, 01310-200"
}

{
  "installation_id": "LX2K9uIfkPIL2UIXxQCqSXDTPKkG8gLG2heKnlMrwAaCLV2KHxuji1WLElDrFBlWYJLCwbkghZVmp5WVb6UAjfxlgcExS3W1fgQ4j0ikcp7Z8x9dGTaYcVFXVf0fupbcvhI8Nh0RO9oy+3NavbBX7Q",
  "address_line": "Av. Paulista, 1578 - Bela Vista, São Paulo - SP, 01310-200",
  "address_coordinates": {
     "lat": -23.561414,
     "lng": -46.6558819
  }
}

Sample cURL request

curl -XPUT -H "Content-type: application/json" -H "Authorization: Bearer <token>" -d @body.json "https://api.incognia.com/api/v2/onboarding/signups/<id>"

Response body

For a 200-OK response, these are the fields you should expect as a result:

Response field	Type	Description
id	string	Unique identifier for the signup event.
request_id	string	Unique identifier for the request. Can be used for audit purposes.
risk_assessment	enum	The risk assessment result. One of `high_risk`, `low_risk` or `unknown_risk`. For more information refer to Understanding risk assessments.
reasons	array	The reasons for the risk assessment. For more information refer to Understanding risk assessments.
evidence	object	The supporting evidence for the risk assessment. For more information refer to Understanding risk assessments.
device_id	string	Unique identifier for the user's device.

Register a new signup​

Headers

Body Parameters

200: OK

400: Bad Request

403: Forbidden

404: Not Found

500: Internal Server Error

Get the latest signup assessment​

Path Parameters

Headers

200: OK

403: Forbidden

404: Not Found

500: Internal Server Error

Coming soon: update signup address​

Path Parameters

Headers

Body Parameters

200: OK

403: Forbidden

404: Not Found

500: Internal Server Error

Register a new signup

Get the latest signup assessment

Coming soon: update signup address