Skip to Content
Docs

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

FieldTypeRequired
namestring, 1 to 120 charactersYes
headlinestring, at most 120 charactersNo: empty if left out
bodystring, at most 4000 charactersNo: empty if left out
ctaUrlstring, at most 500 characters or nullNo: null if left out

Answer

FieldTypeAlways sent
creativeIdstringYes
versionIdstringYes

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

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
versionIdstringYes

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

FieldTypeRequired
idstringYes

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

FieldTypeRequired
idstringYes

Body

FieldTypeRequired
headlinestring, at most 120 charactersYes
bodystring, at most 4000 charactersYes
ctaUrlstring, at most 500 characters or nullYes

Answer

FieldTypeAlways sent
oktrueYes

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

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
idstringYes
detectedTypestringYes
sizeBytesintegerYes

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

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
oktrueYes

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

FieldTypeRequired
idstringYes

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

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
contentSha256stringYes

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

FieldTypeRequired
namestring, 1 to 120 charactersYes
productone of memory, presentationYes

Answer

FieldTypeAlways sent
idstringYes

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

FieldTypeRequired
idstringYes

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

FieldTypeRequired
idstringYes

Body

FieldTypeRequired
namestring, 1 to 120 charactersYes
categoryone of consumer_tech, software, finance, travel, food_beverage, retail, entertainment, education, automotive, home, wellness, otherYes
creativeVersionIdstring or nullYes
verificationLevelstringYes
retentionDaysinteger, 1 to 365 or nullYes
startsAtdate and time or nullYes
endsAtdate and time or nullYes
budgetMicrosinteger, at least 0Yes
dailyCapMicrosinteger, more than 0 or nullYes
maxPriceMicrosinteger, more than 0 or nullNo
minPriceMicrosinteger or nullNo
monthlyDisplaysinteger, more than 0 or nullNo
frequencyCapinteger, 1 to 30Yes
frequencyGapHoursinteger, 1 to 720Yes
targetingobjectYes
targeting.regionslist of one of northeast, midwest, south, westNo: [] if left out
targeting.stateslist 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, WYNo: [] if left out
targeting.ageBandslist of one of 18-24, 25-34, 35-44, 45-54, 55-64, 65+No: [] if left out
targeting.interestslist of one of technology, software, gaming, travel, food, fitness, home, auto, style, entertainment, sports, books, personal_finance, small_business, pets, familyNo: [] if left out
targeting.agentTypeslist of one of grokbot, muse, dots, duetNo: [] if left out
answerTargetingobject or nullNo
answerTargeting.setstring, at most 40 charactersYes
answerTargeting.questionstring, at most 40 charactersYes
answerTargeting.optionslist of string, at most 40 characters, 1 to 50 itemsYes
targetingModeone of broad, firmNo

Answer

FieldTypeAlways sent
oktrueYes

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

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
oktrueYes

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

FieldTypeRequired
idstringYes

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

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
oktrueYes

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

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
oktrueYes

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

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
oktrueYes

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

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
oktrueYes

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

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
oktrueYes

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

FieldTypeRequired
idstringYes

Body

FieldTypeRequired
amountMicrosinteger, more than 0Yes

Answer

FieldTypeAlways sent
oktrueYes

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

FieldTypeRequired
idstringYes

Body

FieldTypeRequired
amountMicrosinteger, more than 0Yes

Answer

FieldTypeAlways sent
oktrueYes

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

FieldTypeRequired
amountMicrosinteger, more than 0Yes
sandboxScenariostring, at most 40 charactersNo
returnTostring, at most 200 characters, matching ^\/(ads|advertiser)(\/[\w\-./]*)?(\?[\w\-=&]*)?$No

Answer

FieldTypeAlways sent
fundingIdstringYes
statusstringYes
checkoutUrlstring or nullYes

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

FieldTypeRequiredAbout
enabledone of false, trueYes
belowMicrosinteger, at least 0NoOnly where enabled is true.
amountMicrosinteger, more than 0NoOnly where enabled is true.
monthlyCapMicrosinteger, more than 0NoOnly where enabled is true.

Answer

FieldTypeAlways sent
oktrueYes

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

FieldTypeAlways sent
kitobject or nullYes
kit.logo_file_idstring or nullYes
kit.colorstring or nullYes
kit.accentstring or nullYes
kit.fontstring or nullYes
kit.voicestringYes
kit.updated_atstringYes
productslist of objectsYes
products[].idstringYes
products[].namestringYes
products[].linestringYes
products[].linkstringYes
products[].picture_file_idstring or nullYes
products[].created_atstringYes
products[].updated_atstringYes

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

