Onboarding

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.

post
Register new signup

https://incognia.inloco.com.br/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.
Request
Response
Request
Headers
Content-Type
required
string
application/JSON
Authorization
required
string
Bearer token generated in Authenticating section.
Body Parameters
address_coordinates
optional
object
Object containing the latitude and longitude of the declared address.
structured_address
optional
object
Object containing the individual address fields.
address_line
optional
string
Complete address declared by the user. It takes precedence over structured_address if both are informed.
installation_id
required
string
Installation ID of the device from which the signup originates.
Response
200: OK
The submission is successful.
{
"id": "5e76a7ca-577c-4f47-a752-9e1e0cee9e49",
"request_id": "8afc84a7-f1d4-488d-bd69-36d9a37168b7",
"risk_assessment": "low_risk",
"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
}
}
}
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 My Apps Page.
Unable to find user device information. Please try again later and check your SDK integration
422: Unprocessable Entity
Your request is correct but Incognia was unable to process and transform the given address into a place in the world.
Empty.
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
Body with structured address
{
"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"
}
}
Body with address line
{
"installation_id": "LX2K9uIfkPIL2UIXxQCqSXDTPKkG8gLG2heKnlMrwAaCLV2KHxuji1WLElDrFBlWYJLCwbkghZVmp5WVb6UAjfxlgcExS3W1fgQ4j0ikcp7Z8x9dGTaYcVFXVf0fupbcvhI8Nh0RO9oy+3NavbBX7Q",
"address_line": "Av. Paulista, 1578 - Bela Vista, São Paulo - SP, 01310-200"
}
Body with address coordinates
{
"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://incognia.inloco.com.br/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 signup identifier which can be used to verify if the assessment changed in later calls.

request_id

string

Unique request identifier. Used for audit purposes.

risk_assessment

string

Assessment result. It may be one of high_risk, low risk, unknown risk. For more information refer to Understanding risk assessments.

evidence

object

An object with supporting evidence for the risk assessment. For more information refer to Understanding risk assessments.

get
Get the latest signup assessment

https://incognia.inloco.com.br/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
Request
Path Parameters
id
required
string
Signup ID of the event whose assessment is being queried.
Headers
Authorization
required
string
Bearer token generated in the Authenticating section.
Response
200: OK
The request is successful.
{
"id": "5e76a7ca-577c-4f47-a752-9e1e0cee9e49",
"request_id": "8afc84a7-f1d4-488d-bd69-36d9a37168b7",
"risk_assessment": "low_risk",
"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
}
}
}
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://incognia.inloco.com.br/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 signup identifier which can be used to verify if the assessment changed in later calls.

request_id

string

Unique request identifier. Used for audit purposes.

risk_assessment

string

Assessment result. It may be one of high_risk, low risk, unknown risk. For more information refer to Understanding risk assessments.

evidence

object

An object with supporting evidence for the risk assessment. For more

information refer to Understanding risk assessments.

put
Coming soon: update signup address

https://incognia.inloco.com.br/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
Request
Path Parameters
id
required
string
Signup ID of the event being updated.
Headers
Content-Type
optional
string
application/json
Authorization
required
string
Bearer token generated in the Authenticating session.
Body Parameters
structured_address
optional
object
Object containing the individual address fields of the declared address.
address_coordinates
optional
object
Object containing the latitude and longitude of the declared address.
address_line
optional
string
Complete address string. It takes precedence over structured_address if both are informed.
Response
200: OK
{
"id": "5e76a7ca-577c-4f47-a752-9e1e0cee9e49",
"request_id": "8afc84a7-f1d4-488d-bd69-36d9a37168b7",
"risk_assessment": "low_risk",
"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",
"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
}
}
}
403: Forbidden
The provided token does not have the necessary 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.
Unbale to find given sign up id.
500: Internal Server Error
Some internal error happened. Try again or, if the problem persists contact us.
Empty.
Body with address line
Body with structured address
Body with address coordinates
Body with address line
{
"address_line": "Av. Paulista, 1578 - Bela Vista, São Paulo - SP, 01310-200"
}
Body with structured address
{
"structured_address": {
"locale": "pt-BR",
"country_name": "Brazil",
"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"
}
}
Body with address coordinates
{
"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://incognia.inloco.com.br/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 signup identifier which can be used to verify if the assessment changed in later calls.

request_id

string

Unique request identifier. Used for audit purposes.

risk_assessment

string

Assessment result. It may be one of high_risk, low risk, unknown risk. For more information refer to Understanding risk assessments.

evidence

object

An object with supporting evidence for the risk assessment. For more

information refer to Understanding risk assessments.