Your First API Call

This guide walks you through making your first request to the Trustfull API, reading the response, and understanding the key fields returned.

Prerequisites

Before you begin, make sure you have:

• An active Trustfull account
• Your API key (available in the Dashboard under API Keys)
• A tool to make HTTP requests (cURL, Postman, or any HTTP client in your language of choice)

Authentication

All Trustfull API requests require an x-api-key header. This key identifies your account and determines your available products and rate limits.

x-api-key: your-api-key-here

Keep your API key secure. Do not expose it in client-side code, public repositories, or browser requests. All API calls should be made from your backend.

Base URL

All API requests are sent to:

https://api.fido.id

Making Your First Request

The simplest way to get started is with a Phone lookup. Send a POST request with a phone number, and Trustfull will return a risk score along with hundreds of enriched data points.

cURL

curl -X POST https://api.fido.id/phone \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "phone": "3912345678"
  }'

Python

import requests

response = requests.post(
    "https://api.fido.id/phone",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "your-api-key-here"
    },
    json={
        "phone": "3912345678"
    }
)

data = response.json()
print(f"Score: {data['phone_score']}")
print(f"Cluster: {data['phone_score_cluster']}")

Node.js

const response = await fetch("https://api.fido.id/phone", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "your-api-key-here"
  },
  body: JSON.stringify({
    phone: "3912345678"
  })
});

const data = await response.json();
console.log(`Score: ${data.phone_score}`);
console.log(`Cluster: ${data.phone_score_cluster}`);

Reading the Response

A successful request returns a JSON object with all the enriched data points. Here are the key fields you should look at first:

Score and Cluster

Every Trustfull product returns a score (0-1000) and a score_cluster that summarizes the risk level:

For a detailed explanation of how to interpret scores and clusters, see Understanding Scores.

Reason Codes

Every response includes reason codes that explain why the score is what it is. These are the building blocks of explainable fraud decisions.

Reason codes starting with R are risk signals (red flags), while codes starting with T are trust signals (positive indicators). For the full catalogue, see Reason Codes.

Sample Response

Below is a simplified example of what a Phone API response looks like. The actual response contains many more fields; see the Phone Data Catalogue for the complete reference.

{
  "customer_id": "your-customer-id",
  "resolution_id": "tf-abc123",
  "phone_value": "3912345678",
  "phone_score": 820,
  "phone_score_cluster": "very_high",
  "phone_number_type": "MOBILE",
  "phone_is_valid_format": true,
  "phone_is_disposable": false,
  "phone_country_code": "IT",
  "phone_original_network": "Vodafone Italia S.p.A",
  "phone_current_network": "Vodafone Italia S.p.A",
  "phone_is_ported": false,
  "phone_has_whatsapp": true,
  "phone_has_telegram": true,
  "phone_has_google": true,
  "phone_data_breaches_count": 3,
  "phone_reason_codes": "TP001,TP002,TP004"
}

In this example:

• The score of 820 and cluster very_high indicate a trustworthy phone number
• The phone is a valid Italian mobile number, not disposable, and not ported
• It has active messaging apps (WhatsApp, Telegram) and a Google account, suggesting real usage
• The trust reason codes confirm: TP001 (image with person), TP002 (consistent names across services), TP004 (regular velocity)

Trying Other Products

The same pattern applies to all Trustfull products. Replace the endpoint and input field:

For combined checks during user onboarding, use the Onboarding endpoint which accepts phone, email, and IP in a single call:

curl -X POST https://api.fido.id/onboarding \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "phone": "3912345678",
    "email": "[email protected]",
    "ip": "8.8.8.8",
    "first_name": "Tony",
    "last_name": "Stark"
  }'

The Onboarding endpoint returns data from all products in a single response, along with cross-signal consistency checks (e.g. whether the name from the email matches the name from the phone).

Using the Sandbox

Before going to production, you can test your integration using the Sandbox environment. Sandbox requests are free and return synthetic data. See Sandbox for setup instructions.

What's Next

• Understanding Scores - Learn how to interpret scores and clusters for your use case
• Integration Guide - End-to-end guide for integrating Trustfull into your application
• Reason Codes - Full catalogue of risk and trust signals
• API Reference - Complete API specification for all endpoints