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	250/day
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

Verify Single Email

POST /api/v1/verify

Request Body

Parameter	Type	Required	Description
email	string	Required	Email address to verify

Response

{ "status": "deliverable", "email": "user@gmail.com", "score": 98, "checks": { "syntax": true, "domain": true, "mx": true, "smtp": true, "disposable": false, "catch_all": false, "role_based": false }, "mx_records": "gmail-smtp-in.l.google.com", "credits_remaining": 249 }

Status Values

Status	Description
deliverable	Email exists and will accept mail
undeliverable	Email does not exist or will bounce
risky	Email may bounce (catch-all, disposable, etc.)
unknown	Unable to determine deliverability

Bulk Verification

POST /api/v1/verify/bulk

Submit a list of emails for batch verification. Returns a job ID for polling results.

Request Body

Parameter	Type	Required	Description
emails	array	Required	Array of email addresses (max 10,000)
webhook_url	string	Optional	URL to receive results when complete

Carrier Lookup

POST /api/v1/carrier/lookup

Parameter	Type	Required	Description
number	string	Required	Phone number (E.164 format)
country	string	Optional	Country code (US, CA, UK). 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

Submit up to 10,000 numbers for batch carrier lookup.

Parameter	Type	Required	Description
numbers	array	Required	Array of phone numbers (max 10,000)
country	string	Required	Country code (US, CA, UK)

Send SMS

POST /api/v1/sms/send

Parameter	Type	Required	Description
to	string	Required	Recipient phone number (E.164 format)
message	string	Required	SMS message text (max 1600 characters)
from	string	Optional	Sender ID or phone number

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