API documentation

REST API v1. Read only, JSON, one tenant per key.

The API returns the leads that have been delivered to your subscription, the same records as your daily CSV. It is available on the Pro and Agency plans. If you would rather click than script, the same data is searchable in the customer dashboard.

Base URL

https://api.alphaai-leads.com/api/v1/{customer_token}

customer_token is a stable, non-secret identifier for your account. It appears in the URL so that traffic can be attributed and rate limited per customer. It is not a credential on its own. Both your token and your API key are issued when API access is enabled on your plan.

Authentication

Send your API key as a bearer token on every request. Keys are stored only as a hash, so if you lose one it can be rotated but not recovered.

curl -H "Authorization: Bearer $ALPHALEADS_API_KEY" \
  "https://api.alphaai-leads.com/api/v1/$CUSTOMER_TOKEN/leads?limit=5"

Key rotation is zero downtime: the previous key keeps working for 24 hours after a rotation, so you can deploy the new one without a gap.

Endpoints

GET/me

Your account: plan tier, the states you are subscribed to, and your current rate limits.

GET/leads

Your delivered leads, newest first.

Parameter	Type	Notes
`limit`	integer	1 to 500. Defaults to 100.
`cursor`	integer	Pass `next_cursor` from the previous response to get the next page.
`from`	date	`YYYY-MM-DD`. Only leads delivered on or after this date.
`to`	date	`YYYY-MM-DD`. Only leads delivered on or before this date.
`state`	string	Two letter state code, for example `FL`.
`has_email`	boolean	`true` returns only leads carrying a verified email.
`has_linkedin`	boolean	`true` returns only leads carrying a LinkedIn URL.

Pagination is cursor based rather than offset based, so a page never shifts underneath you while new leads are being delivered. Keep passing next_cursor until it comes back null.

{
  "leads": [
    {
      "id": 918273,
      "filing_id": 4471902,
      "entity_name": "RIVERBEND PLUMBING LLC",
      "state": "TX",
      "city": "AUSTIN",
      "zip": "78731",
      "county": null,
      "owner_name": "RIVERBEND PLUMBING LLC",
      "company_url": "https://riverbendplumbing.com/",
      "email": "service@riverbendplumbing.com",
      "linkedin_url": null,
      "phone": null,
      "filing_date": "2026-08-28",
      "sent_at": "2026-09-04T09:07:07.000Z"
    }
  ],
  "next_cursor": 918272
}

GET/leads/{filing_id}

A single lead by its filing_id. Returns 404 not_found if that filing was never delivered to your subscription, so this cannot be used to look up records you were not sent.

GET/summary

Totals for your account, plus a breakdown of the last 30 days by state. Useful for a dashboard tile or a delivery check.

POST/keys/rotate

Issues a new API key and returns it once. The old key continues to work for 24 hours.

GET/health

Liveness check. Also available unauthenticated at https://api.alphaai-leads.com/health.

Blank fields are deliberate

email, company_url and phone are populated only when verification tied that contact to the specific business on the filing. Roughly a third of records clear that check. The rest arrive with those fields null rather than filled with a pattern guess, because a guessed address costs you a send and a sender reputation hit. A null here means we could not confirm one, not that we withheld it.

Rate limits

Limits are per account and are returned by /me. Exceeding one returns 429 with a body naming which window was hit. If your use case needs more, email support@alphaai-leads.com.

Errors

Status	Body	Meaning
400	`invalid_filing_id`	Malformed filing id.
401	`missing_bearer`, `invalid_key`	No key, wrong key, or a plan without API access. Unknown and inactive accounts return the same error deliberately, so this cannot be used to discover valid tokens.
404	`not_found`	Unknown route, or a lead not delivered to your account.
429	`rate_limited`	Per minute or per day limit reached.

What this API is not

It is not a search over our whole database. It returns only leads delivered to your subscription.
These are public business filing records, not inquiries and not intent data. Nobody in the feed asked to be contacted.
Leads are non-exclusive: other subscribers covering the same state may receive the same records.
You are responsible for compliance with CAN-SPAM, TCPA and do-not-call rules when contacting anyone in the feed. See the Terms.

Questions, or something here does not match what you are seeing? Email support@alphaai-leads.com.