API documentation
A small REST API for searching contacts, revealing their details and enriching your own records. It uses the same credits as the app, on every plan.
Authentication
Create a key under API in your workspace and send it with every request. Keys are shown once, can be revoked at any time, and should only ever be used from a server, never from a browser or mobile app.
https://www.businesscontacts.io/api/v1curl https://www.businesscontacts.io/api/v1/account \
-H "Authorization: Bearer YOUR_API_KEY"Limits and credits
- 120 requests a minute per account, and 600 searches a day shared with the app.
- Searching is free. One credit reveals one contact: email, phone number and company details.
- A contact you have already revealed, in the app or through the API, is never charged again.
- Requests are all-or-nothing: if credits run short, nothing is revealed and nothing is charged.
- Requests and responses are JSON. Send
Content-Type: application/jsonon POST requests.
Account and balance
GET/api/v1/accountFree
Returns the plan and the credits left on the account the key belongs to. If the account is on a team, the plan and credits are the team's, "remaining" is what this key can still spend (the shared balance, or less if a personal limit applies), and "team" is filled in. Otherwise "team" is null.
{
"account": { "name": "Jane Cooper", "email": "jane@acme.com" },
"plan": { "id": "growth", "name": "Growth", "period_end": "2027-01-16T00:00:00.000Z" },
"credits": { "remaining": 4820, "granted": 5000 },
"team": { "name": "Acme Sales", "role": "member", "credit_limit": null }
}Search contacts
POST/api/v1/contacts/searchFree
Filtered search, 25 results a page. Email, phone and LinkedIn are masked until you reveal the contact. All filters are optional; list filters match any of the values given.
{
"filters": {
"q": "marketing",
"company": "Acme",
"industry": ["Technology & SaaS"],
"seniority": ["C-Level", "VP"],
"department": ["Marketing"],
"country": ["United States"],
"companySize": ["51-200"]
},
"page": 1
}{
"total": 132, "page": 1, "page_size": 25, "total_pages": 6,
"results": [
{
"id": 48213,
"full_name": "Jane Cooper",
"job_title": "Chief Marketing Officer",
"seniority": "C-Level",
"department": "Marketing",
"revealed": false,
"email": "j••••••@a•••.com",
"email_status": "verified",
"phone": "+1• ••• ••• •42",
"linkedin_url": "linkedin.com/in/•••••",
"company": { "id": 911, "name": "Acme Inc", "website": null, "size": "51-200", "revenue": "$10M-$50M", "industry": "Technology & SaaS" },
"location": { "city": "Austin", "state": "Texas", "country": "United States" }
}
]
}Reveal contacts
POST/api/v1/contacts/reveal1 credit per new contact
Returns the full contact for up to 25 ids from a search. Contacts you already own are returned without a charge. If your credits do not cover the whole request, nothing is revealed and nothing is charged.
{ "ids": [48213, 48377] }{
"contacts": [
{
"id": 48213,
"full_name": "Jane Cooper",
"first_name": "Jane",
"last_name": "Cooper",
"job_title": "Chief Marketing Officer",
"seniority": "C-Level",
"department": "Marketing",
"email": "jane.cooper@acme.com",
"email_status": "verified",
"phone": "+1 512 555 0142",
"linkedin_url": "https://www.linkedin.com/in/janecooper",
"company": { "id": 911, "name": "Acme Inc", "website": "https://acme.com", "size": "51-200", "revenue": "$10M-$50M", "industry": "Technology & SaaS", "sub_industry": null },
"location": { "city": "Austin", "state": "Texas", "country": "United States" }
}
],
"not_found": [48377],
"credits": { "charged": 1, "remaining": 4819 }
}Enrich your records
POST/api/v1/enrich1 credit per matched contact
Send up to 25 of your own records and get back the contact we hold for each. A record needs a work email, or a full name together with a company name or website. Records with no match cost nothing. A single record can also be sent on its own, without the records array.
{
"records": [
{ "email": "jane.cooper@acme.com" },
{ "full_name": "Marcus Lee", "company": "Northwind Traders" },
{ "first_name": "Priya", "last_name": "Nair", "domain": "globex.io" }
]
}{
"results": [
{ "matched": true, "matched_by": "email", "contact": { "id": 48213, "full_name": "Jane Cooper", "email": "jane.cooper@acme.com", "...": "same fields as reveal" } },
{ "matched": true, "matched_by": "name+company", "contact": { "id": 51200, "...": "..." } },
{ "matched": false, "matched_by": null, "contact": null }
],
"credits": { "charged": 2, "remaining": 4817 }
}Errors
Errors use standard HTTP status codes and always carry a code and a readable message.
{ "error": { "code": "insufficient_credits", "message": "Not enough credits: 3 needed, 1 left. Nothing was revealed." } }- 400
invalid_request / invalid_json
The body is missing something or is not valid JSON.
- 401
missing_api_key / invalid_api_key
No key was sent, or the key is wrong or revoked.
- 402
insufficient_credits / no_plan
Not enough credits for the whole request. Nothing was charged.
- 403
account_blocked
The account has been blocked.
- 429
rate_limited / daily_search_limit
Too many requests. Wait and retry.
- 500
server_error
Something failed on our side. Safe to retry.
Prefer not to write code?
Upload a CSV or Excel file under Enrich in the workspace and download it back with the details filled in.
Open bulk enrichment