# Contacts

Pull resolved people for one pixel. You need the API key and the canonical `pixel_id` from [Setup](/docs/setup.md).

Header: `Authorization: Bearer <api_key>`. The account must be active. A paid key sees its own pixels. An unlimited key may read any pixel. Someone else's pixel is 404 `pixel not found`.

Pass `on` or `after`. Sending both is 400 `pass on or after, not both`. Sending neither is 400 `pass on or after`.

## By day

`GET /v1/pixels/{pixel_id}/contacts?on=YYYY-MM-DD`

`on` is a UTC date. 400 `on must be YYYY-MM-DD` otherwise.

200:

```json
{"pixel_id": "...", "on": "2026-10-06", "contacts": [{"id": 1, "hem": "<64 hex chars>", "resolved_at": "2026-10-06T15:04:05+00:00", "contact": {}}]}
```

The list is people whose first resolved UTC day is that date, in `id` order. An update does not move the day. `contact` is whatever was stored.

## By id

`GET /v1/pixels/{pixel_id}/contacts?after=0`

Start at `0`. 200 returns `after`, `high_water`, and `contacts` with id greater than `after`, in id order. `high_water` is the last id in this response, or the `after` you sent when the list is empty.

The next call is `after={high_water}`. The same `after` returns the same rows. This cursor is not consumed.

`after` must be zero or greater.

## What a contact is

Each item is `id` (integer), `hem` (64 hex characters), `resolved_at` (UTC ISO-8601), and `contact` (object). Read `contact` for the person's fields. Do not assume a fixed set of name or email keys beyond what that object contains.

## Storing people

Customers read with GET. `POST /v1/pixels/{pixel_id}/contacts` stores people that are already resolved:

```json
{"contacts": [{"hem": "<64 hex chars>", "seen_at": "2026-10-06T15:04:05Z", "contact": {"email": "ada@example.com"}}]}
```

A `contact` of `null` or `{}` is skipped. A bad `hem` or `seen_at` fails the whole call with 400. 200 returns `stored`, which counts writes and updates and skips misses. Updating a known `hem` replaces `contact` and keeps `id` and the first `resolved_at`.

## Quote

`GET /v1/billing/quote` returns `contact_count`, `setup_cents`, `contact_cents`, `usage_cents`, and `total_cents`. A paid account is $1 per month, with zero usage charges. An unlimited account is zero. This call does not charge the card.