Documentation

Table of Contents

Introduction

The Trusty API is a REST API and uses standard HTTP features.

Please contact us for the active API route to test.

Authentication

To perform requests on the API, you need to provide two secrets:

  • API_TOKEN: A token that identifies your application in the x-api-key header.
  • CUSTOMER_UUID: A token that identifies your app in the customer_uuid request body field.

You can get them by contacting us, we are providing them upon request.

Input data

We collect transactional data, currently including but not limited to:

  • phone numbers,
  • email addresses,
  • IP addresses,
  • device information, etc.

Example request

cURL

curl -X POST \
  'Contact us for API access' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: 15ea1279b1818ffe1a61a0430f9f773b' \
  -d '{
    "phone": "+1234567890",
    "ip": "",
    "email": "",
    "device_id": "",
    "customer_uuid": "525d0207-7c79-ABCD-8fa9-02aq9cf6438f"
  }'

Python

import requests

url = "Contact us for API access"

headers = {
    "Content-Type": "application/json",
    "x-api-key": "15ea1279b1818ffe1a61a0430f9f773b"
}

data = {
    "phone": "+1234567890",
    "ip": "",
    "email": "",
    "device_id": "",
    "customer_uuid": "525d0207-7c79-ABCD-8fa9-02aq9cf6438f"
}

response = requests.post(url, headers=headers, json=data)

print(f"Status Code: {response.status_code}")
print(f"Response JSON: {response.json()}")

JavaScript (Node.js)

const axios = require('axios');

const url = "Contact us for API access"

const headers = {
  'Content-Type': 'application/json',
  'x-api-key': '15ea1279b1818ffe1a61a0430f9f773b'
};

const data = {
  phone: '+1234567890',
  ip: '',
  email: '',
  device_id: '',
  sender_id: '', 
  destination_price: '',
  message_content: '',  
  customer_uuid: '525d0207-7c79-ABCD-8fa9-02aq9cf6438f'
};

axios.post(url, data, { headers })
  .then(response => {
    console.log(`Status Code: ${response.status}`);
    console.log(`Response Data:`, response.data);
  })
  .catch(error => {
    console.error('Error:', error);
  });

Ruby

require 'net/http'
require 'uri'
require 'json'

url = URI('Contact us for API access')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/json'
request['x-api-key'] = '15ea1279b1818ffe1a61a0430f9f773b'

data = {
  phone: '+1234567890',
  ip: '',
  email: '',
  device_id: '',
  customer_uuid: '525d0207-7c79-ABCD-8fa9-02aq9cf6438f'
}

request.body = data.to_json

response = http.request(request)

puts "Status Code: #{response.code}"
puts "Response Body: #{response.body}"

Example request for SMS aggregators and CPaaS providers

In addition to the standard inputs from above, SMS aggregators and CPaaS providers should include one more parameter to help distinguish between their internal customers.

By passing this information, you can separate traffic from your own clients and send that information to Trusty.

Simply add the internal_customer_id parameter, an identifier you already use to differentiate your customers to the POST API request. This value can be any alphanumeric (i.e. string) of length up to 64 characters.

Examples in Python and cURL are shown below. The same logic applies for all other languages.

cURL

curl -X POST \
  'Contact us for API access' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: 15ea1279b1818ffe1a61a0430f9f773b' \
  -d '{
    "phone": "+1234567890",
    "ip": "",
    "email": "",
    "device_id": "",
    "internal_customer_id": 1234,
    "customer_uuid": "525d0207-7c79-ABCD-8fa9-02aq9cf6438f"
  }'

Python

import requests

url = "Contact us for API access"

headers = {
    "Content-Type": "application/json",
    "x-api-key": "15ea1279b1818ffe1a61a0430f9f773b"
}

data = {
    "phone": "+1234567890",
    "ip": "",
    "email": "",
    "device_id": "",
    "internal_customer_id": 1234,
    "customer_uuid": "525d0207-7c79-ABCD-8fa9-02aq9cf6438f"
}

response = requests.post(url, headers=headers, json=data)

print(f"Status Code: {response.status_code}")
print(f"Response JSON: {response.json()}")

Example response

Example 1: Successful response

{
    "statusCode": 200,
    "headers": {
        "Content-Type": "application/json"
    },
    "body": {
        "uuid": "d440d82e-5ee9-11ef-95f3-023c8663d13d",
        "time": "2024-08-20 11:46:25.314687+00:00",
        "phone": "+1234567890",
        "email": "",
        "ip": "",
        "device_id": "",   
        "grade_points": 93,
        "grade": "A"
    }
}

