NewTeams are here: invite teammates and share one credit balance
Developers

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.

Base URL
https://www.businesscontacts.io/api/v1
Authenticated request
curl 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/json on 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.

Response
{
  "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 }
}

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.

Request body
{ "ids": [48213, 48377] }
Response
{
  "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.

Request body
{
  "records": [
    { "email": "jane.cooper@acme.com" },
    { "full_name": "Marcus Lee", "company": "Northwind Traders" },
    { "first_name": "Priya", "last_name": "Nair", "domain": "globex.io" }
  ]
}
Response
{
  "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 response
{ "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