# Advertiser API

The calls behind an advertiser’s own screens: the business account, ads, campaigns, funds and the conversion pixel.

Source: https://reachagents.com/docs/api/advertisers

## Calling it
Sign in first ([Accounts and sign-in](/docs/api/accounts)): every call carries the session cookie, `aa_session`, that signing in sets, and a call that changes something carries `x-reachagents-client: web` as well.

Field names are written as the screens’ own code writes them, in camelCase, and amounts are in micros.

Each call runs as the signed-in advertiser, and the database answers with their own business’s rows only. Nothing here says anything about a person, or how many people a campaign could reach.

The conversion pixel’s calls (`/pixel/v1.js` and `/pixel/v1/collect`) are made from the advertiser’s own site, by anyone’s browser, and need no sign-in.

## Read the business account
`GET /api/advertiser/account`

Signed in as an advertiser: the session cookie.

The business, where its review stands, and the balances.

**Answer:** a JSON object.

**Refused with** `unauthorized`, `not_advertiser`.

## List the ads
`GET /api/advertiser/creatives`

Signed in as an advertiser: the session cookie.

Each ad with its versions, and the kinds of file an ad may carry.

**Answer:** a JSON object.

**Refused with** `unauthorized`, `not_advertiser`.

## Write a new ad
`POST /api/advertiser/creatives`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

Makes the ad and its first version, a draft.

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `name` | string, 1 to 120 characters | Yes |
| `headline` | string, at most 120 characters | No: empty if left out |
| `body` | string, at most 4000 characters | No: empty if left out |
| `ctaUrl` | string, at most 500 characters or null | No: `null` if left out |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `creativeId` | string | Yes |
| `versionId` | string | Yes |

**Refused with** `invalid_input`, `unauthorized`, `not_advertiser`, `csrf`.

## Start a new draft of an ad
`POST /api/advertiser/creatives/:id/versions`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

A submitted version never changes: to edit an ad, start a new draft from its latest version.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `versionId` | string | Yes |

**Refused with** `not_found`, `draft_exists`, `unauthorized`, `not_advertiser`, `csrf`.

## Read one version of an ad
`GET /api/advertiser/creative-versions/:id`

Signed in as an advertiser: the session cookie.

Its words, files, screening and reviews, and exactly the record an agent would be asked to keep, built by the code that builds the real one (`recordPreview`).

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer:** a JSON object.

**Refused with** `not_found`, `unauthorized`, `not_advertiser`.

## Change a draft of an ad
`PUT /api/advertiser/creative-versions/:id`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `headline` | string, at most 120 characters | Yes |
| `body` | string, at most 4000 characters | Yes |
| `ctaUrl` | string, at most 500 characters or null | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `not_found`, `invalid_input`, `unauthorized`, `not_advertiser`, `csrf`.

## Attach a file to a draft
`POST /api/advertiser/creative-versions/:id/attachments`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

The file as `multipart/form-data`, in one part. Its type is decided from its bytes, and anything not on the short list of kinds accepted is refused.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `id` | string | Yes |
| `detectedType` | string | Yes |
| `sizeBytes` | integer | Yes |

**Refused with** `not_found`, `submitted`, `no_file`, `unsupported_file`, `file_too_large`, `unauthorized`, `not_advertiser`, `csrf`.

## Remove a file from a draft
`DELETE /api/advertiser/attachments/:id`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

The file is deleted with it.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `not_found`, `unauthorized`, `not_advertiser`, `csrf`.

## Download a file the advertiser attached
`GET /api/advertiser/attachments/:id/file`

Signed in as an advertiser: the session cookie.

Exactly as it was uploaded, sent as an inert file.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer:** `*/*`.

**Refused with** `not_found`, `unauthorized`, `not_advertiser`.

## Submit a version of an ad for screening and review
`POST /api/advertiser/creative-versions/:id/submit`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

Fixes its content: the answer is the hash of exactly what is reviewed, approved and delivered.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `contentSha256` | string | Yes |

**Refused with** `not_found`, `already_submitted`, `unauthorized`, `not_advertiser`, `csrf`.

## List the campaigns
`GET /api/advertiser/campaigns`

Signed in as an advertiser: the session cookie.

Each campaign with its money (available, reserved, spent) and its results on each recent day, and the balances.

**Answer:** a JSON object.

**Refused with** `unauthorized`, `not_advertiser`.

## Read the choices a campaign offers
`GET /api/advertiser/options`

Signed in as an advertiser: the session cookie.

What the campaign form offers: how long a record may be kept, the billing events and which agents support each, the fixed prices, and the ads that can be used.

**Answer:** a JSON object.

