TDS Risk API Quickstart Guide | Integrate in Minutes

1

Create your account

⏱ ~2 minutes

Go to thedatasupermarket.com and click Sign up free. You'll need a work email address and your business details. No credit card required at this stage.

No sales call required. Account creation is entirely self-serve. You'll be in the dashboard within 3 minutes of landing on the signup page.

✓Enter your work email address

✓Set a password

✓Verify your email address

✓Confirm your business details

2

Generate your API key

⏱ ~3 minutes

In the dashboard, navigate to Settings → API Keys → Create new key. You'll need to declare your legal basis and use case. TDS Risk validates these automatically and generates your GDPR-compliant policy wording.

What is a legal basis? This is the GDPR Article 6 basis on which you're processing the data. For most fraud prevention use cases, this is Legitimate Interest (Art. 6(1)(f)). If you're not sure, choose Legitimate Interest — it's the most common for fraud screening.

Privacy policy required. Before your key is activated, you'll need to paste your privacy policy URL. TDS Risk scans it automatically to verify the required disclosures are present. Use the generated wording TDS Risk provides — it's already compliant.

✓Select product: Trust Score or Mobile KYC

✓Select legal basis (Legitimate Interest for most use cases)

✓Select your declared use case

✓Copy the generated privacy policy wording into your policy

✓Paste your policy URL — automated scan verifies compliance

✓ Your API key is generated on pass.

3

Top up your credits

⏱ ~1 minute

In the dashboard, go to Billing → Add credits. Enter your debit or credit card. Credits appear in your account instantly. Trust Score checks cost £0.35 each, Mobile KYC £0.45 each.

Credits never expire. Top up as much or as little as you like. There's no minimum. Credits roll over indefinitely — no pressure to use them by a deadline.

✓Navigate to Billing in the dashboard

✓Enter debit or credit card details

✓Select credit amount (start small — you can top up anytime)

✓Credits appear in your balance immediately

✓Your invoice will be generated instantly upon successful top-up

4

Make your first API call

⏱ ~2 minutes

Copy your API key from the dashboard and use it in the header of your request. Replace the phone number with a real UK mobile number to get a live result.

Trust Score — POST /api/trust-score
curl
JavaScript
Python
curl -X POST "https://www.thedatasupermarket.com/api/trust-score" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerReference": "my-first-check-001",
    "leadSourceId": "WEB_FORM_001",
    "phoneNumber": "447911123456",
    "country": "GB",
    "details": true
  }'
// Node.js / fetch
const response = await fetch('https://www.thedatasupermarket.com/api/trust-score', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customerReference: 'my-first-check-001',
    leadSourceId: 'WEB_FORM_001',
    phoneNumber: '447911123456',
    country: 'GB',
    details: true
  })
});
const data = await response.json();
console.log(data.response.trustScore); // e.g. 820
import requests

