Prospect reports API

Use this API to power a lead generator on your agency website. Your visitor does not need a Rankability login. Your server sends the request with a scoped Rankability API key; never put that key in browser code.

The report is owned by the organization that issued the key. It does not create a client, workspace, Tracker project, or active tracked prompt. A successful report draws from that organization’s on-demand usage allowance. Legacy credit-metered accounts use their existing prospect-scan credit charge. A failed report releases its pending reservation.

Create a dedicated key with prospect_scan:run and prospect_scan:read. Store it in your server’s protected environment.

Start one report

POST /api/agent/v1/prospect-scans
Authorization: Bearer rk_live_YOUR_KEY
Idempotency-Key: one-stable-key-for-this-form-submission
Content-Type: application/json

{
  "brandName": "Example Tree Care",
  "domain": "example.com",
  "keyword": "tree removal in St. Louis",
  "location": "St. Louis, Missouri",
  "visitorEmail": "owner@example.com"
}

brandName, domain, keyword, and visitorEmail are required. location is optional. The API returns 201 with scan.id and scan.status: "pending". An identical retry with the same Idempotency-Key returns the same report with 200; reusing that key for different inputs returns 409. Store the ID before polling. The API key’s organization is taken from authentication, never the request body.

Send location whenever you know the prospect’s market. Rankability removes the location from the keyword before reading it, then resolves the report to that market and its main language instead of guessing a language from a few short words. The keyword’s own script or accents, or a country-code domain, still win when they point somewhere else, and a market with no single main language falls back to reading the text.

If an identical report is already in progress under another idempotency key, the API returns 409. Reuse the original key and poll its report instead of starting a duplicate.

The visitor email is retained with the agency’s report for lead follow-up. Obtain the visitor’s consent on your form. Do not send that email to analytics or include it in a public report URL.

Read status and result

GET /api/agent/v1/prospect-scans/psc_REPORT_ID
Authorization: Bearer rk_live_YOUR_KEY

Poll with backoff until status is complete or failed. A completed response contains scan.reportPayload, the stored report evidence. Preserve the returned platform coverage and unavailable states. resolvedLanguage and resolvedCountry report the market the scan actually ran in, so check them before presenting a report to a visitor. Answer and title text is returned as plain text, with provider markdown, escape sequences, and HTML entities already resolved, so you can render it without another cleanup pass. One report is a dated snapshot, not a guarantee that every AI answer will be the same. An ID belonging to another organization returns 404.

GET /api/agent/v1/prospect-scans lists the organization’s recent reports, including submitted lead emails. Keep this response on the agency’s server. Your public site should render only the fields needed for the visitor’s own report.

Usage and limits

GET /api/agent/v1/usage/estimate?operation=prospect_scan reads the current account impact without running a report. For pooled accounts, it shows the on-demand usage window and remaining percentage. Legacy credit-metered accounts see the current prospect-report credit estimate. Each successful report records one usage event or legacy credit charge. A repeat request with the same idempotency key does not run another scan. A full allowance returns 429 usage_limit_reached for pooled accounts.

Public lead forms need their own bot protection and per-visitor rate limits. Rankability also applies key-level API limits and organization-level usage controls. Keep your key server-side and stop polling at a terminal state.