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 an integer of any length.

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"
    }
}

Recommended actions

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

Grade points	Grade	Recommendation
90-100	A	Pass
80-89	B	Pass
70-79	C	Pass
60-69	D	Follow
1-59	F	Block