1lookup logo1lookup
Sign InGet Started

API reference · v1

1Lookup API

One REST API for verifying and enriching the contact, company and web data your business runs on. Every endpoint takes a JSON body, returns the same response envelope, and bills in credits you can see on the call that spent them.

Get an API keyMake your first callBrowse endpoints
Base URL
https://app.1lookup.io/api/v1
Authentication
Bearer API key
Formats
JSON in, JSON out
Endpoints
46 live
A complete request
curl -X POST https://app.1lookup.io/api/v1/phone \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "phone_number": "+14155550123"  }'
…and what comes back
{  "success": true,  "data": {    "request": {      "type": "phone",      "input": "+14155550123"    },    "classification": {      "line_type": "MOBILE",      "number_status": "ACTIVE"    },    "risk_assessment": {      "fraud_score": 45,      "risk_level": "MEDIUM"    },    "recommendations": {      "primary_action": "VERIFY"    },    "metadata": {      "credits_used": 1,      "credits_remaining": 9998    }  }}

Quickstart

Three steps from a fresh account to a live lookup. API access requires a paid plan — free-plan organizations can use the dashboard but not the API.

  1. 1

    Create an API key

    Open API keys in the dashboard and create one. Keys start with sk_live_ and are shown once — store it before closing the dialog.

  2. 2

    Put it in the environment

    Export the key as ONELOOKUP_API_KEY. Every sample on this page reads it from there, so nothing you copy carries a key in plain text.

  3. 3

    Call an endpoint

    Send the key as a bearer token. A successful call returns success: true and a data object; the credits it spent are on data.metadata.

Test without writing code

Every lookup on this page is also available in the dashboard, so you can see a real response for your own data before you integrate.

Set up and call
export ONELOOKUP_API_KEY="sk_live_…" curl -X POST https://app.1lookup.io/api/v1/email \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "email": "jane.doe@acme.com" }'
Check your balance first
curl https://app.1lookup.io/api/v1/account \  -H "Authorization: Bearer $ONELOOKUP_API_KEY"

Authentication

Authenticate with your secret key in the Authorization header. There are no other auth schemes, and there is no unauthenticated access.

Keys belong to an organization, not to a person, and they carry that organization’s full credit balance. Treat one as you would a password: server-side only, in an environment variable, never in a mobile app, a browser bundle or a public repository.

Authorizationheader, required
Bearer sk_live_…. Anything else returns 401 UNAUTHORIZED.
Content-Typeheader
application/json on every request with a body. Malformed JSON returns 400 INVALID_REQUEST.

A paid plan is required

API access is part of a paid subscription. A key on a free-plan organization returns 403 UPGRADE_REQUIRED, even when the account still has credits. Dashboard lookups are unaffected.

Rotate keys on a schedule and whenever someone with access leaves. You can hold several keys at once, so rotation is: create the new key, deploy it, then delete the old one.

Every request
POST /api/v1/phone HTTP/1.1Host: app.1lookup.ioAuthorization: Bearer sk_live_…Content-Type: application/json
Missing or invalid key
{  "success": false,  "error": {    "message": "Invalid or missing API key",    "code": "UNAUTHORIZED",    "type": "api_error"  }}

Requests and responses

Every lookup is a POST with a small JSON body and returns the same envelope, whatever the product. Learn it once and every endpoint reads the same way.

A successful response is always success: true with a data object. Inside data, up to six sections appear. request, metadata and classification are on every product; the other three appear where the product has something to say.

requestobject
What you asked for: the request id, the product type, your input, a timestamp and processing_time_ms.
metadataobject
What the call cost and where the data came from: credits_used, credits_remaining, cache_hit, data_sources, and the API and schema versions.
classificationobject
The product’s own verdict — line type, deliverability status, matched, an authority score. This is the field most integrations branch on.
risk_assessmentobject
fraud_score from 0–100, a risk_level of LOW, MEDIUM, HIGH or CRITICAL, the risk_factors behind it, and a confidence_level.
insightsobject
The detail behind the verdict: carrier, location, deliverability factors, company profile, transcript text. Shape varies by product.
recommendationsobject
What to do next: a primary_action of APPROVE, VERIFY, REVIEW or BLOCK, plus secondary_actions and a customer-safe user_message.

Global parameters

Every single-lookup POST endpoint accepts bypass_cache (boolean) in the body. Set it to skip the 7-day cache and force a fresh lookup.

Keep the request id

Every response carries an X-Request-Id header, and successful lookups repeat it as data.request.id. Log it. Quoting one turns a support question into a two-minute answer.

The envelope
{  "success": true,  "data": {    "request": {      "id": "74d7c3df-c23d-4beb-8267-31c4a26751e6",      "type": "phone",      "input": "+14155550123",      "timestamp": "2026-08-13T09:15:23.883Z",      "processing_time_ms": 651    },    "metadata": {      "api_version": "1.0",      "schema_version": "1.0",      "credits_used": 1,      "credits_remaining": 9998,      "cache_hit": false,      "data_sources": ["carrier_lookup", "fcc_daily_data"]    },    "risk_assessment": {      "fraud_score": 45,      "risk_level": "MEDIUM",      "risk_factors": [],      "confidence_level": 70    },    "classification": { "line_type": "MOBILE" },    "insights": { "carrier": { "name": "T-Mobile USA" } },    "recommendations": {      "primary_action": "VERIFY",      "secondary_actions": ["SEND_SMS_OTP"],      "user_message": "Additional verification recommended."    }  }}

Credits and billing

One balance covers every endpoint. Each call reports what it spent and what is left, so you never have to guess at a burn rate.

Per successful lookup
Credits come off when a lookup completes. A 4xx validation error costs nothing.
Success-based products
Enrichment and live-fetch products charge 0 credits when there is no match. You are billed for records found, not searches run.
Metered products
Audio Transcription is charged per minute of audio. A hold is taken from expected_duration_minutes up front and settled against the true duration.
Cached repeats
A lookup you already ran in the last 7 days is served from cache and charged 0 credits. See Caching below.

When a call would take the balance below zero the API answers 402 INSUFFICIENT_CREDITS and nothing is charged. GET /account returns the live balance, including rollover and purchased credits, which makes it the right pre-flight check before a long run.

Cost of a call
"metadata": {  "credits_used": 10,  "credits_remaining": 9985,  "cache_hit": false}
Out of credits
{  "success": false,  "error": {    "message": "Insufficient credits",    "code": "INSUFFICIENT_CREDITS",    "type": "api_error"  }}

Price list

Phone Number Validation1
Phone Spam Check1
Email Validation1
IP Address Lookup1
Number Type Lookup1
SERP Scraper1
Domain Age Check2
Prospect Search2
MNP Lookup3
Link-in-Bio Lookup3
HLR Lookup5
Email Enrichment5
Social Post Lookup5
Video Transcript5
Social Search5
Job Change Monitoring5
Keyword Metrics6
Audio Transcription6
Email Append10
Skip Trace10
Reverse Phone Lookup10
Phone Scrub10
Reverse IP Append10
Reverse Email Append10
Website Scraper10
Domain SEO Intelligence10
Website Contacts Scraper10
Domain Authority10
Business Lookup10
LinkedIn Profile Lookup10
Social Profile Check10
Ad Library Lookup10
Backlink Overview13
Property Lookup15
Company Profile Lookup25
Business Verify30
Mobile Finder40
TikTok Audience Demographics40
Company Firmographics75
B2B Contact Append75
Target Account Search75
Website Audience Intelligence86

Credits per lookup. Audio Transcription is per minute of audio; Job Change Monitoring is per contact per weekly recheck.

Caching

Repeat lookups are answered from a 7-day cache, keyed on the product and the exact input.

Re-running a lookup you have already run inside the window returns the stored record with cache_hit: true and costs 0 credits. If a teammate ran it, you get the same stored record at the normal price — never more than the original call was charged.

Send bypass_cache: true when freshness matters more than cost: a number you are verifying at sign-in, a listing you know has just changed. The fresh result replaces the cached one for the rest of the window.

Deep-fetch products benefit most

Live-fetch lookups — business, property, company profile, social — take seconds on a first call and milliseconds for the next seven days. Batch work that revisits the same records is close to free after the first pass.

Force a fresh lookup
curl -X POST https://app.1lookup.io/api/v1/phone \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "phone_number": "+14155550123",    "bypass_cache": true  }'
Served from cache
"metadata": {  "credits_used": 0,  "cache_hit": true}

Rate limits

