Quickstart

This guide walks you through signing up, creating an API key, and making your first phone lookup.

Create your account

Sign up for a free account at scamverify.ai. You can register with your email (magic link) or Google OAuth. No credit card is required to get started.

Get your API key

Navigate to Settings > API in your dashboard. Click Create API Key, give it a name, and copy the key immediately.

Your API key is shown only once at creation. Copy it and store it securely. If you lose it, you will need to create a new key.

Your key will look like this:

sv_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789ab

Make your first phone lookup

Use your API key to look up a phone number. Replace YOUR_API_KEY with the key you copied in the previous step.

curl -X POST https://scamverify.ai/api/v1/phone/lookup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+12025551234"}'

import requests

response = requests.post(
    "https://scamverify.ai/api/v1/phone/lookup",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"phone_number": "+12025551234"},
)

data = response.json()
print(f"Risk Score: {data['risk_score']}")
print(f"Verdict: {data['verdict']}")
print(f"Explanation: {data['explanation']}")

const response = await fetch("https://scamverify.ai/api/v1/phone/lookup", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+12025551234" }),
});

const data = await response.json();
console.log(`Risk Score: ${data.risk_score}`);
console.log(`Verdict: ${data.verdict}`);
console.log(`Explanation: ${data.explanation}`);

Read the response

A successful lookup returns a JSON object with these key fields:

{
  "risk_score": 82,
  "verdict": "high_risk",
  "explanation": "This number has 14 FTC complaints filed since 2024...",
  "signals": {
    "ftc_complaints": 14,
    "fcc_complaints": 3,
    "carrier": "Example VoIP Corp",
    "line_type": "voip",
    "robocall_detected": true,
    "community_reports": 7
  },
  "cached": false
}

Field	Description
`risk_score`	Integer from 0 to 100. Higher means more dangerous.
`verdict`	One of `safe`, `low_risk`, `medium_risk`, `high_risk`, or `critical`.
`explanation`	AI-generated plain-English summary of the risk assessment.
`signals`	Object containing the raw data points that contributed to the score.
`cached`	Whether this result was served from cache (no quota consumed).

Try other channels

The same authentication and response pattern works for all four channels.

URL Verification

curl -X POST https://scamverify.ai/api/v1/url/lookup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://suspicious-example.com"}'

Text Message Analysis

curl -X POST https://scamverify.ai/api/v1/text/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "URGENT: Your bank account has been locked. Click here to verify: http://example.com/verify"}'

Email Analysis

curl -X POST https://scamverify.ai/api/v1/email/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email_body": "Dear Customer, We detected unusual activity on your account..."}'

Test mode: Use an sv_test_ key to make API calls without consuming your quota. Test keys return realistic mock data and are perfect for development and integration testing. See Authentication for details.

Next Steps

Authentication - Learn about test keys, key management, and security
SDKs and Libraries - Complete examples in Python, Node.js, Go, PHP, and Ruby
API Reference - Full endpoint documentation with request and response schemas