Workers are one of the most important objects in your Plane account. They represent employees, contractors and vendors that work for or with your company.

Plane is built to support a lot of flexible work arrangements. This means a worker can have one or more employments, some concurrent, each containing their own compensation, role, reporting and classification history.

For convenience, Plane’s data model provides a lot of shortcuts that simplify this structure. This allows you to used a much simpler model if your organization doesn’t require the full complexity that Plane can support.

Here’s what this means in practice:

  • One employment is always designated as primary.
  • Employments, compensations, roles and reportings that are effective now are designated as current.
  • Current compensation, classification, role and reporting values for each employment are available directly on the Employment object.
  • Values from the current primary employment are available directly on the Worker object.

This means that if all you care about is Worker’s current primary employment, you can read worker.classification.type, worker.compensation.amount, or worker.role.title without having to iterate over worker’s employments:

Here’s an example payload with employments and compensations expanded, to show what this looks like in practice:

{
  "id": "wr_anqRSFcK36ie85",
  "compensation": {
    "amount": 120000.0 // worker.employment.compensation.amount
    ...
  },
  "employment": { // worker.employments where current = true and primary = true
    "id": "wre_anqRSFcK36ie85",
    "current": true,
    "primary": true,
    "compensation": { // compensations where current = true
      "amount": 120000.0,
      ...
    },
    "compensations": [ // all compensations for this employment
      {
        "id": "wrc_anqRSFcK36ie85",
        "current": true,
        "amount": 120000.0,
        ...
      }
    ]
  },
  "employments": [ // all employments for this worker
    {
      "id": "wre_anqRSFcK36ie85",
      "current": true,
      "primary": true,
      "compensation": {
        // compensations where current = true
        "amount": 120000.0,
        "additional_fields": {}
      },
      "compensations": [ // all compensations for this employment
        {
          "id": "wrc_anqRSFcK36ie85",
          "current": true,
          "amount": 120000.0,
          "additional_fields": {}
        },
        ...
      ]
    },
    ...
  ]
}

Plane will only return current and primary values, unless you request to expand a particular field (e.g. employments). This allows us to keep responses simple for most of our users, while accommodating the needs of larger, more complicated organizations.

​
Attributes

​
id
string

Unique identifier for the object, e.g. wr_cNqYX2J3s9bI2Aa.

​
number
string

Employee number assigned by the company. Optional.

​
email
object

An object with email addresses associated with this worker.

​
dob
date

The worker’s date of birth.

​
phone
string

The worker’s phone number.

​
ids
list

The worker’s tax and national IDs. This field is not included by default. To include it in the response, expand the ids field.

​
starts
date

The worker’s original start date. Note that this attribute is freely editable and doesn’t always line up with the start date of the worker’s Employment object. This can be useful for representing someone’s start date before they were onboarded on Plane.

​
ends
date

The worker’s termination date. Note that this attribute is freely editable and doesn’t always line up with end dates of the worker’s Employment object. This can be useful when importing historical data about workers that will not be onboarded onto Plane.

​
title
string

The worker’s job title. Matches title on the worker’s current primary employment Role object.

​
status
string

The worker’s current status. One of pending, active, terminated, cancelled, paused or undefined.

​
address
hash

An dicionary of worker’s current addresses.

​
sex
string

The person’s gender as displayed on their legal ID. International regulations require either male or female. May be required to determine tax liability or benefits eligiblity in certain countries.

​
marital_status
string

The person’s marital status, e.g. married or single. Optional. May be required to determine tax liability or benefits eligiblity in certain countries.

​
nationality
string

The country where the person is a national. Two-letter country code (ISO 3166-1 alpha-2).

​
employment
hash

An Employment object representing the worker’s current primary employment.

​
compensation
hash

A Compensation object representing the worker’s current compensation in their current primary employment.

​
location
string

A Location object representing the worker’s work location in their current primary employment.

​
classification
hash

A Classification object representing the worker’s current classification in their current primary employment.

​
role
string

A Role object representing the worker’s current rule in their current primary employment.

​
reporting
string

A Reporting object representing the worker’s current reporting relationship in their current primary employment.