Limits are safety nets against runaway loops and leaked keys, not throttles on normal use. They are applied per API key.

Standard lookupsper key
200 requests per 10 seconds.
Live-fetch lookupsper key
1,000 requests per minute. These hold a connection open for seconds at a time: HLR, MNP, number type, business, property, company profile, LinkedIn, and the social endpoints.
Hard ceilingper key
500 requests per second, and 5,000 per 10 seconds, across everything.
Account and monitoringper organization
1,000 requests per minute.

A limited request returns 429 RATE_LIMIT_EXCEEDED with Retry-After in seconds and the X-RateLimit-* headers describing the window that tripped. X-RateLimit-Reset is a Unix timestamp in seconds.

Respect Retry-After before falling back to exponential backoff, and keep concurrency bounded rather than firing a whole list at once. If your workload needs more than these limits, ask — they are set where they are to catch mistakes, not to shape traffic.

Bulk beats parallelism

For anything above a few thousand records, one bulk job is faster, cheaper to operate and immune to rate limits. See Bulk jobs.

Headers on a 429
HTTP/1.1 429 Too Many RequestsRetry-After: 3X-RateLimit-Limit: 200X-RateLimit-Remaining: 0X-RateLimit-Reset: 1786139880X-Request-Id: 74d7c3df-c23d-4beb-8267-31c4a26751e6
Back off and retry
async function lookup(path, body, attempt = 0) {  const response = await fetch(`https://app.1lookup.io/api/v1${path}`, {    method: "POST",    headers: {      Authorization: `Bearer ${process.env.ONELOOKUP_API_KEY}`,      "Content-Type": "application/json",    },    body: JSON.stringify(body),  });   if (response.status === 429 && attempt < 5) {    const wait = Number(response.headers.get("Retry-After") ?? 2 ** attempt);    await new Promise((resolve) => setTimeout(resolve, wait * 1000));    return lookup(path, body, attempt + 1);  }   return response.json();}

Errors

Errors use conventional HTTP status codes and always carry the same JSON shape, so one handler covers every endpoint.

Branch on error.code, not on error.message. Codes are stable; messages are written for humans and get clearer over time.

CodeStatusMeaning
INVALID_REQUEST400The body was not valid JSON, or a field was the wrong type.
INVALID_INPUT400The value was well formed but not usable — an unparseable number, a bad URL.
MISSING_FIELD400A required parameter was absent.
INVALID_TYPE400A bulk job asked for a product that has no bulk path.
INPUT_LIMIT_EXCEEDED400A bulk job carried more than 100,000 rows.
UNAUTHORIZED401The key is missing, malformed, revoked or expired.
INSUFFICIENT_CREDITS402The balance cannot cover the call. Nothing was charged.
UPGRADE_REQUIRED403The organization has no paid plan, so API access is closed.
NOT_FOUND404The job, monitor or product in the path does not exist for this organization.
IDEMPOTENCY_CONFLICT409A request with the same Idempotency-Key is still in flight. Retry shortly.
RATE_LIMIT_EXCEEDED429A rate limit tripped. Read Retry-After.
INTERNAL_ERROR500Something failed on our side. Safe to retry with backoff.
SERVICE_UNAVAILABLE503An upstream source is degraded and a circuit breaker opened. Retry-After is set.

Retry these, and only these

429, 500 and 503 are worth retrying with backoff. Every 4xx below 429 is a request that will fail again in exactly the same way until you change it.

Error shape
{  "success": false,  "error": {    "message": "Invalid email format",    "code": "INVALID_INPUT",    "type": "api_error"  }}
One handler, every endpoint
import os import requests RETRYABLE = {429, 500, 502, 503, 504}  def lookup(path, payload):    response = requests.post(        f"https://app.1lookup.io/api/v1{path}",        headers={"Authorization": f"Bearer {os.environ['ONELOOKUP_API_KEY']}"},        json=payload,        timeout=60,    )     if response.ok:        return response.json()["data"]     error = response.json()["error"]    if response.status_code in RETRYABLE:        raise TransientError(error["code"], response.headers.get("Retry-After"))    raise PermanentError(error["code"], error["message"])

Bulk jobs

Send up to 100,000 rows in one call, get a job id back immediately, and collect results by polling or by webhook.

Processing starts the moment the job is accepted. status moves through processing to completed, and the counters — processed_count, successful_count, failed_count — update as rows land.

Idempotency-Keyheader
Send a fresh UUID per job. A retry with the same key returns the original job, marked Idempotent-Replay: true, instead of creating and charging for a second one. Keys are remembered for 24 hours.
Credit pre-flight
The whole job is priced before it starts. If the balance cannot cover every row, the job is refused with 402 rather than stopping half way.
results_url
A signed CSV link on completed jobs. It expires an hour after it is issued, so fetch the job again for a fresh one rather than storing it.
Polling cost
Status and result reads are free and do not count against your lookup limits.

Not every product runs in bulk

Search-style products stay single-call by design. The supported job types are listed on the Create a bulk job endpoint.

The full lifecycle
# 1. Submit. The Idempotency-Key makes the retry safe.curl -X POST https://app.1lookup.io/api/v1/bulk/jobs \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: $(uuidgen)" \  -d '{    "type": "email_validation",    "inputs": ["jane.doe@acme.com", "john.doe@example.com"],    "webhook_url": "https://example.com/hooks/1lookup"  }' # 2. Poll for progress.curl https://app.1lookup.io/api/v1/bulk/jobs/JOB_ID \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" # 3. Read rows, or download the signed CSV from results_url.curl "https://app.1lookup.io/api/v1/bulk/jobs/JOB_ID/results?limit=1000&offset=0" \  -H "Authorization: Bearer $ONELOOKUP_API_KEY"

Webhooks

Bulk jobs and monitors can call you back instead of making you poll. Deliveries are signed, so you can prove they came from us.

Registering
Pass webhook_url when you create a bulk job or a monitor. The URL must be HTTPS and publicly resolvable; private and loopback addresses are rejected.
The secretwhsec_…
Returned once, in the response that created the monitor. Store it then — it is never shown again.
X-1Lookup-Signatureheader
sha256= followed by the HMAC-SHA256 of the raw request body, keyed with your secret. Compare in constant time.
Delivery
One attempt, with a 5 second timeout, and redirects are not followed. Return 2xx quickly and do the work afterwards.

A webhook is a hint, not the record

Because delivery is single-attempt, treat the call as a prompt to fetch the job or the monitor’s events. That way a dropped delivery costs you a few minutes, not a batch.

Verify the signature
import crypto from "node:crypto"; // Verify against the RAW body — parse only after the check passes.export function isFrom1Lookup(rawBody, header, secret) {  const received = String(header ?? "").replace(/^sha256=/, "");  const expected = crypto    .createHmac("sha256", secret)    .update(rawBody)    .digest("hex");   const a = Buffer.from(received, "hex");  const b = Buffer.from(expected, "hex");  return a.length === b.length && crypto.timingSafeEqual(a, b);}
Delivery headers
POST /hooks/1lookup HTTP/1.1Content-Type: application/jsonX-1Lookup-Signature: sha256=9f86d081884c7d65…

Recipes

Patterns that come up in most integrations, written the way we would write them.

Screen a sign-up in one round trip

Fire the email and phone lookups together and combine the verdicts. recommendations.primary_action is the fast path; risk_assessment.fraud_score is there when you want your own threshold.

Enrich a lead without wasting credits

Start with the cheap call and widen only when it pays. Domain Age (2 credits) and Domain Authority (10) qualify a domain before Company Firmographics (75) enriches it. Prospect Search previews rows at 2 credits so you only reveal the ones you want.

Clean a list before you dial or send

Run the list through a bulk job, then filter on classification. For phones, scrub DNC and drop number_status: DISCONNECTED; for email, keep deliverability_status: DELIVERABLE and treat RISKY as its own segment.

Keep your CRM from going stale

Point a job change monitor at your champions. When one moves, the event names the old and new roles — which is the moment to reach out, not the quarter after.

Bounded concurrency
// Twenty at a time keeps well inside the limits and finishes// a 10k list in minutes. Above ~5k rows, use a bulk job instead.async function validateAll(emails, concurrency = 20) {  const results = [];  const queue = [...emails];   const workers = Array.from({ length: concurrency }, async () => {    while (queue.length > 0) {      const email = queue.pop();      results.push(await lookup("/email", { email }));    }  });   await Promise.all(workers);  return results;}
Sign-up risk gate
const [email, phone] = await Promise.all([  lookup("/email", { email: form.email }),  lookup("/phone", { phone_number: form.phone }),]); const action = [  email.recommendations?.primary_action,  phone.recommendations?.primary_action,].includes("BLOCK")  ? "BLOCK"  : email.risk_assessment.fraud_score + phone.risk_assessment.fraud_score > 90    ? "REVIEW"    : "APPROVE";

