{"_id":"5719767ec863120e0012a059","category":{"_id":"591e4c461e0dc20f0047b58b","version":"5719767ec863120e0012a042","__v":0,"project":"56008ba98c0c9d0d00dcaeb0","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-05-19T01:37:10.207Z","from_sync":false,"order":3,"slug":"risk-scoring","title":"Risk Verification"},"editedParams":true,"project":"56008ba98c0c9d0d00dcaeb0","editedParams2":true,"__v":1,"parentDoc":null,"user":"56008b651503430d007cc929","version":{"_id":"5719767ec863120e0012a042","hasDoc":true,"project":"56008ba98c0c9d0d00dcaeb0","__v":7,"hasReference":true,"createdAt":"2016-04-22T00:55:26.295Z","releaseDate":"2016-04-22T00:55:26.295Z","categories":["5719767ec863120e0012a043","5719767ec863120e0012a044","5719767ec863120e0012a045","5719767ec863120e0012a046","5719767ec863120e0012a047","5719767ec863120e0012a048","5719767ec863120e0012a049","57f45a18da14e71700d12e4a","582b71b15403840f008c0410","58c060cf3eee111b00a8b210","591e4c277f22100f00031521","591e4c3d094c5b0f006769fe","591e4c461e0dc20f0047b58b"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-04-11T02:42:16.982Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"method":"post","results":{"codes":[{"code":"{\n  \"score\" : 0.900,\n  \"risk_level\": \"red\",\n  \"triggers\": [\n    \"Accessed from the Tor network\",\n    \"China is a new country\"\n  ]\n}\n\n# or\n\n{\n  \"score\" : 0.751,\n  \"risk_level\": \"orange\",\n  \"triggers\": [\n    \"They travelled fast between requests\",\n    \"Activity is not usually seen during this time period\"\n  ]\n}","name":"","status":200,"language":"json"},{"language":"json","code":" {messages: [\"ip must not be blank\", \"user[id] must not be blank\"]}","name":"","status":400}]},"settings":"","examples":{"codes":[{"language":"ruby","code":"# Assuming we have a request and a user object, and the ThisData ruby gem installed.\n# https://github.com/thisdata/thisdata-ruby\n\nThisData.verify(\n  {\n    ip: request.remote_ip,\n    user_agent: request.user_agent,\n    user: {\n      id: user.id.to_s,\n    }\n  }\n)"},{"name":"cURL","language":"text","code":"curl -XPOST 'https://api.thisdata.com/v1/verify.json?api_key=API_KEY' -d '{\n  \"ip\" : \"1.2.3.4\",\n  \"user_agent\" : \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3)...\",\n  \"user\" : {\n    \"id\" : \"112233\"\n   }\n}'\n"}]},"auth":"required","params":[{"_id":"570b1055a3542f170058f398","ref":"","in":"body","required":true,"desc":"Your API Key. Required within the **query string**.<br />&nbsp;<br /><h3>JSON Body</h3>In the body of the JSON request, the following parameters are avaliable:","default":"","type":"string","name":"api_key"},{"_id":"570b1055a3542f170058f397","ref":"","in":"body","required":true,"desc":"The IP address of the request.","default":"","type":"string","name":"ip"},{"_id":"570b1055a3542f170058f396","ref":"","in":"body","required":true,"desc":"The user agent of the request.","default":"","type":"string","name":"user_agent"},{"_id":"570b1055a3542f170058f395","ref":"","in":"body","required":true,"desc":"An Object containing User details.<br /> The available object parameters are:","default":"","type":"object","name":"user"},{"_id":"570b1055a3542f170058f394","ref":"","in":"body","required":true,"desc":"The ID of the User you're verifying.","default":"","type":"string","name":"user[id]"},{"_id":"587feb1d9efedf3b0020035e","ref":"","in":"body","required":false,"desc":"A dictionary of extra information that provides useful context about the session, for example the session ID, or some cookie information","default":"","type":"object","name":"session"},{"_id":"587feb1d9efedf3b0020035d","ref":"","in":"body","required":false,"desc":"If you use a database to track sessions, you can send us the session ID","default":"","type":"string","name":"session[id]"},{"_id":"587feb1d9efedf3b0020035c","ref":"","in":"body","required":false,"desc":"When using our Javascript tracking library, a cookie is created. The cookie's ID should be sent using this *reserved* key name","default":"","type":"string","name":"session[td_cookie_id]"},{"_id":"587feb1d9efedf3b0020035b","ref":"","in":"body","required":false,"desc":"Send true when using our optional Javascript tracking library, and we'll know to expect a cookie","default":"","type":"string","name":"session[td_cookie_expected]"},{"_id":"587feb1d9efedf3b0020035a","ref":"","in":"body","required":false,"desc":"Information about the device being used","default":"","type":"object","name":"device"},{"_id":"587feb1d9efedf3b00200359","ref":"","in":"body","required":false,"desc":"This device's unique identifier (e.g. your mobile app's advertising ID)","default":"","type":"string","name":"device[id]"}],"url":"/:version/verify"},"isReference":false,"order":0,"body":"Verify requests are synchronous calls you can make to ask us \"is this request really from this user?\", and get a response with a risk score.\n\nWhen you send us a `verify` call we calculate a risk score for the person making the request. A high risk indicates that the request is being made by someone attempting to compromise an account.\n\nThe Verify API depends on behaviour ThisData has learned from events you track with the [Events API](doc:apiv1events). Therefore, in order to use the Verify API you need to be tracking events with the Events API as well.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"What does the score mean?\"\n}\n[/block]\nA high risk indicates that the request is being made by someone attempting to compromise an account. \nA lower risk score might indicate that the request looks a little unusual, but could be the legitimate user doing something new.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"What does the risk_level mean?\"\n}\n[/block]\n\n  * `green`: The user looks legitimate; there is a low risk their account is being impersonated\n  * `orange`: There are some aspects of the users behavior which are not normal; you should be wary of them\n  * `red`: The user is exhibiting _very_ suspicious behavior; if possible you should force them to authenticate themselves again, e.g. with a two factor code.\n\n\nAs our algorithm improves, the risk _scores_ may change. For example, at one point in time a score greater than 0.5 might relate to an `orange` risk_level. Then later, it must be a score of 0.6 or more to get that orange status. \n\nWe recommend using the `risk_level` attribute in your app so that you aren't coupled to the value of the `score` itself.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"What should I do with an orange or red risk level?\"\n}\n[/block]\nOrange and Red risk levels are returned when enough attributes of the users behavior are not normal, or if we have some other indications which correspond to high risk.\n\nIn these situations, how you deal with it will depend on the risk of the action the user is attempting, if your website supports other authentication methods, etc. Here are some response ideas:\n\n  * Require them to enter a second factor authentication code\n  * Flag their activity and create a support ticket for internal verification via phone or email\n  * Terminate their session, and force a password reset\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"What is the difference between /verify and /events?\"\n}\n[/block]\n[Verify](http://help.thisdata.com/v2.0/docs/v1verify) is a simple endpoint which answers the question \"How likely is it that this user's account is being impersonated?\". It executes synchronously, meaning you need to wait for us to calculate the risk and respond, before letting the user carry on with their request.\n\nThe [Events API](http://help.thisdata.com/v2.0/docs/apiv1events) is for tracking your users' behaviours, to build up a profile of their typical activity. Tracking events allows the Verify API to have a better understanding of behaviour; it is not recommended to use the Verify API without also using the Events endpoint.\n\nEvents is an asynchronous endpoint; it returns an empty response very quickly, and analyzes risk in the background. You can use this in your app without slowing down the browsing experience of your users.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Should I still send events?\"\n}\n[/block]\nYes. You **must** also send events using the `/events` endpoint, as this teaches us about usual behaviour. [Learn more about the difference between Events and Verify](doc:events-vs-verify).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Will you send was this you notifications?\"\n}\n[/block]\nNo. Only the Events endpoint will send notifications, and even then [only when you tell us to](doc:was-this-you-notifications-when-and-where).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Read More\"\n}\n[/block]\nHere's a post we wrote on [creating an Adaptive Two-Factor Authentication flow with Authy and ThisData](https://thisdata.com/blog/adaptive-two-factor-authentication-with-authy-and-thisdata/)","excerpt":"Use the Verify API to get a immediate risk score for an event","slug":"apiv1verify","type":"endpoint","title":"Get a real-time risk score"}

postGet a real-time risk score

Use the Verify API to get a immediate risk score for an event

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Body Params

api_key:
required
string
Your API Key. Required within the **query string**.<br />&nbsp;<br /><h3>JSON Body</h3>In the body of the JSON request, the following parameters are avaliable:
ip:
required
string
The IP address of the request.
user_agent:
required
string
The user agent of the request.
user:
required
object
An Object containing User details.<br /> The available object parameters are:
user[id]:
required
string
The ID of the User you're verifying.
session:
object
A dictionary of extra information that provides useful context about the session, for example the session ID, or some cookie information
session[id]:
string
If you use a database to track sessions, you can send us the session ID
session[td_cookie_id]:
string
When using our Javascript tracking library, a cookie is created. The cookie's ID should be sent using this *reserved* key name
session[td_cookie_expected]:
string
Send true when using our optional Javascript tracking library, and we'll know to expect a cookie
device:
object
Information about the device being used
device[id]:
string
This device's unique identifier (e.g. your mobile app's advertising ID)

