API Documentation

Integrate ChkSMS into your application to detect virtual numbers in real-time.

Authentication

Include your API Token in the x-api-key header for all requests.

x-api-key: YOUR_API_TOKEN

Endpoint: Check Phone Number

GET /api/v1/check/{international_phone_number}

Returns whether the phone number is a known virtual number found on public SMS sites.

Parameters

Name Type Description
international_phone_number string Target phone number (e.g. +1234567890)
with_evidence boolean If true, returns an evidence object (Optional)

Code Examples

cURL

curl -X GET "http://localhost:8000/api/v1/check/+1234567890?with_evidence=true" \
     -H "x-api-key: YOUR_API_TOKEN"

Python (Requests)

import requests

url = "http://localhost:8000/api/v1/check/+1234567890"
headers = {
    "x-api-key": "YOUR_API_TOKEN"
}
params = {
    "with_evidence": True
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

if data.get("is_virtual"):
    evidence = data.get("evidence")
    if evidence and evidence["type"] == "screenshot":
        print("Virtual Number Detected!", evidence["url"])
    elif evidence and evidence["type"] == "api_response":
        print("Virtual Number Detected!", evidence["data"])
    else:
        print("Virtual Number Detected!")
else:
    print("Number is safe.")

Node.js (Axios)

const axios = require('axios');

async function checkNumber() {
    try {
        const response = await axios.get('http://localhost:8000/api/v1/check/+1234567890', {
            headers: {
                'x-api-key': 'YOUR_API_TOKEN'
            },
            params: {
                with_evidence: true
            }
        });
        
        const data = response.data;
        if (data.is_virtual) {
            const ev = data.evidence;
            if (ev?.type === "screenshot") console.log("Virtual Number Detected!", ev.url);
            else if (ev?.type === "api_response") console.log("Virtual Number Detected!", ev.data);
            else console.log("Virtual Number Detected!");
        } else {
            console.log("Number is safe.");
        }
    } catch (error) {
        console.error(error);
        // Recommendation: If API call fails (e.g., server down), proceed with signup
        // and handle the API response later or fallback to default behavior.
        console.log("API call failed. Proceeding with signup and will re-check later.");
    }
}

checkNumber();

Recommendation for API Call Failures

In the event of a temporary server outage or API call failure, we recommend proceeding with your user signup process first to avoid a poor user experience. You can then implement follow-up actions based on the API response (e.g., retry the failed API call later, or fall back to a default behavior) to maintain service continuity.