FieldTypeRequired
logoFileIdstring, at most 40 characters or nullYes
colorstring, at most 7 characters or nullYes
accentstring, at most 7 characters or nullYes
fontstring, at most 60 characters or nullYes
voicestring, at most 2000 charactersYes

Answer

FieldTypeAlways sent
oktrueYes

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

FieldTypeAlways sent
idstringYes
detectedTypestringYes
sizeBytesintegerYes

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

FieldTypeRequired
idstringYes

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

FieldTypeRequired
namestring, at most 200 charactersYes
linestring, at most 1000 charactersYes
linkstring, at most 500 charactersYes
pictureFileIdstring, at most 40 characters or nullYes

Answer

FieldTypeAlways sent
idstringYes

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

FieldTypeRequired
idstringYes

Body

FieldTypeRequired
namestring, at most 200 charactersYes
linestring, at most 1000 charactersYes
linkstring, at most 500 charactersYes
pictureFileIdstring, at most 40 characters or nullYes

Answer

FieldTypeAlways sent
idstringYes

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

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
oktrueYes

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

FieldTypeRequired
idstringYes

Body

FieldTypeRequired
namestring, 1 to 120 charactersYes
productone of memory, presentationYes
formatslist of one of memory, presentation, 1 to 2 itemsNo
creativeobjectYes
creative.headlinestring, at most 120 charactersYes
creative.bodystring, at most 4000 charactersYes
creative.ctaUrlstring, at most 500 characters or nullYes
verificationLevelstring, at most 40 charactersNo
retentionDaysinteger, 1 to 365 or nullYes
startsAtdate and time or nullYes
endsAtdate and time or nullYes
budgetMicrosinteger, at least 0Yes
dailyCapMicrosinteger, more than 0 or nullYes
maxPriceMicrosinteger, more than 0 or nullNo
monthlyDisplaysinteger, more than 0 or nullNo
frequencyCapinteger, 1 to 30Yes
frequencyGapHoursinteger, 1 to 720Yes
targetingobjectYes
targeting.regionslist of one of northeast, midwest, south, westNo: [] if left out
targeting.stateslist 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, WYNo: [] if left out
targeting.ageBandslist of one of 18-24, 25-34, 35-44, 45-54, 55-64, 65+No: [] if left out
targeting.interestslist of one of technology, software, gaming, travel, food, fitness, home, auto, style, entertainment, sports, books, personal_finance, small_business, pets, familyNo: [] if left out
targeting.agentTypeslist of one of grokbot, muse, dots, duetNo: [] if left out
targetingModeone of broad, firmNo

Answer

FieldTypeAlways sent
oktrueYes
creativeVersionIdstring or nullYes

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

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
movedMicrosintegerYes
shortMicrosintegerYes
statestringYes

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

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
oktrueYes

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

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
movedMicrosintegerYes

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

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
idstringYes

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

FieldTypeRequired
idstringYes

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

FieldTypeRequired
fromstring, matching ^\d{4}-\d{2}-\d{2}$Yes
tostring, matching ^\d{4}-\d{2}-\d{2}$Yes
campaignstring, at most 40 charactersNo

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

FieldTypeAlways sent
audienceslist of objectsYes
audiences[].idstringYes
audiences[].namestringYes
audiences[].stateslist of stringYes
audiences[].ageBandslist of stringYes
audiences[].interestslist of stringYes
audiences[].agentTypeslist of stringYes
audiences[].created_atstringYes
audiences[].updated_atstringYes

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

FieldTypeRequired
namestring, at most 200 charactersYes
stateslist 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 itemsNo: [] if left out
ageBandslist of one of 18-24, 25-34, 35-44, 45-54, 55-64, 65+, at most 6 itemsNo: [] if left out
interestslist of one of technology, software, gaming, travel, food, fitness, home, auto, style, entertainment, sports, books, personal_finance, small_business, pets, family, at most 16 itemsNo: [] if left out
agentTypeslist of one of grokbot, muse, dots, duet, at most 4 itemsNo: [] if left out

Answer

FieldTypeAlways sent
idstringYes

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

FieldTypeRequired
idstringYes

Body

