Skip to Content
Docs

Participant API

The calls behind a participant’s own screens: their agent, sponsored content, earnings, payouts, preferences and consents.

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 participant, and the database answers with their own rows only.

Read the participant’s home screen

GET /api/participant/overview

Signed in as a participant: the session cookie.

Where getting set up stands, the connected agent and its health, the balances, what pays next, and counts of what is waiting.

Answer: a JSON object.

Refused with unauthorized, not_participant.

Read the agent screen

GET /api/participant/agent

Signed in as a participant: the session cookie.

The connected agent with its health and schedule, its last day of check-ins, earlier connections, how each kind of agent is connected, and the addresses an agent is given.

Answer: a JSON object.

Refused with unauthorized, not_participant.

Read where connecting the agent stands

GET /api/participant/connection

Signed in as a participant: the session cookie.

One word for the screen that waits for the agent: waiting (no agent has asked where to begin yet), expired (and the code last made ran out unused), connected (it asked where to begin, and has no check-in yet), setting_up (its check-in is late, or stopped) or set_up (its check-ins arrive). The answer changes only when that does, so a screen that asks every few seconds is nearly always answered 304.

Answer

FieldTypeAlways sentAbout
statusone of waiting, expired, connected, setting_up, set_upYes
agentstring or nullYesThe kind of agent connected, or the one the last code was made for.
connected_atstring or nullYes
code_expires_atstring or nullYesUntil when the code made last works, while one does.

Refused with unauthorized, not_participant.

Read the agent’s check-ins on each of the last days

GET /api/participant/agent/check-days

Signed in as a participant: the session cookie.

How many arrived, how many of them late, and the hours that went by without one.

Answer: a JSON object.

Refused with unauthorized, not_participant.

Make a pairing code for an agent

POST /api/participant/agent/pairing-code

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

For an app with no OAuth connector. Shown once, and only its hash is kept; it works once, for a few minutes, and a new one ends any not used. message is the one message the person pastes into their agent, with the code in it: the agent trades the code for its key at /agent/v1/pair and goes on with the setup by web requests.

Body

FieldTypeRequired
agentTypeone of grokbot, muse, dots, duet, otherYes

Answer

FieldTypeAlways sent
codestringYes
expiresAtstringYes
mcpUrlstringYes
apiUrlstringYes
messagestringYes

Refused with unknown_agent, invalid_input, unauthorized, not_participant, csrf.

Make an API key for an agent

POST /api/participant/agent/key

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

For an app that signs in to the MCP server with a key pasted into its settings. It connects one agent, and ends the one connected before. It takes no pairing code, so the limit on wrong codes never stands in the way. Shown once.

Body

FieldTypeRequired
agentTypeone of grokbot, muse, dots, duet, otherYes

Answer

FieldTypeAlways sent
keystringYes
mcpUrlstringYes

Refused with unknown_agent, invalid_input, unauthorized, not_participant, csrf.

Disconnect the agent

POST /api/participant/agent/disconnect

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

Its key stops working at once.

Answer

FieldTypeAlways sent
oktrueYes

Refused with not_connected, unauthorized, not_participant, csrf.

List the sponsored records

GET /api/participant/memories

Signed in as a participant: the session cookie.

Every sponsored record offered or kept, and the preferences that decide them.

Answer: a JSON object.

Refused with unauthorized, not_participant.

List the sponsored messages

GET /api/participant/messages

Signed in as a participant: the session cookie.

Answer: a JSON object.

Refused with unauthorized, not_participant.

Read one sponsored record or message

GET /api/participant/placements/:id

Signed in as a participant: the session cookie.

What was sent, and everything that happened to it.

In the path

FieldTypeRequired
idstringYes

Answer: a JSON object.

Refused with not_found, unauthorized, not_participant.

Keep a sponsored record that was offered

POST /api/participant/memories/:id/accept

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

In the path

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
oktrueYes

Refused with not_open, offer_expired, withdrawn, unauthorized, not_participant, csrf.

Turn down a sponsored record that was offered

POST /api/participant/memories/:id/decline

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

In the path

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
oktrueYes

Refused with not_open, unauthorized, not_participant, csrf.

Delete a sponsored record

POST /api/participant/memories/:id/delete

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

In the path

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
oktrueYes

Refused with unauthorized, not_participant, csrf.

Delete every sponsored record

POST /api/participant/memories/delete-all

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

Answer

FieldTypeAlways sent
deletedintegerYes

Refused with unauthorized, not_participant, csrf.

Read the earnings screen

GET /api/participant/earnings

Signed in as a participant: the session cookie.

The balances, the latest earnings and rewards withheld (each with what it was for), the disputes, and any hold on the account. Every earning, one by one, is the paged list at /api/participant/earnings/list.

Answer: a JSON object.

Refused with unauthorized, not_participant.

Read the home screen’s money

GET /api/participant/wallet

Signed in as a participant: the session cookie.

