API Documentation

Getting Started

Authenticate every request with your API key. Find your key in the SubscriberVerify dashboard after you create an account.

API endpoint

HTTPS https://api2.subscriberverify.com/api

Accepted request formats:

Form POST
JSON POST
URL-encoded query string (GET)

Account Services

The following services are available on SubscriberVerify accounts. Contact [email protected] to enable optional add-ons.

Service	Credits	Availability
Carrier Lookup and SMS Eligibility (DIP)	1	Included
Recent Deactivation Notices	0	Included
Estimated Time Zone	0	Included
Landline SMS Eligibility Check	1	Add `landlinesmslookup=1` to any request
Realtime Litigator Check	1	Add `litigatorfilter=1` to any request
Do-Not-Call List Check (Federal, State, Complainers)	1	Contact support to enable; then add `dnccheck=1`

API Reference

Request fields

key — Your API key (required).
phone — The 10-digit US subscriber phone number (required).
ip — IPv4 or IPv6 address of the subscriber opt-in (optional). Improves geolocation and blacklist accuracy.
list — Your internal list ID for usage reporting by campaign (optional). Do not send a unique lead ID per request — accounts are limited to 1,000 unique list values.
litigatorfilter — Set to 1 or true to check against our litigator database. Returns litigator, litigator_type, and litigator_name. Costs 1 additional credit.
landlinesmslookup — Set to 1 or true for landline SMS eligibility. If the number is a landline, a second lookup runs (1 additional credit). Mobile numbers are unaffected.
dnccheck — Set to 1 or true to check Federal DNC, State DNC, and DNC Complainers lists. Returns dncChecked and dncResult. Costs 1 additional credit. Requires DNC to be enabled on your account.

Legacy field names (deprecated): subscriber → phone, optip → ip, list1 → list.

Response fields

Engine version 2.0. The engineVersion field is returned on every lookup response.

Field	Sample	Description
`engineVersion`	2.0	Lookup engine version
`creditsUsed`	1	Credits deducted for this lookup
`subscriber`	8015550100	Phone number looked up
`optDate`	2023-07-27T18:55:56.532Z	Opt-in date used for lookup
`doNotSms`	true	Present only when true. Number not eligible for SMS (undeliverable, deactivated, blacklisted, or litigator).
`smsEligible`	true	Present only when true. Primary send/no-send signal; includes SMS-capable landlines when confirmed.
`action`	send	Recommended list action: `send`, `unsubscribe`, `blacklist`, or `error`
`deliverable`	true	Eligible to receive text messages (carriers do not guarantee delivery)
`error`	false	True if a request error occurred
`reason`	…	Explanation for the recommended action
`deactivationDate`	2019-06-01	Most recent deactivation date
`age`	381	Days subscriber has had this active number
`clicker`	true	A URL texted to this subscriber has been visited
`nanpType`	mobile	Phone type per NANP: `mobile`, `landline`, etc.
`nanpCarrier`	verizon	Carrier per NANP (not authoritative due to porting)
`ipResult`	valid-v4	IP address type and validity
`geoCountry`	US	Country code
`geoState`	UT	US state code
`geoCity`	Example City	US city name
`geoMetro`	671	US metro code
`geoSource`	ip	Geolocation method: `ip` or `area-code`
`timezone`	America/Denver	Subscriber time zone
`blackList`	false	True if blacklisted in our internal file
`litigator`	false	True if suspected litigator — do not contact
`litigator_type`	plaintiff	Classification when litigator filter is active
`litigator_name`	…	Name on record when litigator filter is active
`dncChecked`	true	`true` if DNC check ran; `error` if service unavailable
`dncResult`	Federal, State	Comma-separated DNC lists matched; empty when clean
`dip`	success	DIP lookup status
`dipLrn`	…	DIP location routing number
`dipPorted`	false	Likely ported number
`dipOcn`	…	Operating carrier numeric ID
`dipCarrier`	VERIZON	DIP carrier name
`dipCarrierType`	mobile	DIP carrier type
`dipCarrierSubType`	PCS	DIP carrier sub-type (see reference table)
`dipMessagingLookup`	true	Landline messaging lookup performed
`dipMessagingEnabled`	true	Landline SMS messaging enabled
`dipMessagingProvider`	…	Landline messaging provider
`dipMessagingRefId`	…	Landline messaging provider ID
`dipMessagingCountryCode`	US	Landline messaging country code
`tzOffset`	-7	Time zone offset from UTC
`elapsed`	0.1 sec	Server response time

Summary fields: smsEligible and doNotSms are present only when true and absent when false. Use smsEligible as your primary send/no-send signal.

Examples & Testing

Basic lookup

Standard carrier lookup with IP geolocation:

HTTPS GET

https://api2.subscriberverify.com/api?key=YOUR_API_KEY&phone=8015550100&ip=203.0.113.10&list=campaign_a

