API Reference

Phone Validation API

Validate phone numbers in real time. Get the line type, carrier, porting status and disposable number signals before you send an OTP or accept a sign-up.

Base URL

All API requests should be made to the following base URL.

https

https://api.trueguard.io/v2

Authentication

All API requests require authentication using your secret API key.

Security note

Never expose your secret API key in client-side code. Only use it in your backend services.

Required Header

header

x-api-key: YOUR_SECRET_API_KEY

Endpoints

Validate a single phone number and receive a full breakdown of validity, format, location, line and risk signals.

No live line test

The API does not call or ping the number. A valid number matches the numbering plan of its country. It is not proof that the line is in service.

POST/phone/validation

Phone Validation

Validate a single phone number. Returns validity, formats, location, line type, carrier, porting and risk signals in one response.

javascript

import axios from 'axios';

const response = await axios.post(
  "https://api.trueguard.io/v2/phone/validation",
  {
    phone: "+14155552671",
  },
  {
    headers: {
      "x-api-key": "YOUR_SECRET_API_KEY",
    },
  }
);

bash

curl -X POST https://api.trueguard.io/v2/phone/validation \
  -H "x-api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+14155552671"}'

bash (national format)

curl -X POST https://api.trueguard.io/v2/phone/validation \
  -H "x-api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"(415) 555-2671","country":"US"}'

Status

risk.status is the overall verdict. It is set from validity, risk.isDisposable and line.type (premium rate). No other field changes it.

safestatus

The number is valid, is not disposable and is not a premium rate number.

riskystatus

The number is valid, but it is disposable (risk.isDisposable is true) or a premium rate number.

invalidstatus

The input is not a phone number, has a wrong length or country code, or is in a range reserved for fiction.

unknownstatus

The country is not clear from the input, or the range is not known.

Validity reasons

validity.reason tells why a number is not valid. The type column shows the status that each reason gives.

notANumberinvalid

The input is not a phone number.

invalidCountryCodeinvalid

The number starts with + but the country calling code does not exist.

tooShortinvalid

The number has too few digits.

tooLonginvalid

The number has too many digits.

invalidLengthinvalid

The digit count is between the shortest and longest length for the country, but no number type has that length.

fictionalRangeinvalid

The range is reserved for films, TV and examples.

ambiguousCountryunknown

The number has no + and no country was sent, so the country is not clear.

unallocatedRangeunknown

The number range is not assigned to any operator.

unknownRangeunknown

The number does not match the numbering plan of its country.

Line types

All values of line.type.

mobileline.type

Mobile number.

landlineline.type

Fixed line number at a physical address.

voipline.type

VoIP number. line.voipType tells fixed and non-fixed VoIP apart.

fixedLineOrMobileline.type

The country uses the same ranges for fixed and mobile lines, so the two cannot be told apart.

tollFreeline.type

Toll free number, free for the caller.

premiumRateline.type

Premium rate number. The caller pays a high rate.

sharedCostline.type

Shared cost number. The caller and the receiver share the cost.

personalline.type

Personal number that forwards to another line.

pagerline.type

Pager number.

uanline.type

Universal access number.

voicemailline.type

Voicemail access number.

shortCodeline.type

Short code.

m2mline.type

Machine-to-machine (IoT) number.

satelliteline.type

Satellite phone number.

unknownline.type

The line type is not known, or the number is not valid.

Carrier types

All values of line.carrierType.

mnoline.carrierType

Mobile network operator that runs its own radio network.

mvnoline.carrierType

Mobile virtual network operator that uses the network of another operator.

cpaasVirtualline.carrierType

Communications platform (CPaaS) or virtual number provider.

fixedIspline.carrierType

Fixed line telephone company or internet provider.

m2mline.carrierType

Operator for machine-to-machine and IoT connections.

satelliteline.carrierType

Satellite operator.

unknownline.carrierType

The operator type is not known.

Error handling

HTTP status codes the API returns.

HTTP Status Codes

400Bad Request - Missing phone, phone longer than 64 characters, unsupported country code, or malformed request body

401Unauthorized - Invalid or missing API key

403Forbidden - Your plan does not include the Phone Validation API

429Too Many Requests - Quota exceeded for the current billing period

500Internal Server Error - Something went wrong on our end

A number that is not valid is not an error: the API returns 200 with risk.status "invalid" or "unknown". Every 200 response counts toward your quota. 400 responses do not. Check your dashboard for current plan limits and remaining quota.

Support

Need help with integration?

Check out our quick start guide or reach out to our support team for assistance with implementing the Phone Validation API.

Quick Start Guide Contact Support