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.

Base URL
https://app.1lookup.io/api/v1
Authentication
Bearer API key
Formats
JSON in, JSON out
Endpoints
80 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"    },    "insights": {      "reachability": { "is_reachable": true },      "compliance": { "dnc_listed": false, "dno_flag": false }    },    "recommendations": {      "primary_action": "APPROVE"    },    "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
A risk_level of LOW, MEDIUM, HIGH or CRITICAL, the risk_factors behind it, and a confidence_level. Many products also carry a fraud_score from 0–100, email, IP and spam checks among them; phone validation does not.
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": ["phone_validator", "carrier_lookup", "hlr_check", "fcc_daily_data"]    },    "risk_assessment": {      "risk_level": "LOW",      "risk_factors": [],      "confidence_level": 90    },    "classification": { "line_type": "MOBILE" },    "insights": { "raw_api_fields": { "network": "T-MOBILE USA, INC." } },    "recommendations": {      "primary_action": "APPROVE",      "secondary_actions": [],      "user_message": "Phone number is reachable. Check DNC/DNO flags before contacting."    }  }}

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
Tech Stack Lookup1
Domain Age Check2
Email Authentication Check2
Prospect Search2
Search Trends2
Google Reviews Export2
NPI Lookup2
EU VAT Check2
LEI Lookup2
Bank Lookup2
SEC Company Facts2
Funding Trigger2
Complaint Check2
SSL Certificate Check2
8-K Event Lookup2
Census Tract Lookup2
Brand Lookup2
Nonprofit Verify2
VIN Decoder2
DNS Lookup2
Reported Number Check2
MNP Lookup3
Google News Search3
Link-in-Bio Lookup3
Website Traffic Checker3
Sanctions Screening3
OIG Exclusion Check3
Federal Contractor Lookup3
Environmental Compliance Check3
Skip Trace5
HLR Lookup5
Email Enrichment5
Social Post Lookup5
Video Transcript5
Social Search5
LinkedIn Post Engagers5
Signup Check5
Job Change Monitoring5
Keyword Metrics6
Audio Transcription6
Email Append10
Reverse Phone Lookup10
Phone Scrub10
Reverse IP Append10
Reverse Email Append10
Website Scraper10
Domain SEO Intelligence10
Website Contacts Scraper10
Domain Authority10
Business Lookup10
DOT Number Lookup10
LinkedIn Profile Lookup10
LinkedIn Company Lookup10
Social Profile Check10
Ad Library Lookup10
Backlink Overview13
Property Lookup15
X Post Search15
X Profile Posts15
X Post Replies15
Company Profile Lookup25
Keyword Rank Checker30
Business Verify30
LinkedIn Email Finder30
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.
UNSUPPORTED_COUNTRY400A phone_validation bulk job carried a number from outside the US and Canada. The response lists the rows in row_indexes, and nothing is charged.
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.
LOOKUP_FAILED400The lookup could not be finished for this input. Nothing was charged.
SERVICE_UNAVAILABLE503The lookup is temporarily unavailable on our side. Nothing was charged. Retry-After is set.
LOOKUP_TIMEOUT503The lookup did not finish in time. Nothing was charged. Retry-After is set.
NO_RESULT503Phone spam check only: no rating came back for this number. Nothing was charged. 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.
Monitor events
After a check pass that found changes, one POST carries every new event for the list. Each event names the number (phoneNumber in E.164, your label), the event id and detectedAt, the time of the check that found it. changes holds only the fields that changed, each as { from, to }: status, lineType, carrier (the number's own network), ported, dncListed and, with Spam & Risk on, spamRiskLevel (LOW, MEDIUM, HIGH, CRITICAL). A field with no reading on either side never fires, so a number's first rating is not a change.
Test event
Send Test Event on a watch list page posts one signed sample to the saved URL: a spam risk change on a sample number, with "test": true at the top level. Real events never carry that field. No credits are used and nothing is recorded.

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…
Number Monitoring event
{  "listId": "0b6f3c1e-5d2a-4c8e-9f7a-1e2d3c4b5a69",  "listName": "Office lines",  "events": [    {      "id": "9a1d2c3b-4e5f-4a6b-8c7d-0e1f2a3b4c5d",      "phoneNumber": "+12025550143",      "label": "Front desk",      "changes": {        "spamRiskLevel": { "from": "LOW", "to": "CRITICAL" }      },      "detectedAt": "2026-11-15T10:00:42.000Z"    }  ]}

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; the email risk_assessment.fraud_score and the phone classification.number_status are there when you want your own rule.

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: INACTIVE, the status for a line that failed its reachability check. number_status returns ACTIVE, INACTIVE or INVALID, and INVALID means the carrier lookup came back with nothing to classify, so treat it as unknown rather than dead. 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 > 50 ||      phone.classification.number_status !== "ACTIVE"    ? "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 with an API key as the bearer token, or sign in with OAuth instead. Using Claude, ChatGPT or Grok? Open API & MCP in the app: the Connect your AI wizard hands you a personal link with the key built in and exact steps for your tool. The server exposes validate_phone, verify_email, ip_lookup, bulk_verify, get_account and confirm_connection.
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",      "headers": { "Authorization": "Bearer sk_live_..." }    }  }}
Version markers on every response
"metadata": {  "api_version": "1.0",  "schema_version": "1.0"}

API reference

All 80 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

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

Works for numbers in any country. US and Canada numbers are checked against the live carrier record: reachability, LRN and porting, rate center, and the DNC and DNO lists. A toll-free number (800, 833, 844, 855, 866, 877 or 888) comes back with classification.line_type TOLL_FREE, classification.number_status UNKNOWN and insights.reachability.is_reachable null: carrier records don't cover toll-free numbers, so whether one is in service can't be checked. A US or Canadian number the network could not be asked about (insights.reachability.reason "No SS7 ID", about half of Canadian numbers) also comes back with classification.number_status UNKNOWN and insights.reachability.is_reachable null, not false. Every other country is checked against international carrier data and comes back in the same shape with classification.coverage set to "international": classification.line_type (MOBILE, LANDLINE, VOIP, TOLL_FREE or PREMIUM), classification.number_status (VALID or INVALID), the carrier under insights.carrier.name and insights.raw_api_fields.network, and the country under insights.location. Validity there comes from the numbering plan and the network the number belongs to, so insights.reachability.is_reachable is null, insights.routing.is_ported is null when the number may have moved networks, and the DNC and DNO fields are null because those are US and Canada lists. For whether a mobile is switched on right now, run an HLR lookup. An international number that comes back INVALID is not charged. Send international numbers with their country code (+44..., or 0044...).

Returns a lookup object whose classification carries line type and number status, insights carries reachability, porting, time zone, DNC and DNO flags and the carrier record, and recommendations carries the action to take.

Parameters

phone_numberstringRequired

The number to validate. US and Canada numbers work with or without the +1. Numbers in any other country need their country code, e.g. +442079460958.

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"    },    "insights": {      "reachability": { "is_reachable": true },      "compliance": { "dnc_listed": false, "dno_flag": false }    },    "metadata": {      "credits_used": 1,      "credits_remaining": 9998    }  }}

Check a number for spam

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

ftc_reports_12m sits beside recommendations and counts the reports the U.S. Federal Trade Commission's Do Not Call data holds for the number over the last 12 months (0 when it holds none). It is null when the count is not available: a number outside the US and Canada, or data not counted yet. A cached answer carries the count as of the moment it is served, not the one from when it was cached. The FTC does not verify these reports and caller numbers can be spoofed, so treat the count as a signal, not a verdict. The same data is free to browse at https://www.1lookup.io/tools/call-reports-checker.

Returns a lookup object whose risk_assessment holds a rule-based spam score and risk level and whose classification names the caller type and threat category. These come from two facts about the number: its user reputation and whether it is flagged as a robocaller. A number with no rating comes back as UNKNOWN with a null score. Fields we have no source for (report counts, scam types, callback odds, confidence) are null.

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": 78,      "risk_level": "CRITICAL",      "risk_factors": ["SPAM_REPORTS"]    },    "classification": {      "caller_type": "SPAM_HUMAN",      "threat_category": "SPAM_CALLER"    },    "ftc_reports_12m": 18  }}

Scrub a number against DNC

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

Returns a lookup object whose classification carries doNotCall, the line type as phoneTypeCode (the one-letter code, e.g. W wireless, L landline, V VoIP, X litigator) and phoneTypeLabel (e.g. MOBILE), and litigator: true when the number belongs to a known litigator, serial complainer or attorney. recommendations.business_rules.do_not_call carries the same Do Not Call answer. Do Not Call and litigator numbers come back with primary_action BLOCK, litigators with the LITIGATOR_RISK risk factor, never APPROVE.

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, "phoneTypeCode": "W", "phoneTypeLabel": "MOBILE", "doNotCall": false, "litigator": false },    "recommendations": {      "primary_action": "APPROVE",      "business_rules": { "can_use_contact": true, "do_not_call": false, "litigator_risk": 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-append5 credits per lookup

Returns a lookup object whose classification.matched says whether the contact was found. classification.phones lists the numbers found (one for standard, up to two for premium), cell first, each with phone, type (mobile, landline or unknown) and doNotCall; classification.phone, phone_type and do_not_call repeat the first one.

Billing. Two kinds are available and you pick one per request with lookup_source. Standard costs 5 credits and returns one phone per match. Premium returns up to two phones, a mobile and a landline: 10 credits when both come back, 5 when only one does. Either way, a trace that does not match is free.

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.

lookup_sourcestringOptional

Which kind of trace to run: "standard" (5 credits, one phone per match) or "premium" (up to two phones, a mobile and a landline: 10 credits for two, 5 for one). Defaults to "standard".

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"    },    "lookup_source": "premium"  }'
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": 9956, "cache_hit": false, "lookup_source": "premium" },    "classification": {      "matched": true,      "phone": "2125550001",      "phone_type": "C",      "phoneTypeLabel": "MOBILE",      "do_not_call": false,      "phones": [        { "phone": "2125550001", "type": "mobile", "doNotCall": false },        { "phone": "2125550002", "type": "landline", "doNotCall": true }      ]    }  }}

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 }  }}

Check whether a number was reported to the FTC

POST/api/v1/reported-number-check2 credits per lookup

Reads the U.S. Federal Trade Commission's public Do Not Call reported calls data, which holds the numbers people reported to it. Send phone_number as a 10-digit US or Canadian number in any common format (212-555-0142, (212) 555-0142, +1 212 555 0142). You get the number of reports over up to the last 12 months, how many of them said a recorded message or robocall, the subjects people gave, the count for each month and the date of the latest report. The count starts at classification.counted_from; while older months are still being added classification.window_complete is false and the count covers fewer than 12 months. The FTC does not verify these reports, and a caller number can be spoofed, so a report count says that people reported the number, not what the number is. Reporter details are never returned. A number from another country is refused.