Best practices

The short version of everything above.

Security

  • Keep keys server-side. A key in a browser bundle or mobile app is a public key.
  • Read keys from the environment, never from source control.
  • Rotate on a schedule and whenever someone with access leaves.
  • Verify every webhook signature before trusting the payload.

Reliability

  • Branch on error.code, and retry only 429, 500 and 503.
  • Honour Retry-After before falling back to exponential backoff.
  • Log X-Request-Id with every call you make.
  • Set a client timeout above 60 seconds for live-fetch lookups.

Cost

  • Let the 7-day cache do its work; only send bypass_cache when freshness matters.
  • Qualify with cheap lookups before spending on enrichment.
  • Move anything over a few thousand rows to a bulk job.
  • Check GET /account before a long run.
A production-shaped client
const BASE = "https://app.1lookup.io/api/v1"; export async function lookup(path, body, { retries = 3 } = {}) {  for (let attempt = 0; ; attempt += 1) {    const response = await fetch(BASE + path, {      method: "POST",      headers: {        Authorization: `Bearer ${process.env.ONELOOKUP_API_KEY}`,        "Content-Type": "application/json",      },      body: JSON.stringify(body),      signal: AbortSignal.timeout(90_000),    });     const requestId = response.headers.get("X-Request-Id");    const payload = await response.json();     if (response.ok) return payload.data;     const retryable = [429, 500, 503].includes(response.status);    if (!retryable || attempt >= retries) {      throw Object.assign(new Error(payload.error.message), {        code: payload.error.code,        status: response.status,        requestId,      });    }     const wait = Number(response.headers.get("Retry-After") ?? 2 ** attempt);    await new Promise((resolve) => setTimeout(resolve, wait * 1000));  }}

Versioning and support

The API is versioned in the path. Everything documented here is v1, and v1 is not going to move under you.

Additive changes ship continuously
New endpoints, new fields inside insights and classification, and new enum values can appear at any time. Parse defensively: ignore fields you do not know rather than failing on them.
Breaking changes get a new version
Removing a field, renaming one, or changing its type means a new path, not a silent edit to v1.
MCP
AI clients can connect to the hosted MCP server at https://app.1lookup.io/api/mcp and sign in with OAuth — no API key in a config file. It exposes validate_phone, verify_email, ip_lookup, bulk_verify and get_account.
No-code
Zapier, Make and n8n integrations are in the integration library if you would rather not write the client at all.

Support is at support@1lookup.io. Quote the X-Request-Id from the call you are asking about and the answer arrives a lot faster.

Connect an AI client over MCP
{  "mcpServers": {    "1lookup": {      "url": "https://app.1lookup.io/api/mcp"    }  }}
Version markers on every response
"metadata": {  "api_version": "1.0",  "schema_version": "1.0"}

API reference

All 46 endpoints, grouped by what they answer. Every one takes a JSON body against the base URL https://app.1lookup.io/api/v1, and every single-lookup POST accepts bypass_cache.

Phone

9 endpoints

Email

4 endpoints

IP & network

2 endpoints

Web & SEO

9 endpoints

Company & B2B

6 endpoints

Social & media

8 endpoints

Business & property

3 endpoints

Monitoring

1 endpoint

Bulk jobs

3 endpoints

Account

1 endpoint

Phone

Validation, spam and DNC screening, carrier and portability data, and reverse lookups for phone numbers.

Validate a phone number

POST/api/v1/phone1 credit per lookup

Returns a lookup object whose classification carries line type and number status, insights carries carrier, location and risk indicators, and recommendations carries the action to take.

Parameters

phone_numberstringRequired

The number to validate, with or without a country code. US and Canada numbers are normalized for you.

curl -X POST https://app.1lookup.io/api/v1/phone \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "phone_number": "+14155550123"  }'
POST https://app.1lookup.io/api/v1/phone
Response
{  "success": true,  "data": {    "request": {      "type": "phone",      "input": "+14155550123"    },    "classification": {      "line_type": "MOBILE",      "number_status": "ACTIVE"    },    "risk_assessment": {      "fraud_score": 45,      "risk_level": "MEDIUM"    },    "metadata": {      "credits_used": 1,      "credits_remaining": 9998    }  }}

Check a number for spam

POST/api/v1/phone-spam1 credit per lookup

Returns a lookup object whose classification names the caller type and threat category, with report counts under insights.reputation.

Billing. Numbers outside the US and Canada are served by a metered provider and can carry a higher per-lookup cost.

Parameters

phone_numberstringRequired

The number to screen for spam and robocall reports.

curl -X POST https://app.1lookup.io/api/v1/phone-spam \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "phone_number": "+14155550123"  }'
POST https://app.1lookup.io/api/v1/phone-spam
Response
{  "success": true,  "data": {    "risk_assessment": {      "fraud_score": 74,      "risk_level": "HIGH",      "risk_factors": ["SPAM_REPORTS"]    },    "classification": {      "caller_type": "SPAM_HUMAN",      "threat_category": "SPAM_CALLER"    }  }}

Scrub a number against DNC

POST/api/v1/phone-scrub10 credits per lookup

Returns a lookup object whose classification carries do_not_call and the phone type behind it.

Parameters

phone_numberstringRequired

The number to scrub, with or without a country code.

curl -X POST https://app.1lookup.io/api/v1/phone-scrub \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "phone_number": "12125550001"  }'
POST https://app.1lookup.io/api/v1/phone-scrub
Response
{  "success": true,  "data": {    "request": {      "id": "71faccd6-8a12-4f0e-b6a1-5c9d3e2f7a44",      "type": "phone_scrub",      "input": "12125550001",      "processing_time_ms": 1721    },    "metadata": { "credits_used": 10, "credits_remaining": 9990, "cache_hit": false },    "classification": { "matched": true, "phone_type": "mobile", "do_not_call": false }  }}

Check network status (HLR)

POST/api/v1/hlr-lookup5 credits per lookup

HLR queries the subscriber register the number is registered against, so it answers whether a handset is switched on and reachable right now rather than whether the number is well formed. connectivity_status carries the carrier's own wording: CONNECTED (registered and reachable), ABSENT (assigned, but the handset is off or out of coverage), INVALID_MSISDN (not assigned to a subscriber) or UNDETERMINED (the network did not answer). Score on that field. is_valid is a convenience rollup of it and is false only for INVALID_MSISDN, so ABSENT and UNDETERMINED both read as true. An INVALID_MSISDN result is not charged.

Returns a lookup object whose classification carries the live network status and roaming flag, with MCC/MNC carrier detail under insights.

Parameters

phone_numberstringRequired

The number to look up. International format (E.164) is strongly recommended.

curl -X POST https://app.1lookup.io/api/v1/hlr-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "phone_number": "+447700900000"  }'
POST https://app.1lookup.io/api/v1/hlr-lookup
Response
{  "success": true,  "data": {    "request": { "type": "hlr_lookup", "input": "+447700900000", "processing_time_ms": 1200 },    "metadata": { "credits_used": 5, "credits_remaining": 9985, "cache_hit": false },    "classification": { "network_status": "CONNECTED", "roaming": false },    "insights": {      "carrier": { "name": "Vodafone UK", "mcc": "234", "mnc": "15" },      "location": { "country": "United Kingdom", "country_code": "GB" }    },    "recommendations": { "primary_action": "APPROVE" }  }}

Check carrier portability (MNP)

POST/api/v1/mnp-lookup3 credits per lookup

Returns a lookup object whose classification.is_ported is set, with the current and original carrier under insights.carrier.

Parameters

phone_numberstringRequired

The number to check. International format (E.164) is strongly recommended.

curl -X POST https://app.1lookup.io/api/v1/mnp-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "phone_number": "+447700900000"  }'
POST https://app.1lookup.io/api/v1/mnp-lookup
Response
{  "success": true,  "data": {    "request": { "type": "mnp_lookup", "input": "+447700900000", "processing_time_ms": 800 },    "metadata": { "credits_used": 3, "credits_remaining": 9982, "cache_hit": false },    "classification": { "is_ported": true },    "insights": { "carrier": { "current": "Three UK", "original": "O2 UK" } },    "recommendations": { "primary_action": "APPROVE" }  }}