FieldTypeRequired
namestring, at most 200 charactersYes
stateslist 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 itemsNo: [] if left out
ageBandslist of one of 18-24, 25-34, 35-44, 45-54, 55-64, 65+, at most 6 itemsNo: [] if left out
interestslist of one of technology, software, gaming, travel, food, fitness, home, auto, style, entertainment, sports, books, personal_finance, small_business, pets, family, at most 16 itemsNo: [] if left out
agentTypeslist of one of grokbot, muse, dots, duet, at most 4 itemsNo: [] if left out

Answer

FieldTypeAlways sent
idstringYes

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

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
oktrueYes

Refused with not_found, unauthorized, not_advertiser, csrf.

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

FieldTypeRequired
tokenstring, 16 to 200 charactersYes

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

FieldTypeAlways sent
byInvitationbooleanYes
expiresAtstring or nullYes

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

FieldTypeRequired
qstring, at most 200 charactersNo: empty if left out
sortstring, at most 40 charactersNo
dirone of asc, descNo: desc if left out
pageinteger, at least 1No
perinteger, at least 1No
afterstring, at most 2000 charactersNo
beforestring, at most 2000 charactersNo
fromstring, matching ^\d{4}-\d{2}-\d{2}$No
formatcsvNo

Answer

FieldTypeAlways sent
rowslist of object of string to anythingYes
totalintegerYes
morebooleanYes
nextstring or nullYes
previousstring or nullYes

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

FieldTypeRequired
tzstring, at most 64 charactersNo

Answer

FieldTypeAlways sent
todaystringYes
daysintegerYes
rowslist of objectsYes
rows[].daystringYes
rows[].valuenumberYes
rows[].partstringNo

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

FieldTypeRequired
tzstring, at most 64 charactersNo

Answer

FieldTypeAlways sent
todaystringYes
daysintegerYes
rowslist of objectsYes
rows[].daystringYes
rows[].valuenumberYes
rows[].partstringNo

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

FieldTypeRequired
pixelstring, matching ^pix_[0-9a-f]{20}$Yes
eventstring, at most 40 charactersYes
clickstring, at most 64 charactersNo
valuenumber, at least 0No
currencystring, at most 3 charactersNo
order_idstring, at most 100 charactersNo

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

FieldTypeRequired
pixelstring, matching ^pix_[0-9a-f]{20}$Yes
eventstring, at most 40 charactersYes
clickstring, at most 64 charactersNo
valuenumber, at least 0No
currencystring, at most 3 charactersNo
order_idstring, at most 100 charactersNo

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

FieldTypeAlways sent
idstringYes

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

FieldTypeRequired
idstringYes

In the query

FieldTypeRequired
tzstring, at most 64 charactersNo

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

FieldTypeRequired
namestring, 2 to 80 charactersYes
websitestring, 3 to 200 charactersYes

Answer

FieldTypeAlways sent
advertiserIdstringYes

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

On this page

Calling itRead the business accountList the adsWrite a new adStart a new draft of an adRead one version of an adChange a draft of an adAttach a file to a draftRemove a file from a draftDownload a file the advertiser attachedSubmit a version of an ad for screening and reviewList the campaignsRead the choices a campaign offersStart a campaignRead one campaignChange a campaignDelete a draft campaignRead what a campaign would pay nowSubmit a campaign for reviewReopen a campaign to change what was reviewedLaunch an approved campaignPause a campaignEnd a campaignMove funds from the account into a campaign’s budgetMove what is left in a campaign’s budget back to the accountRead the billing screenAdd funds to the accountTurn autopay on or offRead the brand kit and the productsSave the brand kitUpload a logo or a product photoRead back a logo or a product photoAdd a productChange a productRemove a productRead the advertiser’s dashboardSave a campaign and its ad togetherLaunch a campaign: submit it, fund it, and run it once approvedResume a paused campaignMove money so the campaign holds its budgetCopy a campaign to a new draftRead what was done to a campaignRead the account’s figures by day and campaignList the saved audiencesSave an audienceChange a saved audienceDelete a saved audienceOpen an invitation’s linkRead whether a new advertiser account needs an invitationList every movement of the advertiser’s fundsRead what campaigns were charged on each dayRead what the advertiser added on each dayLoad the conversion pixel’s scriptSend a conversion eventSend a conversion event as an imageRead the advertiser’s pixel and what it receivedMake the advertiser’s pixelRead a campaign’s conversionsRegister a business as an advertiser