Overview API Reference Audience Builder CRM Field Setup Enrichment API Beta

Company Enrichment API

Beta

Submit a domain or company name and get back enriched company data — NAICS code, contact information, and an AI-generated description.

This API is in beta. Endpoints, response fields, and rate limits may change. Contact your Grizz point of contact to have enrichment enabled for your organization.

Authentication

All requests require an Authorization header with your API key as a bearer token. Keys are available on your dashboard (domain admin access required). Your organization must also have the Enrichment API enabled.

Authorization: Bearer <your-api-key>

Base URL

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

How It Works

Enrichment is asynchronous. For domains already in the Grizz database, results return immediately. For unknown domains, Grizz scrapes the company website and uses AI to classify and describe the company. That process typically completes within 60 seconds.

1
Submit a request — POST /enrichment/. Returns a request record with a status of PENDING or COMPLETE.
2
Poll for completion — GET /enrichment/:id/. Poll until status is COMPLETE or FAILED. We recommend polling every 5 seconds.
3
Fetch results — GET /enrichment/:id/results/. Returns the enriched company data. Results are marked as retrieved and removed from the unretrieved queue.

You can also use GET /enrichment/ to list all completed, unretrieved requests in bulk — useful when processing large batches.

Rate Limits

Each organization has a monthly call limit set by Grizz. Submitting a request counts against the limit immediately on POST. Polling and fetching results do not count against the limit. When the limit is reached, POST /enrichment/ returns 429 with the current usage in the response body.

Endpoints

POST /api/v1/enrichment/

Submit a company lookup request. Provide at least one of domain or grizz_id. You may also provide company name and location to help resolve fuzzy matches against the Grizz database.

Request body

Field	Type	Required	Description
domain	string	One of domain / grizz_id required	Company web domain (e.g. `acme.com`). Protocols and trailing slashes are stripped automatically.
grizz_id	string	One of domain / grizz_id required	Grizz company ID for direct database lookup.
company_name	string	No	Company name. Used alongside location fields to improve fuzzy matching.
hq_city	string	No	HQ city.
hq_state	string	No	HQ state or region.
hq_country	string	No	HQ country.
hq_phone	string	No	Company phone number.

Example

curl -X POST https://app.getgrizz.com/api/v1/enrichment/ \ -H "Authorization: Bearer <key>" \ -H "Content-Type: application/json" \ -d '{"domain": "acme.com"}'

Response 201 Created

{ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "PENDING", "result_type": null, "match_confidence": null, "error_detail": null, "input_domain": "acme.com", "input_grizz_id": null, "input_company_name": null, "input_hq_city": null, "input_hq_state": null, "input_hq_country": null, "input_hq_phone": null, "created_at": "2026-03-06T14:00:00Z", "completed_at": null, "retrieved_at": null }

GET /api/v1/enrichment/

List all completed requests that have not yet been retrieved. Useful for batch processing — poll this endpoint and drain the queue rather than tracking individual IDs. Returns up to 100 records by default, maximum 500 via the limit parameter.

Query parameters

Parameter	Default	Description
limit	100	Max records to return. Capped at 500.

Response 200 OK

{ "total": 42, "returned": 42, "results": [ { "id": "...", "status": "COMPLETE", ... } ] }

GET /api/v1/enrichment/:id/

Poll the status of a single enrichment request. The status field will be one of PENDING, RUNNING, COMPLETE, or FAILED. We recommend polling every 5 seconds.

Example

curl https://app.getgrizz.com/api/v1/enrichment/a1b2c3d4-.../ \ -H "Authorization: Bearer <key>"

Response 200 OK

{ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "COMPLETE", "result_type": "ENRICHED", "match_confidence": null, "error_detail": null, "input_domain": "acme.com", "created_at": "2026-03-06T14:00:00Z", "completed_at": "2026-03-06T14:00:47Z", "retrieved_at": null }

GET /api/v1/enrichment/:id/results/

Fetch the enriched company data for a completed request. Returns 409 if the request is not yet complete. Calling this endpoint stamps retrieved_at on the first call, removing it from the unretrieved queue.

The source field indicates where the result came from:

database — matched an existing company in the Grizz database.
enrichment — domain was scraped and classified by AI.
no_match — domain could not be resolved or scraped. company will be null.

Example

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

Response — source: "enrichment"

{ "source": "enrichment", "company": { "domain": "acme.com", "company_name": "Acme Construction Inc.", "naics_code": "236220", "naics_description": "Commercial and Institutional Building Construction", "valid_domain": true, "rationale": "Active commercial GC website with project portfolio and contact info.", "company_description": "Acme Construction is a Denver-based commercial general contractor specializing in ground-up office and retail projects across the Mountain West. Founded in 1998, they pride themselves on self-performing concrete and steel work and maintaining long-term subcontractor relationships.", "street_address": "1234 Main St", "city": "Denver", "state_province_region": "CO", "country": "United States", "zip_code": "80202", "phone": "303-555-0100", "email": "info@acme.com" } }

Response — source: "database"

{ "source": "database", "match_confidence": 0.97, "company": { "grizz_id": "GRZ-00012345", "company_name": "Acme Construction Inc.", "domain": "acme.com", "hq_city": "Denver", "hq_state": "CO", "hq_country": "United States", "employee_range": "50-200", "naics6": "236220", "grizz_construction": true } }

Enrichment response fields

Field	Description
domain	The domain that was enriched.
company_name	Formatted company name as identified from the website.
naics_code	6-digit NAICS code.
naics_description	NAICS category description.
valid_domain	`true` if the domain represents a real operating business (not parked, placeholder, or coming-soon).
rationale	Short AI explanation of the classification (≤200 characters).
company_description	AI-generated description (≤1000 characters) covering location, line of work, values, and differentiators as conveyed on the company's website.
street_address	Street address from the website, if found.
city	City from the website, if found.
state_province_region	State, province, or region from the website, if found.
country	Country from the website, if found.
zip_code	Postal code from the website, if found.
phone	Phone number from the website, if found.
email	Email address from the website, if found.

Error Codes

Status	Meaning
400	Bad request — no domain or grizz_id provided.
401	Missing or invalid API key.
403	Valid key but account lacks domain admin, org membership, or Enrichment API access.
404	Request not found or belongs to a different org.
409	Results requested but the request is not yet complete.
429	Monthly call limit reached. Response includes `limit` and `used` fields.