Detect number type

POST/api/v1/nt-lookup1 credit per lookup

Returns a lookup object whose classification carries number_type and is_valid.

Parameters

phone_numberstringRequired

The number to classify. International format (E.164) is strongly recommended.

curl -X POST https://app.1lookup.io/api/v1/nt-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "phone_number": "+447700900000"  }'
POST https://app.1lookup.io/api/v1/nt-lookup
Response
{  "success": true,  "data": {    "request": { "type": "nt_lookup", "input": "+447700900000", "processing_time_ms": 600 },    "metadata": { "credits_used": 1, "credits_remaining": 9981, "cache_hit": false },    "classification": { "number_type": "MOBILE", "is_valid": true },    "insights": { "carrier": { "name": "Vodafone UK", "country": "United Kingdom" } },    "recommendations": { "primary_action": "APPROVE" }  }}

Reverse phone lookup

POST/api/v1/reverse-phone-lookup10 credits per lookup

US numbers only. A Canadian or Caribbean number is not sent to the data sources at all: it comes back with classification.matched false, classification.coverage_supported false, classification.coverage_region set to the country the area code belongs to, and recommendations.user_message saying so. Out-of-coverage numbers are never charged, so a coverage gap reads differently from a genuine miss.

Returns a lookup object whose classification.matched says whether a person was found, with the record under insights.contact.

Billing. Two data sources are available and you pick one per request with lookup_source. Standard costs 10 credits and reads caller ID records only, which return a name for a minority of numbers. Premium costs 25 credits and reads the full consumer database. Either way, a lookup that does not match is free.

Parameters

phone_numberstringRequired

The number to look up, e.g. "2125550001".

lookup_sourcestringOptional

Which data source to use: "standard" (10 credits, caller ID records) or "premium" (25 credits, full consumer database, best name coverage). Defaults to "standard".

curl -X POST https://app.1lookup.io/api/v1/reverse-phone-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "phone_number": "2125550001",    "lookup_source": "premium"  }'
POST https://app.1lookup.io/api/v1/reverse-phone-lookup
Response
{  "success": true,  "data": {    "request": { "type": "reverse_phone_lookup", "input": "2125550001", "processing_time_ms": 546 },    "metadata": { "credits_used": 10, "credits_remaining": 9971, "cache_hit": false },    "classification": { "matched": true },    "insights": {      "contact": {        "first_name": "Jane",        "last_name": "Doe",        "address": "123 Main St",        "city": "New York",        "state": "NY",        "zip": "10001",        "email": "jane.doe@example.com"      }    }  }}

Skip trace a contact

POST/api/v1/phone-append10 credits per lookup

Returns a lookup object whose classification.matched says whether the contact was found, with the appended numbers under insights.contact.

Parameters

input.firstNamestringRequired

Given name of the contact, nested inside the input object.

input.lastNamestringRequired

Family name of the contact.

input.addressstringRequired

Street address of the contact.

input.citystringRequired

City of the contact.

input.zipstringRequired

ZIP code of the contact.

curl -X POST https://app.1lookup.io/api/v1/phone-append \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "firstName": "John",      "lastName": "Doe",      "address": "123 Main St",      "city": "Anytown",      "zip": "12345"    }  }'
POST https://app.1lookup.io/api/v1/phone-append
Response
{  "success": true,  "data": {    "request": { "type": "phone_append", "processing_time_ms": 546 },    "metadata": { "credits_used": 10, "credits_remaining": 9961, "cache_hit": false },    "classification": { "matched": true },    "insights": { "contact": { "phone": "+12125550001", "phone_type": "mobile" } }  }}

Find a mobile number

POST/api/v1/mobile-finder40 credits per lookup

Send any combination of a professional profile URL, a work email and a personal email. At least one is required, and more identifiers raise the match rate.

Returns a lookup object whose classification.mobile_number holds the number when one is found.

Billing. Success-based: 0 credits when no number is found.

Parameters

profile_urlstringOptional

Professional profile URL, e.g. LinkedIn. One of profile_url, work_email or personal_email is required.

work_emailstringOptional

Work email address for the person.

personal_emailstringOptional

Personal email address for the person.

curl -X POST https://app.1lookup.io/api/v1/mobile-finder \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "profile_url": "https://www.linkedin.com/in/jane-doe/",    "work_email": "jane.doe@acme.com"  }'
POST https://app.1lookup.io/api/v1/mobile-finder
Response
{  "success": true,  "data": {    "classification": {      "matched": true,      "mobile_number": "+12125550123"    },    "metadata": { "credits_used": 40 }  }}

Email

Deliverability and fraud checks, plus appending and finding email addresses from what you already know.

Validate an email address

POST/api/v1/email1 credit per lookup

Returns a lookup object whose classification carries the deliverability status and provider tier, with quality, reputation and deliverability scores under insights.

Parameters

emailstringRequired

The email address to validate.

curl -X POST https://app.1lookup.io/api/v1/email \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "email": "jane.doe@acme.com"  }'
POST https://app.1lookup.io/api/v1/email
Response
{  "success": true,  "data": {    "classification": {      "email_type": "BUSINESS",      "deliverability_status": "DELIVERABLE"    },    "insights": {      "quality": { "score": 85 },      "deliverability": { "score": 70 }    },    "risk_assessment": {      "risk_level": "LOW",      "fraud_score": 5    }  }}

Find a work email

POST/api/v1/email-enrichment5 credits per lookup

Returns a lookup object whose classification.email holds the work email when one is found.

Billing. Success-based: 0 credits when no email is found.

Parameters

firstNamestringRequired

Given name. Required with lastName, unless you send fullName or name carrying both.

lastNamestringRequired

Family name.

domainstringRequired

Company website domain, e.g. acme.com.

fullNamestringOptional

Full name; must split into at least a first and last name.

namestringOptional

Alias for fullName.

curl -X POST https://app.1lookup.io/api/v1/email-enrichment \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "firstName": "Jane",    "lastName": "Doe",    "domain": "1lookup.io"  }'
POST https://app.1lookup.io/api/v1/email-enrichment
Response
{  "success": true,  "data": {    "request": { "type": "email_enrichment", "processing_time_ms": 800 },    "metadata": {      "credits_used": 5,      "credits_remaining": 9994,      "cache_hit": false,      "data_sources": ["1lookup", "email_intelligence"]    },    "classification": { "matched": true, "email": "jane.doe@1lookup.io", "domain": "1lookup.io" },    "insights": { "email_enrichment": { "email": "jane.doe@1lookup.io" } },    "recommendations": { "primary_action": "APPROVE" }  }}

Append an email address

POST/api/v1/email-append10 credits per lookup

Returns a lookup object whose classification.matched says whether the contact was found, with the appended address under insights.contact.

Parameters

input.firstNamestringRequired

Given name of the contact, nested inside the input object.

input.lastNamestringRequired

Family name of the contact.

input.addressstringRequired

Street address of the contact.

input.citystringRequired

City of the contact.

input.zipstringRequired

ZIP code of the contact.

curl -X POST https://app.1lookup.io/api/v1/email-append \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "firstName": "John",      "lastName": "Doe",      "address": "123 Main St",      "city": "Anytown",      "zip": "12345"    }  }'
POST https://app.1lookup.io/api/v1/email-append
Response
{  "success": true,  "data": {    "request": { "type": "email_append", "processing_time_ms": 546 },    "metadata": { "credits_used": 10, "credits_remaining": 9984, "cache_hit": false },    "classification": { "matched": true },    "insights": { "contact": { "email": "john.doe@example.com" } }  }}

Reverse email lookup

POST/api/v1/reverse-email-append10 credits per lookup

Returns a lookup object whose classification.matched says whether a person was found, with the record under insights.contact.

Parameters

emailstringRequired

The email address to look up.

curl -X POST https://app.1lookup.io/api/v1/reverse-email-append \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "email": "jane.doe@example.com"  }'
POST https://app.1lookup.io/api/v1/reverse-email-append
Response
{  "success": true,  "data": {    "request": { "type": "reverse_email_append", "input": "jane.doe@example.com", "processing_time_ms": 45 },    "metadata": { "credits_used": 10, "credits_remaining": 9974, "cache_hit": false },    "classification": { "matched": true },    "insights": {      "contact": {        "first_name": "Jane",        "last_name": "Doe",        "address": "123 Main St",        "city": "New York",        "state": "NY",        "zip": "10001"      }    }  }}

IP & network

