API Reference
The core api provides two main token types, MetricsToken
and SignToken
. The metrics token is used to quickly get visitor data. The sign token can be thought of as an invisible captcha which verifies the legitimacy of the visitor and there interactions.
Metrics Token
To track visitor interactions and get enhanced visitor metrics you can use the GetMetricsToken
. If you don't care about enforcing the validity of an action and you need to perform a fast lookup, this is the reccomended token to use.
const synthient = await Synthient()
const token = await synthient.GetMetricsToken()
document.getElementById('token').value = token
Sign Token
The challenge difficulty can be set to true
for a more difficult challenge or false
for an easier challenge. This token is validated and cross checked to ensure the client has passed all the integrity checks.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script id="synthient-public-key" value="YOUR_PUBLIC_KEY" src="https://cdn.synthient.com/client.js"></script>
<title>Form</title>
</head>
<body>
<script>
window.addEventListener('load', async () => {
window.shield = await Synthient()
});
</script>
<form id="myForm" action="/your-server-endpoint" method="post">
<button type="button" onclick="sign()">Click Me</button>
<input type="hidden" id="token" name="token">
</form>
<script src="script.js"></script>
</body>
</html>
Get Visitor Data
Return visitor for a specific token.
Attributes
- Name
token
- Type
- string
- Description
The visitor token that was queried.
- Name
token_type
- Type
- string
- Description
The type of token issued, the possible values will be
metrics
sign
orstrict
.
- Name
session
- Type
- string
- Description
The persistent device session token. This will be the same for all visits from the same device. Will persist indefinitely.
- Name
timestamp
- Type
- number
- Description
Unix timestamp of when the token was issued.
- Name
solved
- Type
- boolean?
- Description
Boolean value that indicates if the token has been solved. Will be
null
for metrics tokens.
- Name
consumed
- Type
- boolean
- Description
To prevent replay attacks, the token will be consumed after the first successful lookup. Will be
true
if the token has already been used.
- Name
device
- Type
- object?
- Description
The device object will contain the device information. If for some reason the device cannot be determined this value will be
null
.
- Name
device.model
- Type
- string?
- Description
Returns the specific device model. This value will be
null
in cases where the model cannot be determined with confidence.
- Name
device.brand
- Type
- string
- Description
Device manufacturer.
- Name
device.os
- Type
- string
- Description
The operating system of the device.
- Name
device.version
- Type
- string
- Description
The device version. For android the will be a number like
11.0
for iOS it will be a string like17.4
.
- Name
browser
- Type
- object
- Description
Browser object. Contains information relating to the visitors browser.
- Name
browser.name
- Type
- string
- Description
Browser name being used. Will show the chrome fork being used if detected; check Fraud Section to understand what chrome forks are supported.
- Name
browser.version
- Type
- string
- Description
Browser version being used.
- Name
browser.version
- Type
- number
- Description
IP address of the visitor. This will be the IP address of the established connection. X-Forward-For headers will not be used due to the potential for abuse.
- Name
ip
- Type
- string
- Description
The ip address of the visitor.
- Name
intel
- Type
- object
- Description
The intelligence object will contain numerous datapoints about the visitor's ip address. This can be queried separately if you don't need to use the synthient client, check Intel Section for more information.
- Name
intel.tags
- Type
- string[]
- Description
Array of tags that are associated with the ip address. Check Intel Section for more information.
- Name
intel.asn
- Type
- number
- Description
The ASN of the ip address.
- Name
intel.isp
- Type
- string
- Description
The ISP of the ip address.
- Name
intel.device_count
- Type
- number
- Description
The number of devices that have been seen using this ip address.
- Name
location
- Type
- object
- Description
Location data associated with the ip address.
- Name
location.city
- Type
- string
- Description
City of the ip address.
- Name
location.region
- Type
- string
- Description
Region of the ip address.
- Name
location.country
- Type
- string
- Description
Country of the ip address.
- Name
location.country_code
- Type
- string
- Description
Country code of the ip address.
- Name
location.latitude
- Type
- number
- Description
Latitude of the ip address.
- Name
location.longitude
- Type
- number
- Description
Longitude of the ip address.
- Name
page
- Type
- string
- Description
The page that the visitor was on when the token was generated.
- Name
risk_score
- Type
- number
- Description
The risk score of the visitor. This value will be between 0 and 100.
- Name
is_incognito
- Type
- boolean
- Description
Boolean value that indicates if the visitor is in incognito mode. Does not impact the risk score.
- Name
is_bot
- Type
- boolean
- Description
Boolean value that indicates if the visitor is a bot. If true risk score will be set to 100.
- Name
is_vm
- Type
- boolean
- Description
Boolean value that indicates if the visitor is using a virtual machine. Does not impact the risk score.
- Name
is_emulator
- Type
- boolean
- Description
Boolean value that indicates if the visitor is using an emulator. If true risk score will be set to 100.
- Name
is_jailbroken
- Type
- boolean
- Description
Boolean value that indicates if the visitor is using a jailbroken device. If true risk score will be set to 100.
- Name
is_mobile
- Type
- boolean
- Description
Boolean value that indicates if the visitor is using a mobile device.
Request
curl -G https://api.synthient.com/api/v2/lookup/{token} \
-H "Authorization: {api_key}"
{
"token": "f7632969042612f2679e2ab65136a7dc",
"token_type": "metrics",
"session": "01cef124dead83e3f7c4fa56569f22cf",
"timestamp": 1723882034971,
"solved": null,
"consumed": false,
"device": {
"model": "iPhone 15 Pro Max",
"brand": "Apple",
"os": "iOS",
"version": "17.5"
},
"browser": {
"name": "Mobile Chrome",
"version": "125.0.6422.51"
},
"ip": "67.183.XX.XX",
"intel": {
"tags": [
"VPN",
"TOR",
"RESIDENTIAL_PROXY",
"PUBLIC_PROXY",
"CELLULAR",
"DATACENTER",
"ABUSIVE",
"POTENTIAL_BOT"
],
"asn": 20055,
"isp": "Whidbey Telephone Company",
"device_count": 1
},
"location": {
"city": "Seattle",
"region": "Washington",
"country": "United States",
"country_code": "US",
"latitude": 47.6061,
"longitude": -122.3328
},
"page": "https://synthient.com/",
"risk_score": 0,
"is_incognito": true,
"is_bot": false,
"is_vm": false,
"is_emulator": false,
"is_jailbroken": false,
"is_mobile": true
}
Session Tracking
Allows you to query all visits for a specific session. Will return 20 results per page, use the page
param to paginate through the results.
Attributes
- Name
session
- Type
- string
- Description
The session token that was queried.
- Name
session
- Type
- string
- Description
The session token that was queried.
- Name
visits
- Type
- array
- Description
Array of visit objects, each object will contain the visitor data. Note:
consumed
will be null for this endpoint. Do not use it to enforce the validity of the token.
- Name
has_next
- Type
- boolean
- Description
Boolean value that indicates if there are more results to paginate through.
Request
curl -G https://api.synthient.com/api/v2/visits/{session_token}?page=1 \
-H "Authorization: {api_key}"
{
"session": "f7632969042612f2679e2ab65136a7dc",
"visits": [ VisitObject ... ],
"has_next": true
}
Delete a Visitor
Allows you to visit data to comply with GDPR guidelines. This action is irreversible and will remove all data associated with the visitor.
Request
curl -X DELETE https://api.synthient.com/api/v2/lookup/{token} \
-H "Authorization: {api_key}"
{
"message": "Visitor data deleted"
}
Event Streaming
Synthient offers a real-time websocket server that will stream all visitor events. This can be used to build complex and efficient applications on top of the core API. The public key defines a specific channel in which all visitor events will be published to. If you are working with multiple sites you will need to subscribe to multiple websocket connections.
Visit Event: ↓ {"token":"f7632969042612f2679e2ab65136a7dc","token_type":"metrics","session":"01cef124dead83e3f7c4fa56569f22cf","solved":null,"consumed":false,"device":{"model":"iPhone 15 Pro Max","brand":"Apple","os":"iOS","version":"17.5"},"browser":{"name":"Mobile Chrome","version":"125.0.6422.51"},"ip":"67.183.XX.XX","intel":{"tags":["VPN","TOR","RESIDENTIAL_PROXY","PUBLIC_PROXY","CELLULAR","DATACENTER","ABUSIVE","POTENTIAL_BOT"],"asn":20055,"isp":"Whidbey Telephone Company","device_count":1},"location":{"city":"Seattle","region":"Washington","country":"United States","country_code":"US","latitude":47.6061,"longitude":-122.3328},"page":"https://synthient.com/","risk_score":0,"is_incognito":true,"is_bot":false,"is_vm":false,"is_emulator":false,"is_jailbroken":false,"is_mobile":true}
Websocket Connection
const WebSocket = require('ws');
const publicKey = 'PUBLIC_KEY';
const privateKey = 'PRIVATE_KEY';
const ws = new WebSocket(`wss://api.synthient.com/api/v2/stream/${publicKey}`, {
headers: {
Authorization: `Bearer ${privateKey}`,
},
});
ws.on('open', function open() {
console.log('Connected to the WebSocket server');
});
ws.on('message', function message(data) {
console.log('Received visit event:', data);
// Event data will be same format as lookup
});
ws.on('close', function close() {
console.log('Disconnected from the WebSocket server');
});