> For the complete documentation index, see [llms.txt](https://fair-indonesia.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fair-indonesia.gitbook.io/docs/developers/concepts.md).

# Core Concepts

Everything you need to understand before working through the [API Reference](/docs/developers/api-reference.md). 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](/docs/developers/authentication.md) 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.

```bash
# 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": ["creator@example.com"] }'
# -> { "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.

{% hint style="info" %}
Webhook delivery is not part of the current public API — use polling. If you need event-driven updates, [contact the Fair team](https://app.fair-influence.com/login).
{% endhint %}

## 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`:

```json
{
  "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](https://app.fair-influence.com/login) 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](/docs/developers/quickstart.md)
* [API Reference](/docs/developers/api-reference.md)
* [Dictionaries](/docs/developers/dictionaries.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://fair-indonesia.gitbook.io/docs/developers/concepts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.