Examples


Result Format


Documentation

Verify requests are synchronous calls you can make to ask us "is this request really from this user?", and get a response with a risk score. When you send us a `verify` call we calculate a risk score for the person making the request. A high risk indicates that the request is being made by someone attempting to compromise an account. The Verify API depends on behaviour ThisData has learned from events you track with the [Events API](doc:apiv1events). Therefore, in order to use the Verify API you need to be tracking events with the Events API as well. [block:api-header] { "type": "basic", "title": "What does the score mean?" } [/block] A high risk indicates that the request is being made by someone attempting to compromise an account. A lower risk score might indicate that the request looks a little unusual, but could be the legitimate user doing something new. [block:api-header] { "type": "basic", "title": "What does the risk_level mean?" } [/block] * `green`: The user looks legitimate; there is a low risk their account is being impersonated * `orange`: There are some aspects of the users behavior which are not normal; you should be wary of them * `red`: The user is exhibiting _very_ suspicious behavior; if possible you should force them to authenticate themselves again, e.g. with a two factor code. As our algorithm improves, the risk _scores_ may change. For example, at one point in time a score greater than 0.5 might relate to an `orange` risk_level. Then later, it must be a score of 0.6 or more to get that orange status. We recommend using the `risk_level` attribute in your app so that you aren't coupled to the value of the `score` itself. [block:api-header] { "type": "basic", "title": "What should I do with an orange or red risk level?" } [/block] Orange and Red risk levels are returned when enough attributes of the users behavior are not normal, or if we have some other indications which correspond to high risk. In these situations, how you deal with it will depend on the risk of the action the user is attempting, if your website supports other authentication methods, etc. Here are some response ideas: * Require them to enter a second factor authentication code * Flag their activity and create a support ticket for internal verification via phone or email * Terminate their session, and force a password reset [block:api-header] { "type": "basic", "title": "What is the difference between /verify and /events?" } [/block] [Verify](http://help.thisdata.com/v2.0/docs/v1verify) is a simple endpoint which answers the question "How likely is it that this user's account is being impersonated?". It executes synchronously, meaning you need to wait for us to calculate the risk and respond, before letting the user carry on with their request. The [Events API](http://help.thisdata.com/v2.0/docs/apiv1events) is for tracking your users' behaviours, to build up a profile of their typical activity. Tracking events allows the Verify API to have a better understanding of behaviour; it is not recommended to use the Verify API without also using the Events endpoint. Events is an asynchronous endpoint; it returns an empty response very quickly, and analyzes risk in the background. You can use this in your app without slowing down the browsing experience of your users. [block:api-header] { "type": "basic", "title": "Should I still send events?" } [/block] Yes. You **must** also send events using the `/events` endpoint, as this teaches us about usual behaviour. [Learn more about the difference between Events and Verify](doc:events-vs-verify). [block:api-header] { "type": "basic", "title": "Will you send was this you notifications?" } [/block] No. Only the Events endpoint will send notifications, and even then [only when you tell us to](doc:was-this-you-notifications-when-and-where). [block:api-header] { "type": "basic", "title": "Read More" } [/block] Here's a post we wrote on [creating an Adaptive Two-Factor Authentication flow with Authy and ThisData](https://thisdata.com/blog/adaptive-two-factor-authentication-with-authy-and-thisdata/)