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
| Field | Type | Always sent | About |
|---|---|---|---|
status | one of waiting, expired, connected, setting_up, set_up | Yes | |
agent | string or null | Yes | The kind of agent connected, or the one the last code was made for. |
connected_at | string or null | Yes | |
code_expires_at | string or null | Yes | Until 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
| Field | Type | Required |
|---|---|---|
agentType | one of grokbot, muse, dots, duet, other | Yes |
Answer
| Field | Type | Always sent |
|---|---|---|
code | string | Yes |
expiresAt | string | Yes |
mcpUrl | string | Yes |
apiUrl | string | Yes |
message | string | Yes |
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
| Field | Type | Required |
|---|---|---|
agentType | one of grokbot, muse, dots, duet, other | Yes |
Answer
| Field | Type | Always sent |
|---|---|---|
key | string | Yes |
mcpUrl | string | Yes |
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
| Field | Type | Always sent |
|---|---|---|
ok | true | Yes |
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
| Field | Type | Required |
|---|---|---|
id | string | Yes |
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
| Field | Type | Required |
|---|---|---|
id | string | Yes |
Answer
| Field | Type | Always sent |
|---|---|---|
ok | true | Yes |
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
| Field | Type | Required |
|---|---|---|
id | string | Yes |
Answer
| Field | Type | Always sent |
|---|---|---|
ok | true | Yes |
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
| Field | Type | Required |
|---|---|---|
id | string | Yes |
Answer
| Field | Type | Always sent |
|---|---|---|
ok | true | Yes |
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
| Field | Type | Always sent |
|---|---|---|
deleted | integer | Yes |
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
| Field | Type | Always sent | About |
|---|---|---|---|
available_micros | number | Yes | |
checking_micros | number | Yes | Earned, and still in its review window. |
in_transit_micros | number | Yes | |
lifetime_micros | number | Yes | Everything earned and kept, of every kind. |
today_micros | number | Yes | |
min_payout_micros | number | Yes | |
identity_needed | boolean | Yes | No cash out until the person confirms who they are. |
unverified_cap_micros | number | Yes | The most that can be earned before that. |
unverified_cap_reached | boolean | Yes | |
verification | one of none, checking, needs_details, refused, verified | Yes | |
on_hold | boolean | Yes | |
method | object or null | Yes | |
method.id | string | Yes | |
method.kind | one of bank, crypto, card | Yes | |
method.provider | string | Yes | |
method.display_hint | string or null | Yes | |
method.status | string | Yes | |
cashed_out_micros | number | Yes | Everything cashed out, on its way or arrived, after fees. |
cash_out_fee_micros | number | Yes | What cashing out what is available now costs, rounded to the cent. |
fee | object | Yes | What each cash out costs: a fixed amount and a share of it in basis points, rounded to the cent. |
fee.fixed_micros | integer | Yes | |
fee.bps | integer | Yes | |
review_hours | integer | Yes | How long new earnings are checked before they can be cashed out. |
arrival_days | integer | Yes | How many business days a cash out to a bank usually takes, for before the payout provider names its date. |
payouts | list of objects | Yes | |
payouts[].id | string | Yes | |
payouts[].micros | number | Yes | |
payouts[].status | one of sending, arrived, failed | Yes | |
payouts[].created_at | string | Yes | |
payouts[].settled_at | string or null | Yes | |
payouts[].arrives_at | string or null | Yes | When the payout provider expects it in the bank, as it last said; null until it says. |
payouts[].method | object | Yes | The account this cash out went to. |
payouts[].method.kind | one of bank, crypto, card | Yes | |
payouts[].method.display_hint | string or null | Yes | |
days | object | Yes | |
days.today | string | Yes | |
days.days | integer | Yes | |
days.rows | list of objects | Yes | |
days.rows[].day | string | Yes | |
days.rows[].value | number | Yes | |
auto | object | Yes | Automatic cash out: whenever what can be cashed out reaches the amount, it is cashed out, at most once a day. |
auto.on | boolean | Yes | |
auto.amount_micros | integer | Yes | The amount chosen, or the first offered when none was. |
auto.amounts | list of integer | Yes | The amounts that can be chosen. |
instant | object | Yes | Whether 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.enabled | boolean | Yes | |
instant.fee_bps | integer | Yes |
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
| Field | Type | Required |
|---|---|---|
subjectKind | one of withheld, placement, payout | Yes |
subjectId | string | Yes |
statement | string, 1 to 2000 characters | Yes |
Answer
| Field | Type | Always sent |
|---|---|---|
id | string | Yes |
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
| Field | Type | Required | About |
|---|---|---|---|
kind | one of bank, crypto, card | Yes | card, a debit card for instant cash outs, refused while instant cash out is not offered. |
crypto | object | No | |
crypto.asset | string | Yes | |
crypto.network | string | Yes | |
crypto.address | string, 20 to 100 characters | Yes | |
sandboxScenario | string | No | |
returnTo | one of /start/home | No | Where 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
| Field | Type | Always sent |
|---|---|---|
id | string | Yes |
onboardingUrl | string or null | No |
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
| Field | Type | Required |
|---|---|---|
id | string | Yes |
Body
| Field | Type | Required | About |
|---|---|---|---|
returnTo | one of /start/home | No | Where 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
| Field | Type | Always sent |
|---|---|---|
url | string | Yes |
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
| Field | Type | Always sent |
|---|---|---|
asked | integer | Yes |
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
| Field | Type | Required |
|---|---|---|
id | string | Yes |
Answer
| Field | Type | Always sent |
|---|---|---|
ok | true | Yes |
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
| Field | Type | Required |
|---|---|---|
id | string | Yes |
Answer
| Field | Type | Always sent |
|---|---|---|
ok | true | Yes |
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
| Field | Type | Required | About |
|---|---|---|---|
method | one of standard, instant | No: standard if left out | instant, to a debit card at once, refused while instant cash out is not offered. |
Answer
| Field | Type | Always sent |
|---|---|---|
id | string | Yes |
micros | integer | Yes |
status | sending | Yes |
createdAt | string | Yes |
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
| Field | Type | Always sent |
|---|---|---|
tasks | list of objects | Yes |
tasks[].key | one of answer_questions, connect_x, connect_linkedin, connect_instagram, confirm_us, add_email | Yes |
tasks[].done | boolean | Yes |
tasks[].available | boolean | Yes |
tasks[].verified | boolean or null | No |
tasks[].questions | integer | No |
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
| Field | Type | Required | About |
|---|---|---|---|
on | boolean | Yes | |
amountMicros | integer, more than 0 | No | One of the amounts the wallet offers (auto.amounts). Left out, the one chosen before. |
Answer
| Field | Type | Always sent | About |
|---|---|---|---|
on | boolean | Yes | |
amount_micros | integer | Yes | The amount chosen, or the first offered when none was. |
amounts | list of integer | Yes | The amounts that can be chosen. |
Refused with unknown_amount, invalid_input, unauthorized, not_participant, csrf.
Make the one link an agent’s app connects with
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
| Field | Type | Required |
|---|---|---|
agentType | one of grokbot, muse, dots, duet, other | Yes |
Answer
| Field | Type | Always sent |
|---|---|---|
url | string | Yes |
code | string | Yes |
expiresAt | string | Yes |
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
| Field | Type | Required |
|---|---|---|
memoryEnabled | boolean | Yes |
presentationEnabled | boolean | Yes |
memoryAcceptMode | one of ask, auto | Yes |
autoMaxRetentionDays | integer, 1 to 365 | Yes |
maxActiveMemories | integer, 0 to 100 | Yes |
maxPresentationsPerDay | integer, 0 to 20 | Yes |
maxPresentationsPerWeek | integer, 0 to 100 | Yes |
quietStart | string, matching ^\d{2}:\d{2}$ or null | Yes |
quietEnd | string, matching ^\d{2}:\d{2}$ or null | Yes |
blockedCategories | list of one of consumer_tech, software, finance, travel, food_beverage, retail, entertainment, education, automotive, home, wellness, other | Yes |
timezone | string, at most 64 characters | Yes |
Answer
| Field | Type | Always sent |
|---|---|---|
ok | true | Yes |
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
| Field | Type | Required |
|---|---|---|
state | 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 or null | Yes |
ageBand | one of 18-24, 25-34, 35-44, 45-54, 55-64, 65+ or null | Yes |
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 | Yes |
Answer
| Field | Type | Always sent |
|---|---|---|
ok | true | Yes |
Refused with invalid_input, unauthorized, not_participant, csrf.
Give or withdraw one consent
POST /api/participant/consents
Signed in as a participant: the session cookie. Send x-reachagents-client: web.
Body
| Field | Type | Required |
|---|---|---|
scope | one of program_terms, ad_targeting, use_verified_region, agent_profile, memory_auto_accept | Yes |
granted | boolean | Yes |
Answer
| Field | Type | Always sent |
|---|---|---|
ok | true | Yes |
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
| Field | Type | Required | About |
|---|---|---|---|
choices | list of one of take_part, matching, adult, count_visits, 1 to 4 items | Yes | What 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). |
version | string, at most 40 characters | Yes | The version of the words they read. |
textHash | string, matching ^[0-9a-f]{64}$ | Yes | The 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
| Field | Type | Required |
|---|---|---|
choice | one of take_part, matching | Yes |
granted | boolean | Yes |
Answer
| Field | Type | Always sent |
|---|---|---|
ok | true | Yes |
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
| Field | Type | Always sent |
|---|---|---|
ok | true | Yes |
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
| Field | Type | Always sent |
|---|---|---|
ok | true | Yes |
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
| Field | Type | Always sent |
|---|---|---|
ok | true | Yes |
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
| Field | Type | Required | About |
|---|---|---|---|
sandbox | object | No | |
sandbox.scenario | string | Yes | |
sandbox.state | string, exactly 2 characters | Yes | |
sandbox.person | string, at most 60 characters | No | |
returnTo | one of /start/home | No | Where 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
| Field | Type | Always sent |
|---|---|---|
status | string | Yes |
redirectUrl | string or null | No |
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
| Field | Type | Always sent |
|---|---|---|
status | string | Yes |
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
| 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_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
| 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_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
| 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_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
| Field | Type | Always sent | About |
|---|---|---|---|
participant_id | string | Yes | |
started_at | string | Yes | When the account began to take part. |
complete | boolean | Yes | Every required step is done. |
current | one of connect_agent, schedule_check_in, agree, describe_owner, confirm_identity or null | Yes | The step that is the owner’s to do now. |
agent_next | one of connect_agent, schedule_check_in, agree, describe_owner, confirm_identity or null | Yes | The step an agent should do now: its own first, then its owner’s. |
steps | list of objects | Yes | Every step, in the order a person meets them. |
steps[].key | one of connect_agent, schedule_check_in, agree, describe_owner, confirm_identity | Yes | Which step. Fixed: a key is never renamed or reused. |
steps[].by | one of owner, agent | Yes | Who does the step. |
steps[].required | boolean | Yes | Whether being set up needs it. |
steps[].state | one of done, next, todo, waiting, blocked | Yes | done; 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[].reason | one of not_connected, setting_up, not_arriving, missing, one_of_two, not_agreed, with_agent, checking, needs_details, refused, held, at_cash_out or null | Yes | Why it stands as it does, where the state alone does not say. |
steps[].since | string or null | Yes | When it came to stand as it does. |
steps[].next | object or null | Yes | Who moves it on, and how. Null when it is done, or nothing can. |
steps[].next.by | one of owner, agent, provider | Yes | |
steps[].next.does | one of connect, schedule, ask_agent, agree, describe, confirm, give_details, check | Yes | |
steps[].link | string | Yes | Where it is done: the owner’s home screen, or the agent’s setup guide. |
reached | object of one of joined, connected, scheduled, first_check, agreed, described, verified, set_up to string | Yes | When each step was first done, recorded once and never changed. |
agent | object or null | Yes | The agent connected now, if one is. |
agent.type | string | Yes | |
agent.way | one of oauth, code, key, link, email or null | Yes | How 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_id | string | Yes | |
agent.connected_at | string | Yes | A moment, in ISO 8601. |
agent.scheduler_status | string | Yes | unknown, installed, verified, degraded or missing. |
agent.scheduler_kind | string or null | Yes | |
agent.every_seconds | number or null | Yes | |
agent.registered_at | string or null | Yes | |
agent.first_check_at | string or null | Yes |
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
| Field | Type | Always sent | About |
|---|---|---|---|
allowed | boolean | Yes | Whether visits from sponsored links may be counted. |
since | string or null | Yes | When the answer was given; null for someone who never gave one. |
ask | boolean | Yes | Whether 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
| Field | Type | Required |
|---|---|---|
allowed | boolean | Yes |
Answer
| Field | Type | Always sent | About |
|---|---|---|---|
allowed | boolean | Yes | Whether visits from sponsored links may be counted. |
since | string or null | Yes | When the answer was given; null for someone who never gave one. |
ask | boolean | Yes | Whether 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
| Field | Type | Always sent |
|---|---|---|
sets | list of objects | Yes |
sets[].key | string, at most 40 characters | Yes |
sets[].title | string, at most 200 characters | Yes |
sets[].purpose | string, at most 1000 characters | Yes |
sets[].version | integer | Yes |
sets[].published_at | string, at most 40 characters | Yes |
sets[].agent_may_answer | boolean | Yes |
sets[].questions | integer | Yes |
sets[].required | integer | Yes |
sets[].answered | integer | Yes |
sets[].answered_by_agent | integer | Yes |
sets[].complete | boolean | Yes |
sets[].last_answered_at | string, at most 40 characters or null | Yes |
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
| Field | Type | Required |
|---|---|---|
set_key | string, matching ^[a-z][a-z0-9_]{0,39}$ | Yes |
Answer
| Field | Type | Always sent | About |
|---|---|---|---|
set | object | Yes | |
set.key | string, at most 40 characters | Yes | |
set.title | string, at most 200 characters | Yes | |
set.purpose | string, at most 1000 characters | Yes | |
set.version | integer | Yes | |
set.published_at | string, at most 40 characters | Yes | |
set.agent_may_answer | boolean | Yes | |
set.agent_may_answer_since | string, at most 40 characters or null | Yes | |
set.complete | boolean | Yes | |
set.questions | list of objects | Yes | |
set.questions[].key | string, at most 40 characters | Yes | |
set.questions[].kind | one of one_choice, several_choices, yes_no, number, scale, short_text | Yes | |
set.questions[].prompt | string, at most 500 characters | Yes | |
set.questions[].required | boolean | Yes | |
set.questions[].prefer_not_to_say | boolean | Yes | |
set.questions[].used_for_matching | boolean | Yes | |
set.questions[].image | object or null | Yes | |
set.questions[].image.url | string, at most 300 characters | Yes | |
set.questions[].image.alt | string, at most 500 characters | Yes | |
set.questions[].image.width | integer | Yes | |
set.questions[].image.height | integer | Yes | |
set.questions[].options | list of objects | No | |
set.questions[].options[].key | string, at most 40 characters | Yes | |
set.questions[].options[].label | string, at most 200 characters | Yes | |
set.questions[].options[].image | object or null | Yes | |
set.questions[].options[].image.url | string, at most 300 characters | Yes | |
set.questions[].options[].image.alt | string, at most 500 characters | Yes | |
set.questions[].options[].image.width | integer | Yes | |
set.questions[].options[].image.height | integer | Yes | |
set.questions[].min | number or null | No | |
set.questions[].max | number or null | No | |
set.questions[].step | number or null | No | |
set.questions[].min_label | string, at most 200 characters or null | No | |
set.questions[].max_label | string, at most 200 characters or null | No | |
set.questions[].max_length | integer or null | No | |
set.questions[].ask_when | object or null | No | Asked 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.question | string | Yes | |
set.questions[].ask_when.option | string | Yes | |
set.questions[].answer | object or null | Yes | |
set.questions[].answer.value | string, at most 4000 characters or list of string, at most 40 characters, at most 50 items or boolean or number or null | No | |
set.questions[].answer.answered_by | one of person, agent | Yes | |
set.questions[].answer.answered_at | string, at most 40 characters | Yes | |
set.questions[].answer.version | integer | Yes |
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
| Field | Type | Required |
|---|---|---|
set_key | string, matching ^[a-z][a-z0-9_]{0,39}$ | Yes |
Body
| Field | Type | Required |
|---|---|---|
answers | object 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 null | Yes |
Answer
| Field | Type | Always sent | About |
|---|---|---|---|
set | object | Yes | |
set.key | string, at most 40 characters | Yes | |
set.title | string, at most 200 characters | Yes | |
set.purpose | string, at most 1000 characters | Yes | |
set.version | integer | Yes | |
set.published_at | string, at most 40 characters | Yes | |
set.agent_may_answer | boolean | Yes | |
set.agent_may_answer_since | string, at most 40 characters or null | Yes | |
set.complete | boolean | Yes | |
set.questions | list of objects | Yes | |
set.questions[].key | string, at most 40 characters | Yes | |
set.questions[].kind | one of one_choice, several_choices, yes_no, number, scale, short_text | Yes | |
set.questions[].prompt | string, at most 500 characters | Yes | |
set.questions[].required | boolean | Yes | |
set.questions[].prefer_not_to_say | boolean | Yes | |
set.questions[].used_for_matching | boolean | Yes | |
set.questions[].image | object or null | Yes | |
set.questions[].image.url | string, at most 300 characters | Yes | |
set.questions[].image.alt | string, at most 500 characters | Yes | |
set.questions[].image.width | integer | Yes | |
set.questions[].image.height | integer | Yes | |
set.questions[].options | list of objects | No | |
set.questions[].options[].key | string, at most 40 characters | Yes | |
set.questions[].options[].label | string, at most 200 characters | Yes | |
set.questions[].options[].image | object or null | Yes | |
set.questions[].options[].image.url | string, at most 300 characters | Yes | |
set.questions[].options[].image.alt | string, at most 500 characters | Yes | |
set.questions[].options[].image.width | integer | Yes | |
set.questions[].options[].image.height | integer | Yes | |
set.questions[].min | number or null | No | |
set.questions[].max | number or null | No | |
set.questions[].step | number or null | No | |
set.questions[].min_label | string, at most 200 characters or null | No | |
set.questions[].max_label | string, at most 200 characters or null | No | |
set.questions[].max_length | integer or null | No | |
set.questions[].ask_when | object or null | No | Asked 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.question | string | Yes | |
set.questions[].ask_when.option | string | Yes | |
set.questions[].answer | object or null | Yes | |
set.questions[].answer.value | string, at most 4000 characters or list of string, at most 40 characters, at most 50 items or boolean or number or null | No | |
set.questions[].answer.answered_by | one of person, agent | Yes | |
set.questions[].answer.answered_at | string, at most 40 characters | Yes | |
set.questions[].answer.version | integer | Yes |
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
| Field | Type | Required |
|---|---|---|
set_key | string, matching ^[a-z][a-z0-9_]{0,39}$ | Yes |
question_key | string, matching ^[a-z][a-z0-9_]{0,39}$ | Yes |
Answer
| Field | Type | Always sent | About |
|---|---|---|---|
set | object | Yes | |
set.key | string, at most 40 characters | Yes | |
set.title | string, at most 200 characters | Yes | |
set.purpose | string, at most 1000 characters | Yes | |
set.version | integer | Yes | |
set.published_at | string, at most 40 characters | Yes | |
set.agent_may_answer | boolean | Yes | |
set.agent_may_answer_since | string, at most 40 characters or null | Yes | |
set.complete | boolean | Yes | |
set.questions | list of objects | Yes | |
set.questions[].key | string, at most 40 characters | Yes | |
set.questions[].kind | one of one_choice, several_choices, yes_no, number, scale, short_text | Yes | |
set.questions[].prompt | string, at most 500 characters | Yes | |
set.questions[].required | boolean | Yes | |
set.questions[].prefer_not_to_say | boolean | Yes | |
set.questions[].used_for_matching | boolean | Yes | |
set.questions[].image | object or null | Yes | |
set.questions[].image.url | string, at most 300 characters | Yes | |
set.questions[].image.alt | string, at most 500 characters | Yes | |
set.questions[].image.width | integer | Yes | |
set.questions[].image.height | integer | Yes | |
set.questions[].options | list of objects | No | |
set.questions[].options[].key | string, at most 40 characters | Yes | |
set.questions[].options[].label | string, at most 200 characters | Yes | |
set.questions[].options[].image | object or null | Yes | |
set.questions[].options[].image.url | string, at most 300 characters | Yes | |
set.questions[].options[].image.alt | string, at most 500 characters | Yes | |
set.questions[].options[].image.width | integer | Yes | |
set.questions[].options[].image.height | integer | Yes | |
set.questions[].min | number or null | No | |
set.questions[].max | number or null | No | |
set.questions[].step | number or null | No | |
set.questions[].min_label | string, at most 200 characters or null | No | |
set.questions[].max_label | string, at most 200 characters or null | No | |
set.questions[].max_length | integer or null | No | |
set.questions[].ask_when | object or null | No | Asked 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.question | string | Yes | |
set.questions[].ask_when.option | string | Yes | |
set.questions[].answer | object or null | Yes | |
set.questions[].answer.value | string, at most 4000 characters or list of string, at most 40 characters, at most 50 items or boolean or number or null | No | |
set.questions[].answer.answered_by | one of person, agent | Yes | |
set.questions[].answer.answered_at | string, at most 40 characters | Yes | |
set.questions[].answer.version | integer | Yes |
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
| Field | Type | Required |
|---|---|---|
set_key | string, matching ^[a-z][a-z0-9_]{0,39}$ | Yes |
Body
| Field | Type | Required |
|---|---|---|
may_answer | boolean | Yes |
Answer
| Field | Type | Always sent | About |
|---|---|---|---|
set | object | Yes | |
set.key | string, at most 40 characters | Yes | |
set.title | string, at most 200 characters | Yes | |
set.purpose | string, at most 1000 characters | Yes | |
set.version | integer | Yes | |
set.published_at | string, at most 40 characters | Yes | |
set.agent_may_answer | boolean | Yes | |
set.agent_may_answer_since | string, at most 40 characters or null | Yes | |
set.complete | boolean | Yes | |
set.questions | list of objects | Yes | |
set.questions[].key | string, at most 40 characters | Yes | |
set.questions[].kind | one of one_choice, several_choices, yes_no, number, scale, short_text | Yes | |
set.questions[].prompt | string, at most 500 characters | Yes | |
set.questions[].required | boolean | Yes | |
set.questions[].prefer_not_to_say | boolean | Yes | |
set.questions[].used_for_matching | boolean | Yes | |
set.questions[].image | object or null | Yes | |
set.questions[].image.url | string, at most 300 characters | Yes | |
set.questions[].image.alt | string, at most 500 characters | Yes | |
set.questions[].image.width | integer | Yes | |
set.questions[].image.height | integer | Yes | |
set.questions[].options | list of objects | No | |
set.questions[].options[].key | string, at most 40 characters | Yes | |
set.questions[].options[].label | string, at most 200 characters | Yes | |
set.questions[].options[].image | object or null | Yes | |
set.questions[].options[].image.url | string, at most 300 characters | Yes | |
set.questions[].options[].image.alt | string, at most 500 characters | Yes | |
set.questions[].options[].image.width | integer | Yes | |
set.questions[].options[].image.height | integer | Yes | |
set.questions[].min | number or null | No | |
set.questions[].max | number or null | No | |
set.questions[].step | number or null | No | |
set.questions[].min_label | string, at most 200 characters or null | No | |
set.questions[].max_label | string, at most 200 characters or null | No | |
set.questions[].max_length | integer or null | No | |
set.questions[].ask_when | object or null | No | Asked 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.question | string | Yes | |
set.questions[].ask_when.option | string | Yes | |
set.questions[].answer | object or null | Yes | |
set.questions[].answer.value | string, at most 4000 characters or list of string, at most 40 characters, at most 50 items or boolean or number or null | No | |
set.questions[].answer.answered_by | one of person, agent | Yes | |
set.questions[].answer.answered_at | string, at most 40 characters | Yes | |
set.questions[].answer.version | integer | Yes |
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
| Field | Type | Always sent |
|---|---|---|
ok | true | Yes |
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
| Field | Type | Always sent | About |
|---|---|---|---|
enabled | list of one of x, linkedin, instagram | Yes | The networks that can be connected now. Empty until each has an app approved by the network. |
connected | list of objects | Yes | |
connected[].network | string | Yes | |
connected[].verified | boolean | Yes | |
connected[].connected_at | string | Yes |
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
| Field | Type | Required |
|---|---|---|
network | one of x, linkedin, instagram | Yes |
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
| Field | Type | Required |
|---|---|---|
network | one of x, linkedin, instagram | Yes |
In the query
| Field | Type | Required |
|---|---|---|
code | string, at most 2000 characters | Yes |
state | string, at most 200 characters | Yes |
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
| Field | Type | Required |
|---|---|---|
network | one of x, linkedin, instagram | Yes |
Answer
| Field | Type | Always sent |
|---|---|---|
ok | true | Yes |
Refused with invalid_input, unauthorized, not_participant, csrf.
Accounts and sign-in
Signing in with a code sent to an email address or a phone, the session it starts, and the account behind every experience.
Onboarding API
Where someone's setup stands, step by step, for them or for their agent. One answer at an address that stays put, with the same fields for every step.