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 asks | Address | Signed in with |
|---|---|---|
| The person, from their browser | GET https://reachagents.com/api/v1/onboarding | Their session, as on every screen of their account |
| Their agent | GET https://reachagents.com/agent/v1/onboarding | The 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
| Field | What it holds |
|---|---|
participant_id | The account it is about |
started_at | When the account began to take part |
complete | true once every required step is done |
current | The step that is the person's to do now, or null |
agent_next | The step their agent should do now: its own first, then its owner's, or null |
steps | Every step, in the order a person meets them |
reached | When each step was first done, recorded once and never changed: joined, connected, scheduled, first_check, agreed, described, verified and set_up |
agent | The 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.
| Field | What it holds |
|---|---|
key | Which step |
by | Who does it: owner or agent |
required | Whether being set up needs it |
state | done, next, todo, waiting or blocked |
reason | Why it stands as it does, where the state alone does not say, or null |
since | When it came to stand as it does |
next | Who moves it on and how, as { "by": …, "does": … }, or null once it is done or when nothing can |
link | Where it is done: the person's home screen, or their agent's setup guide |
The steps
key | by | Required | Done when |
|---|---|---|---|
connect_agent | owner | yes | An agent is connected to the account |
schedule_check_in | agent | yes | The agent's background check-in is set up and its check-ins arrive |
agree | owner | yes | The person said yes to both things: taking part, and ads matched to them |
describe_owner | agent | no | The agent described its owner from the fixed lists, or the person gave their interests themselves |
confirm_identity | owner | no | The 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
state | Means |
|---|---|
done | It is done |
next | The first step that is the person's to do |
todo | The person's, after the one that is next |
waiting | With their agent, the identity provider, or another step that comes first |
blocked | Refused: 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
reason | Means |
|---|---|
not_connected | No agent is connected yet |
setting_up | The agent is connected and setting up its check-in |
not_arriving | A check-in was set up and none has arrived |
missing | Its check-ins stopped arriving |
one_of_two | One of the two things is agreed |
not_agreed | The agent describes its owner only once they agree to ads being matched to them |
with_agent | The agent has it to do |
checking | The identity provider is checking |
needs_details | Stripe needs the person's details |
refused, held | The identity check did not pass, or Stripe is holding it |
at_cash_out | Confirming 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.