Core Concepts
Response Modes
Control what fields appear in the response and how they're formatted.
Field mode
| Parameter | Values | Description |
|---|---|---|
mode | basic, full | Controls which fields are returned |
basic— basic-tier fields only (~15–20 per entity). Lower credit cost.full— all fields allowed by the key. Advanced-only fields require advanced-tier access.
Default: basic. Use fields= for explicit projections.
Custom field selection
Override mode with an explicit field list:
bash
GET /v1/companies?states=CA&fields=id,company_name,total_premiums,primary_brokerOnly the specified fields are returned. Credit cost is determined by whether any advanced field is included. id is always included regardless of the field list — you can't exclude it.
How mode and fields are validated
Invalid combinations are rejected up front, not silently downgraded. This keeps credit estimates and dry-run results honest.
| Situation | Response | Why |
|---|---|---|
page_size > 500 | 400 VALIDATION_ERROR | Hard cap. Lower the page size. |
mode=full with a basic-tier key | 200 with allowed fields | The response includes fields allowed by the key. Advanced-only fields still require advanced access. |
| Unknown query parameter | 400 VALIDATION_ERROR | Catches typos before they cost credits. |
Unknown field in fields= | 400 VALIDATION_ERROR | Response includes the entity's allowlist in the expected[] array. |
Advanced field requested via fields= with a basic key | 403 FORBIDDEN | Issue: field_not_allowed. |
fields= overrides mode= only when fully authorized
If every field in
fields= is allowed for the key, the explicit list wins over mode. If any field is unauthorized, the entire request is rejected — the API does not partially honor the list.Response format
| Parameter | Values | Description |
|---|---|---|
format | json, flat | Response format |
json(default) — standard nested JSONflat— flattened for Clay, spreadsheets, and reverse ETL. See Flat-File Mode.
Need a key?
Keys are issued by our team, not a signup form. Book a 25-minute walkthrough and you'll leave with sandbox and live credentials.