Getting Started — TDS Risk

1

Create your account

⏱ ~3 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

4

Make your first API call

⏱ ~3 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 /trust/v1
curl
JavaScript
Python
curl -X POST "https://api.thedatasupermarket.com/trust/v1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leadReference": "my-first-check-001",
    "phoneNumber": "447911123456",
    "country": "GB",
    "details": true
  }'
// Node.js / fetch
const response = await fetch('https://api.thedatasupermarket.com/trust/v1', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    leadReference: 'my-first-check-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://api.thedatasupermarket.com/trust/v1',
  headers={
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  json={
    'leadReference': 'my-first-check-001',
    'phoneNumber': '447911123456',
    'country': 'GB',
    'details': Always true
  }
)
data = response.json()
print(data['response']['trustScore']) # e.g. 820

leadReference must be unique per call. Use a UUID, your internal transaction ID, or any unique string. The leadReference is recorded in the audit trail for every check.

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,
"requestId": "12345abc-67d8-910ef11-gh1213ijk",
"leadReference": "my-first-check-001",
"response": {
  "trustScore": 820,          // 0–1000. Higher = more trusted
  "indicators": ["OL"],         // OL = ownership >45 days ✓
  "callInSession": false,       // Not call in session ✓
  "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
    "callDirection": "IN",
    "callDuration": "347"
  },
  "troubleshootingId": "7c179940-d14b-477f-8a5e-123456789abc",
  "numberInfo": {
    "carrier": "EE",
    "lineType": "mobile",         // Not VoIP, not landline ✓
    "countryCode": "GB"
  }
},
"audit_url": "https://app.tdsrisk.io/tds-verify/audit-summary/...",
"risk_recall": {
  "signature": "8252bc1c3a42d791e4f80a92c5b18e2f1d6c4a83",
  "available": true
},
"latency_ms": 1.84

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 ✓

requestId

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

UUID per call

indicators

Array of reason codes explaining the score. OL = ownership >45 days. DV = high device velocity (block). See full reason code reference.

["OL"] = positive signal ✓

callInSession

true = the number is currently in an active call. Useful signal — a number in-session is live and in use.

false = not in call

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

callDirection

Direction of the active call at time of check. IN = inbound, OUT = outbound. Only present when callInSession is true.

"IN" = inbound call

callDuration

Duration in seconds of the current active call. Only present when callInSession is true.

"347" = ~5.7 min

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, cryptographically signed audit record for this check. ICO-admissible evidence.

Permanent URL

risk_recall

Signed recall object. available: true means you can retrieve the frozen original response at any point in the future.

available: true ✓

latency_ms

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

1.84s ✓

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://sandbox.thedatasupermarket.com/trust/v1
// Production: https://api.thedatasupermarket.com/trust/v1

// 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.

Your first check in under 10 minutes

Cookie preferences