Totals only, never what any one ad paid: what can be cashed out, what is still being checked and for how long, what is on its way, everything earned, everything cashed out, today, the minimum, what cashing out now costs, whether identity is still to confirm (it is, at the first cash out) and the most that can be earned before, where a cash out goes, the latest cash outs (each sending, arrived or failed, with the account it went to), and what was earned on each of the last days, as /api/participant/earnings/by-day answers.

Answer

FieldTypeAlways sentAbout
available_microsnumberYes
checking_microsnumberYesEarned, and still in its review window.
in_transit_microsnumberYes
lifetime_microsnumberYesEverything earned and kept, of every kind.
today_microsnumberYes
min_payout_microsnumberYes
identity_neededbooleanYesNo cash out until the person confirms who they are.
unverified_cap_microsnumberYesThe most that can be earned before that.
unverified_cap_reachedbooleanYes
verificationone of none, checking, needs_details, refused, verifiedYes
on_holdbooleanYes
methodobject or nullYes
method.idstringYes
method.kindone of bank, crypto, cardYes
method.providerstringYes
method.display_hintstring or nullYes
method.statusstringYes
cashed_out_microsnumberYesEverything cashed out, on its way or arrived, after fees.
cash_out_fee_microsnumberYesWhat cashing out what is available now costs, rounded to the cent.
feeobjectYesWhat each cash out costs: a fixed amount and a share of it in basis points, rounded to the cent.
fee.fixed_microsintegerYes
fee.bpsintegerYes
review_hoursintegerYesHow long new earnings are checked before they can be cashed out.
arrival_daysintegerYesHow many business days a cash out to a bank usually takes, for before the payout provider names its date.
payoutslist of objectsYes
payouts[].idstringYes
payouts[].microsnumberYes
payouts[].statusone of sending, arrived, failedYes
payouts[].created_atstringYes
payouts[].settled_atstring or nullYes
payouts[].arrives_atstring or nullYesWhen the payout provider expects it in the bank, as it last said; null until it says.
payouts[].methodobjectYesThe account this cash out went to.
payouts[].method.kindone of bank, crypto, cardYes
payouts[].method.display_hintstring or nullYes
daysobjectYes
days.todaystringYes
days.daysintegerYes
days.rowslist of objectsYes
days.rows[].daystringYes
days.rows[].valuenumberYes
autoobjectYesAutomatic cash out: whenever what can be cashed out reaches the amount, it is cashed out, at most once a day.
auto.onbooleanYes
auto.amount_microsintegerYesThe amount chosen, or the first offered when none was.
auto.amountslist of integerYesThe amounts that can be chosen.
instantobjectYesWhether cashing out to a debit card at once is offered, and what it adds to the fee. Off until the payout provider offers it.
instant.enabledbooleanYes
instant.fee_bpsintegerYes

Refused with unauthorized, not_participant.

Dispute a withheld reward, a record or message, or a payout

POST /api/participant/disputes

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

Body

FieldTypeRequired
subjectKindone of withheld, placement, payoutYes
subjectIdstringYes
statementstring, 1 to 2000 charactersYes

Answer

FieldTypeAlways sent
idstringYes

Refused with already_disputed, invalid_subject, not_found, statement_required, invalid_input, unauthorized, not_participant, csrf.

Read the payouts screen

GET /api/participant/payouts

Signed in as a participant: the session cookie.

The balances, whether identity is confirmed, the payout methods with what the provider last reported, the latest payouts, and which providers are offered here.

Answer: a JSON object.

Refused with unauthorized, not_participant.

Add a payout method

POST /api/participant/payouts/destinations

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

A bank account, set up on the provider’s own pages (onboardingUrl), or a crypto wallet. Where the bank account is how identity is confirmed, nothing is asked for first; otherwise identity has to be confirmed before. returnTo names the screen the provider’s pages send the person back to.

Body

FieldTypeRequiredAbout
kindone of bank, crypto, cardYescard, a debit card for instant cash outs, refused while instant cash out is not offered.
cryptoobjectNo
crypto.assetstringYes
crypto.networkstringYes
crypto.addressstring, 20 to 100 charactersYes
sandboxScenariostringNo
returnToone of /start/homeNoWhere the provider’s pages send the person back to, as one of the screens that send them there. The route’s own screen when left out.

Answer

FieldTypeAlways sent
idstringYes
onboardingUrlstring or nullNo

Refused with not_offered, provider_unavailable, no_wallet, unsupported_asset, invalid_address, not_eligible, too_many, no_account, invalid_input, unauthorized, not_participant, csrf.

Go back to the provider’s pages for a payout method

POST /api/participant/payouts/destinations/:id/continue

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

To finish setting it up, or to give what the provider asks for later. Each link works once and soon expires, so one is made each time. returnTo names the screen the provider’s pages send the person back to.

In the path

FieldTypeRequired
idstringYes

Body

FieldTypeRequiredAbout
returnToone of /start/homeNoWhere the provider’s pages send the person back to, as one of the screens that send them there. The route’s own screen when left out.

Answer

FieldTypeAlways sent
urlstringYes

Refused with not_found, no_provider_pages, provider_unavailable, invalid_input, unauthorized, not_participant, csrf.

Ask the provider about each payout method that confirms identity

POST /api/participant/payouts/refresh

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