Example 2: Bad phone number format

{
    "statusCode": 200,
    "headers": {
        "Content-Type": "application/json"
    },
    "body": {
        "uuid": "3e1ae7b2-5eec-11ef-95f3-023c8663d13d",
        "time": "2024-08-20 12:03:41.899888+00:00",
        "phone": "",
        "email": "",
        "ip": "",
        "device_id": "",
        "grade_points": 1,
        "grade": "F"
    }
}

Example 3: Invalid token or customer UUID

{
    "statusCode": 401,
    "headers": {
        "Content-Type": "application/json"
    },
    "body": {
        "message": "Invalid token or UUID"
    }
}

The identity API v3 version (beta)

The API v3 returns an additional important piece of information in the API response: rationale codes. These codes explain why a particular transaction received its grade and grade points. The codes are provided as a list, with variable length depending on the specific reasons behind the assigned grade.

Example 4: Successful response with rationale codes

{
    "statusCode": 200,
    "headers": {
        "Content-Type": "application/json"
    },
    "body": {
        "uuid": "d440d82e-5ee9-11ef-95f3-023c8663d13d",
        "time": "2024-08-20 11:46:25.314687+00:00",
        "phone": "+1234567890",
        "email": "",
        "ip": "",
        "device_id": "",   
        "grade_points": 93,
        "grade": "A",
        "rationale_codes": [
            101,
            111,
            201,
            211,
            301,
            311
        ]        
    }
}

Rationale codes

Rationale codes correspond to specific behaviors detected during transaction evaluation. The complete list of available codes and their descriptions is provided below.

Code groupRationale codeDescriptionRationale signal type
Transactional behavior codes101Low short-term phone transactional behaviorTrust Signal
Transactional behavior codes102Medium short-term phone transactional behaviorTrust Signal
Transactional behavior codes103High short-term phone transactional behaviorRisk Signal
Transactional behavior codes111Low long-term phone transactional behaviorTrust Signal
Transactional behavior codes112Medium long-term phone transactional behaviorTrust Signal
Transactional behavior codes113High long-term phone transactional behaviorRisk Signal
Range behavior codes201Low short-term phone range behaviorTrust Signal
Range behavior codes202Medium short-term phone range behaviorTrust Signal
Range behavior codes203High short-term phone range behaviorRisk Signal
Range behavior codes211Low long-term phone range behaviorTrust Signal
Range behavior codes212Medium long-term phone range behaviorTrust Signal
Range behavior codes213High long-term phone range behaviorRisk Signal
Cross customer behavior codes301Low short-term phone cross customer behaviorTrust Signal
Cross customer behavior codes302Medium short-term phone cross customer behaviorTrust Signal
Cross customer behavior codes303High short-term phone cross customer behaviorRisk Signal
Cross customer behavior codes311Low long-term phone cross customer behaviorTrust Signal
Cross customer behavior codes312Medium long-term phone cross customer behaviorTrust Signal
Cross customer behavior codes313High long-term phone cross customer behaviorRisk Signal
Email behavior codes401Low short-term email behaviorTrust Signal
Email behavior codes402Medium short-term email behaviorTrust Signal
Email behavior codes403High short-term email behaviorRisk Signal
Email behavior codes411Low long-term email behaviorTrust Signal
Email behavior codes412Medium long-term email behaviorTrust Signal
Email behavior codes413High long-term email behaviorRisk Signal
Email behavior codes451Not a valid email addressRisk Signal
IP behavior codes501Low short-term IP behaviorTrust Signal
IP behavior codes502Medium short-term IP behaviorTrust Signal
IP behavior codes503High short-term IP behaviorRisk Signal
IP behavior codes511Low long-term IP behaviorTrust Signal
IP behavior codes512Medium long-term IP behaviorTrust Signal
IP behavior codes513High long-term IP behaviorRisk Signal
Other codes600Whitelisted phone numberTrust Signal
Other codes601Blacklisted phone numberRisk Signal
Other codes602Not a valid phone numberRisk Signal
Other codes603Bad phone type of a phone numberRisk Signal
Other codes604Transactional spike in a particular countryRisk Signal
Other codes605Suspicious phone number carrierRisk Signal
Other codes606Bad short-term historical behaviorRisk Signal

The table below shows how grade points map to grades and what is our recommendation for each grade.

Grade pointsGradeRecommendation
90-100APass
80-89BPass
70-79CPass
60-69DFollow
1-59FBlock