**Refused with** `unauthorized`, `not_advertiser`.

## Start a campaign
`POST /api/advertiser/campaigns`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

A draft, for sponsored records or sponsored messages.

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `name` | string, 1 to 120 characters | Yes |
| `product` | one of `memory`, `presentation` | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `id` | string | Yes |

**Refused with** `invalid_input`, `unauthorized`, `not_advertiser`, `csrf`.

## Read one campaign
`GET /api/advertiser/campaigns/:id`

Signed in as an advertiser: the session cookie.

The campaign, its formats, its audience, its ad, the price of one placement, its reviews and its report, and why a live campaign is offered to nobody at the moment, if it is (`stoppedBy`).

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer:** a JSON object.

**Refused with** `not_found`, `unauthorized`, `not_advertiser`.

## Change a campaign
`PUT /api/advertiser/campaigns/:id`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

Every field, each time. Prices are fixed, so the bids are ignored. Once it is submitted, only the name, the end date and the budgets change; the rest is what was reviewed. Amounts are in micros.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `name` | string, 1 to 120 characters | Yes |
| `category` | one of `consumer_tech`, `software`, `finance`, `travel`, `food_beverage`, `retail`, `entertainment`, `education`, `automotive`, `home`, `wellness`, `other` | Yes |
| `creativeVersionId` | string or null | Yes |
| `verificationLevel` | string | Yes |
| `retentionDays` | integer, 1 to 365 or null | Yes |
| `startsAt` | date and time or null | Yes |
| `endsAt` | date and time or null | Yes |
| `budgetMicros` | integer, at least 0 | Yes |
| `dailyCapMicros` | integer, more than 0 or null | Yes |
| `maxPriceMicros` | integer, more than 0 or null | No |
| `minPriceMicros` | integer or null | No |
| `monthlyDisplays` | integer, more than 0 or null | No |
| `frequencyCap` | integer, 1 to 30 | Yes |
| `frequencyGapHours` | integer, 1 to 720 | Yes |
| `targeting` | object | Yes |
| `targeting.regions` | list of one of `northeast`, `midwest`, `south`, `west` | No: `[]` if left out |
| `targeting.states` | list of one of `AK`, `AL`, `AR`, `AZ`, `CA`, `CO`, `CT`, `DC`, `DE`, `FL`, `GA`, `HI`, `IA`, `ID`, `IL`, `IN`, `KS`, `KY`, `LA`, `MA`, `MD`, `ME`, `MI`, `MN`, `MO`, `MS`, `MT`, `NC`, `ND`, `NE`, `NH`, `NJ`, `NM`, `NV`, `NY`, `OH`, `OK`, `OR`, `PA`, `RI`, `SC`, `SD`, `TN`, `TX`, `UT`, `VA`, `VT`, `WA`, `WI`, `WV`, `WY` | No: `[]` if left out |
| `targeting.ageBands` | list of one of `18-24`, `25-34`, `35-44`, `45-54`, `55-64`, `65+` | No: `[]` if left out |
| `targeting.interests` | list of one of `technology`, `software`, `gaming`, `travel`, `food`, `fitness`, `home`, `auto`, `style`, `entertainment`, `sports`, `books`, `personal_finance`, `small_business`, `pets`, `family` | No: `[]` if left out |
| `targeting.agentTypes` | list of one of `grokbot`, `muse`, `dots`, `duet` | No: `[]` if left out |
| `answerTargeting` | object or null | No |
| `answerTargeting.set` | string, at most 40 characters | Yes |
| `answerTargeting.question` | string, at most 40 characters | Yes |
| `answerTargeting.options` | list of string, at most 40 characters, 1 to 50 items | Yes |
| `targetingMode` | one of `broad`, `firm` | No |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `not_found`, `submitted`, `invalid_input`, `unauthorized`, `not_advertiser`, `csrf`.

## Delete a draft campaign
`DELETE /api/advertiser/campaigns/:id`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

A campaign money was ever moved into is kept, with the record of that money.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `not_found`, `unauthorized`, `not_advertiser`, `csrf`.

## Read what a campaign would pay now
`GET /api/advertiser/campaigns/:id/quote`

Signed in as an advertiser: the session cookie.

What one placement costs, for each of the campaign’s formats (`prices`): the fixed price of one display reported for a sponsored message, or of one agent keeping a sponsored record for its days (priced by the month), as it stood when the campaign was submitted, shared into the person’s reward, the fee and processing. Also the price of the campaign’s own format as the release before read it (`now`, `range`, `rates`), and what one result costs with each billing event on offer. A campaign submitted before prices were fixed (`pricing: market`) is quoted as the market priced it.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer:** a JSON object.