For coming back from the provider’s pages. Answers with how many were asked about.

Answer

FieldTypeAlways sent
askedintegerYes

Refused with unauthorized, not_participant, csrf.

Make a payout method the one payouts go to

POST /api/participant/payouts/destinations/:id/default

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

In the path

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
oktrueYes

Refused with not_found, unauthorized, not_participant, csrf.

Remove a payout method

DELETE /api/participant/payouts/destinations/:id

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

In the path

FieldTypeRequired
idstringYes

Answer

FieldTypeAlways sent
oktrueYes

Refused with not_found, payout_in_progress, unauthorized, not_participant, csrf.

Ask to be paid out

POST /api/participant/payouts/request

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

Pays out what has cleared, to the default payout method. The database decides whether it can, and answers with what it did.

Answer: a JSON object.

Refused with idempotency_key, unauthorized, not_participant, csrf.

Cash out the whole available balance

POST /api/participant/cash-out

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

As /api/participant/payouts/request, with an Idempotency-Key header, and method (instant is refused 409 not_available while instant cash out is off), answered 201 with the cash out made, or with an error a screen can act on: 403 verification_required until the person confirms who they are (at their first cash out), 409 method_required with no payout method, 409 method_not_ready while the method is being set up or is restricted, 422 below_minimum, 409 payout_in_progress, 409 on_hold, 403 account_suspended.

Body

FieldTypeRequiredAbout
methodone of standard, instantNo: standard if left outinstant, to a debit card at once, refused while instant cash out is not offered.

Answer

FieldTypeAlways sent
idstringYes
microsintegerYes
statussendingYes
createdAtstringYes

Refused with idempotency_key, verification_required, account_suspended, on_hold, payout_in_progress, method_required, method_not_ready, below_minimum, invalid_input, unauthorized, not_participant, csrf.

Read the ways to earn more, from what the person said about themselves

GET /api/participant/tasks

Signed in as a participant: the session cookie.

In order: answering "About you" while questions they were asked are unanswered; connecting each of X, LinkedIn and Instagram they said they use (with verified for X, as they said, and available only once the network can be connected); confirming who they are, for someone who said they live in the U.S., once what they can cash out reaches the minimum; and adding an email, for someone without one. Each says whether it is done.

Answer

FieldTypeAlways sent
taskslist of objectsYes
tasks[].keyone of answer_questions, connect_x, connect_linkedin, connect_instagram, confirm_us, add_emailYes
tasks[].donebooleanYes
tasks[].availablebooleanYes
tasks[].verifiedboolean or nullNo
tasks[].questionsintegerNo

Refused with unauthorized, not_participant.

Turn automatic cash out on or off

PUT /api/participant/payouts/auto

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

On at one of the amounts the wallet offers (auto.amounts), or off. Whenever what can be cashed out reaches it, it is cashed out to the payout method, at most once a day, as a cash out the person asked for would be; one that cannot be made then (identity, method, minimum) waits for the next money to arrive. Turned on with enough there already, it is due at once. Answers as auto in the wallet.

Body

FieldTypeRequiredAbout
onbooleanYes
amountMicrosinteger, more than 0NoOne of the amounts the wallet offers (auto.amounts). Left out, the one chosen before.

Answer

FieldTypeAlways sentAbout
onbooleanYes
amount_microsintegerYesThe amount chosen, or the first offered when none was.
amountslist of integerYesThe amounts that can be chosen.

Refused with unknown_amount, invalid_input, unauthorized, not_participant, csrf.

POST /api/participant/agent/link

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

An address, <origin>/a/<code>, for the person to add as a connector in their agent’s app. Its OAuth sign-in names the address as the resource, and the consent screen then asks only whether to connect this agent to this account: no sign-in in the app’s window. The code is a pairing code, single use, lasting as long as one does (expiresAt); a new link or message ends the one before. Once used it is worth nothing, and the address serves the agent’s connector like /mcp.

Body

FieldTypeRequired
agentTypeone of grokbot, muse, dots, duet, otherYes

Answer

FieldTypeAlways sent
urlstringYes
codestringYes
expiresAtstringYes

Refused with unknown_agent, invalid_input, unauthorized, not_participant, csrf.

Read the participant’s preferences, profile and consents

GET /api/participant/preferences

Signed in as a participant: the session cookie.

Answer: a JSON object.

Refused with unauthorized, not_participant.

Change what sponsored content the participant receives

PUT /api/participant/preferences

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

Every field, each time: what may be sent, how much and when, the categories never to send, and the time zone. Quiet hours have both ends or neither.

Body

FieldTypeRequired
memoryEnabledbooleanYes
presentationEnabledbooleanYes
memoryAcceptModeone of ask, autoYes
autoMaxRetentionDaysinteger, 1 to 365Yes
maxActiveMemoriesinteger, 0 to 100Yes
maxPresentationsPerDayinteger, 0 to 20Yes
maxPresentationsPerWeekinteger, 0 to 100Yes
quietStartstring, matching ^\d{2}:\d{2}$ or nullYes
quietEndstring, matching ^\d{2}:\d{2}$ or nullYes
blockedCategorieslist of one of consumer_tech, software, finance, travel, food_beverage, retail, entertainment, education, automotive, home, wellness, otherYes
timezonestring, at most 64 charactersYes

