Offboarding an engagement

This guide will show you how to create an offboarding (resignation or termination) request, upload any additional documents, initiate or submit the offboarding, and get information and updates related to a specific offboarding and documents.

Note for Reseller partners using the API - you will need to use the X-Oyster-Customer-Id header for all of the calls in this guide. For more information, see the Reseller guide to using the Oyster API.

1. Get necessary fields

Before submitting an offboarding request, you must obtain the offboarding categories that are required when submitting an offboarding request. You may also need to obtain the pay types if there is an additional payment.

2. Create offboarding

Then you need to create an offboarding record. There are five different endpoints to create an offboarding record depending on the type of Team Member, each with different required fields for submission.

If the API call is successful, the API will return a 200 Created response with the newly created offboarding details, including an id that you will need for future submission. The offboarding process will then enter a draft phase.

Example response

{
  "data": {
    "id": "B62eff68",
    "engagement": {
      "id": "B0b779a8",
      "name": "Willie Mraz",
      "countryCode": "US"
    },
    "state": "draft",
    "initiatedAt": null,
    "cancelledAt": null,
    "cancelReason": null,
    "requestorId": "Be6a8269",
    "category": {
      "id": "Dd9fa175",
      "name": "Tardiness",
      "parentCategory": {
        "id": "B473f979",
        "name": "Termination"
      }
    },
    "lastDayOn": null
  }
}

3. Attaching documents to an offboarding

Some offboarding requests require the upload of documents like resignation letters, performance documents or any other documents. This can be added when an offboarding request is being created in draft, or if it is in draft, using the Attach documents to an offboarding endpoint. You will receive the offboarding’s information in the API response.

Example response

{
  "data": {
    "id": "B62eff68",
    "engagement": {
      "id": "B0b779a8",
      "name": "Willie Mraz",
      "countryCode": "GB"
    },
    "state": "draft",
    "initiatedAt": "2022-10-15T12:34:56Z",
    "cancelledAt": null,
    "cancelReason": null,
    "requestorId": "D5234bdb",
    "category": null,
    "lastDayOn": null
  }
}

4. Initiate offboarding

After creating a draft offboarding, you can initiate the offboarding. This marks the offboarding as Initiated. Once initiated, the Oyster team will start processing the offboarding request.

Example request

curl --request POST \
     --url https://api.oysterhr.com/v0.1/offboardings/btYBqK6v/initiate \
     --header 'accept: application/json' \
     --header 'authorization: Bearer BEARER_TOKEN_GOES_HERE'

Example response

{
  "data": {
    "id": "B62eff68",
    "engagement": {
      "id": "B0b779a8",
      "name": "Willie Mraz",
      "countryCode": "GB"
    },
    "state": "initiated",
    "initiatedAt": "2022-10-15T12:34:56Z",
    "cancelledAt": null,
    "cancelReason": null,
    "requestorId": "Be6a8269",
    "category": null,
    "lastDayOn": null
  }
}

5. Request the cancellation of an initiated offboarding request.

Users can request the cancellation of an initiated offboarding request using the **Request cancellation for an initiated offboarding request endpoint. This cancellation of the offboarding request must be confirmed by Oyster staff for it to be effective.

Example response

{
  "data": {
    "id": "B62eff68",
    "engagement": {
      "id": "B0b779a8",
      "name": "Willie Mraz",
      "countryCode": "GB"
    },
    "state": "cancellation_requested",
    "initiatedAt": "2022-10-15T12:34:56Z",
    "cancelledAt": "2022-10-15T12:34:56Z",
    "cancelReason": "Some cancellation reason",
    "requestorId": "D5234bdb",
    "category": null,
    "lastDayOn": null
  }
}

6. Checking an offboarding’s status

You can view an offboarding request's status using the Return offboarding endpoint, and you can also be notified via our webhook events:

offboarding.approved

offboarding.engagement_terminated

offboarding.cancelled

offboarding.request_updated

7. Checking the Termination of Service Agreement

Some time after an employment is offboarded, a Termination of Service Agreement is generated. You can obtain an offboarding's agreements via the offboarding agreements endpoint. This will return the agreement along with its current status.

Example response

{
  "data": [
    {
      "id": "Ba41c2d4",
      "name": "Termination of Service Agreement",
      "type": "TERMINATION_OF_SERVICE_AGREEMENT",
      "state": "PENDING"
    }
  ],
}

You can be notified of the status of the agreement using our event webhooks.

offboarding.agreement_generated

offboarding.agreement_sent_for_signature

offboarding.agreement_signed