Monitoring the EOR hire process

This guide explains how to track the progress of an EOR hire by retrieving the hiring process tasks via the Oyster API.

What are hiring process tasks? Tasks are the steps required to take a hire through to engagement. They include actions for the company (e.g. completing the hiring form, signing the Oyster Service Agreement) and for the team member (e.g. submitting the onboarding form, signing employment agreements).

1. Get hiring process tasks for an employment

To retrieve the progress of an employment's hiring process, use the Get hiring process tasks for an employment endpoint.

The response includes a data array of tasks. Each task has:

type — The task identifier, unique per employment (e.g. HIRING_FORM_COMPLETED, OYSTER_SERVICE_AGREEMENT_SIGNED).
state — The task's status in the flow. See task states and state transitions below for more details.
visibleTo — Who the task is visible to: COMPANY, TEAM_MEMBER, or both.
parties — Who is responsible for completing the task: COMPANY, TEAM_MEMBER, or both. (In some cases Oyster Staff can complete tasks in the responsible party’s stead.)

2. Task states and transitions overview

Each task has a state that reflects its status in the hiring flow. The possible values are:

PENDING — The task is active and can be worked on.
BLOCKED — The task cannot be started yet because it depends on other tasks or events.
COMPLETED — The task has been completed.
INACTIVE — The task is not applicable for this hire and is not shown in the active process.

State transitions

BLOCKED → PENDING — When prerequisites are met (e.g. a prior task is completed or a certain condition is satisfied).
PENDING → COMPLETED — When the responsible party completes the action.
COMPLETED → PENDING — In some cases (e.g. a new agreement version is uploaded and must be re-signed), a task can move back from COMPLETED to PENDING.

Additional notes on some task transitions

TEAM_MEMBER_RIGHT_TO_WORK_CHECKED — Completes when the team member's right to work is verified by Oyster.
INVITE_TEAM_MEMBER_TO_THE_PLATFORM — Unblocks when the company submits the hiring form.
OYSTER_SERVICE_AGREEMENT_ACCEPTED — Unblocks when the agreement is verified by Oyster.
OYSTER_SERVICE_AGREEMENT_SIGNED — Unblocks when the agreement is uploaded.
EMPLOYMENT_AGREEMENT_SIGNED / CONFIDENTIALITY_AND_INTELLECTUAL_PROPERTY_SIGNED / REMOTE_WORK_SIGNED / RESTRICTIVE_COVENANT_SIGNED — Unblocks when the corresponding agreement is shared with the team member.

3. Subscribing to task state changes

To get notified when a hiring task changes state, you can subscribe to the hiring.task_updated webhook event.

The event includes:

data.engagementId — the engagement the task belongs to.
data.type — the task identifier (e.g. HIRING_FORM_COMPLETED).
changes.state.from — previous state.
changes.state.to — new state.