Answer

FieldTypeAlways sent
oktrueYes

Refused with quiet_hours, invalid_input, unauthorized, not_participant, csrf.

Answer the short questionnaire

PUT /api/participant/targeting

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

The participant’s own answers: a state, an age band and interests, each of which can be changed or cleared. Removing an interest removes it whatever said it.

Body

FieldTypeRequired
stateone 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 or nullYes
ageBandone of 18-24, 25-34, 35-44, 45-54, 55-64, 65+ or nullYes
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 itemsYes

Answer

FieldTypeAlways sent
oktrueYes

Refused with invalid_input, unauthorized, not_participant, csrf.

POST /api/participant/consents

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

Body

FieldTypeRequired
scopeone of program_terms, ad_targeting, use_verified_region, agent_profile, memory_auto_acceptYes
grantedbooleanYes

Answer

FieldTypeAlways sent
oktrueYes

Refused with unknown_scope, invalid_input, unauthorized, not_participant, csrf.

Agree to take part, in one act

POST /api/participant/agree

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

What the person read as they signed up (the site’s deal screen, and the line under "Send code"), recorded right after they sign in: each choice they said yes to, against the version and the SHA-256 of the words (agreementText(), in the shared package). Words that are not the ones served now are refused (terms_changed), and the person reads them again. Taking part needs adult, now or before. count_visits is recorded only with the words that say advertisers can count visits; a request with Sec-GPC: 1, or with the words a browser sending Global Privacy Control is shown, records a no instead. An answer about counting visits already given stands. Answers with where each choice stands.

Body

FieldTypeRequiredAbout
choiceslist of one of take_part, matching, adult, count_visits, 1 to 4 itemsYesWhat the person said yes to: taking part, ads matched to them, that they are 18 or older, and that advertisers may count visits (count_visits, taken only with the words that say so).
versionstring, at most 40 charactersYesThe version of the words they read.
textHashstring, matching ^[0-9a-f]{64}$YesThe SHA-256, in lowercase hex, of the words they read, as agreementText() in the shared package gives them.

Answer: a JSON object.

Refused with terms_changed, no_choice, unknown_choice, version_required, text_hash_required, age_required, invalid_input, unauthorized, not_participant, csrf.

Say yes or no to taking part, or to matching

POST /api/participant/choices

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

The two things a participant is asked, each standing for the consents behind it.

Body

FieldTypeRequired
choiceone of take_part, matchingYes
grantedbooleanYes

Answer

FieldTypeAlways sent
oktrueYes

Refused with unknown_choice, invalid_input, unauthorized, not_participant, csrf.

Read what the participant agreed to

GET /api/participant/consent

Signed in as a participant: the session cookie.

The two choices, where getting set up stands, how many sponsored records are kept, and the latest consents given or withdrawn.

Answer: a JSON object.

Refused with unauthorized, not_participant.

Use the state identity confirmed for matching

POST /api/participant/use-verified-region

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

Answer

FieldTypeAlways sent
oktrueYes

Refused with consent_required, no_verified_state, not_verified, unauthorized, not_participant, csrf.

Pause sponsored content

POST /api/participant/pause

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

Answer

FieldTypeAlways sent
oktrueYes

Refused with unauthorized, not_participant, csrf.

Resume sponsored content

POST /api/participant/resume

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

Answer

FieldTypeAlways sent
oktrueYes

Refused with unauthorized, not_participant, csrf.

Read where confirming identity stands

GET /api/participant/identity

Signed in as a participant: the session cookie.

Whether identity is confirmed, the latest checks, which provider is used here, and the rule every check is decided by.

Answer: a JSON object.

Refused with unauthorized, not_participant.

Start confirming who the participant is

POST /api/participant/identity/start

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

Answers with the provider’s page to go to (redirectUrl), or, from the simulated provider, with its decision at once. returnTo names the screen the provider’s pages send the person back to; it is asked for at the first cash out.

Body

FieldTypeRequiredAbout
sandboxobjectNo
sandbox.scenariostringYes
sandbox.statestring, exactly 2 charactersYes
sandbox.personstring, at most 60 charactersNo
returnToone of /start/homeNoWhere the provider’s pages send the person back to, as one of the screens that send them there. The route’s own screen when left out.

Answer

FieldTypeAlways sent
statusstringYes
redirectUrlstring or nullNo

Refused with provider_unavailable, already_verified, invalid_input, unauthorized, not_participant, csrf.

Ask the provider whether it has decided

POST /api/participant/identity/refresh

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

For coming back from the provider’s page: none when no check is waiting.

Answer

FieldTypeAlways sent
statusstringYes

Refused with unauthorized, not_participant, csrf.

List the participant’s earnings, one by one

GET /api/participant/earnings/list

Signed in as a participant: the session cookie.

Each amount earned: what for, from which advertiser, and whether it is pending, cleared or reversed. 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 earned, 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_participant.

