Advertiser API
The calls behind an advertiser’s own screens: the business account, ads, campaigns, funds and the conversion pixel.
Calling it
Sign in first (Accounts and sign-in): 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.