Core Concepts

Everything you need to understand before working through the API Reference. Read this once and the rest of the docs will make sense.

Environments

Environment	Base URL	Use for
Staging	https://stg.api.fair-indonesia.com/api/fairservice	Free trials, development, testing
Production	https://api.fair-indonesia.com/api/fairservice	Live traffic

Your token is tied to an environment. A staging token will not work against production.

Authentication

Pass your token in the Authorization header, directly, with no Bearer prefix:

Authorization: <your_token>

See Authentication for details.

Synchronous vs. asynchronous endpoints

Some endpoints return data in the same response. Others kick off a job that takes a few seconds to run, so they follow a submit-then-fetch pattern:

1. Submit — POST the request. You get back an id and a status (for example IN_PROGRESS).
2. Fetch — call GET .../{id} with that id. While the job runs you'll see an in-progress status; once it's done, the full result is returned.

# 1. submit
curl -X POST https://stg.api.fair-indonesia.com/api/fairservice/email-lookup \
  -H "Authorization: <your_token>" -H "Content-Type: application/json" \
  -d '{ "emails": ["[e-mail]"] }'
# -> { "id": "3a1b...", "status": "IN_PROGRESS" }

# 2. poll until ready
curl https://stg.api.fair-indonesia.com/api/fairservice/email-lookup/3a1b... \
  -H "Authorization: <your_token>"

Async endpoints include search export, profile analytics (async), email lookup, audience overlap, purchase intent, comments relevance, social background check, and social listening. Poll the GET .../{id} endpoint until the status is complete — a few seconds of backoff between polls is plenty.

Webhook delivery is not part of the current public API — use polling. If you need event-driven updates, contact the Fair team.

Pagination

List and search endpoints page with limit and offset:

Field	Meaning
limit	Number of results to return (typically 1–100, default 10)
offset	Number of results to skip

For POST /discovery, limit + offset must stay under 500. For larger result sets, use the asynchronous POST /discovery-export.

Errors

Errors return a consistent JSON shape with a machine-readable error_code:

{
  "error": {
    "type": "INVALID_REQUEST_PARAMETERS",
    "error_code": "product_not_subscribed",
    "message": "Please use the staging environment for a free trial or contact us to enable this product.",
    "request_id": "3a1b6adb-...",
    "http_status_code": 400
  }
}

Status	Common error_code	Meaning
400	product_not_subscribed	The product isn't enabled on your key (see Entitlements)
401	invalid_credentials	Missing or invalid token
422	MISSING_FIELDS	Request failed validation
429	rate_limit_exceeded	Too many requests — back off and retry

Always log the request_id — quote it when contacting support.

Entitlements

Products are enabled per key. If you call a product that isn't enabled on your key, you'll get a 400 with error_code: product_not_subscribed. On staging, most products are available for trial; on production, contact the Fair team to enable the ones you need.

Rate limits

Rate limits depend on your plan. If you hit one you'll get a 429 — back off and retry after a short delay. For your plan's specific limits, check with the Fair team.

Related

• Quickstart
• API Reference
• Dictionaries