Read what was earned on each day

GET /api/participant/earnings/by-day

Signed in as a participant: the session cookie.

In micros. An earning reversed after review is not counted. 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_participant.

Read what was earned on each day, by what earned it

GET /api/participant/earnings/by-day-and-source

Signed in as a participant: the session cookie.

The same days in their parts: a message opened, a day a record was kept, a dispute credited (part). 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_participant.

Where the signed-in participant’s onboarding stands, step by step

GET /api/v1/onboarding

Signed in as a participant: the session cookie.

Every step of getting set up, in the order a person meets them, with its state, since when, and who moves it on. Each step has the same fields: key, by, required, state, reason, since, next and link. Keys and states are fixed, and a new step is added without changing the others.

Answer

FieldTypeAlways sentAbout
participant_idstringYes
started_atstringYesWhen the account began to take part.
completebooleanYesEvery required step is done.
currentone of connect_agent, schedule_check_in, agree, describe_owner, confirm_identity or nullYesThe step that is the owner’s to do now.
agent_nextone of connect_agent, schedule_check_in, agree, describe_owner, confirm_identity or nullYesThe step an agent should do now: its own first, then its owner’s.
stepslist of objectsYesEvery step, in the order a person meets them.
steps[].keyone of connect_agent, schedule_check_in, agree, describe_owner, confirm_identityYesWhich step. Fixed: a key is never renamed or reused.
steps[].byone of owner, agentYesWho does the step.
steps[].requiredbooleanYesWhether being set up needs it.
steps[].stateone of done, next, todo, waiting, blockedYesdone; next, the first that is the owner’s to do; todo, theirs after that; waiting, with the agent, the identity provider or another step; blocked, refused.
steps[].reasonone of not_connected, setting_up, not_arriving, missing, one_of_two, not_agreed, with_agent, checking, needs_details, refused, held, at_cash_out or nullYesWhy it stands as it does, where the state alone does not say.
steps[].sincestring or nullYesWhen it came to stand as it does.
steps[].nextobject or nullYesWho moves it on, and how. Null when it is done, or nothing can.
steps[].next.byone of owner, agent, providerYes
steps[].next.doesone of connect, schedule, ask_agent, agree, describe, confirm, give_details, checkYes
steps[].linkstringYesWhere it is done: the owner’s home screen, or the agent’s setup guide.
reachedobject of one of joined, connected, scheduled, first_check, agreed, described, verified, set_up to stringYesWhen each step was first done, recorded once and never changed.
agentobject or nullYesThe agent connected now, if one is.
agent.typestringYes
agent.wayone of oauth, code, key, link, email or nullYesHow it was connected: the connector’s sign-in, a pasted code, an API key, the sign-up link the agent gave its owner, or joining by email, which has closed. Null for one connected before this was recorded.
agent.connection_idstringYes
agent.connected_atstringYesA moment, in ISO 8601.
agent.scheduler_statusstringYesunknown, installed, verified, degraded or missing.
agent.scheduler_kindstring or nullYes
agent.every_secondsnumber or nullYes
agent.registered_atstring or nullYes
agent.first_check_atstring or nullYes

Refused with unauthorized, not_participant.

Read whether advertisers’ sites may count a visit

GET /api/participant/measurement

Signed in as a participant: the session cookie.

Whether an advertiser’s site may count, without learning who it was, that the participant signed up or bought something after opening a sponsored link: allowed, their latest answer, or false for someone who never gave one, and since, when they gave it. ask is true for someone who never answered, from a browser that does not send Sec-GPC: 1: they are asked once, and either answer is recorded.

Answer

FieldTypeAlways sentAbout
allowedbooleanYesWhether visits from sponsored links may be counted.
sincestring or nullYesWhen the answer was given; null for someone who never gave one.
askbooleanYesWhether to ask them, once: they never answered, and their browser does not send Global Privacy Control.

Refused with unauthorized, not_participant.

Choose whether advertisers’ sites may count a visit

PUT /api/participant/measurement

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

Records the answer, from the switch or from the one question someone who never answered is asked. Turning it off forgets the references already on links at once. Answers with the choice as it now stands.

Body

FieldTypeRequired
allowedbooleanYes

Answer

FieldTypeAlways sentAbout
allowedbooleanYesWhether visits from sponsored links may be counted.
sincestring or nullYesWhen the answer was given; null for someone who never gave one.
askbooleanYesWhether to ask them, once: they never answered, and their browser does not send Global Privacy Control.

Refused with invalid_input, unauthorized, not_participant, csrf.

The question sets you can answer, with how far you are through each

GET /api/v1/question-sets

Signed in as a participant: the session cookie.

Answer

FieldTypeAlways sent
setslist of objectsYes
sets[].keystring, at most 40 charactersYes
sets[].titlestring, at most 200 charactersYes
sets[].purposestring, at most 1000 charactersYes
sets[].versionintegerYes
sets[].published_atstring, at most 40 charactersYes
sets[].agent_may_answerbooleanYes
sets[].questionsintegerYes
sets[].requiredintegerYes
sets[].answeredintegerYes
sets[].answered_by_agentintegerYes
sets[].completebooleanYes
sets[].last_answered_atstring, at most 40 characters or nullYes