**Refused with** `unauthorized`, `not_advertiser`.

## Submit a campaign for review
`POST /api/advertiser/campaigns/:id/submit`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

A person reviews it before it can be launched. What was reviewed (the ad, the audience, the dates) cannot be changed after, unless the campaign is reopened.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `already_submitted`, `advertiser_blocked`, `no_creative`, `creative_draft`, `creative_screening`, `creative_rejected`, `link_required`, `no_budget`, `budget_too_low`, `max_price_too_low`, `retention`, `unauthorized`, `not_advertiser`, `csrf`.

## Reopen a campaign to change what was reviewed
`POST /api/advertiser/campaigns/:id/reopen`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

It goes back to being a draft, and is reviewed again when it is next submitted.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `completed`, `unauthorized`, `not_advertiser`, `csrf`.

## Launch an approved campaign
`POST /api/advertiser/campaigns/:id/launch`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `not_approved`, `advertiser_not_approved`, `creative_not_approved`, `not_funded`, `chargeback_debt`, `paused_by_staff`, `completed`, `ended`, `prices_fixed`, `unauthorized`, `not_advertiser`, `csrf`.

## Pause a campaign
`POST /api/advertiser/campaigns/:id/pause`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `unauthorized`, `not_advertiser`, `csrf`.

## End a campaign
`POST /api/advertiser/campaigns/:id/end`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

For good. What is left in its budget goes back to the account at once, and what its open messages had reserved goes back as each closes. A campaign approved and not yet started can be ended too.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `not_started`, `unauthorized`, `not_advertiser`, `csrf`.

## Move funds from the account into a campaign’s budget
`POST /api/advertiser/campaigns/:id/fund`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`. Send an `Idempotency-Key` of your own for this one request.

In micros. The same Idempotency-Key moves the money once.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `amountMicros` | integer, more than 0 | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `idempotency_key`, `advertiser_not_approved`, `completed`, `invalid_amount`, `invalid_input`, `unauthorized`, `not_advertiser`, `csrf`.

## Move what is left in a campaign’s budget back to the account
`POST /api/advertiser/campaigns/:id/withdraw`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`. Send an `Idempotency-Key` of your own for this one request.

In micros. The same Idempotency-Key moves the money once.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `amountMicros` | integer, more than 0 | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `idempotency_key`, `invalid_amount`, `invalid_input`, `unauthorized`, `not_advertiser`, `csrf`.

## Read the billing screen
`GET /api/advertiser/billing`

Signed in as an advertiser: the session cookie.

The balances, the latest payments, autopay and the bounds it stays inside, and the payment provider. Every movement of the money is the paged list at `/api/advertiser/billing/activity`.

**Answer:** a JSON object.

**Refused with** `unauthorized`, `not_advertiser`.

## Add funds to the account
`POST /api/advertiser/billing/fund`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`. Send an `Idempotency-Key` of your own for this one request.

Starts a payment, in micros: `checkoutUrl` is the provider’s page to pay on, where there is one. Money reaches the account only when the provider confirms it.

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `amountMicros` | integer, more than 0 | Yes |
| `sandboxScenario` | string, at most 40 characters | No |
| `returnTo` | string, at most 200 characters, matching `^\/(ads\|advertiser)(\/[\w\-./]*)?(\?[\w\-=&]*)?$` | No |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `fundingId` | string | Yes |
| `status` | string | Yes |
| `checkoutUrl` | string or null | Yes |

**Refused with** `idempotency_key`, `provider_unavailable`, `advertiser_not_approved`, `invalid_amount`, `invalid_input`, `unauthorized`, `not_advertiser`, `csrf`.

## Turn autopay on or off
`PUT /api/advertiser/billing/autopay`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

Tops the account up from the saved payment method when funds run low: below this much, add this much, and no more than this in a month, in micros. Turning it off is never refused.

**Body**

| Field | Type | Required | About |
| --- | --- | --- | --- |
| `enabled` | one of `false`, `true` | Yes |  |
| `belowMicros` | integer, at least 0 | No | Only where `enabled` is `true`. |
| `amountMicros` | integer, more than 0 | No | Only where `enabled` is `true`. |
| `monthlyCapMicros` | integer, more than 0 | No | Only where `enabled` is `true`. |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `autopay_unavailable`, `amount_out_of_range`, `cap_out_of_range`, `invalid_amount`, `invalid_input`, `unauthorized`, `not_advertiser`, `csrf`.

## Read the brand kit and the products
`GET /api/advertiser/brand`

Signed in as an advertiser: the session cookie.

The brand kit (its logo’s file, main and accent colours, type family and voice), or `null` before one is saved, and the products, oldest first: each one’s name, line, link and photo’s file. A file is read back with `GET /api/advertiser/brand/files/:id/file`.

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `kit` | object or null | Yes |
| `kit.logo_file_id` | string or null | Yes |
| `kit.color` | string or null | Yes |
| `kit.accent` | string or null | Yes |
| `kit.font` | string or null | Yes |
| `kit.voice` | string | Yes |
| `kit.updated_at` | string | Yes |
| `products` | list of objects | Yes |
| `products[].id` | string | Yes |
| `products[].name` | string | Yes |
| `products[].line` | string | Yes |
| `products[].link` | string | Yes |
| `products[].picture_file_id` | string or null | Yes |
| `products[].created_at` | string | Yes |
| `products[].updated_at` | string | Yes |

**Refused with** `unauthorized`, `not_advertiser`.

## Save the brand kit
`PUT /api/advertiser/brand`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

Every field, each time. A colour is `#rrggbb` or `null`; the type family is a name like `Inter`; the voice is plain words, up to the platform’s length. The logo is a file this advertiser uploaded. A refusal about one field names it in `details.field`.

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `logoFileId` | string, at most 40 characters or null | Yes |
| `color` | string, at most 7 characters or null | Yes |
| `accent` | string, at most 7 characters or null | Yes |
| `font` | string, at most 60 characters or null | Yes |
| `voice` | string, at most 2000 characters | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `invalid_color`, `invalid_font`, `voice_too_long`, `file_not_found`, `invalid_input`, `unauthorized`, `not_advertiser`, `csrf`.