Returns a lookup object whose classification carries the report count, the robocall share and the dates as flat fields, with the subjects and the month-by-month counts under insights.reported_number_result.

Billing. Charged when the number has at least one report. 0 credits when no report is found, when the number is not a US or Canadian number, and when the reports are not available yet (503 with a Retry-After).

Parameters

phone_numberstringRequired

A 10-digit US or Canadian phone number, e.g. "212-555-0142" or "+1 212 555 0142". Spaces, dashes, dots and brackets are fine. A number with a country code other than +1 is refused.

A number with no report returns classification.found: false with reason: no_reports and 0 credits. That is an answer, not an error: the number has no report in the FTC data we hold for the window.
If the reports cannot be read (they are still being loaded, or the database does not answer) the call returns 503 with a Retry-After and 0 credits. It is never read as the number having no reports.
by_month lists every month in the window, oldest first, including months with 0 reports. The month totals add up to reports, and the subject counts add up to reports too.
The FTC data is updated every weekday, so a report made today can take a day or more to appear. data_through is the last day loaded.
The window is the last 12 months. counted_from is the first day the count covers; until the older months are loaded it can be later than 12 months ago and window_complete is false.
Results are cached for 24 hours. Send bypass_cache: true to read them again at once.
curl -X POST https://app.1lookup.io/api/v1/reported-number-check \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "phone_number": "212-555-0142"  }'
POST https://app.1lookup.io/api/v1/reported-number-check
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "number": "2125550142",      "reports": 42,      "robocall_reports": 36,      "last_reported": "2026-10-22"    },    "metadata": { "credits_used": 2 }  }}

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 with a top-level deliverable (true only when the mailbox checked out, the one field to branch on in GoHighLevel, Zapier or Make), a classification with the deliverability status and provider tier, and 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": {    "deliverable": true,    "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" }  }}

Find a work email from a profile URL

POST/api/v1/linkedin-email-finder30 credits per lookup

For the case where you have the profile URL but not the person's name and company domain, which is what /email-enrichment needs. A profile with no verified work email answers matched: false and costs nothing. Repeat lookups inside the 7-day cache window return instantly and are not charged again.

Returns a lookup object whose classification.work_email holds the work email when one is found, with the name, job title, company, company domain and location that came with it, and the same fields plus the company's location under insights.linkedin_email_finder.

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

Parameters

profile_urlstringRequired

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

profileUrlstringOptional

Alias for profile_url.

linkedin_urlstringOptional

Alias for profile_url.

linkedinUrlstringOptional

Alias for profile_url.

urlstringOptional

Alias for profile_url.

usernamestringOptional

Alias for profile_url, for the bare vanity username on its own.

vanitystringOptional

Alias for username.

A hit answers in about a second; a miss is the slow case, because the search runs to exhaustion before giving up. Allow up to 45 seconds for a single call and do not set a client timeout below that, or you will abandon free no-match answers you have already waited for.
The URL and the bare vanity username resolve to the same cache key, so https://www.linkedin.com/in/avery-chen?utm_source=x and avery-chen are one lookup, not two.
curl -X POST https://app.1lookup.io/api/v1/linkedin-email-finder \  -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-email-finder
Response
{  "success": true,  "data": {    "metadata": { "credits_used": 30, "cache_hit": false },    "classification": {      "matched": true,      "work_email": "avery.chen@acmeanalytics.com",      "full_name": "Avery Chen",      "job_title": "VP of Revenue Operations",      "company": "Acme Analytics",      "company_domain": "acmeanalytics.com"    }  }}
No verified email found (0 credits)
{  "success": true,  "data": {    "request": { "type": "linkedin_email_finder", "processing_time_ms": 31290 },    "metadata": { "credits_used": 0, "credits_remaining": 9585, "cache_hit": false },    "classification": {      "matched": false,      "work_email": null,      "query": "https://www.linkedin.com/in/avery-chen"    },    "insights": { "linkedin_email_finder": null },    "recommendations": {      "primary_action": "REVIEW",      "user_message": "No verified work email was found for that profile. You have not been charged."    }  }}

Check a domain's email authentication

POST/api/v1/email-auth-check2 credits per lookup

Read from the domain's public DNS records, so it shows what a receiving mail server sees. SPF is counted through every include, because a record that passes 10 DNS lookups is silently ignored. DKIM is checked on the 20 selector names most mail systems use, so a key published under a custom name will not show up. Run it weekly on the domains you send from to catch a DMARC or SPF record someone broke.

Returns a lookup object whose classification carries the 0 to 100 grade, its letter and whether the domain can be spoofed, with the full MX, SPF, DMARC, DKIM and BIMI findings and an ordered list of plain fixes under insights.email_auth_result.

Billing. Charged when the domain exists in DNS. A domain that does not exist, and a DNS timeout, cost 0.

Parameters

domainstringRequired

The domain to check, e.g. "stripe.com". An email address or URL is reduced to its domain, and a subdomain such as "news.stripe.com" is checked as written.

can_be_spoofed is true until DMARC is published and set to quarantine or reject for all mail. A policy of none only monitors.
Results are cached for 7 days. After you change a record, send bypass_cache: true to check it again.
curl -X POST https://app.1lookup.io/api/v1/email-auth-check \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "domain": "stripe.com"  }'
POST https://app.1lookup.io/api/v1/email-auth-check
Response
{  "success": true,  "data": {    "metadata": { "credits_used": 2, "cache_hit": false },    "classification": {      "domain": "stripe.com",      "grade": 87,      "grade_letter": "B",      "can_be_spoofed": false,      "dmarc_policy": "reject",      "has_spf": true,      "has_dkim": true,      "fix_count": 3    }  }}
Domain does not exist (0 credits)
{  "success": true,  "data": {    "request": { "type": "email_auth_check", "input": "no-such-domain-example.com", "processing_time_ms": 90 },    "metadata": { "credits_used": 0, "credits_remaining": 9953, "cache_hit": false },    "classification": {      "found": false,      "domain_exists": false,      "domain": "no-such-domain-example.com",      "grade": null    },    "insights": { "email_auth_result": null },    "recommendations": {      "primary_action": "REVIEW",      "user_message": "no-such-domain-example.com does not exist in DNS. You have not been charged."    }  }}

Check a new signup

POST/api/v1/signup-check5 credits per lookup

Send the new signup's email, and the ip address and phone number it came with when you have them. The email is looked through to the real inbox, so dots and plus tags that point to one mailbox count once, and it is checked for disposable inbox services, brand-new domains and domains with no mail server. The IP address is checked for proxy, VPN, Tor, hosting-provider and public spam-list use, and the phone number for validity and line type. The recent-signup check counts the signups your own API key sent in the last hour that share this one's IP address, inbox or domain, so a burst of fake accounts shows up even when each one looks fine alone. Each reason is one plain sentence with the points it added, largest first. A fact that could not be established adds nothing, and insights.signup_check_result.checks says which groups of checks ran. Call it once per signup, at the moment of signup.

Returns a lookup object whose classification carries the verdict, the risk score, the top reason and the main signals as flat fields, with every reason and the full email, IP address, phone and recent-signup findings under insights.signup_check_result.

Billing. Charged when the check runs, with or without an IP address and phone number. 0 credits when the check fails outright, and when the email, IP address or phone number is malformed (400).

Parameters

emailstringRequired

The email address the person signed up with.

ipstringOptional

The IPv4 or IPv6 address the signup came from. Leave it out when you do not have one. It makes the verdict sharper and lets the check count signups from the same address.

phonestringOptional

The phone number given at signup, with its country code, e.g. "+44 20 7946 0958". A 10-digit number with no country code is read as a US number.

verdict is allow below a risk score of 35, review from 35 to 69 and block from 70. A single hard fact is enough for a block: a disposable inbox, a domain with no mail server or an address that bounces.
The recent-signup counts are per API key and cover the last hour. They count only the signups your own key sent, never anyone else's, and the counts leave out the signup being checked, so the first signup of a burst shows 0.
The same signup sent twice within a minute returns the same answer. Send bypass_cache: true to check it again at once.
In a bulk job, write each row as email | ip | phone (the IP address and phone number are optional). Bulk rows are checked one at a time and do not read the recent-signup counts.
curl -X POST https://app.1lookup.io/api/v1/signup-check \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "email": "sample.person+trial7@gmail.com",    "ip": "203.0.113.24",    "phone": "+12125550142"  }'
POST https://app.1lookup.io/api/v1/signup-check
Response
{  "success": true,  "data": {    "classification": {      "verdict": "review",      "risk_score": 49,      "top_reason": "The IP address belongs to a hosting or cloud provider, not a home or phone network.",      "signups_same_ip_1h": 2    },    "metadata": { "credits_used": 5 }  }}

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. The fraud score, risk level, reputation score and probabilities are rule-based estimates worked out from the address's flags (proxy, hosting, mobile, Tor, blocklists), not measurements. A field with no source comes back null.

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": { "domainAuthority": 90, "pageAuthority": 85, "domainStrength": 92, "trustScore": 80 },      "backlinks": { "totalBacklinks": 15000000, "referringDomains": 200000 },      "traffic": { "organicTraffic": 50000000, "organicKeywords": 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,      "search_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 }        ]      }    }  }}

Check a domain's SSL certificate

POST/api/v1/ssl-certificate-check2 credits per lookup

Read by our own TLS handshake against port 443 of the domain, so it shows what a visitor's browser is shown. Send domain (a URL or an email address is reduced to its hostname, and a subdomain such as shop.example.com is checked as written, because each name can present its own certificate). The verdict is one of valid, expiring_soon (30 days or fewer), expired, not_yet_valid, hostname_mismatch, self_signed or untrusted, and issues lists every problem in plain words, most serious first. Only the certificate is read: nothing is sent to the site beyond the handshake. IP addresses and names that resolve to private or internal addresses are refused.

Returns a lookup object whose classification carries the verdict, the days left and the headline facts, with the full certificate, trust verdict, connection details and chain under insights.ssl_certificate_result.

Billing. Charged when a certificate is read, whatever its verdict: an expired or untrusted certificate is still an answer. 0 credits when the domain does not exist, has no HTTPS on port 443, or resolves to a private address, and when the connection fails (503 with a Retry-After).

Parameters

domainstringRequired

The domain to check, e.g. "shop.example.com". A URL or an email address is reduced to its hostname. IP addresses, single-word names and public suffixes are refused.