Refused with unauthorized, not_participant.

One question set at its current version, with every question and your answer to it

GET /api/v1/question-sets/:set_key

Signed in as a participant: the session cookie.

In the path

FieldTypeRequired
set_keystring, matching ^[a-z][a-z0-9_]{0,39}$Yes

Answer

FieldTypeAlways sentAbout
setobjectYes
set.keystring, at most 40 charactersYes
set.titlestring, at most 200 charactersYes
set.purposestring, at most 1000 charactersYes
set.versionintegerYes
set.published_atstring, at most 40 charactersYes
set.agent_may_answerbooleanYes
set.agent_may_answer_sincestring, at most 40 characters or nullYes
set.completebooleanYes
set.questionslist of objectsYes
set.questions[].keystring, at most 40 charactersYes
set.questions[].kindone of one_choice, several_choices, yes_no, number, scale, short_textYes
set.questions[].promptstring, at most 500 charactersYes
set.questions[].requiredbooleanYes
set.questions[].prefer_not_to_saybooleanYes
set.questions[].used_for_matchingbooleanYes
set.questions[].imageobject or nullYes
set.questions[].image.urlstring, at most 300 charactersYes
set.questions[].image.altstring, at most 500 charactersYes
set.questions[].image.widthintegerYes
set.questions[].image.heightintegerYes
set.questions[].optionslist of objectsNo
set.questions[].options[].keystring, at most 40 charactersYes
set.questions[].options[].labelstring, at most 200 charactersYes
set.questions[].options[].imageobject or nullYes
set.questions[].options[].image.urlstring, at most 300 charactersYes
set.questions[].options[].image.altstring, at most 500 charactersYes
set.questions[].options[].image.widthintegerYes
set.questions[].options[].image.heightintegerYes
set.questions[].minnumber or nullNo
set.questions[].maxnumber or nullNo
set.questions[].stepnumber or nullNo
set.questions[].min_labelstring, at most 200 characters or nullNo
set.questions[].max_labelstring, at most 200 characters or nullNo
set.questions[].max_lengthinteger or nullNo
set.questions[].ask_whenobject or nullNoAsked only when the question it names was given this answer: the database refuses an answer to it otherwise (not_asked). Null for a question always asked.
set.questions[].ask_when.questionstringYes
set.questions[].ask_when.optionstringYes
set.questions[].answerobject or nullYes
set.questions[].answer.valuestring, at most 4000 characters or list of string, at most 40 characters, at most 50 items or boolean or number or nullNo
set.questions[].answer.answered_byone of person, agentYes
set.questions[].answer.answered_atstring, at most 40 charactersYes
set.questions[].answer.versionintegerYes

Refused with unknown_set, invalid_input, unauthorized, not_participant.

Answers several questions of a set at once

PUT /api/v1/question-sets/:set_key/answers

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

Questions left out are left as they are. Each answer is checked against its question, and the first that does not fit refuses the whole request with a sentence naming it.

In the path

FieldTypeRequired
set_keystring, matching ^[a-z][a-z0-9_]{0,39}$Yes

Body

FieldTypeRequired
answersobject of string, matching ^[a-z][a-z0-9_]{0,39}$ to string, at most 4000 characters or list of string, at most 40 characters, at most 50 items or boolean or number or nullYes

Answer

FieldTypeAlways sentAbout
setobjectYes
set.keystring, at most 40 charactersYes
set.titlestring, at most 200 charactersYes
set.purposestring, at most 1000 charactersYes
set.versionintegerYes
set.published_atstring, at most 40 charactersYes
set.agent_may_answerbooleanYes
set.agent_may_answer_sincestring, at most 40 characters or nullYes
set.completebooleanYes
set.questionslist of objectsYes
set.questions[].keystring, at most 40 charactersYes
set.questions[].kindone of one_choice, several_choices, yes_no, number, scale, short_textYes
set.questions[].promptstring, at most 500 charactersYes
set.questions[].requiredbooleanYes
set.questions[].prefer_not_to_saybooleanYes
set.questions[].used_for_matchingbooleanYes
set.questions[].imageobject or nullYes
set.questions[].image.urlstring, at most 300 charactersYes
set.questions[].image.altstring, at most 500 charactersYes
set.questions[].image.widthintegerYes
set.questions[].image.heightintegerYes
set.questions[].optionslist of objectsNo
set.questions[].options[].keystring, at most 40 charactersYes
set.questions[].options[].labelstring, at most 200 charactersYes
set.questions[].options[].imageobject or nullYes
set.questions[].options[].image.urlstring, at most 300 charactersYes
set.questions[].options[].image.altstring, at most 500 charactersYes
set.questions[].options[].image.widthintegerYes
set.questions[].options[].image.heightintegerYes
set.questions[].minnumber or nullNo
set.questions[].maxnumber or nullNo
set.questions[].stepnumber or nullNo
set.questions[].min_labelstring, at most 200 characters or nullNo
set.questions[].max_labelstring, at most 200 characters or nullNo
set.questions[].max_lengthinteger or nullNo
set.questions[].ask_whenobject or nullNoAsked only when the question it names was given this answer: the database refuses an answer to it otherwise (not_asked). Null for a question always asked.
set.questions[].ask_when.questionstringYes
set.questions[].ask_when.optionstringYes
set.questions[].answerobject or nullYes
set.questions[].answer.valuestring, at most 4000 characters or list of string, at most 40 characters, at most 50 items or boolean or number or nullNo
set.questions[].answer.answered_byone of person, agentYes
set.questions[].answer.answered_atstring, at most 40 charactersYes
set.questions[].answer.versionintegerYes