DIP + landline SMS lookup

Enable real-time DIP carrier lookup with landline SMS eligibility. Costs 1 additional credit per landline record.

HTTPS GET

https://api2.subscriberverify.com/api?key=YOUR_API_KEY&phone=8015550100&landlinesmslookup=1

Example response when landline SMS lookup is performed:

JSON response

{
  "subscriber": "8015550100",
  "action": "send",
  "deliverable": "true",
  "smsEligible": "true",
  "nanpType": "mobile",
  "dip": "success",
  "dipCarrier": "Verizon",
  "dipCarrierType": "mobile",
  "dipMessagingLookup": "true",
  "dipMessagingEnabled": "true",
  "dipMessagingProvider": "Example Messaging Provider",
  "geoState": "UT",
  "geoSource": "area-code",
  "timezone": "America/Denver"
}

Litigator filter lookup

Check against our litigator database. Requires DIP. Costs 2 credits (1 DIP + 1 litigator). A match sets doNotSms to true.

HTTPS GET

https://api2.subscriberverify.com/api?key=YOUR_API_KEY&phone=4155550199&litigatorfilter=1

Example when a litigator match is found:

JSON response

{
  "subscriber": "4155550199",
  "action": "unsubscribe",
  "deliverable": "false",
  "doNotSms": "true",
  "blackList": "true",
  "litigator": "true",
  "litigator_type": "plaintiff",
  "litigator_name": "[redacted]",
  "reason": "Associated with TCPA Litigator DO NOT CONTACT",
  "nanpType": "mobile",
  "geoState": "CA",
  "geoSource": "area-code",
  "timezone": "America/Los_Angeles"
}

Example when no litigator match is found:

JSON response

{
  "subscriber": "4155550199",
  "action": "send",
  "deliverable": "true",
  "smsEligible": "true",
  "litigator": "false",
  "litigator_type": "",
  "litigator_name": "",
  "nanpType": "mobile",
  "geoState": "CA",
  "geoSource": "area-code",
  "timezone": "America/Los_Angeles"
}

Do-Not-Call (DNC) check

Add dnccheck=1 to check Federal, State, and DNC Complainers lists. DNC results are informational — action relates to SMS eligibility, not DNC status.

HTTPS GET

https://api2.subscriberverify.com/api?key=YOUR_API_KEY&phone=8015550100&dnccheck=1

On a DNC list (action may still be send):

JSON response

{
  "subscriber": "8015550100",
  "action": "send",
  "deliverable": "true",
  "smsEligible": "true",
  "dncChecked": "true",
  "dncResult": "Federal, State",
  "nanpType": "mobile",
  "geoState": "UT",
  "geoSource": "area-code",
  "timezone": "America/Denver"
}

Not on any DNC list:

JSON response

{
  "subscriber": "8015550100",
  "action": "send",
  "deliverable": "true",
  "smsEligible": "true",
  "dncChecked": "true",
  "dncResult": "",
  "nanpType": "mobile",
  "geoState": "UT",
  "geoSource": "area-code",
  "timezone": "America/Denver"
}

Other example responses

JSON — eligible mobile

{
  "subscriber": "8015550123",
  "action": "send",
  "smsEligible": "true",
  "nanpType": "mobile",
  "nanpCarrier": "other",
  "litigator": false,
  "blackList": false,
  "ipResult": "valid-v6",
  "geoCountry": "US",
  "geoState": "TX",
  "geoSource": "ip",
  "timezone": "America/Chicago",
  "tzOffset": -6
}

JSON — deactivated

{
  "subscriber": "8015550456",
  "action": "unsubscribe",
  "doNotSms": "true",
  "reason": "Number deactivated on 2020-01-09",
  "nanpType": "mobile",
  "nanpCarrier": "verizon",
  "litigator": false,
  "blackList": false,
  "ipResult": "valid-v4",
  "geoCountry": "US",
  "geoState": "CA",
  "geoCity": "Example City",
  "geoMetro": 813,
  "geoSource": "ip",
  "timezone": "America/Los_Angeles",
  "tzOffset": -8
}

JSON — not mobile

{
  "subscriber": "8015550789",
  "action": "unsubscribe",
  "doNotSms": "true",
  "reason": "Not a valid mobile number",
  "nanpType": "not-mobile"
}

JSON — out of credits

{
  "action": "error",
  "reason": "You are out of credits. Please recharge your account"
}

Credits Management

Check available credits from your dashboard or via the API. Call the same API URL with your key and credits set to any true value. GET and POST are both accepted.

Credits check

https://api2.subscriberverify.com/api?key=YOUR_API_KEY&credits=1

Response:

JSON response

{
  "availableCredits": 100000
}

High-Concurrency & Performance Strategies

API usage patterns significantly affect throughput. Each call uses HTTPS, so the bulk API is far more efficient than single-lookup calls.

Sequential lookups ~5–10 records per second

