Cancel Onboarding

Overview

Customers and partners using the Remote API can create an EOR (Employer of Record) employment and invite potential employees to onboarding via the API. However, in some cases, the invited employee does not proceed with the onboarding process. Without a way to cancel onboarding via the API, these employees remain in the invited state indefinitely, creating confusion and management challenges.

To address this, the Cancel Onboarding endpoint is introduced that allows users to cancel onboarding under specific conditions. These conditions are mentioned below.

Eligibility Criteria

The following requirements need to be met for an API user to make a successful endpoint call to cancel employee's onboarding.

1. Employment should be in status: invited, created, created_awaiting_reserve, created_reserve_paid, or pre_hire.
2. Contract should not be in status: employee_signed, both_parties_signed, terminated, deleted, or declined.

If the above criteria are not met, the request will fail with the following error message:

{
    "status": "error",
    "message": "Employment not eligible for Onboarding Cancellation"
}

ℹ️ An easy way to identify whether an employment ID is eligible for onboarding cancellation is to call the Show Employment endpoint and notice the eligible_for_onboarding_cancellation flag. To know more, jump to the eligibility flag section.

Let's understand the use case a little better with an example. Say, you have an employment record empl_123 that is currently in the invited state while its contract is already been created. Consulting the eligibility criteria, you understand that this particular employment record is eligible for cancellation so you make the following request:

curl --request POST \
     --url /v1/cancel-onboarding/empl_123 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer YOUR_API_TOKEN

The response of your request will be:

{
  "data": {
    "status": "ok"
  }
}

Supported Webhooks

The following webhooks are supported with this endpoint:

1. A webhook triggers when an employment record is ineligible for onboarding cancellation.

   JSON

   {
     "employment_slug": "empl_slug"
   }
   

2. A webhook triggers when onboarding cancellation succeeds.

   JSON

   {
     "employment_id": "empl_123",
     "event_type": "employment.onboarding.cancelled"
   }
   

Error codes 2XX confirm that these webhooks were successfully delivered.

Eligibility Flag

The GET /v1/employments/{employment_id} endpoint now includes an additional field eligible_for_onboarding_cancellation to indicate whether the employment is eligible for onboarding cancellation or not.

"data": {
  "employment": {
    ...
    },
    "eligible_for_onboarding_cancellation": true,
    ...
}

Error Handling

Common error scenarios include:

• Invalid Employment ID: If the provided employment ID does not exist.
• Eligibility Violation: If the employment or contract status does not meet the eligibility criteria.