A domain with no certificate to read returns classification.found: false with 0 credits and a reason: no_such_host (not in DNS), no_https (nothing accepts connections on port 443) or blocked (the name points to a private or internal address). These are answers, not errors.
A connection that times out, is reset or fails the handshake returns 503 with a Retry-After and 0 credits. It is never read as the domain having no HTTPS, because the cause may be a bad moment on either side.
trusted is whether the chain verifies against the public certificate authorities for the name asked. A server that leaves out an intermediate certificate reads as untrusted here, as it does in some browsers and many API clients.
Only port 443 is checked, and the handshake is made from our servers, so a site that blocks our network or serves a different certificate by region can read differently to a visitor.
Results are cached for 1 day. After a renewal, send bypass_cache: true to read the new certificate.
curl -X POST https://app.1lookup.io/api/v1/ssl-certificate-check \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "domain": "shop.example.com"  }'
POST https://app.1lookup.io/api/v1/ssl-certificate-check
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "host": "shop.example.com",      "certificate_status": "expiring_soon",      "days_remaining": 21,      "issuer": "Sample Trust CA 1"    },    "metadata": { "credits_used": 2 }  }}

Look up a domain's DNS records

POST/api/v1/dns-lookup2 credits per lookup

Read with plain DNS queries, so it shows what the domain publishes right now. Send domain (a URL or an email address is reduced to its hostname, and a subdomain such as mail.example.com is looked up as written, because each name has its own records) or ip (an IPv4 or IPv6 address, for its reverse DNS). For a domain you get the A, AAAA, CNAME, MX (lowest priority first), NS, TXT, CAA and SOA records, plus mail_provider (Google Workspace, Microsoft 365, Zoho Mail, Proton Mail and others, read from the MX hosts, or custom) and dns_host (Cloudflare, Amazon Route 53, GoDaddy and others, read from the NS hosts, or custom). For an address you get its PTR names. Private, loopback and internal names and addresses are refused.

Returns a lookup object whose classification carries the record counts, the two labels and each record type as a flat text field, with the structured records under insights.dns_lookup_result.

Billing. Charged when at least one record, or a reverse DNS name, is found. 0 credits when the domain does not exist, when it exists but has none of these records, when an IP address has no reverse DNS name, and when DNS does not answer in time (503 with a Retry-After).

Parameters

domainstringOptional

The domain to look up, e.g. "example.com" or "_dmarc.example.com". A URL or an email address is reduced to its hostname. Send either domain or ip. An IP address sent here also works.

ipstringOptional

Use instead of domain to get the reverse DNS (PTR) name of an IPv4 or IPv6 address, e.g. "8.8.4.4". Private and reserved addresses are refused.

A name with nothing to show returns classification.found: false with 0 credits and a reason: no_such_domain (not in DNS), no_records (the name exists but has none of the eight record types) or no_ptr (the IP address has no reverse DNS name). These are answers, not errors.
A resolver that times out or errors returns 503 with a Retry-After and 0 credits. It is never read as the domain having no records, because the cause may be a bad moment on either side. If only some record types fail to answer, the others are returned and unanswered_types names the missing ones.
Every record list is lower case, without trailing dots, de-duplicated and in a stable order. In the flat classification fields several records of one type are joined with | , because a TXT record can itself contain commas and semicolons; use insights.dns_lookup_result.records for the list.
mail_provider is null when the domain has no MX records or only a null MX (it says it accepts no mail), and custom when its mail servers are not ones we name. dns_host joins up to three providers with + when a zone is split across them.
A reverse lookup (IP address in) returns the PTR names in classification.ptr_names and insights.dns_lookup_result.ptr.
Results are cached for 15 minutes, because records change. Send bypass_cache: true to read them again at once.
curl -X POST https://app.1lookup.io/api/v1/dns-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "domain": "example.com"  }'
POST https://app.1lookup.io/api/v1/dns-lookup
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "query": "example.com",      "mail_provider": "Google Workspace",      "dns_host": "Cloudflare",      "record_count": 11    },    "metadata": { "credits_used": 2 }  }}

Look up a company's brand kit

POST/api/v1/brand-lookup2 credits per lookup

Read from the site's own home page and the files it links (its web app manifest and its first stylesheets), the same pages a visitor's browser loads. Send domain (a URL or an email address is reduced to its hostname, a leading www. is dropped, and any other subdomain is read as written, because shop.example.com can carry its own brand). Logos are listed best first with their type and size, colors are hex values with the most prominent first, and social links cover LinkedIn, X, Facebook, Instagram, YouTube, TikTok and GitHub. Parts a site does not publish come back null or empty. IP addresses and names that resolve to private or internal addresses are refused.

Returns a lookup object whose classification carries the company name, the best logo, the main color, the fonts and the social profile links, with every logo, color, font and profile under insights.brand_lookup_result.

Billing. Charged when a company name or a logo is found. 0 credits when the domain does not exist, the site has no home page or refuses the request, or the page names no company and points to no logo, and when the site cannot be reached (503 with a Retry-After).

Parameters

domainstringRequired

The company website, e.g. "shop.example.com". A URL or an email address is reduced to its hostname. IP addresses, single-word names and public suffixes are refused.

A site with no brand details to read returns classification.found: false with 0 credits and a reason: no_such_host (not in DNS), blocked (the name points to a private or internal address), no_page (no home page), access_refused (the site answered 401, 403 or 451), not_a_web_page (the address answered with something other than a web page) or no_brand_details (the page names no company and points to no logo). These are answers, not errors.
A site that times out, resets the connection or answers with a server error returns 503 with a Retry-After and 0 credits. It is never read as the company having no brand, because the cause may be a bad moment on either side.
Logos have a purpose: logo for a wordmark or symbol, icon for a favicon-style square. A sharing image is returned separately as social_image_url and is not counted as a logo.
Only what the site publishes can be returned. Sites that block automated requests, and sites whose pages are drawn entirely by scripts, can come back with fewer parts or with access_refused.
Results are cached for 7 days. After a rebrand, send bypass_cache: true to read the site again.
curl -X POST https://app.1lookup.io/api/v1/brand-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "domain": "shop.example.com"  }'
POST https://app.1lookup.io/api/v1/brand-lookup
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "company_name": "Sample Shop",      "logo_url": "https://shop.example.com/assets/logo.svg",      "primary_color": "#4f46e5",      "primary_font": "Inter"    },    "metadata": { "credits_used": 2 }  }}

Look up what a website runs on

POST/api/v1/tech-stack-lookup1 credit per lookup

Reads the site's home page once, the way a browser asks for it, together with its DNS records, and matches what they show against thousands of technology fingerprints. Send domain (a URL or an email address is reduced to its hostname; a subdomain such as shop.example.com is its own site). You get each technology with its categories, its group (CMS and site builders, E-commerce and payments, Analytics and tracking, Marketing and sales, Customer engagement, Hosting, CDN and servers, Frameworks and languages, Security and privacy, Themes and plugins, Media, Other) and its version where the site gives one away. email_provider is read from the domain's MX records; dns_services lists the services named in its verification (TXT) records, kept apart because a sign-up is not the site's stack. Private and internal names, and sites that resolve or redirect to internal addresses, are refused.

Returns a lookup object whose classification carries the technology count, every technology as one flat text field, one field per group and the email provider, with the structured list under insights.tech_stack_result.

Billing. Charged only when the site answers with its home page. 0 credits when the site blocks the check (403, 429 or a bot challenge), when the name does not exist or has no home page, and when the site does not answer in time (503 with a Retry-After).

Parameters

domainstringRequired

The website to check, e.g. "example.com". A URL ("https://www.example.com/pricing") or an email address ("jane@example.com") is reduced to its hostname. IP addresses are not accepted.

A site that blocks the check returns classification.found: false, blocked: true, the http_status it answered with and, when it says so, the bot protection in front of it, with 0 credits. A name that does not exist or has no home page returns found: false with a reason (no_such_host or no_page) and 0 credits. These are answers, not errors.
A site that times out, resets the connection or answers with a server error returns 503 with a Retry-After and 0 credits. A site that redirects in a loop returns 400 with SITE_REDIRECT_LOOP.
Everything is detected from the site's headers, HTML and DNS, so tools a site loads only after its page runs in a browser can be missing. implied: true marks a technology that is known to come with another one (WordPress runs on PHP), with implied_by naming it.
Versions are returned when the site gives them away (a generator tag, a script address). In the flat classification fields several technologies are joined with | ; use insights.tech_stack_result.technologies for the list.
Only the first 2 MB of the home page is read; truncated: true says the page was longer.
Results are cached for 1 day. After changing your own site, send bypass_cache: true to read it again at once.
curl -X POST https://app.1lookup.io/api/v1/tech-stack-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "domain": "example.com"  }'
POST https://app.1lookup.io/api/v1/tech-stack-lookup
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "query": "example.com",      "technology_count": 6,      "cms": "WordPress 7.2",      "email_provider": "Google Workspace"    },    "metadata": { "credits_used": 1 }  }}

Check where a website ranks on Google

POST/api/v1/keyword-rank-checker30 credits per lookup

Looks through the top 100 results for the website. A website outside them comes back as not found, and the top 10 are still returned. A fresh check takes 5 to 20 seconds; repeats inside the 1-day cache window are instant.

Returns a lookup object whose classification carries the position, the ranking page and the result count, with the top 10 results and the search features on the page under insights.keyword_rank_result.

Billing. Success-based: 0 credits when no search results come back.

Parameters

keywordstringRequired

The search to check, up to 200 characters.

domainstringRequired

The website to look for. A bare domain, a www address or a full page link all resolve to the same site. Pages on its subdomains count.

countrystringOptional

The country the search is made from, as a two-letter code (US, GB) or a name.

Defaults to US.

citystringOptional

Optional. A city to search from, written with its state or region, like Austin, Texas.

languagestringOptional

Optional. A language code such as en or es. Defaults to the main language of the country.

