Phone Validation

Validates a phone number for a given country and tells you its carrier and whether it looks real or disposable.

Overview#

scoring/phone needs two inputs: the phone number and its countryCode (ISO 3166-1 alpha-2, such as US). The number may be written in several ways, with or without the plus sign or the national prefix. The response contains the normalized phone, isValid, a reason when it is not valid, the carrier, a disposable flag for temporary or virtual numbers, and blacklisted.

When to use it#

• Validate numbers on signup before sending an SMS verification code, saving the cost of messages to numbers that cannot receive them.
• Filter out burner and virtual numbers used for promo abuse.
• Standardize numbers before storing them.

Reading the result#

• isValid: false with a reason such as an invalid structure means the number cannot belong to that country. Ask the user to correct it; do not send a code.
• disposable: true indicates a temporary number. Accept it only where the risk is low, or require a stronger factor.
• carrier can be empty, particularly for invalid numbers, and carriers can change when numbers are ported, so treat it as informative rather than authoritative.
• Always pass the country the user selected, not one guessed from the IP, otherwise valid numbers may be reported invalid.

Notes#

• Counts as one request. Test mode returns fake data, is free and raises no events.
• Not part of the Standard plan; available on trial, Premium and pay-as-you-go. Without access you get error 117 (feature_not_available).
• Custom rules for the phone group can test the number, country and carrier, and can mark the number valid or invalid. The outcome is listed in custom_rules_applied.
• A spam_phone event is raised for numbers judged fake or abusive and is sent to your webhooks.
• A missing or unparsable number returns error 118 (invalid_phone_number) and a wrong country returns 116 (invalid_country_code), both with HTTP 200.

Request#

• Authenticate with the key parameter or an Authorization: Bearer header.
• Counts as 1 request.
• Available on: Free trial Premium Pay-as-you-go

Parameters#

Every method also accepts format, lang, mode, userID, callback. See Options.

Code samples#

curl -G "https://gurdx.cretip.com/api/scoring/phone" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "phone=501234567" \
  --data-urlencode "countryCode=SA"

<?php

$response = file_get_contents('https://gurdx.cretip.com/api/scoring/phone?'.http_build_query(['key' => 'YOUR_API_KEY', 'phone' => '501234567', 'countryCode' => 'SA']));
$result = json_decode($response, true);

if ($result['status'] === 'success') {
    print_r($result['data']);
} else {
    echo $result['code'].': '.$result['description'];
}

const params = new URLSearchParams({"key":"YOUR_API_KEY","phone":"501234567","countryCode":"SA"});
const res = await fetch(`https://gurdx.cretip.com/api/scoring/phone?${params}`);
const result = await res.json();

if (result.status === 'success') {
  console.log(result.data);
} else {
  console.error(result.code, result.description);
}

import requests

res = requests.get("https://gurdx.cretip.com/api/scoring/phone", params={"key": "YOUR_API_KEY", "phone": "501234567", "countryCode": "SA"})
result = res.json()

if result["status"] == "success":
    print(result["data"])
else:
    print(result["code"], result["description"])

Response#

Success#

{
    "data": {
        "carrier": "",
        "reason": "Invalid phone number structure.",
        "isValid": false,
        "blacklisted": false,
        "disposable": false,
        "phone": "+12121234567",
        "countryCode": "US",
        "custom_rules_applied": {
            "total": 0,
            "rules": []
        }
    },
    "status": "success",
    "executionTime": 1
}

Error#

Errors are delivered with HTTP 200 — always check the status field.

{
    "status": "error",
    "code": 101,
    "type": "invalid_key",
    "description": "The API Key is missing or invalid."
}

Response fields#