Geolocation, connection type, threat signals, and contact data from an IP address.

Look up an IP address

POST/api/v1/ip1 credit per lookup

Returns a lookup object whose classification carries the connection and service type, with network, location and security detail under insights.

Parameters

ipstringRequired

The IP address to look up. IPv4 and IPv6 are both accepted.

curl -X POST https://app.1lookup.io/api/v1/ip \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "ip": "104.227.91.244"  }'
POST https://app.1lookup.io/api/v1/ip
Response
{  "success": true,  "data": {    "risk_assessment": {      "risk_level": "MEDIUM",      "fraud_score": 40    },    "classification": {      "connection_type": "DATACENTER"    },    "insights": {      "location": {        "city": "Miami",        "country": "United States"      }    }  }}

Reverse IP lookup

POST/api/v1/reverse-ip-append10 credits per lookup

Returns a lookup object whose classification.matched says whether a record was found, with contact and geolocation detail under insights.

Parameters

ipstringRequired

The IP address to resolve. IPv4 and IPv6 are both accepted.

curl -X POST https://app.1lookup.io/api/v1/reverse-ip-append \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "ip": "104.227.91.244"  }'
POST https://app.1lookup.io/api/v1/reverse-ip-append
Response
{  "success": true,  "data": {    "request": {      "id": "a19cfb0b-2d77-4c19-bb0e-7a5c9d1e2f80",      "type": "reverse_ip_append",      "input": "104.227.91.244",      "processing_time_ms": 22    },    "metadata": { "credits_used": 10, "credits_remaining": 9989, "cache_hit": false },    "classification": { "matched": true },    "insights": {      "contact": { "first_name": "Jane", "last_name": "Doe", "email": "jane.doe@example.com" },      "geolocation": { "city": "Miami", "region": "Florida", "country_code": "US", "zip": "33131" }    }  }}

Web & SEO

Page content, contact details, search authority, backlinks, keywords, and audience data for any domain.

Scrape a web page

POST/api/v1/website-scraper10 credits per lookup

Returns a lookup object whose classification carries the page title and content counts, with the Markdown body under insights.website_scraper_result.

Parameters

urlstringRequired

The page to scrape. Must start with http:// or https://, or be a bare valid domain.

curl -X POST https://app.1lookup.io/api/v1/website-scraper \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "url": "https://scrapethissite.com/pages/"  }'
POST https://app.1lookup.io/api/v1/website-scraper
Response
{  "success": true,  "data": {    "classification": {      "name": "Learn Web Scraping | Scrape This Site",      "characterCount": 1318,      "linksCount": 10    },    "metadata": { "credits_used": 10 }  }}

Extract contacts from a site

POST/api/v1/website-contacts-scraper10 credits per lookup

Returns a lookup object whose classification carries the counts found, with the addresses, numbers and profile URLs under insights.

Parameters

domainstringRequired

Website domain, or a full URL, to extract contacts from.

curl -X POST https://app.1lookup.io/api/v1/website-contacts-scraper \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "domain": "example.com"  }'
POST https://app.1lookup.io/api/v1/website-contacts-scraper
Response
{  "success": true,  "data": {    "request": { "type": "website_contacts_scraper", "input": "example.com", "processing_time_ms": 3400 },    "metadata": { "credits_used": 10, "credits_remaining": 9975, "cache_hit": false },    "classification": {      "domain": "example.com",      "hasEmails": true,      "hasPhones": true,      "emailsCount": 3,      "phonesCount": 2,      "socialsCount": 4    },    "insights": {      "emails": ["contact@example.com", "support@example.com"],      "phones": ["+1-555-123-4567"],      "socials": {        "facebook": ["https://facebook.com/example"],        "linkedin": ["https://linkedin.com/company/example"]      }    }  }}

Domain SEO intelligence

POST/api/v1/domain-seo-intelligence10 credits per lookup

Returns a lookup object whose insights carry authority scores, backlink counts and traffic estimates side by side.

Parameters

domainstringRequired

The domain to analyze, e.g. "theverge.com".

curl -X POST https://app.1lookup.io/api/v1/domain-seo-intelligence \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "domain": "theverge.com"  }'
POST https://app.1lookup.io/api/v1/domain-seo-intelligence
Response
{  "success": true,  "data": {    "request": { "type": "domain_seo_intelligence", "input": "theverge.com", "processing_time_ms": 1250 },    "metadata": { "credits_used": 10, "credits_remaining": 9965, "cache_hit": false },    "insights": {      "authority": { "mozDA": 90, "mozPA": 85, "ahrefsDR": 92, "majesticTF": 80 },      "backlinks": { "ahrefsBacklinks": 15000000, "ahrefsRefDomains": 200000 },      "traffic": { "ahrefsTraffic": 50000000, "ahrefsOrganicKeywords": 10000000 }    },    "risk_assessment": { "fraud_score": 15, "risk_level": "LOW" }  }}

Domain authority

POST/api/v1/domain-authority10 credits per lookup

Returns a lookup object whose classification carries the authority score, rank and organic traffic, with keyword and paid detail under insights.

Parameters

domainstringRequired

The root domain to score, e.g. "stripe.com".

curl -X POST https://app.1lookup.io/api/v1/domain-authority \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "domain": "stripe.com"  }'
POST https://app.1lookup.io/api/v1/domain-authority
Response
{  "success": true,  "data": {    "request": { "type": "domain_authority", "input": "stripe.com", "processing_time_ms": 900 },    "metadata": { "credits_used": 10, "credits_remaining": 9955, "cache_hit": false },    "classification": {      "found": true,      "domain": "stripe.com",      "authority_score": 84,      "semrush_rank": 1285,      "organic_traffic": 2009909,      "runs_paid_ads": true    },    "insights": {      "domain_authority_result": {        "organic_keywords": 1200000,        "organic_traffic_value_usd": 5200000,        "paid_keywords": 18400,        "paid_traffic": 240000,        "paid_share": 0.1067      }    }  }}

Domain age check

POST/api/v1/domain-age2 credits per lookup

Read live from the registry over RDAP, so the creation date is the registry's own record rather than a cached third-party guess.

Returns a lookup object whose classification carries the creation date, age and registrar, with expiry, nameservers and registry status under insights.

Billing. Unregistered domains are not charged.

Parameters

domainstringRequired

The domain to check, e.g. "stripe.com". URLs and subdomains are reduced to the registrable domain.

curl -X POST https://app.1lookup.io/api/v1/domain-age \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "domain": "stripe.com"  }'
POST https://app.1lookup.io/api/v1/domain-age
Response
{  "success": true,  "data": {    "classification": {      "registered": true,      "age_human": "16 years, 11 months",      "age_days": 6180,      "created_date": "2009-09-11T00:00:00.000Z",      "registrar": "MarkMonitor Inc."    },    "metadata": { "credits_used": 2 }  }}

Keyword metrics

POST/api/v1/keyword-metrics6 credits per lookup

Returns a lookup object whose classification carries volume, CPC, difficulty and intent, with trend and SERP features under insights.

Parameters

keywordstringRequired

The keyword to look up. Maximum 200 characters.

countrystringOptional

Country database to query.

Defaults to US.

curl -X POST https://app.1lookup.io/api/v1/keyword-metrics \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "keyword": "crm software"  }'
POST https://app.1lookup.io/api/v1/keyword-metrics
Response
{  "success": true,  "data": {    "request": { "type": "keyword_metrics", "input": "crm software", "processing_time_ms": 700 },    "metadata": { "credits_used": 6, "credits_remaining": 9934, "cache_hit": false },    "classification": {      "found": true,      "keyword": "crm software",      "search_volume": 673000,      "cpc_usd": 14.26,      "keyword_difficulty": 77,      "difficulty_band": "hard",      "primary_intent": "INFORMATIONAL"    },    "insights": {      "keyword_metrics_result": {        "trend_direction": "rising",        "has_ai_overview": true,        "serp_features": ["PEOPLE_ALSO_ASK", "AI_OVERVIEW", "REVIEWS"],        "estimated_monthly_traffic_value_usd": 2879094      }    }  }}

Scrape a SERP

POST/api/v1/search-intent-lookup1 credit per lookup

Returns a lookup object whose classification carries the query and result count, with the full result set under insights.search_intent_result.

Parameters

qstringRequired

The search query to run.

