API documentation

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

The API returns every lead delivered to your account: each row of your verified daily file, plus any replacement leads, with the same values the CSV carried. A day's rows appear once that day's file has been emailed. The same rows are searchable and exportable in the customer dashboard. The API is available on the Pro and Agency plans.

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

Leads delivered to your account, most recently delivered 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. A value that was not issued to your account returns `400 invalid_cursor`.
`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 code of the state registry the filing came from (`source_state`), for example `FL`.
`has_email`	boolean	`true` returns only records that carry an email address. Every Pro and Agency daily row does.
`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. To pick up only new deliveries, pass from set to the date of your last sync rather than paging through your full history each time.

{
  "data": [
    {
      "filing_id": 4471902,
      "entity_name": "RIVERBEND PLUMBING LLC",
      "owner_name": "RIVERBEND PLUMBING LLC",
      "address": "1200 EXAMPLE RD STE 4",
      "city": "AUSTIN",
      "state": "TX",
      "source_state": "TX",
      "zip": "78731",
      "county": null,
      "filing_date": "2026-08-28",
      "entity_type": "DOMESTIC LLC",
      "niche": "Home Services",
      "company_url": "https://riverbendplumbing.com/",
      "website_confidence": 94,
      "website_match_method": "homepage_exact_name+domain",
      "email": "service@riverbendplumbing.com",
      "email_confidence": 95,
      "email_method": "contact_page_scrape_fresh",
      "phone": null,
      "linkedin_url": null,
      "facebook_url": null,
      "contact_form_url": null,
      "delivery_kind": "daily",
      "sent_at": "2026-09-04T10:08:00.642Z"
    }
  ],
  "count": 1,
  "next_cursor": null
}

GET/leads/{filing_id}

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

GET/summary

Delivered-lead totals for your account (today, last 7 days, last 30 days, all time), 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.

What API records contain

The same fields as your daily CSV, with the values that file carried: the filing record, the verified website (company_url) and email with their confidence scores and match methods, and phone when one was found. Every Pro and Agency daily row has a verified website and email. phone, linkedin_url, facebook_url and contact_form_url are filled only when found; a null means nothing was found. delivery_kind is daily for rows from your daily file and replacement for leads sent to replace earlier rows that a later accuracy check withdrew. Withdrawn rows are not returned. sent_at is when the row was recorded as delivered. state is the business address state, which can differ from source_state for a company registered in one state and based in another.

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`, `invalid_cursor`, `invalid_from`, `invalid_to`	Malformed filing id, a cursor not issued to your account, or a date not in `YYYY-MM-DD` form.
401	`missing_bearer`, `invalid_key`	No key or wrong key. Unknown and inactive accounts return the same error deliberately, so this cannot be used to discover valid tokens.
403	`tier_does_not_include_api`	The key is valid but your current plan does not include API access. Upgrading to Pro or Agency restores it; no new key is needed.
404	`not_found`	Unknown route, or a lead not delivered to your account.
429	`rate_limit_minute`, `rate_limit_day`	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 account.
It is not real time. A day's leads appear when that day's file is delivered, not as filings are found.
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.