Refused with unknown_set, unknown_question, invalid_answer, invalid_input, unauthorized, not_participant, csrf.

Clears your answer to one question

DELETE /api/v1/question-sets/:set_key/answers/:question_key

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

Your agent then leaves that question to you.

In the path

FieldTypeRequired
set_keystring, matching ^[a-z][a-z0-9_]{0,39}$Yes
question_keystring, matching ^[a-z][a-z0-9_]{0,39}$Yes

Answer

FieldTypeAlways sentAbout
setobjectYes
set.keystring, at most 40 charactersYes
set.titlestring, at most 200 charactersYes
set.purposestring, at most 1000 charactersYes
set.versionintegerYes
set.published_atstring, at most 40 charactersYes
set.agent_may_answerbooleanYes
set.agent_may_answer_sincestring, at most 40 characters or nullYes
set.completebooleanYes
set.questionslist of objectsYes
set.questions[].keystring, at most 40 charactersYes
set.questions[].kindone of one_choice, several_choices, yes_no, number, scale, short_textYes
set.questions[].promptstring, at most 500 charactersYes
set.questions[].requiredbooleanYes
set.questions[].prefer_not_to_saybooleanYes
set.questions[].used_for_matchingbooleanYes
set.questions[].imageobject or nullYes
set.questions[].image.urlstring, at most 300 charactersYes
set.questions[].image.altstring, at most 500 charactersYes
set.questions[].image.widthintegerYes
set.questions[].image.heightintegerYes
set.questions[].optionslist of objectsNo
set.questions[].options[].keystring, at most 40 charactersYes
set.questions[].options[].labelstring, at most 200 charactersYes
set.questions[].options[].imageobject or nullYes
set.questions[].options[].image.urlstring, at most 300 charactersYes
set.questions[].options[].image.altstring, at most 500 charactersYes
set.questions[].options[].image.widthintegerYes
set.questions[].options[].image.heightintegerYes
set.questions[].minnumber or nullNo
set.questions[].maxnumber or nullNo
set.questions[].stepnumber or nullNo
set.questions[].min_labelstring, at most 200 characters or nullNo
set.questions[].max_labelstring, at most 200 characters or nullNo
set.questions[].max_lengthinteger or nullNo
set.questions[].ask_whenobject or nullNoAsked only when the question it names was given this answer: the database refuses an answer to it otherwise (not_asked). Null for a question always asked.
set.questions[].ask_when.questionstringYes
set.questions[].ask_when.optionstringYes
set.questions[].answerobject or nullYes
set.questions[].answer.valuestring, at most 4000 characters or list of string, at most 40 characters, at most 50 items or boolean or number or nullNo
set.questions[].answer.answered_byone of person, agentYes
set.questions[].answer.answered_atstring, at most 40 charactersYes
set.questions[].answer.versionintegerYes

Refused with unknown_set, unknown_question, invalid_input, unauthorized, not_participant, csrf.

Says yes, or no, to your agent answering a set for you

PUT /api/v1/question-sets/:set_key/agent

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

In the path

FieldTypeRequired
set_keystring, matching ^[a-z][a-z0-9_]{0,39}$Yes

Body

FieldTypeRequired
may_answerbooleanYes

Answer

FieldTypeAlways sentAbout
setobjectYes
set.keystring, at most 40 charactersYes
set.titlestring, at most 200 charactersYes
set.purposestring, at most 1000 charactersYes
set.versionintegerYes
set.published_atstring, at most 40 charactersYes
set.agent_may_answerbooleanYes
set.agent_may_answer_sincestring, at most 40 characters or nullYes
set.completebooleanYes
set.questionslist of objectsYes
set.questions[].keystring, at most 40 charactersYes
set.questions[].kindone of one_choice, several_choices, yes_no, number, scale, short_textYes
set.questions[].promptstring, at most 500 charactersYes
set.questions[].requiredbooleanYes
set.questions[].prefer_not_to_saybooleanYes
set.questions[].used_for_matchingbooleanYes
set.questions[].imageobject or nullYes
set.questions[].image.urlstring, at most 300 charactersYes
set.questions[].image.altstring, at most 500 charactersYes
set.questions[].image.widthintegerYes
set.questions[].image.heightintegerYes
set.questions[].optionslist of objectsNo
set.questions[].options[].keystring, at most 40 charactersYes
set.questions[].options[].labelstring, at most 200 charactersYes
set.questions[].options[].imageobject or nullYes
set.questions[].options[].image.urlstring, at most 300 charactersYes
set.questions[].options[].image.altstring, at most 500 charactersYes
set.questions[].options[].image.widthintegerYes
set.questions[].options[].image.heightintegerYes
set.questions[].minnumber or nullNo
set.questions[].maxnumber or nullNo
set.questions[].stepnumber or nullNo
set.questions[].min_labelstring, at most 200 characters or nullNo
set.questions[].max_labelstring, at most 200 characters or nullNo
set.questions[].max_lengthinteger or nullNo
set.questions[].ask_whenobject or nullNoAsked only when the question it names was given this answer: the database refuses an answer to it otherwise (not_asked). Null for a question always asked.
set.questions[].ask_when.questionstringYes
set.questions[].ask_when.optionstringYes
set.questions[].answerobject or nullYes
set.questions[].answer.valuestring, at most 4000 characters or list of string, at most 40 characters, at most 50 items or boolean or number or nullNo
set.questions[].answer.answered_byone of person, agentYes
set.questions[].answer.answered_atstring, at most 40 charactersYes
set.questions[].answer.versionintegerYes

