synthient

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

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.

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.

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.

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 Connection

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