This page documents conventions that apply across the public Company API endpoints. Refer to this page instead of memorizing per-endpoint notes.
Authentication
All requests require:
--header 'authorization: Bearer YOUR_API_KEY'
--header 'x-api-version: 2025-11-01'
Shared identifier parameters
Enrich and Identify accept the same identifier arrays. Submit exactly one type per request.
| Parameter | Type | Example |
|---|
domains | string[] | ["hubspot.com"] |
names | string[] | ["Retool"] |
crustdata_company_ids | integer[] | [628895] |
professional_network_profile_urls | string[] | ["https://www.linkedin.com/company/mintlify"] |
Current platform behavior: Mixing identifier types in a single request
is not supported. Submit one type per request.
match_type values
The match_type field in Enrich and Identify responses uses these exact values:
| Value | When returned |
|---|
domain | Input was a domain |
name | Input was a company name |
crustdata_company_id | Input was a Crustdata ID |
professional_network_profile_url | Input was a LinkedIn URL |
fields parameter semantics
| Endpoint | fields type | Example | Notes |
|---|
| Search | Dot-path response fields | ["basic_info.name", "headcount.total"] | Only indexed fields are available |
| Enrich | Section group names | ["basic_info", "headcount", "funding"] | Omit to get all sections |
| Identify | Section group names | ["basic_info"] | Same schema as Enrich |
| Autocomplete | Not supported | — | — |
year_founded
| Endpoint | Type | Example | Notes |
|---|
| Search | string | "2017" | Year only |
| Enrich / Identify | string | "2017-01-01" or "2017" | Format varies by data source |
| Endpoint | Format | Example |
|---|
| Search / Autocomplete | ISO3 code | "USA", "GBR", "CAN" |
| Enrich / Identify | ISO3 code | "USA" |
LinkedIn fields
All public company-returning endpoints (Search, Enrich, Identify) return LinkedIn fields under basic_info:
| Field | Path |
|---|
| LinkedIn URL | basic_info.professional_network_url |
| LinkedIn ID | basic_info.professional_network_id |
Error shapes
{
"error": {
"type": "invalid_request",
"message": "Human-readable description of the error",
"metadata": []
}
}
type values: invalid_request, authentication_error, insufficient_credits, permission_error, rate_limit_error, internal_error.
401 — authentication error
Uses a different shape:
{ "message": "Invalid API key in request" }
No-match behavior
| Endpoint | No matches found | Partial match (batch) |
|---|
| Enrich | 200 with empty matches: [] | 200 — matched items have data, unmatched have matches: [] |
| Identify | 200 with empty matches: [] | Same as Enrich |
| Search | 200 with empty companies: [] | N/A |
| Autocomplete | 200 with empty suggestions: [] | N/A |
The OpenAPI spec defines 404 responses for Enrich and Identify, but
current platform behavior returns 200 with empty matches: []. Build your
integration to handle both.
| Endpoint | Method | Next page | Stop condition |
|---|
| Search | Cursor-based | Pass next_cursor as cursor in the next request | next_cursor is null |
| All others | No pagination | — | — |
Integration guidance
| Situation | Action |
|---|
400 error | Fix the request. Do not retry. |
401 error | Check API key. Do not retry. |
403 error | Check permissions or credit balance. Do not retry automatically. |
404 error | Identifier not found. Try a different identifier or type. Do not retry. |
500 error | Retry with exponential backoff (1s, 2s, 4s). Stop after 3 retries. |
| Rate limit hit | Back off for 60 seconds, then retry. |
next_cursor is null | No more pages — stop paginating. |
Empty matches / companies | Broaden filters or check identifier for typos. |
Ordering guarantees
Current platform behavior — not guaranteed by the OpenAPI contract:
- Search: Results are ordered by the
sorts you specify. Without sorts, order is undefined — always include sorts for stable pagination.
- Enrich / Identify: Batch results correspond to the input index position.
- Enrich / Identify matches: Matches within each result are ordered by
confidence_score descending (highest confidence first).
- Autocomplete: Suggestions are ordered by relevance to the query, then by document frequency.
Nullability
Many response fields are nullable. Key fields to handle:
| Field | Nullable | When null |
|---|
next_cursor | Yes | No more pages |
total_count | Yes | Count unavailable |
year_founded | Yes | Data not available |
professional_network_url | Yes | No LinkedIn profile |
company_type | Yes | Classification unknown |
revenue.estimated.lower_bound_usd | Yes | Revenue data unavailable |
Rate limits
Current platform behavior — not specified in the OpenAPI contract:
- All endpoints: 60 requests per minute.
- Credits: Search costs 1 credit per 100 companies returned. Enrich costs credits per company enriched.