## Upload a logo or a product photo
`POST /api/advertiser/brand/files`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

One PNG or JPEG picture as `multipart/form-data`, in one part. Its type is decided from its bytes. Only its owner reads it back.

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `id` | string | Yes |
| `detectedType` | string | Yes |
| `sizeBytes` | integer | Yes |

**Refused with** `no_file`, `unsupported_file`, `file_too_large`, `unauthorized`, `not_advertiser`, `csrf`.

## Read back a logo or a product photo
`GET /api/advertiser/brand/files/:id/file`

Signed in as an advertiser: the session cookie.

Exactly as it was uploaded, sent as an inert file, to the advertiser who uploaded it.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer:** `image/*`.

**Refused with** `not_found`, `unauthorized`, `not_advertiser`.

## Add a product
`POST /api/advertiser/products`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

A name, one line about it, a link (an https address on the advertiser’s own site or a subdomain of it) and, if it has one, a photo this advertiser uploaded. A campaign started from it copies its words, link and photo.

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `name` | string, at most 200 characters | Yes |
| `line` | string, at most 1000 characters | Yes |
| `link` | string, at most 500 characters | Yes |
| `pictureFileId` | string, at most 40 characters or null | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `id` | string | Yes |

**Refused with** `name_required`, `name_too_long`, `line_too_long`, `link_domain`, `file_not_found`, `too_many_products`, `invalid_input`, `unauthorized`, `not_advertiser`, `csrf`.

## Change a product
`PUT /api/advertiser/products/:id`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

Every field, each time. Campaigns started from it keep their own words, link and photo.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `name` | string, at most 200 characters | Yes |
| `line` | string, at most 1000 characters | Yes |
| `link` | string, at most 500 characters | Yes |
| `pictureFileId` | string, at most 40 characters or null | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `id` | string | Yes |

**Refused with** `not_found`, `name_required`, `name_too_long`, `line_too_long`, `link_domain`, `file_not_found`, `invalid_input`, `unauthorized`, `not_advertiser`, `csrf`.

## Remove a product
`DELETE /api/advertiser/products/:id`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

Campaigns started from it keep their own words, link and photo.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `not_found`, `unauthorized`, `not_advertiser`, `csrf`.

## Read the advertiser’s dashboard
`GET /api/advertiser/dashboard`

Signed in as an advertiser: the session cookie.

The business and where its review stands; every campaign with its state (`draft`, `in_review`, `needs_changes`, `approved`, `scheduled`, `live`, `paused`, `ended`), how it is priced (`pricing`: `fixed`, or `market` for one submitted before prices were fixed, which no longer runs), its ad, its audience, its `formats` (in-stream, in memory or both, each with its billing event, retention or package, the price of one placement and its own reserved and spent money), its money from its one budget, and how many agents keep its record now (`agents_keeping`, 0 for one without a record); the balances; the payments made; autopay; the billing events a new campaign may choose, in the words that say what each establishes; and the rules a campaign is held to, the fixed prices among them. Amounts are in micros. No audience size, and nothing about who was reached.

