Overview - Emporia Research

Use the Demand API to quote and buy sample.

Typical flow

Get the taxonomy

Load audiences and filter values with Get taxonomy.

Get a quote

Call Create a preview to get the feasible N, CPI and a preview id.

Create a project

Call Create a project with the preview id. The response includes your redirect URLs.

Upload your screener

Add it with Upload an attachment.

Launch it

Set the status to ACTIVE with Update project status.

Track respondents

Use Get a project and List respondents.

Authentication

Send your API key as a bearer token in the Authorization header of every request.

Authorization: Bearer <api_key>

Requests with a missing or invalid key return 403 UNAUTHORIZED.

Request IDs

Send X-Request-Id with a request to trace it, and we echo it back. If you don’t send one, we generate one. It also appears as requestId in error bodies.

Errors

Errors return a code, a message, the requestId and, for validation errors, the field that failed.

{
  "error": {
    "code": "INVALID_FILTER_VALUE",
    "message": "Unknown employee range 'FIFTY_TO_FIVE_HUNDRED'.",
    "field": "filters.employeeRanges[0]",
    "requestId": "7c1e4b9a-2f3d-4e8a-9b6c-1d5f8a2e4c7b"
  }
}

General errors, which any endpoint can return:

Status	Code	When
400	`INVALID_REQUEST`	Malformed JSON or an unknown field.
403	`UNAUTHORIZED`	Missing or invalid API key.
429	`RATE_LIMITED`	Over the rate limit.
500	`INTERNAL_ERROR`	Server error.

Endpoint pages list their own codes.

Rate limits

Limits apply per API key.

Scope	Limit
`POST /v1/preview`	30 requests per minute
Everything else	120 requests per minute

Every response includes:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1761580800

X-RateLimit-Reset is a Unix timestamp. Over the limit, you get 429 RATE_LIMITED with a Retry-After header in seconds.

Support

For questions about the API, email engineering@emporiaapp.com.

​Typical flow

​Authentication

​Request IDs

​Errors

​Rate limits

​Support