Skip to content
eConsent API

Phone Validation

The Phone Validation integration provides real-time phone number validation including carrier lookup, line type detection, and reachability checks.

DetailValue
Cost$0.05 per validation
Rate limit3,000 requests/min
BillingWallet-based (pre-paid)

Quick start

Section titled “Quick start”
  1. Go to Integrations in your dashboard at app.econsent.org.
  2. Enable Phone Validation and copy your API token.
  3. Make your first request:
Terminal window
curl -X POST https://api.econsent.org/api/integrations/YOUR_COMPANY_ID/vzew/phone \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "phone": "+14155552671"
  }'

Endpoint

Section titled “Endpoint”
POST https://api.econsent.org/api/integrations/:companyId/vzew/phone

Authentication

Section titled “Authentication”

Use Bearer token authentication with your Phone Validation integration token:

Authorization: Bearer YOUR_API_TOKEN

Request parameters

Section titled “Request parameters”

Path parameters

Section titled “Path parameters”
ParameterTypeDescription
companyIdstringYour Company ID

Request body

Section titled “Request body”
FieldTypeRequiredDescription
phonestringYesPhone number to validate (any format accepted)

Response

Section titled “Response”

Success (200)

Section titled “Success (200)”
{
  "success": true,
  "status": 200,
  "data": {
    "phone": "+14155552671",
    "valid": true,
    "formatted": "(415) 555-2671",
    "e164": "+14155552671",
    "country_code": "US",
    "country_name": "United States",
    "line_type": "mobile",
    "carrier": "T-Mobile USA",
    "is_wireless": true,
    "is_reachable": true,
    "is_ported": false,
    "timezone": "America/Los_Angeles",
    "score": 92,
    "risk_level": "low"
  },
  "billing": {
    "currency": "USD",
    "cost_charged": 0.05,
    "remaining_balance": 99.95,
    "formatted": {
      "cost_charged": "$0.05",
      "remaining_balance": "$99.95"
    }
  },
  "processing_time_ms": 180,
  "service": "phone",
  "company_id": "comp-abc",
  "timestamp": "2025-03-18T10:30:00Z",
  "provider": "vzew"
}

Response fields

Section titled “Response fields”
FieldTypeDescription
data.phonestringOriginal phone number submitted
data.validbooleanWhether the phone number is valid
data.formattedstringHuman-readable formatted number
data.e164stringE.164 international format
data.country_codestringISO 3166-1 alpha-2 country code
data.country_namestringFull country name
data.line_typestringmobile, landline, voip, toll_free, or unknown
data.carrierstringCarrier/network name
data.is_wirelessbooleanWhether this is a wireless/mobile number
data.is_reachablebooleanWhether the number can currently receive calls
data.is_portedbooleanWhether the number has been ported to another carrier
data.timezonestringIANA timezone identifier
data.scorenumberOverall quality score (0—100)
data.risk_levelstringlow, medium, or high

Line types

Section titled “Line types”
TypeDescriptionTCPA relevance
mobileWireless/cellular numberSubject to TCPA autodialer restrictions
landlineFixed-line numberVoice calls only, not subject to same TCPA restrictions
voipInternet-based numberVariable; may be subject to TCPA restrictions
toll_free800/888/etc. numbersBusiness lines, typically not consumer numbers
unknownCannot determine typeUse with caution

Quality scores

Section titled “Quality scores”
Score rangeQualityRecommendation
90—100ExcellentSafe to contact
70—89GoodGenerally safe
50—69FairUse with caution
0—49PoorNot recommended

Error responses

Section titled “Error responses”
StatusMeaning
400Bad request: invalid phone number format
401Unauthorized: invalid API token
402Payment required: insufficient wallet balance
403Forbidden: integration not enabled
429Rate limited: exceeded 3,000 requests/min

Health check

Section titled “Health check”

You can verify your integration status, wallet balance, and available services using the health check endpoint:

GET https://api.econsent.org/api/integrations/:companyId/vzew/health

The response includes your current wallet balance, available integrations, service costs, and routing configuration.

Code examples

Section titled “Code examples”
async function validatePhone(phone) {
  const companyId = process.env.ECONSENT_COMPANY_ID;
  const token = process.env.ECONSENT_PHONE_TOKEN;


  const response = await fetch(
    `https://api.econsent.org/api/integrations/${companyId}/vzew/phone`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`,
      },
      body: JSON.stringify({ phone }),
    }
  );


  const data = await response.json();


  if (data.success) {
    console.log('Valid:', data.data.valid);
    console.log('Line Type:', data.data.line_type);
    console.log('Carrier:', data.data.carrier);
    console.log('Reachable:', data.data.is_reachable);
    return data.data;
  } else {
    throw new Error(data.error);
  }
}

Best practices

Section titled “Best practices”
  • Validate before SMS. Always verify that a number is mobile or is_wireless: true before sending text messages to comply with TCPA.
  • Use E.164 format. Store phone numbers in E.164 format (+14155552671) for consistency.
  • Cache results. Store validation results for 30 days to avoid duplicate charges.
  • Check reachability. Avoid contacting numbers flagged as not reachable.
  • Batch processing. When validating lists, process in batches and respect the 3,000 requests/min rate limit.

Pricing

Section titled “Pricing”
  • Cost per validation: $0.05
  • Rate limit: 3,000 requests/min
  • Billing method: Wallet-based (pre-paid via Stripe)

View all pricing details

Next steps

Section titled “Next steps”