---
url: https://docs.dataflair.ai/marketplace/ad-server-api/operations/health.md
description: >-
  The read-only probe DataFlair runs to confirm your credential and read your
  account timezone, currency and capabilities.
---

# GET /health: Connect and verify

DataFlair calls this endpoint first, when an operator connects your platform. It is a cheap, read-only request. It confirms three things at once: your credential works, DataFlair reached the right account, and DataFlair can read your account context.

## What we send

::: code-group

```http [HTTP]
GET /health HTTP/1.1
Host: ads.example.com
Authorization: Bearer sk_live_9f2c…
```

```bash [curl]
curl "$BASE_URL/health" \
  -H "Authorization: Bearer $API_KEY"
```

:::

DataFlair appends `/health` to the base URL you entered. A base URL of `https://ads.example.com/api/v1` gives `https://ads.example.com/api/v1/health`. If your base URL has a query string, DataFlair keeps it and puts the path before it.

## What you return

Status `200` with a JSON body:

::: code-group

```json \[exemplary/health/expected-response.json]
{
  "account_id": "acct_1029",
  "account_name": "Example Media Network",
  "timezone": "Europe/Berlin",
  "currency": "EUR",
  "capabilities": {
    "forecast": true,
    "reporting": true,
    "draft_booking": true
  }
}

```

:::

The JSON on this page is read from the [fixture files](/marketplace/ad-server-api/fixtures), so it cannot drift from the test suite.

## Fields

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `account_id` | string | yes | Your id for the account. It must not be empty. |
| `account_name` | string | no | Display only. DataFlair shows it on the connection card. |
| `timezone` | string | yes | The IANA timezone your platform books flights in, for example `Europe/Berlin`. DataFlair sends and reads all flight dates in this zone. A value that is not a real IANA identifier, such as `UTC+2`, is rejected. |
| `currency` | string | yes | ISO-4217 code in three uppercase letters, for example `EUR`. DataFlair checks that a booking's currency matches it before it pushes an order. A value such as `EURO` is rejected. |
| `capabilities` | object | yes | Three flags, each a JSON boolean. |
| `capabilities.forecast` | boolean | yes | Whether `POST /forecast` works. Declare `true`. `false` is a degraded state: DataFlair then shows the availability you list instead of a live forecast. |
| `capabilities.reporting` | boolean | yes | Declare `true`. A response with `false` is rejected. |
| `capabilities.draft_booking` | boolean | yes | Declare `true`. A response with `false` is rejected. |

`inventory_read` is not in this object. You cannot turn `GET /inventory` off, so there is nothing to declare. DataFlair confirms it the first time a real `GET /inventory` call succeeds.

## Errors

| Status | What caused it | What the operator sees in DataFlair | What to do |
| --- | --- | --- | --- |
| `401` | Missing, invalid or expired key. | State `auth_error`: "DataFlair could not authenticate. Check your API key, then reconnect." | Check the key. Issue a new one if needed. |
| `403` | The key authenticated but lacks a required scope. | State `forbidden`: "Your API key doesn't have the required scope. Update its permissions on your ad server, then reconnect." | Give the key read, create-draft and report scope. |
| `400`, `404`, `429`, any other `4xx`, any `5xx`, or no answer | Malformed request, wrong base URL, rate limit, server error, or a timeout. | State `unreachable`: "Your ad server could not be reached. Check the base URL, then reconnect." | Check the base URL, then check your server's logs. |
| `200` with a body that does not match the fields above | A missing or empty `account_id`, an invalid `timezone` or `currency`, a `capabilities` flag that is not a boolean, or `reporting` or `draft_booking` set to `false`. | State `invalid_response`: "Your ad server responded, but not in the documented /health shape. Check your /health endpoint, then reconnect." | Fix the body. See Fields. |

DataFlair also stores the `message` from your error body as the last error, with credentials redacted. Return a JSON body of the form `{ "code": "...", "message": "..." }`, as described in [Conventions](/marketplace/ad-server-api/conventions#error-model). Do not put secrets in `message`.

DataFlair does not follow redirects. Serve `/health` at the exact base URL you entered.

## Timeouts and retries

DataFlair waits up to 10 seconds to connect and 30 seconds in total for this call. These are the platform's configured defaults. DataFlair does not retry a failed `/health` call. The operator presses **Re-verify** in DataFlair to try again.

DataFlair resolves your host on every call. The host must resolve to public addresses only. A host that resolves to a private, loopback or internal address is refused.

## Verify

Run the [conformance check](/marketplace/ad-server-api/conformance) with `--only health` to check this endpoint against the [fixtures](/marketplace/ad-server-api/fixtures).