**Answer:** a JSON object.

**Refused with** `unauthorized`, `not_advertiser`.

## Save a campaign and its ad together
`PUT /api/advertiser/campaigns/:id/builder`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

Every field, each time, as the dashboard’s builder saves a draft. The ad’s words are written to its draft version; a submitted version is never changed, so different words make a new draft of the same ad. `formats` adds or takes away the second format, before the first submission only; `retentionDays` is the in-memory format’s and `monthlyDisplays` the in-stream format’s, whichever is the campaign’s own. Prices are fixed, so there is no bid: `maxPriceMicros` is ignored. Once the campaign is submitted, only the name, the end date, the budgets and the package change. Answers with the ad’s version, to attach files to.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `name` | string, 1 to 120 characters | Yes |
| `product` | one of `memory`, `presentation` | Yes |
| `formats` | list of one of `memory`, `presentation`, 1 to 2 items | No |
| `creative` | object | Yes |
| `creative.headline` | string, at most 120 characters | Yes |
| `creative.body` | string, at most 4000 characters | Yes |
| `creative.ctaUrl` | string, at most 500 characters or null | Yes |
| `verificationLevel` | string, at most 40 characters | No |
| `retentionDays` | integer, 1 to 365 or null | Yes |
| `startsAt` | date and time or null | Yes |
| `endsAt` | date and time or null | Yes |
| `budgetMicros` | integer, at least 0 | Yes |
| `dailyCapMicros` | integer, more than 0 or null | Yes |
| `maxPriceMicros` | integer, more than 0 or null | No |
| `monthlyDisplays` | integer, more than 0 or null | No |
| `frequencyCap` | integer, 1 to 30 | Yes |
| `frequencyGapHours` | integer, 1 to 720 | Yes |
| `targeting` | object | Yes |
| `targeting.regions` | list of one of `northeast`, `midwest`, `south`, `west` | No: `[]` if left out |
| `targeting.states` | list of one of `AK`, `AL`, `AR`, `AZ`, `CA`, `CO`, `CT`, `DC`, `DE`, `FL`, `GA`, `HI`, `IA`, `ID`, `IL`, `IN`, `KS`, `KY`, `LA`, `MA`, `MD`, `ME`, `MI`, `MN`, `MO`, `MS`, `MT`, `NC`, `ND`, `NE`, `NH`, `NJ`, `NM`, `NV`, `NY`, `OH`, `OK`, `OR`, `PA`, `RI`, `SC`, `SD`, `TN`, `TX`, `UT`, `VA`, `VT`, `WA`, `WI`, `WV`, `WY` | No: `[]` if left out |
| `targeting.ageBands` | list of one of `18-24`, `25-34`, `35-44`, `45-54`, `55-64`, `65+` | No: `[]` if left out |
| `targeting.interests` | list of one of `technology`, `software`, `gaming`, `travel`, `food`, `fitness`, `home`, `auto`, `style`, `entertainment`, `sports`, `books`, `personal_finance`, `small_business`, `pets`, `family` | No: `[]` if left out |
| `targeting.agentTypes` | list of one of `grokbot`, `muse`, `dots`, `duet` | No: `[]` if left out |
| `targetingMode` | one of `broad`, `firm` | No |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |
| `creativeVersionId` | string or null | Yes |

**Refused with** `not_found`, `format_fixed`, `formats_invalid`, `part_of_campaign`, `ends_before_start`, `billing_event_retired`, `package_needs_displays`, `invalid_input`, `unauthorized`, `not_advertiser`, `csrf`.

## Launch a campaign: submit it, fund it, and run it once approved
`POST /api/advertiser/campaigns/:id/request-launch`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`. Send an `Idempotency-Key` of your own for this one request.

Submits the campaign (and its ad, if that is still a draft), moves its budget in from the balance where the business is approved and the balance holds it, and goes live now if it is already approved, or by itself the moment a reviewer approves it. While the business is in review no funds move: `shortMicros` says what it still needs. A refusal about one field names it in `details.field`. The same Idempotency-Key moves the money once.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `movedMicros` | integer | Yes |
| `shortMicros` | integer | Yes |
| `state` | string | Yes |

**Refused with** `idempotency_key`, `completed`, `already_submitted`, `creative_screening`, `creative_rejected`, `budget_below_minimum`, `daily_below_minimum`, `daily_above_budget`, `price_below_costs`, `budget_too_low`, `not_funded`, `prices_fixed`, `unauthorized`, `not_advertiser`, `csrf`.

## Resume a paused campaign
`POST /api/advertiser/campaigns/:id/resume`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

The same as launching it again: it must still be approved and funded, and one staff paused stays paused.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `not_approved`, `not_funded`, `paused_by_staff`, `completed`, `ended`, `prices_fixed`, `unauthorized`, `not_advertiser`, `csrf`.

## Move money so the campaign holds its budget
`POST /api/advertiser/campaigns/:id/budget`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`. Send an `Idempotency-Key` of your own for this one request.