Bulk jobs accept type keyword_rank_checker: one check per row, written as keyword | website | country | city, with the country and city optional.
curl -X POST https://app.1lookup.io/api/v1/keyword-rank-checker \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "keyword": "best trail running shoes",    "domain": "northpeakgear.example",    "country": "US"  }'
POST https://app.1lookup.io/api/v1/keyword-rank-checker
Response
{  "success": true,  "data": {    "request": {      "type": "keyword_rank_checker",      "processing_time_ms": 9800    },    "metadata": {      "credits_used": 30,      "credits_remaining": 9500,      "cache_hit": false    },    "classification": {      "matched": true,      "keyword": "best trail running shoes",      "domain": "northpeakgear.example",      "country_code": "US",      "country_name": "United States",      "city": null,      "found": true,      "position": 7,      "ranking_url": "https://www.northpeakgear.example/trail-running-shoes",      "ranking_title": "Trail running shoes | North Peak Gear",      "results_checked": 100,      "searched_depth": 100,      "pages_ranking": 1,      "top_result_domain": "trailpace.example",      "serp_features": [        "People also ask",        "AI overview",        "Related searches"      ],      "owns_featured_snippet": false    },    "insights": {      "keyword_rank_result": {        "keyword": "best trail running shoes",        "domain": "northpeakgear.example",        "country_code": "US",        "country_name": "United States",        "city": null,        "language": "en",        "searched_depth": 100,        "results_checked": 100,        "total_results": 412000000,        "found": true,        "position": 7,        "ranking_url": "https://www.northpeakgear.example/trail-running-shoes",        "ranking_title": "Trail running shoes | North Peak Gear",        "also_ranking": [],        "top_results": [          {            "position": 1,            "title": "The 12 best trail running shoes we tested this year",            "url": "https://www.trailpace.example/shoes/1",            "domain": "trailpace.example",            "description": "A sample description of the page, a sentence or two long, as it would show on the results page.",            "is_target": false          },          {            "position": 2,            "title": "Best trail running shoes: our editors' picks",            "url": "https://www.runwell-review.example/shoes/2",            "domain": "runwell-review.example",            "description": "A sample description of the page, a sentence or two long, as it would show on the results page.",            "is_target": false          },          {            "position": 3,            "title": "Trail running shoes buyer's guide",            "url": "https://www.milemarker.example/shoes/3",            "domain": "milemarker.example",            "description": "A sample description of the page, a sentence or two long, as it would show on the results page.",            "is_target": false          }        ],        "serp_features": [          {            "type": "people_also_ask",            "label": "People also ask",            "owned": false          },          {            "type": "ai_overview",            "label": "AI overview",            "owned": false          },          {            "type": "related_searches",            "label": "Related searches",            "owned": false          }        ],        "checked_at": "2026-10-22T18:04:11.000Z",        "google_url": "https://www.google.com/search?q=best%20trail%20running%20shoes&hl=en&gl=US"      }    }  }}

Check a website's traffic

POST/api/v1/website-traffic-checker3 credits per lookup

Figures are monthly estimates for the latest full month. A fresh read takes 5 to 15 seconds; repeats inside the 7-day cache window are instant.

Returns a lookup object whose classification carries the latest month's visits, the change over three months, the ranks and the bounce rate, with traffic sources, top countries and search keywords under insights.

Billing. Success-based: 0 credits when no traffic data exists for the site.

Parameters

domainstringRequired

The website to check. A bare domain, a www address or a full page link all resolve to the same site.

curl -X POST https://app.1lookup.io/api/v1/website-traffic-checker \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "domain": "example.com"  }'
POST https://app.1lookup.io/api/v1/website-traffic-checker
Response
{  "success": true,  "data": {    "request": { "type": "website_traffic_checker", "processing_time_ms": 9200 },    "metadata": { "credits_used": 3, "credits_remaining": 9497, "cache_hit": false },    "classification": {      "matched": true,      "domain": "example.com",      "monthly_visits": 1840000,      "month": "2026-09",      "visits_change_pct": 6.4,      "trend": "up",      "global_rank": 18250,      "country_name": "United States",      "country_rank": 5120,      "bounce_rate_pct": 47.3,      "top_traffic_source": "Direct",      "top_traffic_source_share_pct": 52.1    },    "insights": {      "website_traffic_result": {        "domain": "example.com",        "history": [          { "month": "2026-07", "visits": 1690000 },          { "month": "2026-08", "visits": 1730000 },          { "month": "2026-09", "visits": 1840000 }        ],        "traffic_sources": [          { "source": "Direct", "share_pct": 52.1 },          { "source": "Search", "share_pct": 31.4 },          { "source": "Social", "share_pct": 8.2 }        ],        "top_countries": [          { "code": "US", "name": "United States", "share_pct": 41.6 },          { "code": "GB", "name": "United Kingdom", "share_pct": 9.3 }        ]      }    }  }}

Company & B2B

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

DOT number lookup

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

Read from FMCSA's own carrier census and licensing data, both refreshed daily. Risk flags restate FMCSA facts a broker checks before tendering a load: inactive USDOT, no active authority, liability insurance below the FMCSA minimum, a missing broker bond, Unsatisfactory or Conditional rating, prior revocation, a carrier under 180 days old, an MCS-150 more than 2 years old.

Returns a lookup object whose classification carries the carrier's status, authority, safety rating and risk level, with fleet, cargo, contact details and risk flags under insights.

Billing. Numbers that are not in the census are not charged.

Parameters

dot_numberstringOptional

The carrier's USDOT number, e.g. "80806". Send this or mc_number.

mc_numberstringOptional

An MC, MX or FF docket number, e.g. "MC-135797". A bare number is read as MC.

curl -X POST https://app.1lookup.io/api/v1/dot-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "dot_number": "80806"  }'
POST https://app.1lookup.io/api/v1/dot-lookup
Response
{  "success": true,  "data": {    "classification": {      "legal_name": "J B HUNT TRANSPORT INC",      "usdot_status": "Active",      "mc_number": "MC-135797",      "has_active_authority": true,      "insurance_on_file": true,      "risk_level": "LOW"    },    "metadata": { "credits_used": 10 }  }}

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, a name plus company domain, or the person_id of a Prospect Search row.

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.

person_idstringOptional

The person_id of a Prospect Search row. Reveals that row's full contact details.

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 }  }}

LinkedIn company lookup

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

Public, logged-out company page data only. Send a page URL or its slug for an exact read, or a company name for the best match (flagged match_type: "name_search"). A fresh read takes 2 to 5 seconds; repeat lookups inside the 7-day cache window return instantly.

Returns a lookup object whose classification carries the headline facts (name, website, industry, headcount, size band, headquarters, founded year, followers), with the tagline, description, every location, specialties, logo and similar companies under insights.

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

Parameters

company_urlstringOptional

A LinkedIn company page URL (https://www.linkedin.com/company/…) or its slug. Required unless company_name is sent; wins when both are sent.

company_namestringOptional

A company name, 2 to 120 characters. Returns the closest public page, reported as a name search.

curl -X POST https://app.1lookup.io/api/v1/linkedin-company-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "company_url": "https://www.linkedin.com/company/acme-analytics"  }'
POST https://app.1lookup.io/api/v1/linkedin-company-lookup
Response
{  "success": true,  "data": {    "classification": {      "matched": true,      "name": "Acme Analytics",      "website": "https://www.acme-analytics.example/",      "industry": "Software Development",      "employee_range": "51-200",      "headquarters": "San Francisco, CA, United States"    },    "metadata": { "credits_used": 10 }  }}

Check an EU VAT number

POST/api/v1/eu-vat-check2 credits per lookup

Checked against the EU's official VAT registry, which asks the tax authority of the member state that issued the number. Some countries share the registered name and address and some share only a yes or no; a field that is not shared comes back null. Send the number with its two-letter country prefix, or send the national part with country_code. Greece is EL (GR is accepted), Northern Ireland is XI, and Great Britain left the EU VAT system and cannot be checked. A number of the wrong shape for its country is refused before the check and costs nothing.

Returns a lookup object whose classification says whether the number is valid and carries the registered name and address where the member state shares them.

Billing. Success-based: 0 credits when the number is not valid, when it is malformed, and when the registry or the member state's service cannot be reached (503 with a Retry-After).

Parameters

vat_numberstringRequired

The VAT number with its country prefix, e.g. "IE1234567T". Spaces, dots and dashes are ignored.

country_codestringOptional

A two-letter prefix, e.g. "DE", when vat_number holds only the national part.

A number the registry does not list returns classification.found: false and valid: false with 0 credits, which is an answer, not an error.
If one country's tax service is down the call returns 503 with a Retry-After header and costs nothing. The other countries keep working.
curl -X POST https://app.1lookup.io/api/v1/eu-vat-check \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "vat_number": "IE1234567T"  }'
POST https://app.1lookup.io/api/v1/eu-vat-check
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "valid": true,      "vat_number": "IE1234567T",      "name": "EXAMPLE TRADING LIMITED"    },    "metadata": { "credits_used": 2 }  }}

Look up an LEI

POST/api/v1/lei-lookup2 credits per lookup

Read from the global LEI index, the public register of legal entities that take part in financial markets, so the record is the registry's own. The LEI's two check digits are tested before the lookup, so a mistyped code is refused and costs nothing. You can also search by legal name; a search returns up to ten entities whose registered name contains every word, and no single record.

Returns a lookup object whose classification carries the entity's legal name, status, jurisdiction, addresses, dates and parents, with the full record under insights.

Billing. Success-based: 0 credits when the registry has no record, when the LEI is mistyped, when a search finds nothing, and when the registry cannot be reached.

Parameters

leistringRequired

The 20-character LEI, e.g. "5299000SAMPLE000XX85". Not needed when you search by name.

legal_namestringOptional

Search by legal name instead of an LEI. Every word must appear in the registered name.

countrystringOptional

A 2-letter country code that narrows a name search, e.g. "US".

A search by legal_name returns classification.search: true and up to ten rows under insights.lei_lookup_matches. insights.lei_lookup_result is null: look a match up by its lei for the full record.
parent_lei and ultimate_parent_lei are set only when the entity reported a parent. The full relationship status, including an entity that reported having none, is under insights.lei_lookup_result.relationships.
curl -X POST https://app.1lookup.io/api/v1/lei-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "lei": "5299000SAMPLE000XX85"  }'
POST https://app.1lookup.io/api/v1/lei-lookup
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "lei": "5299000SAMPLE000XX85",      "legal_name": "Example Holdings Inc.",      "entity_status": "ACTIVE",      "jurisdiction": "US-DE"    },    "metadata": { "credits_used": 2 }  }}

Look up a bank

POST/api/v1/bank-lookup2 credits per lookup

Read from the FDIC's public bank directory, which lists every FDIC-insured bank and savings institution, open or closed. Send cert (an FDIC certificate number, 1 to 6 digits) for an exact record, or name for a search; a name search returns the best match in full and lists the next few under insights.bank_lookup_result.other_matches. Add a two-letter state to narrow a common name. Credit unions are not in this directory. Money figures are in US dollars as of the institution's last quarterly report.

Returns a lookup object whose classification carries the institution's status, charter, regulator, address, branch count and total assets, with the full record under insights.

Billing. Success-based: 0 credits when no institution matches, when the certificate number is unknown, and when the directory cannot be reached (503 with a Retry-After).

Parameters

namestringOptional

The bank name, e.g. "Wells Fargo Bank". Every word must appear in the institution's name. Not needed when you send cert.

certstringOptional

The FDIC certificate number, e.g. "3511". Wins over name when both are sent.

