HR Desk
What a person asks the company for, and where it stands. A request type is a form with the team that works what comes in; a request is one submitted form with a reference such as REQ-000123, a status, a priority, the team working it and the deadlines for a first reply and a resolution. Read both with requests:read, and create a request for an employee with requests:write, by the same rules the portal applies.
A request is worked in the app: replies, internal notes, files, status and assignment are not part of this API, and no route returns the conversation. request.created, request.updated and request.resolved announce what happens to a request; assigned says whether someone has taken it, never who.
Available on plans that include the HR Desk.
These endpoints need a plan that includes HR Desk (requests). On a plan without it, requests return 402 with code: plan_upgrade_required and feature naming what an upgrade would add.
List request types
/v1/request_typesEvery request type of the workspace, switched on or not, each with its form in fields. Who a type is open to is not part of this API; creating a request answers that for one employee.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Page size. Values above 100 are clamped. |
starting_after | string | No | Opaque cursor from a previous response’s next_cursor. |
updated_since | timestamp | No | Return records changed at or after this instant. Tracks the record itself, not its child collections. |
team_id | string | No | Only types whose requests go to this team. |
is_active | true · false | No | true for the types switched on, false for those switched off. Both when left out. |
Responses
| Status | Meaning |
|---|---|
200 | A page of request types. |
401 | The API key is missing, malformed, revoked or expired. |
402 | The workspace's plan does not include HR Desk (plan_upgrade_required). |
403 | The key does not carry the required scopes. |
429 | Rate limit exceeded. See the RateLimit-* headers. |
Retrieve a request type
/v1/request_types/{id}Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The identifier returned as id on the object. |
Responses
| Status | Meaning |
|---|---|
200 | The request type. |
401 | The API key is missing, malformed, revoked or expired. |
402 | The workspace's plan does not include HR Desk (plan_upgrade_required). |
403 | The key does not carry the required scopes. |
404 | No such request type in this workspace. |
429 | Rate limit exceeded. See the RateLimit-* headers. |
List requests
/v1/requestsRequests, newest first. A list carries no answers and no fields; retrieve one request for those.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Page size. Values above 100 are clamped. |
starting_after | string | No | Opaque cursor from a previous response’s next_cursor. |
updated_since | timestamp | No | Return records changed at or after this instant. Tracks the record itself, not its child collections. |
status | string (enum) | No | Only requests in this state. |
employee_id | string | No | One employee’s requests. |
type_id | string | No | Only requests of this type. |
team_id | string | No | Only requests this team is working. |
Responses
| Status | Meaning |
|---|---|
200 | A page of requests. |
401 | The API key is missing, malformed, revoked or expired. |
402 | The workspace's plan does not include HR Desk (plan_upgrade_required). |
403 | The key does not carry the required scopes. |
429 | Rate limit exceeded. See the RateLimit-* headers. |
Create a request for an employee
/v1/requestsSends a request for an employee, the way they would from the portal. The body is employee_id, type_id and answers: an object keyed by the key of each field in the type’s form.
An answer has the shape its field takes: a string for text, textarea and choice (one of the field’s options); a number for number and money; YYYY-MM-DD for date; an object with from and to for date_range; a list of options for multi; yes or no for yes_no; an employee id for employee. A heading takes no answer. A file field cannot be answered through the API, so a type whose form requires a file is sent from the portal.
The type has to be switched on and open to that employee. Where the type asks for approval the request comes back with status awaiting_approval and reaches its team once approved; otherwise it is open. request.created fires either way.
The response is the request as GET /v1/requests/\{id\} returns it, with answers and fields. Status 400 names employee_id when the employee is not in the workspace and type_id when the type is not open to them.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | No | A unique value per logical request. Replaying it returns the original response with Idempotent-Replay: true. |
Responses
| Status | Meaning |
|---|---|
201 | The resulting request. |
400 | The request body failed validation. |
401 | The API key is missing, malformed, revoked or expired. |
402 | The workspace's plan does not include HR Desk (plan_upgrade_required). |
403 | The key does not carry the required scopes. |
409 | The idempotency key was reused with a different body. |
429 | Rate limit exceeded. See the RateLimit-* headers. |
Retrieve a request
/v1/requests/{id}One request with its answers, keyed by field key, and fields: the form as it was when the request was sent. The answer to a file field is left out. The conversation on a request, its internal notes and its files are not returned by any route.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The identifier returned as id on the object. |
Responses
| Status | Meaning |
|---|---|
200 | The request. |
401 | The API key is missing, malformed, revoked or expired. |
402 | The workspace's plan does not include HR Desk (plan_upgrade_required). |
403 | The key does not carry the required scopes. |
404 | No such request in this workspace. |
429 | Rate limit exceeded. See the RateLimit-* headers. |