response = requests.post(
  'https://www.thedatasupermarket.com/api/trust-score',
  headers={
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  json={
    'customerReference': 'my-first-check-001',
    'leadSourceId': 'WEB_FORM_001',
    'phoneNumber': '447911123456',
    'country': 'GB',
    'details': True
  }
)
data = response.json()
print(data['response']['trustScore']) # e.g. 820

customerReference must be unique per call. Use a UUID, your internal transaction ID, or any unique string. The customerReference is recorded in the audit trail for every check. leadSourceId is optional — it tags the check with where the lead came from (e.g. a form name or campaign ID) so it can be filtered on later; it defaults to "API" if omitted.

5

Understand the response

⏱ ~2 minutes reading

A successful Trust Score response looks like this. Here's what each field means and how to act on it.

Example Trust Score response
200 OK
"status": 0,
"ipMatch": true,
"customerReference": "my-first-check-001",
"leadSource": "WEB_FORM_001",
"requestId": "TDS68ba778a51ccb",
"signature": "b5ed745afd02bd32a70f82dafc6fb2a41394e579206f39efa5",
"response": {
  "trustScore": 820,          // 0–1000. Higher = more trusted
  "indicators": ["PT"],         // PT = ported · info
  "callDivert": false,          // Not call-forwarded ✓
  "phoneRisk": false,           // Not on shared fraud lists ✓
  "details": {
    "riskLevel": 4,             // 4 = no SIM swap in 720+ hours ✓
    "simTimestamp": "2023-05-22T03:48:21Z" // Last SIM event
  },
  "troubleshootingId": "7c179940-d14b-477f-8a5e-123456789abc",
  "numberInfo": {
    "carrier": "EE",
    "lineType": "mobile",         // Not VoIP, not landline ✓
    "countryCode": "GB"
  }
},
"audit_url": "https://www.thedatasupermarket.com/tds-verify/audit-summary/7c179940-d14b-477f-8a5e-123456789abc",
"policy_version": "1.1",
"policy_hash": "abc123",
"latency_ms": 1150

status

0 = success. Any non-zero value means the check failed — see the error reference for what each code means.

0 = success ✓

ipMatch

true = the request's source IP is consistent with the phone number's registered country. Useful signal against proxied/VPN submissions.

true = consistent ✓

leadSource

Echoes back the leadSourceId you sent (or "API" if you didn't send one). Lets you filter checks by source in Verification History.

"WEB_FORM_001"

requestId

Unique identifier for this API call. Use this when contacting support or cross-referencing audit logs.

Unique ID per call

signature

Cryptographic signature for this specific response. Pass it along with requestId to the Risk Recall endpoint to retrieve the frozen original result later.

Per-call signature

trustScore

0–1000 composite risk score. Most teams gate at 600–700: above = proceed, below = review or reject. Tune to your own fraud rate.

820 = high trust ✓

indicators

Array of reason codes explaining the score. PT = ported number (informational). D1 = the number's text messages are exposed publicly (block). See full reason code reference.

["PT"] = informational

callDivert

true = the number currently has call forwarding active. Can indicate the SIM has been compromised or reassigned.

false = not diverted ✓

phoneRisk

true = number appears on public shared fraud lists. Block if true — these are never genuine submissions.

false = clean ✓

riskLevel

SIM swap recency. 1 = swapped in last 24 hrs (block). 4 = no swap in 720+ hrs (safe). -1 = carrier data unavailable.

4 = low risk ✓

simTimestamp

ISO 8601 timestamp of the last SIM swap event for this number. Use this to calculate how long ago the SIM changed.

Last SIM event date

lineType

If not "mobile", consider blocking. fixedvoip and nonfixedvoip are associated with fraud. landline can't receive OTPs.

"mobile" = valid ✓

audit_url

Permanent link to the immutable, signed audit record for this check. ICO-admissible evidence.

Permanent URL

policy_version

The privacy policy version that was in effect for this check, taken from your API key's linked policy scan. Proves which consent terms applied at the time.

"1.1"

policy_hash

The privacy policy hash that was in effect for this check, taken from your API key's linked policy scan. Proves which consent terms applied at the time.

"abc123"

latency_ms

Time in milliseconds taken to return the carrier response. Typically under 2 seconds for live checks.

1150 ms ✓

6

Go live

⏱ You're ready

Once you've tested with real numbers in your sandbox environment and are happy with your decision logic, switch your base URL to production and you're live. Every check from this point produces a live carrier-derived result and a signed audit record.

You're live. Every check now queries live UK carrier data in real time. Responses arrive in under 2 seconds. Each check deducts from your credit balance and produces a permanent, signed audit record.

Production base URL
// Switch from sandbox to production
// Sandbox:    https://www.thedatasupermarket.com/api/sandbox/trust-score
// Production: https://www.thedatasupermarket.com/api/trust-score

// Everything else stays the same
// Same headers, same request body, same response shape

What to explore next

📋

Reason Code Reference

Full reference for all Trust Score and Mobile KYC reason codes — searchable, colour-coded by risk level.

🔍

Mobile KYC

Add identity match scoring — nameScore, addressScore, isLostStolen — to your higher-risk journeys.

📮

Postman Collection

Pre-built requests for every endpoint. Import and be sending live requests in 2 minutes.

Make your first TDS Risk API request

Cookie preferences