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 signup, 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://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.
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. Using this format improves our accuracy.
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 sign-up 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",
      "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 address line
Body with structured address
Body with address coordinates
Body with address line
{
  "installation_id": "LX2K9uIfkPIL2UIXxQCqSXDTPKkG8gLG2heKnlMrwAaCLV2KHxuji1WLElDrFBlWYJLCwbkghZVmp5WVb6UAjfxlgcExS3W1fgQ4j0ikcp7Z8x9dGTaYcVFXVf0fupbcvhI8Nh0RO9oy+3NavbBX7Q",
  "structured_address": {
    "locale": "en-US",
    "country_name": "United States of America",
    "country_code": "US",
    "state": "NY",
    "city": "New York City",
    "borough": "Manhattan",
    "neighborhood": "Midtown",
    "street": " W 34th St.",
    "number": "20",
    "complements" : "Floor 2",
    "postal_code": "10001"
  }
}
Body with structured address
{
  "installation_id": "LX2K9uIfkPIL2UIXxQCqSXDTPKkG8gLG2heKnlMrwAaCLV2KHxuji1WLElDrFBlWYJLCwbkghZVmp5WVb6UAjfxlgcExS3W1fgQ4j0ikcp7Z8x9dGTaYcVFXVf0fupbcvhI8Nh0RO9oy+3NavbBX7Q",
  "structured_address": {
    "locale": "en-US",
    "country_name": "United States of America",
    "country_code": "US",
    "state": "NY",
    "city": "New York City",
    "borough": "Manhattan",
    "neighborhood": "Midtown",
    "street": " W 34th St.",
    "number": "20",
    "complements" : "Floor 2",
    "postal_code": "10001"
  }
}
Body with address coordinates
{
  "installation_id": "LX2K9uIfkPIL2UIXxQCqSXDTPKkG8gLG2heKnlMrwAaCLV2KHxuji1WLElDrFBlWYJLCwbkghZVmp5WVb6UAjfxlgcExS3W1fgQ4j0ikcp7Z8x9dGTaYcVFXVf0fupbcvhI8Nh0RO9oy+3NavbBX7Q",
  "address_line": "350 Fifth Avenue, Manhattan, New York 10118",
  "address_coordinates": {
     "lat": 40.74836007062138,
     "lng": -73.98509720487937
  }
}
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 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://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 Signup ID.
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",
      "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://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 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://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 endpoint is coming soon. Please consult with the  Incognia team before use.
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 structure address
Body with address coordinates
Body with address line
{
  "address_line": "Av. Paulista, 1578 - Bela Vista, São Paulo - SP, 01310-200"
}
Body with structure address
{
  "structured_address": {
    "locale": "en-US",
    "country_name": "United States of America",
    "country_code": "US",
    "state": "NY",
    "city": "New York City",
    "borough": "Manhattan",
    "neighborhood": "Midtown",
    "street": " W 34th St.",
    "number": "20",
    "complements" : "Floor 2",
    "postal_code": "10001"
  }
}
Body with address coordinates
{
  "address_line": "350 Fifth Avenue, Manhattan, New York 10118",
  "address_coordinates": {
     "lat": 40.74836007062138,
     "lng": -73.98509720487937
  }
} 
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 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.
​
Overview
/
​
APIs - Previous
Generating an access token
Next - APIs
Transactions
Last updated 2 months ago
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.
Onboarding

postRegister new signup

getGet the latest signup assessment

putComing soon: Update signup address

post
Register new signup

get
Get the latest signup assessment

put
Coming soon: Update signup address
