Oracle API Reference

The Oracle API is a performant browser fingerprinting library which uses a variety of data points for visitor identification. The Oracle client exposes two endpoints, GetMetricsToken and GetSignToken. The GetMetricsToken endpoint is used to track visitor interactions and get enhanced visitor metrics. The GetSignToken endpoint is used to enforce browser integrity checks and prevent fraudulent 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

SignToken is an invisible captcha. The reccomended usage is to have it be called on a user interaction such as clicking a button or interacting with an element. Calling it on page load is discouraged.

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/api/v2/lookup/:token

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 or strict.
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 like 17.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.

Lookup Request

GET

/api/v2/lookup/:token

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
}

GET/api/v2/visits/:session

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.

Visits Request

GET

/api/v2/visits/:session?page=

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/api/v2/delete/:token

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.

Delete Request

DELETE

/api/v2/delete/:token

curl -X DELETE https://api.synthient.com/api/v2/lookup/{token} \
  -H "Authorization: {api_key}"

  {
    "message": "Visitor data deleted"
  }

WSS/api/v2/stream/:publicKey

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 Streaming

WSS

/api/v2/stream/:publicKey

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');
});