statestringOptional

A two-letter state code that narrows a name search, e.g. "NC".

An institution the directory does not list returns classification.found: false with 0 credits, which is an answer, not an error.
A closed bank is still returned with active: false and end_date set, and is billed, because the record exists.
other_matches is filled only by a name search. Look a match up by its fdic_cert for its full record.
curl -X POST https://app.1lookup.io/api/v1/bank-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "Sample Community Bank",    "state": "NC"  }'
POST https://app.1lookup.io/api/v1/bank-lookup
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "fdic_cert": 99001,      "name": "Sample Community Bank",      "active": true,      "state": "NC",      "total_assets_usd": 412000000    },    "metadata": { "credits_used": 2 }  }}

Get a public company's financials

POST/api/v1/sec-company-facts2 credits per lookup

Read from the SEC's public filing database, the same annual and quarterly reports a company files with the US government. Send ticker (for example AAPL), company (a name) or cik (the SEC's company number, 1 to 10 digits). A ticker matches exactly; a name must contain every word and returns the best match in full, with the next few listed under insights.sec_company_facts_result.other_matches. Companies tag the same figure in different ways over the years, so each figure is read from the tag the company used most recently. Money is in the currency the company reports in (classification.currency, almost always USD).

Returns a lookup object whose classification carries the latest fiscal year's headline figures, with the balance sheet, cash flow, share count, latest quarter and five-year history under insights.

Billing. Success-based: 0 credits when no company matches, when the company has filed no annual statements, and when the SEC cannot be reached (503 with a Retry-After).

Parameters

tickerstringOptional

The stock ticker, e.g. "AAPL". A share class is written with a dash or a dot, e.g. "BRK-B". Not needed when you send company or cik.

companystringOptional

A company name, e.g. "Apple". Every word must appear in the registered name.

cikstringOptional

The SEC CIK number, e.g. "320193". Wins over ticker and company when more than one is sent.

A company the SEC holds nothing for returns classification.found: false with 0 credits and a reason of not_listed or no_annual_statements, which is an answer, not an error. Private companies do not file with the SEC.
A figure the company did not report is null, not 0. Banks, insurers and funds often leave out gross profit and operating income.
shares_outstanding is the cover-page count of the latest report and is null when the company has not kept it current. A company with several share classes may carry one class's count.
Figures are as filed. A company that restates a past year changes that year in its history.
curl -X POST https://app.1lookup.io/api/v1/sec-company-facts \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "ticker": "SMPL"  }'
POST https://app.1lookup.io/api/v1/sec-company-facts
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "name": "Sample Industries Inc.",      "ticker": "SMPL",      "fiscal_year": 2025,      "revenue": 4820000000,      "net_income": 515000000    },    "metadata": { "credits_used": 2 }  }}

List a public company's 8-K events

POST/api/v1/sec-8k-events2 credits per lookup

Read from the SEC's public filing database, the 8-K current reports a company files within days of a material event: an executive leaving, a big contract, an acquisition, layoffs, an auditor change, a restatement, a bankruptcy. Send ticker (for example AAPL), company (a name) or cik (the SEC's company number, 1 to 10 digits), and optionally days (30 to 730, 365 by default). A ticker or CIK answers for one company. A name must contain every word; when it fits several companies you get the candidates back, uncharged, and send the ticker or CIK of the one you mean. Each event is labelled in plain English (headline), grouped into one of eight categories, and marked high_signal for the ones that usually matter (leadership changes, deals, distress, auditor changes, restatements) or low_signal for exhibits-only and press-release filings. events holds the newest 25; summary counts all of them.

Returns a lookup object whose classification carries the counts (8-Ks filed, high-signal, routine), the categories and the newest event, with every filing as an item under insights.sec_8k_events_result.events, each linked to the filing on the SEC's site.

Billing. Charged only when the company filed at least one 8-K or 8-K/A inside the window. 0 credits when it filed none, when no company matches, when a name fits several companies, and when the SEC cannot be reached (503 with a Retry-After).

Parameters

tickerstringOptional

The stock ticker, e.g. "AAPL". A share class is written with a dash or a dot, e.g. "BRK-B". Not needed when you send company or cik.

companystringOptional

A company name, e.g. "Apple". Every word must appear in the registered name.

cikstringOptional

The SEC CIK number, e.g. "320193". Wins over ticker and company when more than one is sent.

daysintegerOptional

How far back to look, from 30 to 730 days. Defaults to 365.

A quiet company returns classification.outcome: "no_events" with 0 credits. A name the SEC does not list returns outcome: "not_found" with 0 credits. A name that fits several companies returns outcome: "several_matches" with classification.candidates and 0 credits. All three are answers, not errors.
Every 8-K/A (an amendment) counts as a filing, and its headline starts with "Amendment:".
events is capped at 25, newest first, and truncated says when more exist. The summary and categories counts cover every filing in the window.
The SEC lists at least the last 12 months of filings for every company. When a very active filer's list does not reach back the whole window, window.complete is false and window.note says how far back it goes.
Private companies and most foreign companies do not file 8-Ks. Foreign filers file a 6-K instead, which this product does not read.
curl -X POST https://app.1lookup.io/api/v1/sec-8k-events \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "ticker": "SMPL"  }'
POST https://app.1lookup.io/api/v1/sec-8k-events
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "outcome": "events_found",      "name": "Sample Industries Inc.",      "ticker": "SMPL",      "total_filings": 7,      "high_signal_count": 4,      "latest_event": "Executive or director departure or appointment"    },    "metadata": { "credits_used": 2 }  }}

Screen a name against U.S. sanctions and export-control lists

POST/api/v1/sanctions-screening3 credits per lookup

Checks the name against the U.S. government's Consolidated Screening List: the Treasury's sanctions lists, the Commerce Department's export-control lists and the State Department's lists, 12 lists in all. Send name (a person, company or vessel, in Latin letters) and, optionally, country (two letters, for example RU). Word order, case, accents and legal forms such as Inc or LLC do not matter, and a spelling that is a letter or two off still matches a longer word. A strong match is the same name or a close spelling of all its words; a possible match shares most of its words. Each match names the list, the agency, the programs, the aliases, the addresses, the countries, any date of birth and the listing date, so a caller can confirm identity. A name alone is never proof, so a strong match is REVIEW, never an approval.

Returns a lookup object whose classification carries the outcome (clear, possible_match or match), the match counts and the closest match, with every match under insights.sanctions_screening_result.matches.

Billing. Charged for every completed screening, including one that finds no match, because the answer "clear" is what the credits buy. 0 credits when the lists cannot be read (503 with a Retry-After) and for a repeat of the same screening within 24 hours.

Parameters

namestringOptional

The name of a person, company or vessel, 2 to 150 characters, in Latin letters, e.g. "Acme Trading Co". The aliases query, company, person, entity and full_name are also read.

countrystringOptional

Optional two-letter country code, e.g. "RU". It does not exclude any match; each match is marked country_match true or false so you can rank them.

outcome: "clear" means no record on the 12 lists matched. It is a billed answer, and records_checked and list_updated say what was checked and when.
At most 10 matches are returned, strongest first. hit_count is the total, so a common name can report more matches than are shown.
Names must be in Latin letters, as the U.S. lists spell them. A name in another script is refused with a 400 before any credit is reserved.
The lists are republished daily. If they cannot be refreshed, a copy up to 48 hours old is used and list_is_stale is true; beyond that the call returns a 503 and charges nothing.
curl -X POST https://app.1lookup.io/api/v1/sanctions-screening \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "Sample Trading Company",    "country": "XX"  }'
POST https://app.1lookup.io/api/v1/sanctions-screening
Response
{  "success": true,  "data": {    "classification": {      "screened": true,      "outcome": "possible_match",      "possible_match_count": 1,      "top_match_name": "SAMPLE TRADING CO",      "top_match_list": "EL (Entity List)"    },    "metadata": { "credits_used": 3 }  }}

Check a provider against the federal exclusion list

POST/api/v1/oig-exclusion-check3 credits per lookup

Checks the HHS Office of Inspector General's public List of Excluded Individuals and Entities (the LEIE). Medicare, Medicaid and the other federal health care programs do not pay for anything an excluded person or business furnishes, orders or prescribes, so healthcare employers, staffing agencies and payers screen against it. Send npi (10 digits, the check digit is verified), or provider (a first and last name, or a business name), with an optional state. Send npi and provider together to check both. An NPI that is on the list is excluded. A name that matches is needs_review, never excluded, because a name alone is not proof of identity: each listing carries the NPI, the birth year, the specialty and the location the OIG recorded, so a caller can confirm who it is. Word order, case, accents and a middle name or initial do not matter. Weaker look-alikes are listed under other_candidates and are not counted as matches.

Returns a lookup object whose classification carries the outcome (clear, needs_review, excluded or reinstated), the match count and the closest listing, with every listing under insights.oig_exclusion_result.matches and the list's publication date in list_updated.

Billing. Charged for every completed check, including one that finds nothing, because the answer "clear" is what the credits buy. 0 credits when the input is refused (400), when the list cannot be read (503 with a Retry-After), and for a repeat of the same question by the same account within 24 hours.

Parameters

npistringOptional

A 10-digit National Provider Identifier, e.g. "1999000015". The check digit is verified before anything is read. Only about 1 in 10 listings carries an NPI, so an NPI that is not listed does not rule a provider out: also send the name.

providerstringOptional

A person's first and last name, e.g. "Jane Q Example", or a business name, e.g. "Example Supply Co". At least two words of two letters for a person; 2 to 120 characters. The aliases name and query are also read.

businessstringOptional

A business name, e.g. "Testville". The only field that accepts a single word, and it matches business listings only.

statestringOptional

Optional two-letter state, e.g. "IL". It never removes a match; a listing in another state is kept and marked state_match: false so you can rank it.

outcome: "clear" means nothing on the list matched. It is a billed answer, and list_updated says which publication of the list was checked. A clear NPI-only check returns primary_action: "VERIFY", not an approval, because most listings carry no NPI: also check by name.
needs_review is a name match. Confirm with the NPI or the birth year in the listing before acting; matches holds up to 10 listings, strongest first, and total_matches is the full count.
other_candidates holds up to 5 weaker look-alikes (a similar name that is not a full match). They are not counted in match_count; similar_count says how many exist.
The OIG removes a provider from the file when it reinstates them, so reinstated is rare. A waiver date and state, when the OIG granted one, are shown on the listing.
The file is republished monthly. If it cannot be refreshed, a copy up to 10 days old is used and list_stale is true; beyond that the call returns a 503 and charges nothing.
This checks the OIG list only. State Medicaid exclusion lists and the federal System for Award Management exclusions are separate.
curl -X POST https://app.1lookup.io/api/v1/oig-exclusion-check \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "npi": "1999000015"  }'
POST https://app.1lookup.io/api/v1/oig-exclusion-check
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "outcome": "excluded",      "name": "Jane Quinn Exampleton",      "npi": "1999000015",      "exclusion_type_text": "License revoked, suspended or surrendered",      "excluded_on": "2024-01-15",      "list_updated": "2026-10-09"    },    "metadata": { "credits_used": 3 }  }}