curl -X POST https://app.1lookup.io/api/v1/search-intent-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "q": "best CRM for plumbers"  }'
POST https://app.1lookup.io/api/v1/search-intent-lookup
Response
{  "success": true,  "data": {    "request": { "type": "search_intent_lookup", "input": "best CRM for plumbers", "processing_time_ms": 1900 },    "metadata": { "credits_used": 1, "credits_remaining": 9933, "cache_hit": false },    "classification": { "query": "best CRM for plumbers", "organicCount": 10 },    "insights": {      "search_intent_result": {        "organic": [          { "position": 1, "title": "The 8 best CRMs for plumbers", "link": "https://example.com/best-crm-plumbers" }        ],        "peopleAlsoAsk": ["Do plumbers need a CRM?"],        "relatedSearches": ["plumbing crm software"]      }    }  }}

Website audience intelligence

POST/api/v1/audience-intelligence86 credits per report

One report per call. Ask for the report you need rather than paying for the whole profile.

Returns a lookup object whose classification names the report and row count, with the rows under insights.audience_intelligence_result.

Parameters

domainstringRequired

The website to profile, e.g. "nytimes.com".

reportstringOptional

One of summary, geo, age_sex, income, sources, destinations.

Defaults to summary.

curl -X POST https://app.1lookup.io/api/v1/audience-intelligence \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "domain": "nytimes.com",    "report": "geo"  }'
POST https://app.1lookup.io/api/v1/audience-intelligence
Response
{  "success": true,  "data": {    "request": { "type": "audience_intelligence", "input": "nytimes.com", "processing_time_ms": 1100 },    "metadata": { "credits_used": 86, "credits_remaining": 9847, "cache_hit": false },    "classification": {      "found": true,      "target": "nytimes.com",      "report": "geo",      "report_label": "Traffic by country",      "row_count": 24    },    "insights": {      "audience_intelligence_result": {        "rows": [          { "country": "US", "traffic": 1250000, "traffic_share": 0.42, "bounce_rate": 0.51 }        ]      }    }  }}

Company & B2B

Firmographics, verified work contacts, and people and account search across the B2B graph.

Company firmographics

POST/api/v1/company-firmographics75 credits per lookup

Returns a lookup object whose classification carries the headline firmographics, with codes, technographics and growth signals under insights.

Billing. Success-based: 0 credits when the company is not matched.

Parameters

domainstringRequired

The company's domain, e.g. "shopify.com".

curl -X POST https://app.1lookup.io/api/v1/company-firmographics \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "domain": "shopify.com"  }'
POST https://app.1lookup.io/api/v1/company-firmographics
Response
{  "success": true,  "data": {    "request": { "type": "company_firmographics", "input": "shopify.com", "processing_time_ms": 950 },    "metadata": { "credits_used": 75, "credits_remaining": 9772, "cache_hit": false },    "classification": {      "matched": true,      "company_name": "Shopify",      "industry": "information technology & services",      "employee_count": 8100,      "employee_band": "5000+",      "annual_revenue": 11556000000,      "founded_year": 2006,      "country": "Canada"    },    "insights": {      "company_firmographics_result": {        "sic_codes": ["7372"],        "naics_codes": ["511210"],        "technology_count": 112,        "headcount_growth_12m": 0.19,        "departmental_head_count": { "engineering": 2400 }      }    }  }}

B2B contact append

POST/api/v1/b2b-contact-append75 credits per lookup

Match on any one of an email, a LinkedIn URL, or a name plus company domain.

Returns a lookup object whose classification carries the work email and its confidence, title and seniority, with department and role history under insights.

Billing. Success-based: 0 credits on a no-match.

Parameters

emailstringOptional

A known email address for the person, work or personal.

linkedin_urlstringOptional

The person's LinkedIn profile URL.

namestringOptional

The person's full name. Must be combined with company_domain.

company_domainstringOptional

The employer's domain. Required when matching by name.

curl -X POST https://app.1lookup.io/api/v1/b2b-contact-append \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "Jane Doe",    "company_domain": "acme.com"  }'
POST https://app.1lookup.io/api/v1/b2b-contact-append
Response
{  "success": true,  "data": {    "request": { "type": "b2b_contact_append", "processing_time_ms": 1050 },    "metadata": { "credits_used": 75, "credits_remaining": 9697, "cache_hit": false },    "classification": {      "matched": true,      "full_name": "Jane Doe",      "work_email": "jane.doe@acme.com",      "email_confidence": "high",      "title": "VP of Marketing",      "seniority": "vp",      "company": "Acme Corporation"    },    "insights": {      "b2b_contact_append_result": {        "departments": ["marketing"],        "linkedin_url": "linkedin.com/in/janedoe",        "company_domain": "acme.com",        "current_role_started": "2022-03-01"      }    }  }}

Company profile lookup

POST/api/v1/company-profile-lookup25 credits per lookup

A deep fetch that takes seconds rather than milliseconds. Repeat lookups inside the 7-day cache window return instantly.

Returns a lookup object whose classification carries size, HQ, founding year and follower count, with specialties and funding under insights.

Billing. Success-based: 0 credits on a no-match.

Parameters

domainstringRequired

The company's domain, e.g. "stripe.com".

profile_urlstringOptional

The company's profile URL, if you already have it. Replaces domain.

include_fundingbooleanOptional

Set false to skip the funding-history enrichment.

Defaults to true.

curl -X POST https://app.1lookup.io/api/v1/company-profile-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "domain": "stripe.com"  }'
POST https://app.1lookup.io/api/v1/company-profile-lookup
Response
{  "success": true,  "data": {    "request": { "type": "company_profile_lookup", "processing_time_ms": 42000 },    "metadata": { "credits_used": 25, "credits_remaining": 9595, "cache_hit": false },    "classification": {      "matched": true,      "company_name": "Stripe",      "industry": "Financial Services",      "company_size": "5,001-10,000 employees",      "headquarters": "San Francisco, California",      "founded": 2010,      "followers": 1050000    },    "insights": {      "company_profile_lookup_result": {        "website": "https://stripe.com",        "employees_on_platform": 8624,        "specialties": ["Payments", "Billing"],        "funding": {          "total_raised": 9109000000,          "rounds": 21,          "last_round_date": "2024-07-01",          "ipo_status": "private"        }      }    }  }}

LinkedIn profile lookup

POST/api/v1/linkedin-profile-lookup10 credits per lookup

Public, logged-out profile data only. Repeat lookups inside the 7-day cache window return instantly.

Returns a lookup object whose classification carries the headline facts, with the full role history, education and skills under insights.

Billing. Success-based: 0 credits when no public profile is found.

Parameters

profile_urlstringRequired

