Skip to main content
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.

Register a new signup

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.

Headers

Content-TypestringRequiredapplication/JSON
AuthorizationstringRequiredBearer token generated in Authenticating section.

Body Parameters

address_coordinatesobjectOptionalObject containing the latitude and longitude of the declared address.
structured_addressobjectOptionalObject containing the individual address fields.
address_linestringOptionalComplete address declared by the user. It takes precedence over structured_address if both are informed.
installation_idstringRequiredInstallation ID of the device from which the signup originates.
{
"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"
}
}

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 fieldTypeDescription
idstringUnique identifier for the signup event.
request_idstringUnique identifier for the request. Can be used for audit purposes.
risk_assessmentenumThe risk assessment result. One of high_risk, low_risk or unknown_risk. For more information refer to Understanding risk assessments.
reasonsarrayThe reasons for the risk assessment. For more information refer to Understanding risk assessments.
evidenceobjectThe supporting evidence for the risk assessment. For more information refer to Understanding risk assessments.
device_idstringUnique identifier for the user's device.

Get the latest signup assessment

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.

Path Parameters

idstringRequiredSignup ID of the event whose assessment is being queried.

Headers

AuthorizationstringRequiredBearer token generated in Authenticating section.

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 fieldTypeDescription
idstringUnique identifier for the signup event.
request_idstringUnique identifier for the request. Can be used for audit purposes.
risk_assessmentenumThe risk assessment result. One of high_risk, low_risk or unknown_risk. For more information refer to Understanding risk assessments.
reasonsarrayThe reasons for the risk assessment. For more information refer to Understanding risk assessments.
evidenceobjectThe supporting evidence for the risk assessment. For more information refer to Understanding risk assessments.
device_idstringUnique identifier for the user's device.

Coming soon: update signup address

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.

Path Parameters

idstringRequiredSignup ID of the event being updated.

Headers

Content-TypestringOptionalapplication/json
AuthorizationstringRequiredBearer token generated in Authenticating section.

Body Parameters

address_coordinatesobjectOptionalObject containing the latitude and longitude of the declared address.
structured_addressobjectOptionalObject containing the individual address fields.
address_linestringOptionalComplete address declared by the user. It takes precedence over structured_address if both are informed.
{
"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"
}
}

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 fieldTypeDescription
idstringUnique identifier for the signup event.
request_idstringUnique identifier for the request. Can be used for audit purposes.
risk_assessmentenumThe risk assessment result. One of high_risk, low_risk or unknown_risk. For more information refer to Understanding risk assessments.
reasonsarrayThe reasons for the risk assessment. For more information refer to Understanding risk assessments.
evidenceobjectThe supporting evidence for the risk assessment. For more information refer to Understanding risk assessments.
device_idstringUnique identifier for the user's device.