Up to 30 concurrent single lookups ~30–40 records per second (threads or processes)

Bulk API (recommended) ~100–300 records per second (up to 1,000 per request)

Bulk API

Bulk API endpoint

POST https://api2.subscriberverify.com/api-bulk

Uses the same API key as the single-record API. Accepts JSON POST only. Processes up to 1,000 records per request with parallel processing.

Bulk request format

JSON body

{
  "key": "YOUR_API_KEY",
  "litigatorfilter": true,
  "landlinesmslookup": false,
  "records": [
    { "phone": "8015550101", "ip": "203.0.113.11" },
    { "phone": "8015550102", "ip": "203.0.113.12" },
    { "phone": "8015550103" }
  ]
}

The ip field is optional per record. Providing IP improves GEO and blacklist accuracy.

Bulk response format

JSON response

{
  "ok": true,
  "lookups": 3,
  "results": [
    {
      "subscriber": "8015550101",
      "action": "send",
      "smsEligible": "true",
      "nanpType": "mobile",
      "blackList": false,
      "dip": "success",
      "dipLrn": "8015550101",
      "dipPorted": false,
      "dipOcn": "6664",
      "dipCarrier": "Example Wireless",
      "dipCarrierSubType": "PCS",
      "dipCarrierType": "mobile",
      "geoState": "UT",
      "geoCity": "example city",
      "timezone": "America/Denver",
      "tzOffset": -7,
      "geoSource": "area-code"
    }
  ]
}

Important notes

Response fields match the single-record API.
Results maintain input order despite parallel processing.
Make only one bulk request at a time per API key.
Maximum 1,000 records per request.
litigatorfilter and landlinesmslookup at the top level apply to every record in the batch.

Carrier Map

The dipCarrier field is sourced from our live carrier registry. Download the full carrier map as JSON or CSV.

Download (full carrier map)

Returns a short-lived signed download URL valid for 24 hours.

HTTPS GET

https://api2.subscriberverify.com/api/carrier-map?key=YOUR_API_KEY&format=json

Request fields: key (required), format — json or csv (required).

JSON response

{
  "ok": true,
  "downloadUrl": "https://app.subscriberverify.com/app/secure-download?token=EXAMPLE_TOKEN",
  "expiresAt": "2026-06-18T12:00:00.000Z",
  "format": "json"
}

Fetch downloadUrl to receive the carrier map file. The URL expires after 24 hours.

Status (lightweight)

Poll carrier map state. Returns lastChanged (ISO timestamp) and carrierCount. GET or POST. Values cached for 1 minute.

HTTPS GET

https://api2.subscriberverify.com/api/carrier-map-status?key=YOUR_API_KEY

JSON response

{
  "ok": true,
  "lastChanged": "2026-06-20T14:32:00.000Z",
  "carrierCount": 1900
}

Sample carrier records

JSON excerpt

[
  {
    "carrier": "AT&T Southeast",
    "firstSeen": "2024-06-28T06:39:37.000Z",
    "lastChanged": "2026-06-02T12:23:32.831Z",
    "ocns": [
      { "ocn": "9419", "type": "RBOC" },
      { "ocn": "2741", "type": "CLEC" }
    ]
  },
  {
    "carrier": "U.S. Cellular",
    "firstSeen": "2024-06-28T06:38:29.000Z",
    "lastChanged": "2026-06-02T12:23:31.934Z",
    "ocns": [
      { "ocn": "6265", "type": "WIRELESS" },
      { "ocn": "6282", "type": "WIRELESS" }
    ]
  }
]

Carrier Subtypes

Values returned in the dipCarrierSubType field.

Acronym	Full name
`ILEC`	Incumbent Local Exchange Carrier
`ICO`	Independent Telephone Company
`ULEC`	Unbundled Local Exchange Carrier
`RBOC`	Regional Bell Operating Company
`CLEC`	Competitive Local Exchange Carrier
`CAP`	Competitive Access Provider
`IXC`	Inter-exchange Carrier
`WRSL`	Wireless Reseller
`IPES`	Internet Protocol Enabled Services
`ETHX`	Ethernet Exchange
`INTL`	International Telecommunications Service Provider
`LRSL`	Local Reseller
`WIRELESS`	Wireless
`PCS`	Personal Communications Service
`PCSR`	Personal Communications Service Reseller
`PAGING`	Paging and Messaging

Getting Started

API endpoint

Account Services

API Reference

Request fields

Response fields

Examples & Testing

Basic lookup

DIP + landline SMS lookup

Litigator filter lookup

Do-Not-Call (DNC) check

Other example responses

Credits Management

High-Concurrency & Performance Strategies

Bulk API

Bulk API endpoint

Bulk request format

Bulk response format

Carrier Map

Download (full carrier map)

Status (lightweight)

Sample carrier records

Carrier Subtypes

Ready to integrate?