Refused with unknown_set, invalid_input, unauthorized, not_participant, csrf.

Become a participant

POST /api/participant/join

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

Adds the participant experience to the signed-in account. Signing up through the participants’ page does this already.

Answer

FieldTypeAlways sent
oktrueYes

Refused with unauthorized, csrf.

Read the person’s connected accounts

GET /api/participant/social

Signed in as a participant: the session cookie.

The networks that can be connected now (none until each has an app the network approved) and the accounts this person has connected, each with whether the network calls it verified. No handle and no token is kept.

Answer

FieldTypeAlways sentAbout
enabledlist of one of x, linkedin, instagramYesThe networks that can be connected now. Empty until each has an app approved by the network.
connectedlist of objectsYes
connected[].networkstringYes
connected[].verifiedbooleanYes
connected[].connected_atstringYes

Refused with unauthorized, not_participant.

Start connecting an account on a network

GET /api/participant/social/:network/start

Signed in as a participant: the session cookie.

Sends the browser to sign in to the network (x, linkedin or instagram), coming back to the callback. 409 not_available while the network is not switched on.

In the path

FieldTypeRequired
networkone of x, linkedin, instagramYes

Answer: a JSON object.

Refused with not_available, invalid_input, unauthorized, not_participant.

Finish connecting an account on a network

GET /api/participant/social/:network/callback

Signed in as a participant: the session cookie.

Where the network sends the browser back. The account is connected (one account connects one person; connecting again replaces the one before) and the browser goes home, to /start/home?connected=<network>.

In the path

FieldTypeRequired
networkone of x, linkedin, instagramYes

In the query

FieldTypeRequired
codestring, at most 2000 charactersYes
statestring, at most 200 charactersYes

Answer: a JSON object.

Refused with not_available, did_not_connect, account_taken, invalid_input, unauthorized, not_participant.

Disconnect an account on a network

DELETE /api/participant/social/:network

Signed in as a participant: the session cookie. Send x-reachagents-client: web.

In the path

FieldTypeRequired
networkone of x, linkedin, instagramYes

Answer

FieldTypeAlways sent
oktrueYes

Refused with invalid_input, unauthorized, not_participant, csrf.

On this page

Calling itRead the participant’s home screenRead the agent screenRead where connecting the agent standsRead the agent’s check-ins on each of the last daysMake a pairing code for an agentMake an API key for an agentDisconnect the agentList the sponsored recordsList the sponsored messagesRead one sponsored record or messageKeep a sponsored record that was offeredTurn down a sponsored record that was offeredDelete a sponsored recordDelete every sponsored recordRead the earnings screenRead the home screen’s moneyDispute a withheld reward, a record or message, or a payoutRead the payouts screenAdd a payout methodGo back to the provider’s pages for a payout methodAsk the provider about each payout method that confirms identityMake a payout method the one payouts go toRemove a payout methodAsk to be paid outCash out the whole available balanceRead the ways to earn more, from what the person said about themselvesTurn automatic cash out on or offMake the one link an agent’s app connects withRead the participant’s preferences, profile and consentsChange what sponsored content the participant receivesAnswer the short questionnaireGive or withdraw one consentAgree to take part, in one actSay yes or no to taking part, or to matchingRead what the participant agreed toUse the state identity confirmed for matchingPause sponsored contentResume sponsored contentRead where confirming identity standsStart confirming who the participant isAsk the provider whether it has decidedList the participant’s earnings, one by oneRead what was earned on each dayRead what was earned on each day, by what earned itWhere the signed-in participant’s onboarding stands, step by stepRead whether advertisers’ sites may count a visitChoose whether advertisers’ sites may count a visitThe question sets you can answer, with how far you are through eachOne question set at its current version, with every question and your answer to itAnswers several questions of a set at onceClears your answer to one questionSays yes, or no, to your agent answering a set for youBecome a participantRead the person’s connected accountsStart connecting an account on a networkFinish connecting an account on a networkDisconnect an account on a network