A public LinkedIn profile URL (https://www.linkedin.com/in/…). A bare vanity username also works.

curl -X POST https://app.1lookup.io/api/v1/linkedin-profile-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "profile_url": "https://www.linkedin.com/in/avery-chen"  }'
POST https://app.1lookup.io/api/v1/linkedin-profile-lookup
Response
{  "success": true,  "data": {    "classification": {      "matched": true,      "name": "Avery Chen",      "current_title": "VP of Revenue Ops",      "current_company": "Acme Analytics",      "followers": 8420    },    "metadata": { "credits_used": 10 }  }}

Social & media

Public profile, post, ad and transcript data across the major social platforms, plus audio transcription.

Check a social profile

POST/api/v1/social-profile-check10 credits per lookup

Ten platforms: Instagram, TikTok, YouTube, X, Facebook, Threads, Twitch, Snapchat, Bluesky and Truth Social.

Returns a lookup object whose classification carries existence, follower count and the verified and private flags, with bio and engagement under insights.

Billing. Success-based: 0 credits when no live profile is found.

Parameters

platformstringOptional

One of instagram, tiktok, youtube, twitter, facebook, threads, twitch, snapchat, bluesky, truthsocial. Required with handle.

handlestringOptional

The profile handle, with or without the @.

urlstringOptional

A full profile URL on any supported platform. Replaces platform and handle.

curl -X POST https://app.1lookup.io/api/v1/social-profile-check \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "platform": "instagram",    "handle": "nike"  }'
POST https://app.1lookup.io/api/v1/social-profile-check
Response
{  "success": true,  "data": {    "request": { "type": "social_profile_check", "processing_time_ms": 35000 },    "metadata": { "credits_used": 10, "credits_remaining": 9575, "cache_hit": false },    "classification": {      "matched": true,      "exists": true,      "platform": "instagram",      "handle": "nike",      "display_name": "Nike",      "followers": 302000000,      "verified": true,      "private": false    },    "insights": {      "social_profile_check_result": {        "following": 165,        "posts_or_videos": 1320,        "engagement_rate": null,        "business_account": true,        "bio": "Spotlighting athlete stories"      }    }  }}

Look up a social post

POST/api/v1/social-post-lookup5 credits per lookup

Instagram, TikTok, YouTube, X, Facebook, Threads, Bluesky, Truth Social, Pinterest and LinkedIn.

Returns a lookup object whose classification carries the platform, author and headline engagement counts, with caption and posted date under insights.

Billing. Success-based: 0 credits on a no-match.

Parameters

urlstringRequired

The full post, video or pin URL on a supported platform.

curl -X POST https://app.1lookup.io/api/v1/social-post-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "url": "https://www.tiktok.com/@nike/video/7300000000000000000"  }'
POST https://app.1lookup.io/api/v1/social-post-lookup
Response
{  "success": true,  "data": {    "request": { "type": "social_post_lookup", "processing_time_ms": 4200 },    "metadata": { "credits_used": 5, "credits_remaining": 9570, "cache_hit": false },    "classification": {      "matched": true,      "exists": true,      "platform": "tiktok",      "author_handle": "nike",      "likes": 184200,      "views": 2400000    },    "insights": {      "social_post_lookup_result": {        "url": "https://www.tiktok.com/@nike/video/7300000000000000000",        "caption": "Run further. #JustDoIt",        "author_name": "Nike",        "comments": 3120,        "shares": 5410,        "posted_at": "2026-07-12T14:03:00.000Z"      }    }  }}

Get a video transcript

POST/api/v1/video-transcript5 credits per lookup

TikTok, Instagram, YouTube, X, Facebook, LinkedIn and Reddit.

Returns a lookup object whose classification says whether a transcript exists and how long it is, with the text under insights.

Billing. Success-based: 0 credits when no transcript is found.

Parameters

urlstringRequired

The full video URL on a supported platform.

curl -X POST https://app.1lookup.io/api/v1/video-transcript \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"  }'
POST https://app.1lookup.io/api/v1/video-transcript
Response
{  "success": true,  "data": {    "request": { "type": "video_transcript", "processing_time_ms": 5100 },    "metadata": { "credits_used": 5, "credits_remaining": 9565, "cache_hit": false },    "classification": {      "matched": true,      "transcript_available": true,      "platform": "youtube",      "word_count": 1240,      "language": "en"    },    "insights": {      "video_transcript_result": {        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",        "transcript": "Welcome back to the channel. Today we are covering…",        "language": "en",        "word_count": 1240      }    }  }}

Look up ads in flight

POST/api/v1/ad-library-lookup10 credits per lookup

Meta, TikTok, LinkedIn and Google ad libraries.

Returns a lookup object whose classification says whether ads are running and how many, with the creatives under insights.

Billing. Success-based: 0 credits when no ads are found.

Parameters

platformstringOptional

One of facebook, tiktok, linkedin, google.

Defaults to facebook.

companystringOptional

The advertiser's name or domain. Provide company or query.

querystringOptional

A keyword to search the ad library for.

curl -X POST https://app.1lookup.io/api/v1/ad-library-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "platform": "facebook",    "company": "nike"  }'
POST https://app.1lookup.io/api/v1/ad-library-lookup
Response
{  "success": true,  "data": {    "request": { "type": "ad_library_lookup", "processing_time_ms": 4600 },    "metadata": { "credits_used": 10, "credits_remaining": 9550, "cache_hit": false },    "classification": {      "matched": true,      "running_ads": true,      "ad_count": 10,      "total_available": 142,      "platform": "facebook",      "query": "nike"    },    "insights": {      "ad_library_lookup_result": {        "ads": [          {            "id": "820000000000001",            "advertiser": "Nike",            "text": "Meet the trainer that goes the distance.",            "active": true,            "started_at": "2026-07-01",            "url": null          }        ]      }    }  }}

TikTok audience demographics

POST/api/v1/audience-demographics40 credits per lookup

Returns a lookup object whose insights.audience_demographics_result.countries hold each country, its ISO code and percentage share.

Billing. Success-based: 0 credits on a no-match.

Parameters

handlestringRequired

The TikTok handle, with or without the @, or the profile URL.

curl -X POST https://app.1lookup.io/api/v1/audience-demographics \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "handle": "nike"  }'
POST https://app.1lookup.io/api/v1/audience-demographics
Response
{  "success": true,  "data": {    "request": { "type": "audience_demographics", "processing_time_ms": 6200 },    "metadata": { "credits_used": 40, "credits_remaining": 9510, "cache_hit": false },    "classification": {      "matched": true,      "platform": "tiktok",      "handle": "nike",      "top_country": "United States"    },    "insights": {      "audience_demographics_result": {        "countries": [          { "label": "United States", "code": "US", "percentage": 38.2 },          { "label": "Brazil", "code": "BR", "percentage": 9.1 },          { "label": "United Kingdom", "code": "GB", "percentage": 6.4 }        ]      }    }  }}

Transcribe audio

POST/api/v1/audio-transcription6 credits per minute of audio

Returns a lookup object whose classification carries duration, word count and speaker count, with the transcript and per-speaker segments under insights.

Billing. Charged on the true duration. An up-front hold is placed from expected_duration_minutes and settled when the transcript completes.

Parameters

audio_urlstringRequired

An https URL of the audio or video file to transcribe.

expected_duration_minutesnumberOptional

Approximate file length in minutes. Sizes the up-front credit hold; the final charge settles to the true duration.

diarizebooleanOptional

Set false to skip speaker labels.

Defaults to true.

curl -X POST https://app.1lookup.io/api/v1/audio-transcription \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "audio_url": "https://example.com/call-recording.mp3",    "expected_duration_minutes": 12  }'
POST https://app.1lookup.io/api/v1/audio-transcription
Response
{  "success": true,  "data": {    "classification": {      "transcribed": true,      "duration_formatted": "12:00",      "speaker_count": 2,      "word_count": 1840    },    "metadata": { "credits_used": 72 }  }}

Business & property

Live business-listing data and US residential property records.

Verify a business

POST/api/v1/business-verify30 credits per lookup

Blends live business-listing data with phone and email cross-checks. A deep fetch that takes seconds; repeats inside the 7-day cache window are instant.

Returns a lookup object whose classification carries the verdict and verification score, with the individual checks that produced it under insights.

Billing. Success-based: 0 credits when the business is not found.

Parameters

business_namestringRequired

The business name to verify.

citystringRequired

The city the business operates in.

countrystringOptional

Two-letter country code.

Defaults to US.

phonestringOptional

A phone number to validate and compare against the listing.

emailstringOptional

An email whose domain is checked against the business website.

websitestringOptional

A website to compare against the listing.

curl -X POST https://app.1lookup.io/api/v1/business-verify \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "business_name": "Blue Bottle Coffee",    "city": "Oakland",    "phone": "+15105551234"  }'
POST https://app.1lookup.io/api/v1/business-verify
Response
{  "success": true,  "data": {    "request": { "type": "business_verify", "processing_time_ms": 38000 },    "metadata": { "credits_used": 30, "credits_remaining": 9405, "cache_hit": false },    "classification": {      "matched": true,      "verdict": "verified",      "verification_score": 100,      "business_name": "Blue Bottle Coffee",      "address": "300 Webster St, Oakland, CA 94607",      "category": "Coffee shop",      "rating": 4.5,      "reviews_count": 1834,      "listing_status": "operational"    },    "insights": {      "business_verify_result": {        "components": {          "listing_found": true,          "listing_operational": true,          "phone_valid": true,          "phone_matches_listing": true        },        "failed_checks": [],        "phone_check": {          "valid": true,          "line_type": "MOBILE",          "dnc": false,          "matches_listing": true        }      }    }  }}

Look up a business

POST/api/v1/business-lookup10 credits per lookup

Returns a lookup object whose classification carries the listing basics, with website, hours and coordinates under insights.

Billing. Success-based: 0 credits on a no-match.

Parameters

business_namestringRequired

The business name to find.

citystringRequired

The city the business operates in.

countrystringOptional

Two-letter country code.

Defaults to US.

place_urlstringOptional

A listing URL to fetch directly. Replaces business_name and city.

curl -X POST https://app.1lookup.io/api/v1/business-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "business_name": "Blue Bottle Coffee",    "city": "Oakland"  }'
POST https://app.1lookup.io/api/v1/business-lookup
Response
{  "success": true,  "data": {    "request": { "type": "business_lookup", "processing_time_ms": 36000 },    "metadata": { "credits_used": 10, "credits_remaining": 9395, "cache_hit": false },    "classification": {      "matched": true,      "business_name": "Blue Bottle Coffee",      "address": "300 Webster St, Oakland, CA 94607",      "phone": "+15105551234",      "category": "Coffee shop",      "rating": 4.5,      "review_count": 1834,      "listing_status": "operational",      "place_id": "ChIJ…"    },    "insights": {      "business_lookup_result": {        "website": "https://bluebottlecoffee.com",        "hours": { "Monday": "6AM-6PM" },        "latitude": 37.7955,        "longitude": -122.2668,        "is_claimed": true      }    }  }}

Look up a property

POST/api/v1/property-lookup15 credits per lookup

US addresses, read from public real-estate listing data. A deep fetch that takes seconds; repeats inside the 7-day cache window are instant.

Returns a lookup object whose classification carries the property basics and listing status, with market history under insights.

Billing. Success-based: 0 credits on a no-match.

Parameters

addressstringRequired

The full US street address: street, city, state, ZIP.

listing_urlstringOptional

A listing URL to fetch directly. Replaces address.

curl -X POST https://app.1lookup.io/api/v1/property-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "address": "301 Mission St, San Francisco, CA 94105"  }'
POST https://app.1lookup.io/api/v1/property-lookup
Response
{  "success": true,  "data": {    "request": { "type": "property_lookup", "processing_time_ms": 39000 },    "metadata": { "credits_used": 15, "credits_remaining": 9380, "cache_hit": false },    "classification": {      "matched": true,      "address": "301 Mission St, San Francisco, CA 94105",      "beds": 2,      "baths": 2,      "sqft": 1421,      "home_type": "condo",      "year_built": 2009,      "listing_status": "for_sale",      "list_price": 1250000    },    "insights": {      "property_lookup_result": {        "city": "San Francisco",        "state": "CA",        "zip_code": "94105",        "days_on_market": 34,        "last_sold_date": "2018-06-12",        "last_sold_price": 1100000,        "photo_count": 27      }    }  }}

Monitoring

Standing watches that push an event to you when the underlying data changes.

Create a job change monitor

POST/api/v1/job-change-monitors5 credits per contact per weekly recheck

Create the monitor, add contacts to it, then read events by polling or by receiving the signed webhook. Contacts are rechecked weekly.

Returns the monitor. When a webhook_url is set, the response also carries webhook_secret — the only time it is ever shown.

Billing. Creating and managing monitors is free. Profiles that cannot be reached are not charged.

Parameters

namestringRequired

A name for the monitor.

alert_emailbooleanOptional

Set false to turn off email alerts for this monitor.

Defaults to true.

webhook_urlstringOptional

HTTPS endpoint for change events. Deliveries are signed; the signing secret is returned once, on create.

GET /job-change-monitors lists your monitors. POST /job-change-monitors/{id}/contacts adds contacts, and GET /job-change-monitors/{id}/events reads detected changes with page and limit query parameters.
curl -X POST https://app.1lookup.io/api/v1/job-change-monitors \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "Key champions"  }'
POST https://app.1lookup.io/api/v1/job-change-monitors
Response
{  "success": true,  "data": {    "monitor": {      "id": "cmon_8f2a1c",      "name": "Key champions",      "frequency": "weekly",      "alert_email": true,      "webhook_url": null,      "active": true,      "created_at": "2026-07-30T12:00:00.000Z"    },    "webhook_secret": null  }}
Add contacts, then read events
# Add contacts to the monitorcurl -X POST https://app.1lookup.io/api/v1/job-change-monitors/MONITOR_ID/contacts \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "contacts": [      { "profile_url": "https://www.linkedin.com/in/jane-doe", "label": "Jane Doe - Acme" }    ]  }' # Read detected changescurl "https://app.1lookup.io/api/v1/job-change-monitors/MONITOR_ID/events?page=1&limit=50" \  -H "Authorization: Bearer $ONELOOKUP_API_KEY"

Bulk jobs

Submit up to 100,000 rows in one call, poll for progress, and download the finished CSV.

Create a bulk job

POST/api/v1/bulk/jobsNo credits

Returns the job id and how many rows were accepted. Processing starts immediately; poll the status endpoint for progress.

Billing. Charged at the per-lookup rate of the job type, per row. Credits are checked up front for the whole job.

Parameters

typestringRequired

The lookup to run on every row. See the supported types below.

inputsstring[]Required

The values to look up — phone numbers, emails, domains, URLs or handles, depending on the type. Maximum 100,000 rows per job.

webhook_urlstringOptional

HTTPS endpoint called once when the job finishes. Signed with the same scheme as monitor webhooks.

Send an Idempotency-Key header on every create. A retry with the same key returns the original job — with Idempotent-Replay: true — instead of creating and charging for a second one. Keys are held for 24 hours.
Supported types: hlr_lookup, mnp_lookup, nt_lookup, email_validation, reverse_email_append, domain_authority, domain_age, backlink_overview, keyword_metrics, company_firmographics, b2b_contact_append, business_verify, business_lookup, company_profile_lookup, linkedin_profile_lookup, social_profile_check, property_lookup, social_post_lookup, video_transcript, audience_demographics, link_in_bio_lookup.
curl -X POST https://app.1lookup.io/api/v1/bulk/jobs \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: c2a7d9f4-1e6b-4b5a-9a3d-2f8e6b0c1d77" \  -d '{    "type": "email_validation",    "inputs": [      "jane.doe@acme.com",      "john.doe@example.com"    ]  }'
POST https://app.1lookup.io/api/v1/bulk/jobs
Response
{  "success": true,  "data": {    "job_id": "235ecda1-9e98-46f1-9cdf-4d410e937e38",    "status": "processing",    "accepted": 2  }}

Check bulk job status

GET/api/v1/bulk/jobs/{job_id}No credits

Returns the job with live row counters. When status is completed, results_url is a signed CSV download link.

Billing. Polling is free and does not count against your lookup budget.

Parameters

job_idstringRequired

The job_id returned when the job was created.

results_url is a signed link that expires one hour after it is issued. Poll again for a fresh one rather than storing it.
curl https://app.1lookup.io/api/v1/bulk/jobs/{job_id} \  -H "Authorization: Bearer $ONELOOKUP_API_KEY"
GET https://app.1lookup.io/api/v1/bulk/jobs/{job_id}
Response
{  "success": true,  "data": {    "job_id": "235ecda1-9e98-46f1-…",    "status": "processing",    "processed_count": 850,    "row_count": 3000,    "results_url": null  }}

Get bulk job results

GET/api/v1/bulk/jobs/{job_id}/resultsNo credits

Returns the persisted lookup rows for the job, with a pagination object carrying has_more.

Billing. Reading results is free.

Parameters

job_idstringRequired

The job_id returned when the job was created.

limitnumberOptional

Rows to return. Maximum 1000.

Defaults to 100.

offsetnumberOptional

Rows to skip before returning results.

Defaults to 0.

curl "https://app.1lookup.io/api/v1/bulk/jobs/{job_id}/results?limit=100&offset=0" \  -H "Authorization: Bearer $ONELOOKUP_API_KEY"
GET https://app.1lookup.io/api/v1/bulk/jobs/{job_id}/results?limit=100&offset=0
Response
{  "success": true,  "data": {    "job_id": "235ecda1-9e98-46f1-9cdf-4d410e937e38",    "status": "completed",    "results_url": "https://1lookup-uploads.s3.us-east-1.amazonaws.com/…",    "lookups": [      {        "id": "3f1c9a20-6b6e-4f57-9f0a-1d2c3b4a5e6f",        "input": "+447911123401",        "status": "completed",        "tokens_consumed": 5,        "response_data": {}      }    ],    "pagination": { "limit": 100, "offset": 0, "returned": 1, "has_more": false }  }}

Account

Read your organization, plan, credit balances, and usage.

Retrieve your account

GET/api/v1/accountNo credits

Returns your organization, subscription, credit balances, period and all-time usage, and the calling key's own totals.

Billing. Free. Use it to check your balance before a large run.

This endpoint takes no parameters.

curl https://app.1lookup.io/api/v1/account \  -H "Authorization: Bearer $ONELOOKUP_API_KEY"
GET https://app.1lookup.io/api/v1/account
Response
{  "success": true,  "data": {    "organization": {      "name": "My Company",      "active": true    },    "subscription": {      "status": "active",      "plan": { "name": "Pro Plan" }    },    "tokens": { "total_available": 11250 },    "usage": {      "current_period": { "lookups": 250 }    }  }}