The Scalelist API gives your code what the app gives a rep: the right people, their verified work email and their mobile number. It is a REST API at api.scalelist.com with one auth header, and you pay only when a result is found: 1 credit per email, 20 per mobile, nothing on a miss.
This page is the developer hub for the Scalelist B2B contact data API: every endpoint and its credit cost, a working curl call, bulk jobs with webhooks, errors, limits and pricing.
- 92% emails and 87% phone numbers found on the North American list in our 8-provider benchmark
- 0 credits on a miss: 1 per email found, 20 per mobile found
- GDPR and Singapore PDPA, with a Data Processing Agreement and Standard Contractual Clauses
Get an API key and 20 free credits to test it on your own records
Get your API keyComparing costs first? See plans and credit prices.
What does the B2B contact data API do?
The Scalelist B2B contact data API finds verified work emails and mobile numbers for people you name, and searches for people by job title, seniority, company, industry, location and company size. Scalelist finds and verifies contact details on demand rather than serving a pre-compiled list.
It runs on the same credits as the app. You pay 1 credit per email found, 20 per mobile found and 1 per profile a search returns. New accounts get 20 free credits, no credit card required.
How it works: three calls from key to contact
Most integrations make three calls: check the key, find the people, then get their contact details. Skip the middle step when you already have names.
- Authenticate. Generate a key in the app and send it as the
X-Api-Keyheader on every request.GET /api/v1/accountreturns your plan and credit balance. - Find the people.
POST /api/v1/people/countestimates how many people match.POST /api/v1/people/searchreturns up to 25 profiles per page at 1 credit each. - Get the contact.
POST /api/v1/email/findreturns a verified work email.POST /api/v1/phone/findreturns a mobile number. Every email is verified before it is returned and labelled Valid or Risky.
Endpoints and credits
Every endpoint below sits under https://api.scalelist.com/api/v1/, and the POST endpoints take a JSON body. The table lists what each one does and what it costs.
| Endpoint | What it does | Credits |
|---|---|---|
GET /account | Your name, plan and credit balance | None |
POST /email/find | Work email from a name plus a company domain or company name | 1 per email found |
POST /email/bulk | 1 to 100 email lookups as one async task | 1 per email found |
POST /email/verify | Checks an email address you already have | Included |
POST /email/domain | Known work emails at a company domain, up to 100 | 1 per email found |
POST /phone/find | Mobile number from a name plus a company, or from a known email | 20 per mobile found |
POST /phone/bulk | 1 to 100 mobile lookups as one async task | 20 per mobile found |
POST /people/search | Up to 25 matching profiles per page | 1 per profile returned |
POST /people/count | Estimated number of matching people, no profiles | Built for sizing |
POST /people/industries/resolve | Maps your industry words to search categories | None |
POST /people/bulk | A multi-page people search delivered to a webhook | 1 per profile delivered |
Each bulk endpoint has a GET twin that takes ?job_id= and returns the task status and results. GET /health reports whether the service is up.
Quickstart: your first call in curl
Store your key in an environment variable, confirm it with the account endpoint, then run one email lookup. The whole test costs at most 1 credit.
- Send
full_namewithcompany_domainwhen you have the domain: the reference marks that pair as preferred.company_nameworks when you do not. - Use
customfor your own IDs. Any object you put there, such as a CRM record ID, comes back in the response and the webhook payload. - Go async when you cannot wait. Set
synctofalsewith awebhook_urland the call returns 202 at once, then posts the result to your endpoint.
The reference at api.scalelist.com/docs generates request snippets in Shell, Ruby, Node.js, PHP and Python, and lets you download the OpenAPI document.
Bulk jobs, webhooks and safe retries
For more than a handful of records, send a bulk task instead of looping single calls. A task holds 1 to 100 records and returns a task ID immediately.
- Submit:
POST /api/v1/email/bulkor/phone/bulkwith arequestsarray. The 202 response carriestaskId,status: "queued"andtotal. - Collect: add a
webhook_urland Scalelist posts the results when the batch finishes, or pollGET /api/v1/email/bulk?job_id=<taskId>. You can do both. - Survive restarts: tasks in progress are re-queued automatically if the server restarts.
- Retry safely: send an
Idempotency-Keyheader. Repeating the same key and body within 24 hours returns the original 202, with no duplicate task and no extra credits. - Search at scale:
POST /api/v1/people/bulkpages through a search and posts the merged results to your webhook.max_resultscaps how many profiles are delivered and billed.
Errors and limits
The reference documents three error statuses and a few hard limits. Error bodies carry statusCode, error and message, plus a code on 400s.
| Response | When it happens | What to do |
|---|---|---|
400 idempotency_key_invalid | The Idempotency-Key header is badly formed | Use 1 to 255 letters, digits, _ or - |
400 idempotency_key_reused | Same key, different body within 24 hours | Use a new key for a new batch |
| 401 | Missing or unrecognized API key | Check the X-Api-Key header |
| 402 | Not enough credits to start a batch, or a search at 0 credits | Top up or change plan |
Limits: 100 records per bulk task, 25 profiles per search page, and 1 to 100 emails per domain search (10 by default). A search page is also capped to your remaining balance, so 20 credits return at most 20 profiles. Rate limits are not published in the reference, so send volume through the bulk endpoints rather than parallel single calls.
Which Scalelist API page do you need?
Start from what you already have. Each page below covers one job in depth, with its own examples and credit math.
People data API
Describe the people you want with search parameters (titles, seniority, functions, locations, company size) and get matching profiles, then their emails and mobiles. The people data API guide covers counting before you spend, cursor paging and bulk people search.
Company data API
Turn a list of company names or domains into the people who work there and their verified contacts. The company data API page also says plainly what Scalelist does not return (revenue, tech stack) and which APIs do.
B2B data API
The B2B data API overview is for teams choosing between data providers: what a B2B data API should return, how to test coverage on your own records, and where Scalelist fits.
Contact enrichment API
Already have names and companies in a CRM? The contact enrichment API page shows real-time and bulk enrichment, webhook delivery and what 1,000 records cost.
Email finder API
The email finder API goes deep on /email/find and /email/bulk: inputs, name handling, statuses and 1 credit per email found.
Email verification API
For addresses you already hold, the email verification API explains /email/verify and how to act on each result before you send.
Mobile number API
The mobile number API covers /phone/find and /phone/bulk: which inputs raise match rates, and why a mobile costs 20 credits only when one is found.
What teams build on it
- Enrich new signups.
/phone/findaccepts a known email on its own, so a trial signup can reach sales with a mobile attached. 20 credits only if one is found. - Backfill a CRM. A nightly job sends contacts with no email to
/email/bulkin tasks of 100 and writes results back using thecustomrecord ID. - Feed a Clay table. Clay connects to Scalelist through the API only; see the Clay API guide for the HTTP column setup.
- Map target accounts. Send company domains and seniority to
/people/search, then enrich the people you keep.
No code? Same credits, other routes
The Scalelist MCP server runs the same lookups inside Claude, ChatGPT or Cursor from a plain-English request. There is also a Zapier app with Email Finder and Mobile Finder actions, and a native push of selected leads to HubSpot with field mapping. The integrations hub lists every connector and its status.
Pricing
API calls draw from the same monthly credits as the app. There is no per-seat price and no annual contract.
| Credits per month | Price per month | Emails it covers | Mobiles it covers |
|---|---|---|---|
| 500 | 29 USD | 500 | 25 |
| 1,000 | 49 USD | 1,000 | 50 |
| 5,000 | 199 USD | 5,000 | 250 |
| 20,000 | 649 USD | 20,000 | 1,000 |
Plans of 2,000 (89 USD) and 10,000 credits (349 USD) sit in between, with custom plans above 20,000 credits a month. Yearly billing gives 2 months free, and unused credits roll over up to 2x your monthly allocation while you are subscribed.
Run your first lookup on 20 free credits, no credit card required
Get your API keyFAQ
How do I test the Scalelist API before paying?
Create an account and you get 20 free credits, no credit card required. Generate a key, call GET /api/v1/account to confirm it works, then run a few /email/find lookups on records you know. Each email found costs 1 credit and a miss costs 0, so 20 credits cover up to 20 test emails or one mobile.
Does a lookup that finds nothing cost credits?
No. Credits are consumed only when a result is found: 1 per email, 20 per mobile. A lookup that returns nothing costs 0. People search is billed per profile returned, and a page is capped to your remaining balance, so you never receive more profiles than you can pay for.
What does the B2B contact data API need to find an email?
A name and a company. Send first_name (with an optional last_name) or full_name, plus company_domain or company_name. The domain gives the best results. For a mobile number, a name plus a company works, and so does a known work email on its own.
Where does Scalelist get its data?
Scalelist finds and verifies contact details on demand rather than serving a pre-compiled list. Every email is verified before it is returned and labelled Valid or Risky. Contact data you submit through the API is never added to Scalelist’s database.
Is the Scalelist API GDPR compliant?
Scalelist operates under the GDPR and Singapore’s PDPA, with a Data Processing Agreement, Standard Contractual Clauses and a published sub-processor list. Contact data you submit is never added to Scalelist’s database. The Scalelist trust center has the details. You remain responsible for how you contact people.
Does the API work for contacts outside the US?
Yes. In our benchmark, Scalelist found an email for 89% of the EMEA list, 76% in APAC and 86% in Latin America, and a phone number for 73%, 75% and 85%. Test a sample of your own records in each region before you commit volume.
Is there an official SDK?
No SDK is listed in the reference, so you call the REST endpoints directly with any HTTP client. The docs generate request snippets in Shell, Ruby, Node.js, PHP and Python, and you can download the OpenAPI 3.0.3 document to generate a typed client in your language.
Are there rate limits?
Rate limits are not published in the API reference. The documented limits are 100 records per bulk task, 25 profiles per search page and 100 emails per domain search. For volume, use the bulk endpoints with webhooks instead of many parallel single calls.