Manage Employment Records

The Employment Records endpoints are designed to help you manage employment records for users in a company. These records include critical information such as hire dates, termination dates, and employment classifications (e.g., employee or contractor). Whether you're integrating with a payroll system, updating HR records, or syncing employee data, these endpoints provide the tools you need.

Termination refers to the permanent ending of an employee's employment. No new pay will be attributed to the Employee for payroll after the termination date. For companies using 7shifts Payroll, the termination date is sent to benefit brokers to end benefit coverage.

❗️

Employment vs User Status

Employment Records refer to the hire and termination dates for an employee, and are used for record keeping and payroll calculations.

Employment Records do not affect the active status of a user. To check or modify user status refer to the Deactivating/Reactivating an Employee guide

Reading Employment Records

Retrieve a list of Employment Records for users within a specific company. You can filter results by a single user_id or multiple user_ids.

For multiple users use user_ids . (e.g., user_ids=1,2,3).

Request URL

curl --request GET --url 'https://api.7shifts.com/v2/company/12345/employment_records?user_id=67890'

Response body

{
  "object": "employment_record",
  "data": [
    {
      "uuid": "abc123",
      "company_id": 12345,
      "user_id": 67890,
      "hire_date": "2023-01-15",
      "termination_date": null,
      "classification": "employee",
      "locked": false
    }
  ]
}

Here’s an explanation of each of the fields in the body:

Creating an Employment Record

Add a new employee or contractor employment record with details like hire date and classification. Note that classification eefaults to employee if not specified.

Request URL

curl --request POST --url 'https://api.7shifts.com/v2/company/12345/employment_records'

Request Body

{
  "user_id": 67890,
  "hire_date": "2023-01-15",
  "classification": "employee"
}

Example Response

{
  "object": "employment_record",
  "data": {
    "uuid": "abc123",
    "company_id": 12345,
    "user_id": 67890,
    "hire_date": "2023-01-15",
    "termination_date": null,
    "classification": "employee",
    "locked": false
  }
}

Update an Employment Record

Modify details like hire date, termination date, or classification for an existing record.

Request URL

curl --request PUT --url 'https://api.7shifts.com/v2/company/12345/employment_record/abc123'

Request Body

{
  "termination_date": "2023-12-31"
}

Example Response

{
  "object": "employment_record",
  "data": {
    "uuid": "abc123",
    "company_id": 12345,
    "user_id": 67890,
    "hire_date": "2023-01-15",
    "termination_date": "2023-12-31",
    "classification": "employee",
    "locked": false
  }
}

Delete an Employment Record

Delete outdated or incorrect employment records.

Request URL

curl --request DELETE --url 'https://api.7shifts.com/v2/company/12345/employment_record/abc123'

A success response returns: 204 No Content

Bulk Create and Update Employment Records

Efficiently sync large batches of employee records in a single request.

Request URL

curl --request POST --url 'https://api.7shifts.com/v2/company/12345/bulk_employment_records'

Request Body

{
  "records": [
    {
      "user_id": 67890,
      "classification": "employee",
      "hire_date": "2023-01-15"
    },
    {
      "user_id": 54321,
      "classification": "contractor",
      "hire_date": "2023-02-01"
    }
  ]
}

Example Response

{
  "object": "employment_record",
  "data": [
    {
      "uuid": "abc123",
      "company_id": 12345,
      "user_id": 67890,
      "hire_date": "2023-01-15",
      "termination_date": null,
      "classification": "employee",
      "locked": false
    },
    {
      "uuid": "xyz789",
      "company_id": 12345,
      "user_id": 54321,
      "hire_date": "2023-02-01",
      "termination_date": null,
      "classification": "contractor",
      "locked": false
    }
  ]
}