{"_id":"5a3255fa408fe9001272f87b","project":"5587ff91b3bcf52b0051314f","version":{"_id":"5a3254fdc049430012f5586d","project":"5587ff91b3bcf52b0051314f","__v":3,"createdAt":"2017-12-14T10:39:57.964Z","releaseDate":"2017-12-14T10:39:57.964Z","categories":["5a3254fdc049430012f5586e","5a3255199a6f2000125c0d61","5bbc98ba817d5b00038e914a"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.6.0","version":"1.6"},"category":{"_id":"5a3255199a6f2000125c0d61","project":"5587ff91b3bcf52b0051314f","version":"5a3254fdc049430012f5586d","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-12-14T10:40:25.234Z","from_sync":false,"order":2,"slug":"real-time-api","title":"Real-time API"},"user":"5587ff84b3bcf52b0051314e","githubsync":"","__v":5,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-12-14T10:44:10.310Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"method":"post","examples":{"codes":[{"code":"$.post('https://frankfurt.rt.s6.io/v1/lookup', \n  {\n    uid: '12345',\n    ua: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.94 Safari/537.36',\n    ip: '1.2.3.4'\n  }, \n    function(data) {\n    console.log(data.matchid); \n  }\n);","language":"javascript"}]},"results":{"codes":[{"name":"","code":"{ \n\t\"matchid\": \"fd2fc338-8ccd-4c31-9a81-7401e8df867b\", \n  \"confidence\": 1.0 \n}","language":"json","status":200},{"name":"","code":"{\n  error: \"Cannot match without uid or ip\"\n}","language":"json","status":400}]},"settings":"","auth":"required","params":[{"_id":"5a3257ddc049430012f558a1","ref":"","in":"body","required":false,"desc":"Identifer of the end-user can be a cookie value, a device ID (IDFA, GAID), etc.","default":"End-user identifier","type":"string","name":"uid"},{"_id":"5a3257ddc049430012f558a0","ref":"","in":"body","required":false,"desc":"IP addess of the end-user should match the IP format provided in batch data delivery","default":"IP address in ipv4, ipv6 or hashed format","type":"string","name":"ip"},{"_id":"5a3257ddc049430012f5589e","ref":"","in":"body","required":false,"desc":"Full user-agent string from the end-user web request, otherwise, an equivalent application access identifier.","default":"Web user-agent string or application identifier","type":"string","name":"ua"},{"_id":"5a3257ddc049430012f5589d","ref":"","in":"header","required":false,"desc":"","default":"Authorization access token","type":"string","name":"Authorization: Bearer"}],"url":"/{version}/lookup"},"isReference":false,"order":0,"body":"The main endpoint is accessed by an authenticated POST request to `/lookup` by providing, in the body of the request, at least one of: user identifier value (`uid`) or a combination of IP address (`ip`) and User Agent (`ua`). \n\nAll payload parameters are strings and optional, however either `uid` or `ip` must have a value or the result will be 400 Bad Request. Also, matching coverage will drop significantly if not all parameters are provided.\n\nThe format of the parameter should correspond with the raw data sent for batch processing, for example, if the IP address is hashed in batch delivery, it should be identically hashed for lookup requests. If this isn't possible, the hashing mechanism must be re-implemented on this service.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.post('https://frankfurt.rt.s6.io/v1/lookup', \\n  data: {\\n    uid: '12345',\\n    ip: '1.2.3.4',\\n    ua: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.94 Safari/537.36'\\n  }, \\n  dataType: 'json',\\n  success: function(data) {\\n    console.log(data.matchid);\\n    console.log(\\\"Match provided with confidence; \\\" + data.confidence);\\n  },\\n  beforeSend: function (xhr) {\\n    xhr.setRequestHeader('Authorization', <Bearer Authorization Token>);\\n  },\\n  error: function (data, error) {\\n    console.log(data);\\n  }\\n);\",\n      \"language\": \"javascript\",\n      \"name\": \"Full code sample (JS)\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Results\"\n}\n[/block]\nIf the uid was associated with a MatchID in batch processing, the MatchID will be returned with full confidence (1.0).\n\nIf a MatchID is not found, the provided parameters and the matching history of the batch graph will be used to associate the uid to an existing MatchID. If that's successful, the MatchID will be returned with a confidence score ranging from 0 to 1.0\n\nIf a MatchID is still not obtained, one will be generated with full confidence (1.0). Future requests for this uid will return the same MatchID.","excerpt":"","slug":"api-reference","type":"endpoint","title":"API reference"}

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Body Params

uid:
stringEnd-user identifier
Identifer of the end-user can be a cookie value, a device ID (IDFA, GAID), etc.
ip:
stringIP address in ipv4, ipv6 or hashed format
IP addess of the end-user should match the IP format provided in batch data delivery
ua:
stringWeb user-agent string or application identifier
Full user-agent string from the end-user web request, otherwise, an equivalent application access identifier.

Headers

Authorization:
stringAuthorization access token

Examples


Result Format


Documentation

The main endpoint is accessed by an authenticated POST request to `/lookup` by providing, in the body of the request, at least one of: user identifier value (`uid`) or a combination of IP address (`ip`) and User Agent (`ua`). All payload parameters are strings and optional, however either `uid` or `ip` must have a value or the result will be 400 Bad Request. Also, matching coverage will drop significantly if not all parameters are provided. The format of the parameter should correspond with the raw data sent for batch processing, for example, if the IP address is hashed in batch delivery, it should be identically hashed for lookup requests. If this isn't possible, the hashing mechanism must be re-implemented on this service. [block:code] { "codes": [ { "code": "$.post('https://frankfurt.rt.s6.io/v1/lookup', \n data: {\n uid: '12345',\n ip: '1.2.3.4',\n ua: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.94 Safari/537.36'\n }, \n dataType: 'json',\n success: function(data) {\n console.log(data.matchid);\n console.log(\"Match provided with confidence; \" + data.confidence);\n },\n beforeSend: function (xhr) {\n xhr.setRequestHeader('Authorization', <Bearer Authorization Token>);\n },\n error: function (data, error) {\n console.log(data);\n }\n);", "language": "javascript", "name": "Full code sample (JS)" } ] } [/block] [block:api-header] { "title": "Results" } [/block] If the uid was associated with a MatchID in batch processing, the MatchID will be returned with full confidence (1.0). If a MatchID is not found, the provided parameters and the matching history of the batch graph will be used to associate the uid to an existing MatchID. If that's successful, the MatchID will be returned with a confidence score ranging from 0 to 1.0 If a MatchID is still not obtained, one will be generated with full confidence (1.0). Future requests for this uid will return the same MatchID.