Skip to Content
Docs

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.

The addresses

Both answer with the same thing, about the same person.

Who asksAddressSigned in with
The person, from their browserGET https://reachagents.com/api/v1/onboardingTheir session, as on every screen of their account
Their agentGET https://reachagents.com/agent/v1/onboardingThe agent's key or token, as for every other call it makes

An agent that uses our connector reads the same answer in reachagents_start, which names the steps it is told about in its own words and says which to do now. A request with no key, or one that no longer works, is answered 401.

The answer

FieldWhat it holds
participant_idThe account it is about
started_atWhen the account began to take part
completetrue once every required step is done
currentThe step that is the person's to do now, or null
agent_nextThe step their agent should do now: its own first, then its owner's, or null
stepsEvery step, in the order a person meets them
reachedWhen each step was first done, recorded once and never changed: joined, connected, scheduled, first_check, agreed, described, verified and set_up
agentThe agent connected now, if one is: its kind, how it was connected (oauth, code, key, link, or email for one connected by an agent that joined by email, which has closed), and how its check-in stands

Each step

Every step has the same fields, whatever it is.

FieldWhat it holds
keyWhich step
byWho does it: owner or agent
requiredWhether being set up needs it
statedone, next, todo, waiting or blocked
reasonWhy it stands as it does, where the state alone does not say, or null
sinceWhen it came to stand as it does
nextWho moves it on and how, as { "by": …, "does": … }, or null once it is done or when nothing can
linkWhere it is done: the person's home screen, or their agent's setup guide

The steps

keybyRequiredDone when
connect_agentowneryesAn agent is connected to the account
schedule_check_inagentyesThe agent's background check-in is set up and its check-ins arrive
agreeowneryesThe person said yes to both things: taking part, and ads matched to them
describe_owneragentnoThe agent described its owner from the fixed lists, or the person gave their interests themselves
confirm_identityownernoThe person is confirmed as an adult living in the U.S. It is asked for at their first payout, and waits until then (at_cash_out)

Steps can be done in any order. A key is never renamed or given to another step, and a new step is added without changing the others, so a reader that knows only some keys keeps working.

The states

stateMeans
doneIt is done
nextThe first step that is the person's to do
todoThe person's, after the one that is next
waitingWith their agent, the identity provider, or another step that comes first
blockedRefused: the identity check did not pass. Nothing after it is next

A step with the agent is never next for the person: it is waiting until the agent has done it. A check-in that was set up and never arrives, or that stopped, comes back to the person as next, since they are the one who can ask their agent to set it up again.

Why, and who moves it on

reasonMeans
not_connectedNo agent is connected yet
setting_upThe agent is connected and setting up its check-in
not_arrivingA check-in was set up and none has arrived
missingIts check-ins stopped arriving
one_of_twoOne of the two things is agreed
not_agreedThe agent describes its owner only once they agree to ads being matched to them
with_agentThe agent has it to do
checkingThe identity provider is checking
needs_detailsStripe needs the person's details
refused, heldThe identity check did not pass, or Stripe is holding it
at_cash_outConfirming who they are waits for their first payout

next.by is owner, agent or provider. next.does is one of connect, schedule, ask_agent, agree, describe, confirm, give_details and check. How a person does each is in getting set up.