After the budget changes: a raised budget moves the difference in from the balance, a lowered one moves it back. Answers with what moved, in micros (in is positive). The same Idempotency-Key moves the money once.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `movedMicros` | integer | Yes |

**Refused with** `idempotency_key`, `advertiser_not_approved`, `not_enough_funds`, `unauthorized`, `not_advertiser`, `csrf`.

## Copy a campaign to a new draft
`POST /api/advertiser/campaigns/:id/duplicate`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

Its formats, its settings, its ad and its audience, at the fixed prices, and nothing of its money, its reviews or its dates.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `id` | string | Yes |

**Refused with** `not_found`, `unauthorized`, `not_advertiser`, `csrf`.

## Read what was done to a campaign
`GET /api/advertiser/campaigns/:id/history`

Signed in as an advertiser: the session cookie.

Oldest first: submitted, checked, approved or sent back (with what the reviewer said), live, paused, resumed, reopened, ended, its unspent budget returned. Who did it is `you`, `reviewer` or `platform`.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer:** a JSON object.

**Refused with** `not_found`, `unauthorized`, `not_advertiser`.

## Read the account’s figures by day and campaign
`GET /api/advertiser/reports/daily`

Signed in as an advertiser: the session cookie.

For each day from `from` to `to` (days of the reporting time zone; a range longer than the platform allows is refused, saying how long it may be), each campaign that launched and each of its formats (`product`), narrowed to one campaign with `campaign`: placements offered, the results it is billed on (displays reported by agents, or days a record was kept and checked), visits the advertiser’s pixel counted from the ad’s link (`visits`, also given as `clicks` for the release before), conversions the pixel attributed, and spend in micros. Days with nothing counted are left out. Nothing is split by who was reached.

**In the query**

| Field | Type | Required |
| --- | --- | --- |
| `from` | string, matching `^\d{4}-\d{2}-\d{2}$` | Yes |
| `to` | string, matching `^\d{4}-\d{2}-\d{2}$` | Yes |
| `campaign` | string, at most 40 characters | No |

**Answer:** a JSON object.

**Refused with** `invalid_range`, `range_too_long`, `invalid_input`, `unauthorized`, `not_advertiser`.

## List the saved audiences
`GET /api/advertiser/audiences`

Signed in as an advertiser: the session cookie.

The account’s saved audiences, most recently changed first: each one’s name and the targeting it holds (states, age bands, interests, agent types; an empty list means any). Never a size, and nothing about who matches.

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `audiences` | list of objects | Yes |
| `audiences[].id` | string | Yes |
| `audiences[].name` | string | Yes |
| `audiences[].states` | list of string | Yes |
| `audiences[].ageBands` | list of string | Yes |
| `audiences[].interests` | list of string | Yes |
| `audiences[].agentTypes` | list of string | Yes |
| `audiences[].created_at` | string | Yes |
| `audiences[].updated_at` | string | Yes |

**Refused with** `unauthorized`, `not_advertiser`.

## Save an audience
`POST /api/advertiser/audiences`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

A name and the targeting a campaign can hold, from the vocabularies only. To use it on a campaign, the dashboard copies it into the campaign’s targeting through the builder; the campaign keeps that targeting whatever later happens to the audience.

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `name` | string, at most 200 characters | Yes |
| `states` | list of one of `AK`, `AL`, `AR`, `AZ`, `CA`, `CO`, `CT`, `DC`, `DE`, `FL`, `GA`, `HI`, `IA`, `ID`, `IL`, `IN`, `KS`, `KY`, `LA`, `MA`, `MD`, `ME`, `MI`, `MN`, `MO`, `MS`, `MT`, `NC`, `ND`, `NE`, `NH`, `NJ`, `NM`, `NV`, `NY`, `OH`, `OK`, `OR`, `PA`, `RI`, `SC`, `SD`, `TN`, `TX`, `UT`, `VA`, `VT`, `WA`, `WI`, `WV`, `WY`, at most 51 items | No: `[]` if left out |
| `ageBands` | list of one of `18-24`, `25-34`, `35-44`, `45-54`, `55-64`, `65+`, at most 6 items | No: `[]` if left out |
| `interests` | list of one of `technology`, `software`, `gaming`, `travel`, `food`, `fitness`, `home`, `auto`, `style`, `entertainment`, `sports`, `books`, `personal_finance`, `small_business`, `pets`, `family`, at most 16 items | No: `[]` if left out |
| `agentTypes` | list of one of `grokbot`, `muse`, `dots`, `duet`, at most 4 items | No: `[]` if left out |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `id` | string | Yes |