Check whether a company has raised private money

POST/api/v1/funding-trigger2 credits per lookup

Read from the SEC's public filing database. A company that sells securities in a private raise files a Form D within 15 days of the first sale, and it is public the day it is filed. Send company (a name as the company registered it, for example Space Exploration Technologies) or cik (the SEC's company number, 1 to 10 digits). The SEC matches a name from its start, so funds named after a company can match too: the best match is returned in full, with the next few listed under insights.funding_trigger_result.other_matches. Send the CIK to ask about one exact filer.

Returns a lookup object whose classification carries the newest Form D's date, amounts and investor count, with the full filing, the people named in it and the company's filing history under insights.

Billing. Success-based: 0 credits when no company matches, when the company has filed no Form D, and when the SEC cannot be reached (503 with a Retry-After).

Parameters

companystringOptional

A company name as it is registered with the SEC, e.g. "Space Exploration Technologies". Matched from the start of the name. Not needed when you send cik.

cikstringOptional

The SEC CIK number, e.g. "1181412". Wins over company when both are sent, and is the way to name one exact filer.

A company with no Form D returns classification.found: false with 0 credits and a reason of no_company or no_form_d, which is an answer, not an error. Not every raise is filed: some are exempt from the notice, and a few are filed late.
recent_raise is true when the newest Form D was filed within the last 90 days. days_since_latest_filing counts from the day the lookup ran.
Amounts are the newest Form D's. A figure the filing leaves out is null, not 0. An open-ended offering has offering_indefinite: true and a null offering amount.
Investment funds also file Form D. pooled_investment_fund is true when the filing is a fund interest, so a fund is not mistaken for an operating company.
Only the newest three Form D documents are opened for their detail; form_d_count counts every Form D the SEC lists for the company.
curl -X POST https://app.1lookup.io/api/v1/funding-trigger \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "company": "Sample Rocketry"  }'
POST https://app.1lookup.io/api/v1/funding-trigger
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "name": "Sample Rocketry Inc.",      "latest_filing_date": "2026-09-02",      "recent_raise": true,      "amount_sold_usd": 12500000,      "investors_count": 14    },    "metadata": { "credits_used": 2 }  }}

Check the consumer complaints filed against a company

POST/api/v1/complaint-check2 credits per lookup

Read from the CFPB's public consumer complaint database, which publishes a complaint once the company has responded or after 15 days, and refreshes daily. Send company (a name, for example Wells Fargo). The name is matched against the CFPB's own company list: the best match is returned in full, with the next few listed under insights.complaint_check_result.other_matches so a caller can tell similar names apart. Only counts are returned, never an individual complaint, a consumer's narrative or a consumer's location.

Returns a lookup object whose classification carries the headline counts and rates, with the response, product, issue and channel breakdowns under insights.

Billing. Success-based: 0 credits when the database holds no complaints for the name, and when the CFPB cannot be reached (503 with a Retry-After).

Parameters

companystringOptional

A company name, e.g. "Wells Fargo". Letter case and legal forms such as Inc and LLC do not matter. 2 to 100 characters.

A name the database holds no complaints for returns classification.found: false with 0 credits, which is an answer, not an error. It cannot tell a company with no complaints from one that is not covered: the database lists only companies that have at least one published complaint.
timely_response_pct is the share of responses the company sent on time. relief_pct is the share of complaints the company has finished with that ended in monetary or non-monetary relief, so complaints still in progress are left out of the base.
change_pct compares the last 365 days with the 365 before them and is null when nothing was filed in the earlier year. The newest weeks are always short, because a complaint appears only after the company responds or 15 days pass.
A complaint is a consumer's account, passed to the company by the CFPB, and the CFPB does not verify it. Larger companies receive more, so compare a company with its peers.
Matching is by the CFPB's own company names. A parent and its subsidiaries are often listed separately, so check other_matches and look up the exact name you want.
curl -X POST https://app.1lookup.io/api/v1/complaint-check \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "company": "Sample Lending"  }'
POST https://app.1lookup.io/api/v1/complaint-check
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "name": "SAMPLE LENDING CO.",      "total_complaints": 12840,      "complaints_last_12_months": 1960,      "change_pct": 24.1    },    "metadata": { "credits_used": 2 }  }}

Check a company's environmental compliance record

POST/api/v1/epa-compliance-check3 credits per lookup

Read from the EPA's public compliance database (ECHO), which covers the facilities regulated under the Clean Air Act, the Clean Water Act, the hazardous waste rules and the drinking water rules. Send company (a company or facility name, for example Dow Chemical) and, optionally, state (two letters). The EPA's own name search is loose, so every facility it returns is checked and only the active facilities whose own name has every word you sent are counted; the response says how many the EPA returned (total_matches_in_epa) and how many carried the name (matched_facilities). Compliance is counted over the last 12 quarters (3 years); inspections, notices of violation, formal enforcement actions and penalties over the last 5 years. Facilities are matched by their own name, not by who owns them, so confirm they are the sites you mean. APPROVE says the EPA's records show no violations, enforcement or penalties for the facilities matched. It never says that no violation exists.

Returns a lookup object whose classification carries the totals across the matched facilities and a REVIEW, VERIFY or APPROVE assessment, with the ten riskiest facilities under insights.epa_compliance_result.facilities, each linked to its full record on the EPA's site.

Billing. Charged only when at least one active facility's own name carries the words you sent. 0 credits when the EPA returns facilities but none carries the name (outcome: "no_name_match"), when it has no active facility for the name (outcome: "not_found"), and when the EPA cannot be reached (503 with a Retry-After). A repeat of the same lookup by the same account inside the 7-day cache window is not charged again.

Parameters

companystringOptional

A company or facility name, e.g. "Dow Chemical", 3 to 120 characters. Letter case and legal forms such as Inc and LLC do not matter. A state may also be written after a comma, e.g. "Dow Chemical, TX". The aliases facility, name and business are also read.

statestringOptional

Optional two-letter US state or territory code, e.g. "TX". Narrows the search to facilities in that state.

classification.outcome is matched (charged), no_name_match (the EPA returned facilities but none carries the name; 0 credits) or not_found (no active facility at all; 0 credits). The last two are answers, not errors, and carry found: false and a plain reason.
Every total counts only the matched facilities, never the EPA's own summary counts. insights.epa_compliance_result.facilities lists the ten riskiest (significant non-compliance first, then penalties, formal actions and quarters in violation), so a company with more sites reports matched_facilities above facilities_listed.
assessment is REVIEW when a matched facility is in significant non-compliance or has formal enforcement or penalties, VERIFY when there are violations or notices of violation on record, and APPROVE when none of those appear. It describes what the EPA's records show for the facilities matched.
A very common name can match thousands of facilities. Up to 3,000 are read; when the EPA returned more, truncated is true, the totals are partial, and a clean result is VERIFY instead of APPROVE. Add a state to narrow the search.
Only active facilities are searched, and only the EPA's compliance database: other agencies' records, such as OSHA, are not included.
curl -X POST https://app.1lookup.io/api/v1/epa-compliance-check \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "company": "Sample Chemical",    "state": "TX"  }'
POST https://app.1lookup.io/api/v1/epa-compliance-check
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "outcome": "matched",      "matched_facilities": 2,      "facilities_in_snc": 1,      "formal_actions_5yr": 4,      "penalties_usd_5yr": 2204913,      "assessment": "REVIEW"    },    "metadata": { "credits_used": 3 }  }}

Look up a company's federal contracts

POST/api/v1/federal-contractor-lookup3 credits per lookup

Read from the federal government's public spending database, the record of every contract the US government awards. Send company (a name) or uei (the 12-character Unique Entity ID that every federal contractor is registered under). A UEI always finds one company. A name is matched after case, accents and legal forms such as Inc or Corporation are ignored; when the name fits one company clearly the lookup returns it, and when several fit (a partial name, or look-alike registrations) it returns up to five candidates with their UEIs and states so you can run the lookup again with the right UEI. The dollars cover contract awards (not grants or loans) for the last three completed federal fiscal years (October 1 to September 30), summed across all agencies. A large company is registered many times; the lookup returns the parent record, which includes its subsidiaries.

Returns a lookup object whose classification carries the company's identity, its contract dollars and award count for the last three federal fiscal years and its largest agency. The full agency and industry breakdown sits under insights.federal_contractor_result.

Billing. Success-based: charged only when one company is clearly identified. 0 credits when several companies fit the name (classification.outcome is ambiguous), when no company matches, and when the spending database cannot be reached (503 with a Retry-After). A repeat of the same lookup by the same account inside the 1-day cache window is not charged again.

Parameters

companystringOptional

A company name, e.g. "Lockheed Martin". Legal forms and case do not matter. Not needed when you send uei.

ueistringOptional

The 12-character Unique Entity ID, e.g. "ZFN2JJXBLZT3". Wins over company when both are sent.

When several companies fit a name, classification.outcome is ambiguous with 0 credits, and classification.candidates and insights.federal_contractor_result.candidates list up to five, each with its UEI, level, state and last-12-month dollars. Run the lookup again with the uei of the one you mean.
A name that no recipient carries returns classification.found: false with outcome: "not_found" and 0 credits, which is an answer, not an error. A company with no federal contracts is not in the database at all.
total_obligated_usd is contract dollars only, summed over the window in classification.window. all_awards_all_time_usd counts every kind of award (contracts, grants, loans) over all years, so it is larger. A company that is a recipient but holds no contract dollars in the window returns a total of 0 and 0 credits.
contract_count is the number of contract awards with activity in the window. A figure is null when that part of the database could not be read; insights.federal_contractor_result.breakdown_note then says which.
Dollars are obligations (the amount the government committed), not payments or revenue, and a de-obligation can lower a total. A record with no UEI on file has no agency or industry breakdown.
curl -X POST https://app.1lookup.io/api/v1/federal-contractor-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "company": "Example Defense Systems"  }'
POST https://app.1lookup.io/api/v1/federal-contractor-lookup
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "outcome": "found",      "name": "EXAMPLE DEFENSE SYSTEMS INC",      "uei": "EXMPL0000001",      "window": "FY2024 to FY2026",      "total_obligated_usd": 48250000,      "contract_count": 37,      "top_agency": "Department of Defense"    },    "metadata": { "credits_used": 3 }  }}

