Skip to main content

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.

Plan feature

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​

GET/v1/request_types

Every 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​

NameTypeRequiredDescription
limitintegerNoPage size. Values above 100 are clamped.
starting_afterstringNoOpaque cursor from a previous response’s next_cursor.
updated_sincetimestampNoReturn records changed at or after this instant. Tracks the record itself, not its child collections.
team_idstringNoOnly types whose requests go to this team.
is_activetrue · falseNotrue for the types switched on, false for those switched off. Both when left out.

Responses​

StatusMeaning
200A page of request types.
401The API key is missing, malformed, revoked or expired.
402The workspace's plan does not include HR Desk (plan_upgrade_required).
403The key does not carry the required scopes.
429Rate limit exceeded. See the RateLimit-* headers.

Retrieve a request type​

GET/v1/request_types/{id}

Path parameters​

NameTypeRequiredDescription
idstringYesThe identifier returned as id on the object.

Responses​

StatusMeaning
200The request type.
401The API key is missing, malformed, revoked or expired.
402The workspace's plan does not include HR Desk (plan_upgrade_required).
403The key does not carry the required scopes.
404No such request type in this workspace.
429Rate limit exceeded. See the RateLimit-* headers.

List requests​

GET/v1/requests

Requests, newest first. A list carries no answers and no fields; retrieve one request for those.

Query parameters​

NameTypeRequiredDescription
limitintegerNoPage size. Values above 100 are clamped.
starting_afterstringNoOpaque cursor from a previous response’s next_cursor.
updated_sincetimestampNoReturn records changed at or after this instant. Tracks the record itself, not its child collections.
statusstring (enum)NoOnly requests in this state.
employee_idstringNoOne employee’s requests.
type_idstringNoOnly requests of this type.
team_idstringNoOnly requests this team is working.

Responses​

StatusMeaning
200A page of requests.
401The API key is missing, malformed, revoked or expired.
402The workspace's plan does not include HR Desk (plan_upgrade_required).
403The key does not carry the required scopes.
429Rate limit exceeded. See the RateLimit-* headers.

Create a request for an employee​

POST/v1/requests

Sends 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​

NameTypeRequiredDescription
Idempotency-KeystringNoA unique value per logical request. Replaying it returns the original response with Idempotent-Replay: true.

Responses​

StatusMeaning
201The resulting request.
400The request body failed validation.
401The API key is missing, malformed, revoked or expired.
402The workspace's plan does not include HR Desk (plan_upgrade_required).
403The key does not carry the required scopes.
409The idempotency key was reused with a different body.
429Rate limit exceeded. See the RateLimit-* headers.

Retrieve a request​

GET/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​

NameTypeRequiredDescription
idstringYesThe identifier returned as id on the object.

Responses​

StatusMeaning
200The request.
401The API key is missing, malformed, revoked or expired.
402The workspace's plan does not include HR Desk (plan_upgrade_required).
403The key does not carry the required scopes.
404No such request in this workspace.
429Rate limit exceeded. See the RateLimit-* headers.