**Refused with** `name_required`, `name_too_long`, `too_many_audiences`, `invalid_input`, `unauthorized`, `not_advertiser`, `csrf`.

## Change a saved audience
`PUT /api/advertiser/audiences/:id`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

Every field, each time. Campaigns started from it keep their own targeting.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `name` | string, at most 200 characters | Yes |
| `states` | list of one of `AK`, `AL`, `AR`, `AZ`, `CA`, `CO`, `CT`, `DC`, `DE`, `FL`, `GA`, `HI`, `IA`, `ID`, `IL`, `IN`, `KS`, `KY`, `LA`, `MA`, `MD`, `ME`, `MI`, `MN`, `MO`, `MS`, `MT`, `NC`, `ND`, `NE`, `NH`, `NJ`, `NM`, `NV`, `NY`, `OH`, `OK`, `OR`, `PA`, `RI`, `SC`, `SD`, `TN`, `TX`, `UT`, `VA`, `VT`, `WA`, `WI`, `WV`, `WY`, at most 51 items | No: `[]` if left out |
| `ageBands` | list of one of `18-24`, `25-34`, `35-44`, `45-54`, `55-64`, `65+`, at most 6 items | No: `[]` if left out |
| `interests` | list of one of `technology`, `software`, `gaming`, `travel`, `food`, `fitness`, `home`, `auto`, `style`, `entertainment`, `sports`, `books`, `personal_finance`, `small_business`, `pets`, `family`, at most 16 items | No: `[]` if left out |
| `agentTypes` | list of one of `grokbot`, `muse`, `dots`, `duet`, at most 4 items | No: `[]` if left out |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `id` | string | Yes |

**Refused with** `not_found`, `name_required`, `name_too_long`, `invalid_input`, `unauthorized`, `not_advertiser`, `csrf`.

## Delete a saved audience
`DELETE /api/advertiser/audiences/:id`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

Campaigns started from it keep their own targeting.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `ok` | `true` | Yes |

**Refused with** `not_found`, `unauthorized`, `not_advertiser`, `csrf`.

## Open an invitation’s link
`POST /api/advertiser/invitation/open`

No sign-in. Send `x-reachagents-client: web`.

For the sign-up page the link opens, before anyone is signed in: the address to fill in, and until when the link works.

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `token` | string, 16 to 200 characters | Yes |

**Answer:** a JSON object.

**Refused with** `rate_limited`, `unknown_invitation`, `invitation_expired`, `invitation_used`, `invitation_withdrawn`, `invalid_input`, `csrf`.

## Read whether a new advertiser account needs an invitation
`GET /api/advertiser/invitation`

Signed in: the session cookie.

For someone signed in and about to make an advertiser account: whether one needs an invitation here, and until when theirs works if they have one.

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `byInvitation` | boolean | Yes |
| `expiresAt` | string or null | Yes |

**Refused with** `unauthorized`.

## List every movement of the advertiser’s funds
`GET /api/advertiser/billing/activity`

Signed in as an advertiser: the session cookie.

Each entry of the account balance and of the campaigns’ budgets, newest first. A page at a time: `q` searches it (every word, in any column it shows, whatever the capitals or accents), `sort` and `dir` order it, `after` and `before` name where a page begins (`next` and `previous` in the answer), and `format=csv` sends the whole selection as a file instead. `sort` takes one of `when`, `amount`.

**In the query**

| Field | Type | Required |
| --- | --- | --- |
| `q` | string, at most 200 characters | No: empty if left out |
| `sort` | string, at most 40 characters | No |
| `dir` | one of `asc`, `desc` | No: `desc` if left out |
| `page` | integer, at least 1 | No |
| `per` | integer, at least 1 | No |
| `after` | string, at most 2000 characters | No |
| `before` | string, at most 2000 characters | No |
| `from` | string, matching `^\d{4}-\d{2}-\d{2}$` | No |
| `format` | `csv` | No |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `rows` | list of object of string to anything | Yes |
| `total` | integer | Yes |
| `more` | boolean | Yes |
| `next` | string or null | Yes |
| `previous` | string or null | Yes |

**Refused with** `too_long_to_export`, `invalid_input`, `unauthorized`, `not_advertiser`.

## Read what campaigns were charged on each day
`GET /api/advertiser/billing/spent-by-day`

