Audience Builder API

Submit a plain-English prompt, get back a list of matching companies.

Authentication

All requests must include an Authorization header with your API key as a bearer token. Keys are per-user and available on your dashboard (domain admin access required).

Authorization: Bearer <your-api-key>

Base URL

https://app.getgrizz.com/api/v1/

How It Works

The API is asynchronous. Building an audience involves three steps:

1
Submit a prompt — POST /audiences/. Returns an audience record with status: "RUNNING".
2
Poll for completion — GET /audiences/:id/. Poll until status is COMPLETE or FAILED. Typical build time is 30–90 seconds.
3
Download results — GET /audiences/:id/results/. Returns JSON or CSV.

Endpoints

POST /api/v1/audiences/

Submit a plain-English prompt to build an audience. Grizz sends the prompt to Claude, which generates a structured Snowflake query. The query is then executed to produce the company list.

Request body

Field	Type	Required	Description
prompt	string	Yes	A description of the companies you want. Be specific — industry, geography, and technology signals all help.

Example

curl -X POST https://app.getgrizz.com/api/v1/audiences/ \ -H "Authorization: Bearer <key>" \ -H "Content-Type: application/json" \ -d '{"prompt": "Scaffolding contractors in New York"}'

Response 201 Created

{ "id": "38be76d4-b5bf-4bca-8872-2dd513f25177", "name": "AI Audience", "ai_customer_summary": null, "status": "RUNNING", "result_count": null, "created_at": "2026-02-18T23:42:08.800416Z", "completed_at": null, "api_sourced": true }

GET /api/v1/audiences/:id/

Poll the status of an audience. The status field will be one of PENDING, RUNNING, COMPLETE, or FAILED.

Example

curl https://app.getgrizz.com/api/v1/audiences/38be76d4-.../ \ -H "Authorization: Bearer <key>"

Response 200 OK

{ "id": "38be76d4-b5bf-4bca-8872-2dd513f25177", "name": "AI Audience", "ai_customer_summary": "Construction companies in New York specializing in scaffolding services.", "status": "COMPLETE", "result_count": 30, "created_at": "2026-02-18T23:42:08.800416Z", "completed_at": "2026-02-18T23:44:35.987511Z", "api_sourced": true }

GET /api/v1/audiences/:id/results/

Download the company list. Returns JSON by default. Pass ?format=csv or set Accept: text/csv for a CSV download. Returns 409 if the audience is not yet complete.

Query parameters

Parameter	Values	Description
format	`csv`	Return a streaming CSV download instead of JSON.

JSON example

curl https://app.getgrizz.com/api/v1/audiences/38be76d4-.../results/ \ -H "Authorization: Bearer <key>"

CSV example

curl -o results.csv \ "https://app.getgrizz.com/api/v1/audiences/38be76d4-.../results/?format=csv" \ -H "Authorization: Bearer <key>"

Response fields (JSON)

Field	Description
company_id	Grizz company UUID
company_name	Company display name
domain	Primary web domain
linkedin_url	LinkedIn company page
hq_city / hq_region / hq_country	HQ location
employee_range	Headcount band (e.g. `50-200`)
revenue_range	Estimated annual revenue band
erp_tech_stack	Detected ERP software
erp_job_title	Job title of the signal that confirmed the ERP
ats_tech_stack	Detected ATS software
ats_job_title	Job title of the signal that confirmed the ATS
other_tech_signals	Other confirmed software, comma-separated

Error Codes

Status	Meaning
400	Bad request — missing or invalid `prompt`
401	Missing or invalid API key
403	Valid key but account lacks domain admin or org membership
404	Audience not found or belongs to a different org
409	Results requested but audience is not yet complete