Skip to main content
Version: v5

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 within 48 hours. 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.us.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 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.us.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 signup identifier which can be used to verify if the assessment changed in later calls.
request_idstringUnique request identifier. Used for audit purposes.
risk_assessmentstringAssessment result. It may be one of high_risk, low risk, unknown risk. For more information refer to Understanding risk assessments.
evidenceobjectAn object with supporting evidence for the risk assessment. For more information refer to Understanding risk assessments.

Get the latest signup assessment#

GET
https://api.us.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.us.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 signup identifier which can be used to verify if the assessment changed in later calls.
request_idstringUnique request identifier. Used for audit purposes.
risk_assessmentstringAssessment result. It may be one of high_risk, low risk, unknown risk. For more information refer to Understanding risk assessments.
evidenceobjectAn object with supporting evidence for the risk assessment. For more information refer to Understanding risk assessments.

Coming soon: update signup address#

PUT
https://api.us.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.us.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 signup identifier which can be used to verify if the assessment changed in later calls.
request_idstringUnique request identifier. Used for audit purposes.
risk_assessmentstringAssessment result. It may be one of high_risk, low risk, unknown risk. For more information refer to Understanding risk assessments.
evidenceobjectAn object with supporting evidence for the risk assessment. For more information refer to Understanding risk assessments.