Verify a nonprofit by EIN

POST/api/v1/nonprofit-verify2 credits per lookup

Read from the IRS's own files: the master list of tax-exempt organizations, which the IRS updates monthly, and its annual extract of the returns nonprofits file (Forms 990, 990-EZ and 990-PF). We load both into our own database and refresh them whenever the IRS posts a new file. Revenue, expenses, assets and liabilities come from the newest return in the IRS's latest annual extract, which runs one to two years behind, and latest_filing_year says which year that is. The IRS's own rounded summary of its newest return is kept separately under insights, because it can name a later year. record_updated is the date of the IRS master list the answer came from. Names and addresses are shown as the IRS writes them, in capital letters. The EIN is checked for nine digits and an IRS-issued prefix before the lookup, so a mistyped number is refused and costs nothing.

Returns a lookup object whose classification carries the organization's name, location, tax-exempt status, category, ruling year and the latest filing's figures, with the full record under insights.

Billing. Success-based: 0 credits when the EIN is not in the records, when it is malformed, and when the records cannot be reached.

Parameters

einstringRequired

The 9-digit EIN, with or without the dash, e.g. "12-3456789".

An EIN that is not in the records returns classification.found: false with 0 credits, which is an answer, not an error. Most for-profit businesses are not listed.
An organization the IRS has dropped from its current list (its exemption was revoked, or it was removed) also returns found: false with 0 credits, with partial_record: true and the name and newest_filing_year we still hold. We keep the row and flag it; nothing is deleted.
newest_filing_year_on_record can be later than latest_filing_year: a return is on file but its figures are not in the IRS's annual extract yet.
ruling_date is the month the IRS recognised the exemption (YYYY-MM); the IRS publishes no day.
Until the first complete load of the IRS files has finished, the endpoint answers 503 with a Retry-After header and charges nothing, so an empty table is never read as a miss.
curl -X POST https://app.1lookup.io/api/v1/nonprofit-verify \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "ein": "12-3456789"  }'
POST https://app.1lookup.io/api/v1/nonprofit-verify
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "ein": "123456789",      "name": "EXAMPLE COMMUNITY PANTRY",      "tax_exempt_status": "501(c)(3)",      "latest_filing_year": 2023,      "latest_filing_revenue": 1842300    },    "metadata": { "credits_used": 2 }  }}

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      }    }  }}

Search X posts

POST/api/v1/x-post-search15 credits per lookup

Any keyword, phrase or X search query, newest or most popular first.

Returns a lookup object whose insights.x_post_search_result.posts hold the matching posts, each with its text, author, followers, likes, reposts, replies, quotes, views and link.

Billing. Success-based: 0 credits when no posts match.

Parameters

querystringRequired

A keyword, a phrase, or an X search query such as from:handle lang:en. Up to 200 characters.

sortstringOptional

latest (the default) or top.

Every request returns at most 20 posts, whatever you send. The result size is fixed.
A request with no posts returns classification.matched: false and costs 0 credits.
Results are cached for 15 minutes per organization, and a cached repeat is free.
curl -X POST https://app.1lookup.io/api/v1/x-post-search \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "query": "ai agents",    "sort": "latest"  }'
POST https://app.1lookup.io/api/v1/x-post-search
Response
{  "success": true,  "data": {    "request": { "type": "x_post_search", "processing_time_ms": 14200 },    "metadata": { "credits_used": 15, "credits_remaining": 9545, "cache_hit": false },    "classification": {      "matched": true,      "result_count": 20,      "query": "ai agents",      "sort": "latest",      "newest_post_at": "2026-10-20T11:42:08.000Z",      "oldest_post_at": "2026-10-20T10:58:31.000Z",      "top_post_author": "demo_maker_one",      "top_post_likes": 212,      "top_post_url": "https://x.com/demo_maker_one/status/1900000000000000101",      "post_authors": ["demo_maker_one", "sample_writer"]    },    "insights": {      "x_post_search_result": {        "query": "ai agents",        "sort": "latest",        "result_count": 20,        "posts": [          {            "id": "1900000000000000101",            "url": "https://x.com/demo_maker_one/status/1900000000000000101",            "text": "Sample post about shipping a small feature on a Friday.",            "posted_at": "2026-10-20T11:42:08.000Z",            "language": "en",            "likes": 212,            "reposts": 31,            "replies": 9,            "quotes": 1,            "bookmarks": 6,            "views": 18400,            "is_reply": false,            "is_repost": false,            "is_quote": false,            "is_pinned": false,            "in_reply_to": null,            "author": {              "handle": "demo_maker_one",              "name": "Demo Maker One",              "url": "https://x.com/demo_maker_one",              "followers": 12840,              "following": 410,              "verified": true,              "bio": "Builds small tools for imaginary teams.",              "location": "Springfield"            }          }        ]      }    }  }}

Get an X account's latest posts

POST/api/v1/x-profile-posts15 credits per lookup

Any public X account, by handle or profile link. Reposts are included and marked.

Returns a lookup object whose insights.x_profile_posts_result.posts hold the account's latest posts, and whose classification carries the account's followers and bio.

Billing. Success-based: 0 credits when the account returns no posts.

Parameters

handlestringRequired

The account's handle with or without the @, or its profile link such as x.com/example_handle.

Every request returns at most 20 posts, whatever you send. The result size is fixed.
A request with no posts returns classification.matched: false and costs 0 credits.
A pinned post comes first and can be older than the rest; it is marked is_pinned.
Results are cached for 15 minutes per organization, and a cached repeat is free.
curl -X POST https://app.1lookup.io/api/v1/x-profile-posts \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "handle": "example_handle"  }'
POST https://app.1lookup.io/api/v1/x-profile-posts
Response
{  "success": true,  "data": {    "request": { "type": "x_profile_posts", "processing_time_ms": 12900 },    "metadata": { "credits_used": 15, "credits_remaining": 9530, "cache_hit": false },    "classification": {      "matched": true,      "result_count": 20,      "handle": "example_handle",      "account_handle": "example_handle",      "account_name": "Demo Maker One",      "account_followers": 12840,      "account_bio": "Builds small tools for imaginary teams.",      "account_verified": true,      "newest_post_at": "2026-10-20T11:42:08.000Z",      "oldest_post_at": "2026-10-14T09:15:40.000Z",      "top_post_likes": 212,      "top_post_url": "https://x.com/example_handle/status/1900000000000000101"    },    "insights": {      "x_profile_posts_result": {        "handle": "example_handle",        "result_count": 20,        "posts": [          {            "id": "1900000000000000101",            "url": "https://x.com/example_handle/status/1900000000000000101",            "text": "Sample post about shipping a small feature on a Friday.",            "posted_at": "2026-10-20T11:42:08.000Z",            "language": "en",            "likes": 212,            "reposts": 31,            "replies": 9,            "quotes": 1,            "bookmarks": 6,            "views": 18400,            "is_reply": false,            "is_repost": false,            "is_quote": false,            "is_pinned": false,            "in_reply_to": null,            "author": {              "handle": "example_handle",              "name": "Demo Maker One",              "url": "https://x.com/example_handle",              "followers": 12840,              "following": 410,              "verified": true,              "bio": "Builds small tools for imaginary teams.",              "location": "Springfield"            }          }        ]      }    }  }}

Get the replies to an X post

POST/api/v1/x-post-replies15 credits per lookup

Pass the link to the original post. Replies to replies in the same thread are included and marked with in_reply_to.

Returns a lookup object whose insights.x_post_replies_result.posts hold the replies, each with the replier's handle, name, followers and bio.

Billing. Success-based: 0 credits when the post has no replies.

Parameters

post_urlstringRequired

The link to the post, such as https://x.com/example_handle/status/1900000000000000001. A link to a reply returns nothing.

Every request returns at most 20 posts, whatever you send. The result size is fixed.
A request with no posts returns classification.matched: false and costs 0 credits.
Results are cached for 15 minutes per organization, and a cached repeat is free.
curl -X POST https://app.1lookup.io/api/v1/x-post-replies \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "post_url": "https://x.com/example_handle/status/1900000000000000001"  }'
POST https://app.1lookup.io/api/v1/x-post-replies
Response
{  "success": true,  "data": {    "request": { "type": "x_post_replies", "processing_time_ms": 11800 },    "metadata": { "credits_used": 15, "credits_remaining": 9515, "cache_hit": false },    "classification": {      "matched": true,      "result_count": 20,      "post_id": "1900000000000000001",      "unique_repliers": 17,      "biggest_replier": "sample_writer",      "biggest_replier_followers": 3120,      "biggest_replier_bio": "Writes sample posts for test fixtures.",      "newest_post_at": "2026-10-20T11:42:08.000Z"    },    "insights": {      "x_post_replies_result": {        "post_id": "1900000000000000001",        "result_count": 20,        "posts": [          {            "id": "1900000000000000102",            "url": "https://x.com/sample_writer/status/1900000000000000102",            "text": "An invented reply used only as a sample.",            "posted_at": "2026-10-20T11:42:08.000Z",            "language": "en",            "likes": 14,            "reposts": 1,            "replies": 0,            "quotes": 1,            "bookmarks": 6,            "views": 18400,            "is_reply": true,            "is_repost": false,            "is_quote": false,            "is_pinned": false,            "in_reply_to": "example_handle",            "author": {              "handle": "sample_writer",              "name": "Sample Writer",              "url": "https://x.com/sample_writer",              "followers": 3120,              "following": 410,              "verified": true,              "bio": "Builds small tools for imaginary teams.",              "location": "Springfield"            }          }        ]      }    }  }}

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 }  }}

List who engaged with a LinkedIn post

POST/api/v1/linkedin-post-engagers5 credits per lookup

Public posts only. One call returns one list: send engagement as reactions or comments, and call again for the other. A fresh pull takes 3 to 10 seconds; repeats inside the 7-day cache window are instant.

Returns a lookup object whose classification carries the count and the reaction mix, with each person (name, profile link, headline and the reaction or comment) under insights.

Billing. Success-based: 0 credits when nobody is found.

Parameters

post_urlstringRequired

The link to the LinkedIn post, from its three-dot menu (Copy link to post). A post id is accepted too.

engagementstringOptional

reactions or comments.

Defaults to reactions.

