DOCUMENTATION

API Reference

Everything you need to integrate Brain Lead into your applications.

Authentication

All API requests require authentication via Bearer token. Include your API key in the Authorization header:

Authorization: Bearer bl_your_api_key_here

Get your API key from the Dashboard after creating a free account.

Base URL

All API endpoints are relative to:

https://brainlead.dev/api/v1

Rate Limits

Plan	Requests/Second	Monthly Limit
Free	1	1,000
Starter	5	10,000
Pro	20	50,000
Business	50	200,000
Enterprise	100	1,000,000

Rate limit info is included in response headers: X-RateLimit-Remaining, X-RateLimit-Reset

Error Handling

Errors return standard HTTP status codes with a JSON body:

{ "error": "invalid_api_key", "message": "The provided API key is invalid", "code": 401 }

Code	Meaning
200	Success
400	Bad request — check your parameters
401	Unauthorized — invalid or missing API key
429	Rate limited — slow down
500	Server error — retry later

Carrier Lookup

POST /api/v1/carrier/lookup

Parameter	Type	Required	Description
number	string	Required	Phone number (E.164 format)
country	string	Optional	Country code (e.g., US, CA, UK, DE, FR, etc. 65+ countries supported). Default: auto-detect

Response

{ "carrier": "T-MOBILE", "line_type": "mobile", "location": "New York, NY", "number": "+12125551234", "country": "US", "credits_remaining": 497 }

Bulk Carrier Lookup

POST /api/v1/carrier/bulk

Send a JSON array of phone numbers and get back a JSON array of results — one object per number, in the same order you sent them. This is the easiest way to check many numbers in a single request.

Max 100 numbers per request. For larger lists, split into chunks of 100 and send several requests (in parallel is fine). The Master API key is unlimited here too.

Parameter	Type	Required	Description
numbers	array	Required	Array of phone numbers (max 100 per request)
country	string	Required	Country code (e.g., US, CA, UK, DE, FR, etc. 65+ countries supported)

Example request

curl -X POST https://brainlead.dev/api/v1/carrier/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"US","numbers":["+14155552671","+12125551234","+13105559876"]}'

Example response

{
  "status": "success",
  "results": [
    {"number":"+14155552671","carrier":"MULTIPLE OCN LISTING","carrier_group":"MULTIPLE OCN LISTING","type":"Landline","location":"DIR ASST, CA","ported":"Unknown","is_wireless":"Unknown","status":"valid"},
    {"number":"+12125551234","carrier":"Unknown","carrier_group":"Unknown","type":"Landline","location":"DIR ASST, NY","ported":"Unknown","is_wireless":"Unknown","status":"valid"},
    {"number":"+13105559876","carrier":"MULTIPLE OCN LISTING","carrier_group":"MULTIPLE OCN LISTING","type":"Landline","location":"DIR ASST, CA","ported":"Unknown","is_wireless":"Unknown","status":"valid"}
  ],
  "total": 3,
  "credits_remaining": 497
}

Usage Stats

GET /api/v1/account/usage

Returns your account usage statistics and API call history.

Credit Balance

GET /api/v1/account/credits

Returns your remaining credit balance and plan details.

Need Help?

Our team is available 24/7 on Telegram for integration support.

Chat on Telegram Contact Us