Transactions

Verify transactions, including logins and payments, by analyzing the behavioral pattern of each user and matching it to in-app transaction history. Transactions initiated at unfamiliar locations will increase the Incognia risk score and can be used to trigger step-up authentication.
We secure digital transactions by matching the historical location fingerprint and the transaction history of the initiating user, to their real-time location. Transactions initiated at unfamiliar locations will result in a higher risk score.
Prevent fraudsters from taking over user accounts by continually analyzing user location behavior. If Incognia detects suspicious location activity, you can trigger additional authentication to confirm the user is legitimate.
post
Assess new transaction
https://api.us.incognia.com/api/v2/authentication/transactions
This method registers a new transaction for the given installation with the available information, returning a risk assessment and the supporting evidence.
Request
Response
Request
Headers
Authorization
required
string
Bearer token generated in the Authenticating section
Content-Type
required
string
application/json
Body Parameters
external_id
optional
string
Client provided transaction identifier which can be used for providing later feedbacks.
addresses
optional
array
For payment type, a list of address related to the transaction may be given. Supported address types are shipping, billing and home.
installation_id
required
string
Installation ID from which the transaction originates.
type
required
string
Type of the transaction. For now, only login is supported. payment coming soon.
account_id
required
string
ID of the user account performing the transaction.
Response
200: OK
The transaction was assessed successfully
{
  "id": "dfe1f2ff-8f0d-4ce8-aed1-af8435143044",
  "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",
    "known_account": true,
    "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",
    "distance_to_trusted_location": 21.06295635345013,
    "last_location_ts": "2022-11-01T22:45:53.299Z",
    "sensor_match_type": "gps"
  }
}
400: Bad Request
The request was malformed (missing required fields, invalid fields). The response body will contain error details.
{
  "errors": [
    "missing installation_id"
  ]
}
403: Forbidden
The provided token is invalid (or has expirated)
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 installation. 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.
Sample request 
Sample payment request with external id
Sample payment request with shipping address
Sample request 
{
  "installation_id": "LX2K9uIfkPIL2UIXxQCqSXDTPKkG8gLG2heKnlMrwAaCLV2KHxuji1WLElDrFBlWYJLCwbkghZVmp5WVb6UAjfxlgcExS3W1fgQ4j0ikcp7Z8x9dGTaYcVFXVf0fupbcvhI8Nh0RO9oy+3NavbBX7Q",
  "account_id": "c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2",
  "type": "login"
}
Sample payment request with external id
{
  "installation_id": "LX2K9uIfkPIL2UIXxQCqSXDTPKkG8gLG2heKnlMrwAaCLV2KHxuji1WLElDrFBlWYJLCwbkghZVmp5WVb6UAjfxlgcExS3W1fgQ4j0ikcp7Z8x9dGTaYcVFXVf0fupbcvhI8Nh0RO9oy+3NavbBX7Q",
  "account_id": "c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2",
  "type": "payment",
  "external_id": "3720e8ad9047dd39466b3c8974e592c2fa383d4ac3ab8ff1"
}
Sample payment request with shipping address
{
  "installation_id": "LX2K9uIfkPIL2UIXxQCqSXDTPKkG8gLG2heKnlMrwAaCLV2KHxuji1WLElDrFBlWYJLCwbkghZVmp5WVb6UAjfxlgcExS3W1fgQ4j0ikcp7Z8x9dGTaYcVFXVf0fupbcvhI8Nh0RO9oy+3NavbBX7Q",
  "account_id": "c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2",
  "type": "payment",
  "addresses": [
    {
      "type": "shipping",
      "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"
      },
      "address_coordinates": {
        "lat": 40.74836007062138,
        "lng": -73.98509720487937
      }
    }
  ]
}
Sample cURL:
curl -XPOST -H "Content-type: application/json" -H "Authorization: Bearer <token>" -d @body.json "https://api.us.incognia.com/api/v2/authentication/transactions"
Response body
For a 200-OK response, these are the fields you should expect as a result:
Response field
Type
Description
id
string
Unique transaction 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
Coming soon: Get the latest transaction assessment
https://api.us.incognia.com/api/v2/authentication/transactions/<id>
This method allows you to query the latest assessment for a given transaction event, identified by its id.

Request
Response
Request
Path Parameters
id
required
string
Transaction 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",
      "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:
curl -H "Authorization: Bearer <token>" "https://api.us.incognia.com/api/v2/authentication/transactions/<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 transaction 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.
​
APIs - Previous
Onboarding
Next - APIs
Feedback
Last updated 3 days ago
Response field	Type	Description
id	string	Unique transaction 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.
Transactions

postAssess new transaction

getComing soon: Get the latest transaction assessment

post
Assess new transaction

get
Coming soon: Get the latest transaction assessment