Signed in as an advertiser: the session cookie.

In micros. Days are the platform’s reporting days, ending today, and only a day on which something happened is sent.

**In the query**

| Field | Type | Required |
| --- | --- | --- |
| `tz` | string, at most 64 characters | No |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `today` | string | Yes |
| `days` | integer | Yes |
| `rows` | list of objects | Yes |
| `rows[].day` | string | Yes |
| `rows[].value` | number | Yes |
| `rows[].part` | string | No |

**Refused with** `invalid_input`, `unauthorized`, `not_advertiser`.

## Read what the advertiser added on each day
`GET /api/advertiser/billing/added-by-day`

Signed in as an advertiser: the session cookie.

Their own payments the provider confirmed, on the day it confirmed them, in micros. Days are the platform’s reporting days, ending today, and only a day on which something happened is sent.

**In the query**

| Field | Type | Required |
| --- | --- | --- |
| `tz` | string, at most 64 characters | No |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `today` | string | Yes |
| `days` | integer | Yes |
| `rows` | list of objects | Yes |
| `rows[].day` | string | Yes |
| `rows[].value` | number | Yes |
| `rows[].part` | string | No |

**Refused with** `invalid_input`, `unauthorized`, `not_advertiser`.

## Load the conversion pixel’s script
`GET /pixel/v1.js`

No sign-in.

For the advertiser’s own site. It keeps a sponsored message’s click id in one cookie of that site, sets none of its own, and sends only the events the site reports. Any site may load it.

**Answer:** `text/javascript`.

## Send a conversion event
`POST /pixel/v1/collect`

No sign-in.

What the script sends, as JSON in a text body so that no preflight is needed. It answers the same whether the event was kept, dropped as out of shape or over the limit, or came from a program: the sender is told nothing.

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `pixel` | string, matching `^pix_[0-9a-f]{20}$` | Yes |
| `event` | string, at most 40 characters | Yes |
| `click` | string, at most 64 characters | No |
| `value` | number, at least 0 | No |
| `currency` | string, at most 3 characters | No |
| `order_id` | string, at most 100 characters | No |

**Answer:** 204, with nothing.

## Send a conversion event as an image
`GET /pixel/v1/collect`

No sign-in.

For a page that cannot run the script: the same fields in the address of an image, which answers with a transparent pixel. It answers the same whether the event was kept, dropped as out of shape or over the limit, or came from a program: the sender is told nothing.

**In the query**

| Field | Type | Required |
| --- | --- | --- |
| `pixel` | string, matching `^pix_[0-9a-f]{20}$` | Yes |
| `event` | string, at most 40 characters | Yes |
| `click` | string, at most 64 characters | No |
| `value` | number, at least 0 | No |
| `currency` | string, at most 3 characters | No |
| `order_id` | string, at most 100 characters | No |

**Answer:** `image/gif`.

## Read the advertiser’s pixel and what it received
`GET /api/advertiser/pixel`

Signed in as an advertiser: the session cookie.

The pixel, the events it received lately, and what to put on the site to install it.

**Answer:** a JSON object.

**Refused with** `unauthorized`, `not_advertiser`.

## Make the advertiser’s pixel
`POST /api/advertiser/pixel`

Signed in as an advertiser: the session cookie. Send `x-reachagents-client: web`.

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `id` | string | Yes |

**Refused with** `unauthorized`, `not_advertiser`, `csrf`.

## Read a campaign’s conversions
`GET /api/advertiser/campaigns/:id/conversions`

Signed in as an advertiser: the session cookie.

Totals only, by day in the time zone named (`tz`): what the pixel attributed to the campaign.

**In the path**

| Field | Type | Required |
| --- | --- | --- |
| `id` | string | Yes |

**In the query**

| Field | Type | Required |
| --- | --- | --- |
| `tz` | string, at most 64 characters | No |

**Answer:** a JSON object.

**Refused with** `invalid_input`, `unauthorized`, `not_advertiser`.

## Register a business as an advertiser
`POST /api/advertiser/join`

Signed in: the session cookie. Send `x-reachagents-client: web`.

Makes the signed-in account an advertiser, for the business at this website. Where advertisers join by invitation, it needs one.

**Body**

| Field | Type | Required |
| --- | --- | --- |
| `name` | string, 2 to 80 characters | Yes |
| `website` | string, 3 to 200 characters | Yes |

**Answer**

| Field | Type | Always sent |
| --- | --- | --- |
| `advertiserId` | string | Yes |

**Refused with** `invalid_website`, `already_advertiser`, `domain_taken`, `invitation_required`, `invalid_input`, `unauthorized`, `csrf`.