curl -X POST https://app.1lookup.io/api/v1/linkedin-post-engagers \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "post_url": "https://www.linkedin.com/posts/example-person_sample-post-activity-7300000000000000001-AbCd",    "engagement": "reactions"  }'
POST https://app.1lookup.io/api/v1/linkedin-post-engagers
Response
{  "success": true,  "data": {    "request": { "type": "linkedin_post_engagers", "processing_time_ms": 4100 },    "metadata": { "credits_used": 5, "credits_remaining": 9492, "cache_hit": false },    "classification": {      "matched": true,      "result_count": 100,      "engagement": "reactions",      "post": "urn:li:activity:7300000000000000001",      "with_job_title": 92,      "top_reaction": "Like"    },    "insights": {      "linkedin_post_engagers_result": {        "engagement": "reactions",        "result_count": 100,        "people": [          {            "name": "Sample Person One",            "profile_url": "https://www.linkedin.com/in/sample-person-one",            "job_title": "Head of Growth at Sample Co",            "reaction_type": "Like"          }        ]      }    }  }}

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.

phonestringOptional

The business's phone number. When sent, a listing with a different phone comes back as no match.

websitestringOptional

The business's website or domain. When sent, a listing with a different website comes back as no match.

addressstringOptional

The business's street address. When sent, a listing with a different street number or ZIP comes back as no match.

Only a listing whose name matches business_name is returned. When the closest listing is a different business, the response is a no-match at 0 credits, with classification.nearest_listing_name and classification.failed_checks saying what was found and why it was turned down.
A search reads the live listing, so it can take up to 4 minutes. Set your HTTP client's timeout to at least 300 seconds; a shorter one can give up before the answer arrives.
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…",      "match_checks": { "name": true, "phone": null, "website": null, "address": null }    },    "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      }    }  }}

Look up an NPI

POST/api/v1/npi-lookup2 credits per lookup

Read live from the CMS NPPES registry, the public list of every US healthcare provider number, so the record is the registry's own. The NPI's check digit is tested before the lookup, so a mistyped number is refused and costs nothing. You can also search by name; a search returns up to ten matches and no single record.

Returns a lookup object whose classification carries the provider's name, specialty, license and active status, with the full record (all taxonomies, addresses, identifiers and endpoints) under insights.

Billing. Success-based: 0 credits when the registry has no record, when the NPI is invalid, and when the registry cannot be reached.

Parameters

npistringRequired

The 10-digit NPI, e.g. "1234567893". Not needed when you search by name.

last_namestringOptional

Search for an individual by last name instead of an NPI. At least 2 characters.

first_namestringOptional

Narrows a last_name search to a first name.

organization_namestringOptional

Search for an organization by name instead of an NPI.

statestringOptional

A 2-letter state code that narrows a name search, e.g. "IL".

A search by last_name or organization_name returns classification.search: true and up to ten rows under insights.npi_lookup_matches. insights.npi_lookup_result is null: look a match up by its npi for the full record.
curl -X POST https://app.1lookup.io/api/v1/npi-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "npi": "1234567893"  }'
POST https://app.1lookup.io/api/v1/npi-lookup
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "npi": "1234567893",      "name": "Jane Q Example",      "status": "active",      "primary_specialty": "Hospitalist",      "license_number": "036123456",      "license_state": "IL"    },    "metadata": { "credits_used": 2 }  }}

Get the census tract for an address

POST/api/v1/census-tract-lookup2 credits per lookup

Read from the US Census Bureau's public address geocoder, which places the address on the Census Bureau's own map and names every boundary it sits inside. Send address as one line, or street, city, state and zip. The tract id joins to the Census Bureau's tables, such as the American Community Survey; this endpoint returns ids and names, not demographics. If the geocoder finds more than one possible match, the first is returned in full, the next few are listed under insights.census_tract_result.other_matches, and the verdict reads VERIFY.

Returns a lookup object whose classification carries the matched address, the 11-digit census tract id, the county, state, congressional district and metro area, with the full set of geography ids under insights.

Billing. Success-based: 0 credits when the Census Bureau cannot locate the address, and when its service cannot be reached (503 with a Retry-After).

Parameters

addressstringOptional

The full US street address on one line, e.g. "100 Main St, Springfield, IL 62701". It needs a street number and a street name. Not needed when you send street, city, state and zip.

streetstringOptional

The street line, e.g. "100 Main St". Send it with city, state and zip.

citystringOptional

The city or town.

statestringOptional

The two-letter state code, e.g. "IL".

zipstringOptional

The ZIP code, e.g. "62701". Send it as text so a leading zero is kept.

An address the Census Bureau cannot locate returns classification.found: false with insights.census_tract_result null and 0 credits. That is an answer, not an error: check the street suffix and the ZIP code.
IDs are strings, so leading zeros are kept (Alabama's state code is "01"). insights.census_tract_result.fips_codes carries the state, county and tract codes separately for joins.
benchmark and vintage say which address ranges and boundaries answered, so a result can be repeated later. Fields the address is not in, such as the metro area of a rural address, are null.
Where elementary and high schools have separate districts, insights.census_tract_result.school_districts lists both and school_district is the first.
curl -X POST https://app.1lookup.io/api/v1/census-tract-lookup \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "address": "100 Example St, Sampletown, IL 62999"  }'
POST https://app.1lookup.io/api/v1/census-tract-lookup
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "matched_address": "100 EXAMPLE ST, SAMPLETOWN, IL, 62999",      "tract_geoid": "17999990001",      "tract_name": "Census Tract 9900.01",      "county_name": "Sample County",      "state_abbreviation": "IL",      "congressional_district": "Congressional District 99",      "metro_area": "Sampletown, IL Metro Area"    },    "metadata": { "credits_used": 2 }  }}

Decode a VIN

POST/api/v1/vin-decoder2 credits per lookup

Read from the official US vehicle records, the public database that every manufacturer files its VINs with, so the record is the government's own. The VIN's length and characters are tested before the lookup, so a VIN that cannot exist is refused and costs nothing. A VIN whose check digit does not match is still decoded: the mismatch comes back as a warning, because many VINs built outside North America never used one.

Returns a lookup object whose classification carries the year, make, model, trim, body style, engine, drive type, transmission, plant and weight class, with the full record (engine and transmission detail, plant location and safety equipment) under insights.

Billing. Success-based: 0 credits when the records hold nothing for the VIN, when the VIN is not 17 valid characters, and when the records cannot be reached.

Parameters

vinstringRequired

The 17-character VIN, e.g. "1HGCM82633A004352". Spaces and dashes are ignored and lower case is accepted. A VIN never contains the letters I, O or Q.

A VIN the records hold nothing for returns classification.found: false with insights.vin_decoder_result null and costs 0 credits. When its check digit also fails, the message says a typo is the likely cause.
classification.warnings lists anything worth knowing before you rely on the record, such as a check digit that does not match or details the records leave out. Fields the records do not hold are null, never a placeholder string.
curl -X POST https://app.1lookup.io/api/v1/vin-decoder \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "vin": "1HGCM82633A004352"  }'
POST https://app.1lookup.io/api/v1/vin-decoder
Response
{  "success": true,  "data": {    "classification": {      "found": true,      "vin": "1HGCM82633A004352",      "vehicle": "2003 Honda Accord EX-V6",      "body_class": "Coupe",      "engine_cylinders": 6,      "engine_displacement_l": 3,      "drive_type": "FWD/Front-Wheel Drive",      "transmission": "Automatic, 5-speed",      "check_digit_valid": true    },    "metadata": { "credits_used": 2 }  }}

Export Google reviews

POST/api/v1/google-reviews-export2 credits per lookup

Send a place id, or a Google Maps link to one business. A fresh pull takes 5 to 12 seconds; repeats inside the 7-day cache window are instant.

Returns a lookup object whose classification carries the place, its overall rating and a summary of the reviews returned, with each review (rating, text, date, reviewer and owner reply) under insights.

Billing. Success-based: 0 credits when no reviews come back.

Parameters

placestringRequired

A Google place id (starts with ChIJ) or a Google Maps link to the place. A link to a search results page does not name one place and is refused.

sortstringOptional

newest, highest, lowest or relevant.

Defaults to newest.

curl -X POST https://app.1lookup.io/api/v1/google-reviews-export \  -H "Authorization: Bearer $ONELOOKUP_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "place": "ChIJ_sample_place_id_0000",    "sort": "newest"  }'
POST https://app.1lookup.io/api/v1/google-reviews-export
Response
{  "success": true,  "data": {    "request": { "type": "google_reviews_export", "processing_time_ms": 6800 },    "metadata": { "credits_used": 2, "credits_remaining": 9490, "cache_hit": false },    "classification": {      "matched": true,      "result_count": 100,      "place_name": "Harbor Light Sample Cafe",      "place_rating": 4.6,      "place_review_count": 1284,      "average_rating": 4.5,      "with_owner_reply": 38    },    "insights": {      "google_reviews_export_result": {        "sort": "newest",        "rating_counts": { "5": 71, "4": 14, "3": 6, "2": 3, "1": 6 },        "reviews": [          {            "rating": 5,            "text": "Great coffee and a calm room to work in.",            "date": "2026-10-14T09:12:00.000Z",            "reviewer": "Sample Reviewer",            "owner_reply": "Thank you, see you again soon."          }        ]      }    }  }}

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.

Bulk jobs also accept website_traffic_checker (one domain per row), linkedin_post_engagers (one post link per row, returning the people who reacted) and google_reviews_export (one place per row).
phone_validation takes one phone number per row at the normal Phone Number Validation price. Through the API it accepts US and Canada numbers only for now: if any row is a number from another country, the whole job is refused with 400 UNSUPPORTED_COUNTRY, the response names those rows in row_indexes, and nothing is charged. A row that is not a phone number is skipped and not charged.
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: phone_validation, hlr_lookup, mnp_lookup, nt_lookup, email_validation, reverse_email_append, domain_authority, domain_age, email_auth_check, dot_lookup, backlink_overview, keyword_metrics, company_firmographics, b2b_contact_append, business_verify, business_lookup, company_profile_lookup, linkedin_profile_lookup, linkedin_company_lookup, linkedin_email_finder, social_profile_check, property_lookup, npi_lookup, eu_vat_check, lei_lookup, bank_lookup, sec_company_facts, federal_contractor_lookup, sec_8k_events, funding_trigger, complaint_check, epa_compliance_check, ssl_certificate_check, brand_lookup, nonprofit_verify, sanctions_screening, oig_exclusion_check, dns_lookup, tech_stack_lookup, signup_check, reported_number_check, census_tract_lookup, vin_decoder, social_post_lookup, video_transcript, audience_demographics, link_in_bio_lookup, x_post_search, x_profile_posts, x_post_replies.
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  }}
Phone Number Validation (US and Canada numbers)
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": "phone_validation",    "inputs": ["+14155550123", "(212) 555-0147", "4165550198"]  }'

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/…?X-Amz-Signature=…",    "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. On a very large account the all-time and per-key totals come back null when they cannot be counted within a few seconds. Balances are always returned.

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 }    }  }}