Skip to content
Using the API

API reference

79 endpoints with one base URL, one authentication scheme and one response format.

The API gives you programmatic access to every product in the catalog. Each product is a single POST endpoint that takes a small JSON body. What is described on this page applies to all of them.

Products

Base URL

Base URL
https://api.1lookup.dev

Every product lives at /v1/{product-slug}. The slug is the last part of the product's page address, such as phone-validation.

Authentication

Send your API key as a Bearer token on every request. Keys that start with 1lk_live_ run live lookups. Keys that start with 1lk_test_ return sample responses and never spend credits. See authentication.

Header
Authorization: Bearer 1lk_live_YOUR_KEY

Request format

Requests are JSON. Send Content-Type: application/json and the product's fields as the body. Two optional fields work on every endpoint.

Request
curl -X POST https://api.1lookup.dev/v1/phone-validation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"+15125550142"}'
freshboolean

Skip the 7-day cache and run a new lookup. Charged as a normal lookup.

referencestring

Your own identifier, echoed back in meta and shown in lookup history.

Response format

Every endpoint returns the same envelope. data holds the product result, and meta reports what the call cost.

200 OK
{
  "success": true,
  "data": {
    "phone_number": "+15125550142",
    "valid": true,
    "line_type": "mobile",
    "carrier": {
      "name": "Example Wireless",
      "ocn": "6010",
      "lrn": "+15125550000",
      "ported": true
    },
    "location": {
      "city": "Austin",
      "state": "TX",
      "country": "US",
      "timezone": "America/Chicago"
    },
    "dnc": {
      "listed": false,
      "dno": false
    },
    "risk": {
      "level": "low",
      "factors": []
    }
  },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 999,
    "cached": false,
    "request_id": "req_8f3a2c1e9b7d"
  }
}
successboolean

true when the lookup ran. A false response carries an error object instead of data.

dataobject

The product result. Its fields are documented on each endpoint page.

meta.credits_usednumber

Credits charged for this call. 0 for cached repeats, misses on match-priced products and failures.

meta.credits_remainingnumber

Your balance after the call.

meta.cachedboolean

true when the result came from the 7-day cache.

meta.request_idstring

Quote this when you contact support.

Response codes

StatusMeaning
200The lookup ran. A lookup that finds nothing is still a 200.
202A bulk job was accepted and is queued.
401The key is missing, malformed or revoked.
402Your credits are used up and pay as you go is off or at its limit.
403The product needs approval before it is switched on for your account.
404The endpoint or bulk job does not exist.
422A field is missing or malformed.
429More than 50 requests per second for this key.
500, 503Something failed on our side or at an upstream source. Safe to retry.

See errors for the error codes and rate limits for the headers.

Phone

Validity, carrier, line type, live status, DNC and ownership for any number.

EndpointRequest fieldsCredits
Phone ValidationPOST/v1/phone-validationphone_number1
Phone Spam CheckPOST/v1/phone-spam-checkphone_numberfrom 1
Reported Number CheckPOST/v1/reported-number-checkphone_number2
HLR LookupPOST/v1/hlr-lookupphone_number5
Carrier LookupPOST/v1/carrier-lookupphone_number3
DNC ScrubPOST/v1/dnc-scrubphone_number10
Reverse Phone LookupPOST/v1/reverse-phone-lookupphone_numberfrom 10 / match
Skip TracePOST/v1/skip-tracefirst_name, last_name, address, city, state, zip?5 / match
Mobile FinderPOST/v1/mobile-finderlinkedin_url, work_email?40 / match

Email

Deliverability, authentication, finding and reverse lookup for email addresses.

EndpointRequest fieldsCredits
Email ValidationPOST/v1/email-validationemail1
Email Authentication CheckPOST/v1/email-authentication-checkdomain2
Email AppendPOST/v1/email-appendfirst_name, last_name, address, city, state, zip?10 / match
Reverse Email LookupPOST/v1/reverse-email-lookupemail10 / match
Email FinderPOST/v1/email-finderfirst_name, last_name, domain5 / match
LinkedIn Email FinderPOST/v1/linkedin-email-finderlinkedin_url30 / match

IP & Network

Geolocation, VPN and proxy detection, DNS, TLS and visitor identification.

Risk & Fraud

Composite verdicts that combine several signals into one allow, review or block.

EndpointRequest fieldsCredits
Fraud DetectionPOST/v1/fraud-detectionemail?, phone_number?, ip?3 / check
Signup CheckPOST/v1/signup-checkemail, ip, phone_number?5 / check
Business VerifyPOST/v1/business-verifybusiness_name, city, domain?, phone_number?30 / check

Website & Domain

Scrape pages, pull contacts, and measure authority, traffic, brand and tech stack.

Live search results, keyword demand, rankings, trends and news.

EndpointRequest fieldsCredits
SERP ScraperPOST/v1/serp-scraperquery, country1 / search
Keyword MetricsPOST/v1/keyword-metricskeyword, country6 / keyword
Keyword Rank CheckerPOST/v1/keyword-rank-checkerkeyword, domain, country30 / check
Search TrendsPOST/v1/search-trendskeywords, timeframe2 / search
Google News SearchPOST/v1/google-news-searchquery3 / search

Company & B2B

Firmographics, people, funding and filings for account and contact research.

Compliance & Registries

Sanctions, exclusions and official registries, straight from the public source.

Social

Public profiles, posts, replies, ads and audience data across social platforms.

Audio & Media

Speech to text for calls and recordings, with speakers and timestamps.

EndpointRequest fieldsCredits
Audio TranscriptionPOST/v1/audio-transcriptionaudio_url, speakers6 / minute