Employments
A person's job at the business: when it started, on what basis, and (with the pay permission) what they are paid. An employment is created and ended in Shiftly.
Needs the people:read permission, depending on the operation. The business sees it as "Staff details".
Fields
| Field | Type | Access | Meaning |
|---|---|---|---|
| id | string | Read-only | The employment. |
| employee_id | string | Read-only | The person employed. |
| start_date | date, may be null | Read-only | The day the employment started. |
| employment_basis | "fulltime", "parttime", "casual" | Read-only | fulltime, parttime or casual. |
| ordinary_hours_per_week | number, may be null | Read-only | Ordinary hours a week. |
| payroll_employee_number | string, may be null | Read-only | The person's number in the payroll system. |
| pay_basis | string, may be null | Read-only | hourly or salary. Returned only with pay:read. |
| base_hourly_rate | number, may be null | Read-only | Base rate in dollars an hour. Returned only with pay:read. |
| hourly_rate_multiplier | number, may be null | Read-only | Percentage paid above the base rate. Returned only with pay:read. |
| annual_salary | number, may be null | Read-only | Salary in dollars a year, for salaried staff. Returned only with pay:read. |
| salary_weekly_hours | number, may be null | Read-only | Hours a week the salary covers. Returned only with pay:read. |
| classification_level | string, may be null | Read-only | Award classification. Returned only with pay:read. |
| award_code | string, may be null | Read-only | The award the person is paid under. Returned only with pay:read. |
| award_stream | string, may be null | Read-only | The stream within the award. Returned only with pay:read. |
| rate_overrides | object, may be null | Read-only | Rates set for this person in place of the award's, in dollars an hour, by rate category. Returned only with pay:read. |
| archived | boolean | Read-only | True when the record has been removed in Shiftly. |
| created_at | timestamp | Read-only | When the record was created. |
| updated_at | timestamp | Read-only | When the record last changed. |
Operations
List employments
GET/v1/employments
Permission: people:read
| Parameter | Type | Meaning | |
|---|---|---|---|
| limit | integer, default 50, up to 200 | Optional | How many records per page. Up to 200. |
| after | string | Optional | The next_cursor from the previous page. |
| updated_since | timestamp | Optional | Only records changed at or after this moment. Pair it with include_archived to see removals. |
| include_archived | "true", "false" | Optional | Include records that have been archived. |
| employee_id | string | Optional | Only this person. |
{
"data": [
{
"id": "66f1c2a4b3d9e8f7a6b5c4d3",
"employee_id": "66f1c2a4b3d9e8f7a6b5c4d3",
"start_date": "2026-10-06",
"employment_basis": "fulltime",
"ordinary_hours_per_week": 1.5,
"payroll_employee_number": "text",
"pay_basis": "text",
"base_hourly_rate": 1.5,
"hourly_rate_multiplier": 1.5,
"annual_salary": 1.5,
"salary_weekly_hours": 1.5,
"classification_level": "text",
"award_code": "text",
"award_stream": "text",
"rate_overrides": {},
"archived": true,
"created_at": "2026-10-06T09:00:00+11:00",
"updated_at": "2026-10-06T09:00:00+11:00"
}
],
"has_more": true,
"next_cursor": "text"
}| Status | When |
|---|---|
| 400 | The error's code is invalid_request or range_too_long. The Errors page describes each code. |
| 401 | The error's code is invalid_token or token_expired. The Errors page describes each code. |
| 403 | The error's code is origin_not_allowed, permission_denied, not_available, connection_disconnected, connection_suspended or app_suspended. The Errors page describes each code. |
| 404 | There is nothing at this address, or no such record in this business. |
| 429 | Too many requests. Retry-After says when to try again. |
| 500 | Something went wrong at Shiftly. Quote the request id. |
| 503 | This environment is not set up for partner apps yet. |
Get one employment
GET/v1/employments/{id}
Permission: people:read
{
"id": "66f1c2a4b3d9e8f7a6b5c4d3",
"employee_id": "66f1c2a4b3d9e8f7a6b5c4d3",
"start_date": "2026-10-06",
"employment_basis": "fulltime",
"ordinary_hours_per_week": 1.5,
"payroll_employee_number": "text",
"pay_basis": "text",
"base_hourly_rate": 1.5,
"hourly_rate_multiplier": 1.5,
"annual_salary": 1.5,
"salary_weekly_hours": 1.5,
"classification_level": "text",
"award_code": "text",
"award_stream": "text",
"rate_overrides": {},
"archived": true,
"created_at": "2026-10-06T09:00:00+11:00",
"updated_at": "2026-10-06T09:00:00+11:00"
}| Status | When |
|---|---|
| 400 | The error's code is invalid_request or range_too_long. The Errors page describes each code. |
| 401 | The error's code is invalid_token or token_expired. The Errors page describes each code. |
| 403 | The error's code is origin_not_allowed, permission_denied, not_available, connection_disconnected, connection_suspended or app_suspended. The Errors page describes each code. |
| 404 | There is nothing at this address, or no such record in this business. |
| 429 | Too many requests. Retry-After says when to try again. |
| 500 | Something went wrong at Shiftly. Quote the request id. |
| 503 | This environment is not set up for partner apps yet. |
Not available to partner apps
PATCH /v1/employments/{id}
Employments are changed in Shiftly, not by partner apps.