API Reference

Introduction

Humaans API is organized around REST. Our API has consistently structured resource-oriented URLs, accepts and returns JSON, and uses standard HTTP response codes, authentication, and verbs.

Use Humaans API to retrieve or modify data stored in your Humaans account programmatically and to create custom integrations.

Authentication

Humaans API uses API access tokens to authenticate requests. You can view and manage your API access tokens in Humaans.

Access Token Management

Your API access tokens carry many privileges, so be sure to keep them secure! Do not share your secret API access tokens in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

The API access token should be passed as a Bearer authorization header, e.g.:

curl https://app.humaans.io/api/me \
  -H 'Authorization: Bearer <your_api_access_token>'

Scopes

The API access token can be restricted to certain scopes, which limits what actions the API access token can perform.

Scopes

public:read

Allow view access to data that is public to the entire company
private:read

Allow view access to all data except compensations and documents
private:write

Allow modifying all data except compensations and documents
compensations:read

Allow view access to compensation data
compensations:write

Allow modifying compensation data
documents:read

Allow view access to personal documents and identity documents
documents:write

Allow modifying personal documents and identity documents
webhooks:manage

Allow view and modifying access to webhooks

For example, if an owner creates an access token with private:read scope, that token will be able to access the full profile details of each employee, such as their job title, place of work, teams, banking details, emergency contacts and time away entries with specific leave reasons notes. But if the same owner creates an access token with public:read scope, that token will only be able to access the public details of every profile that everyone in the company has access to already, such as job title, place of work, teams and time away entries without specific leave reasons or notes. The access tokens with public:read tokens are great for many internal applications that only need the rich public metadata about the company and its employees found in the Humaans API.

Roles

In addition to scopes, the API access tokens are limited to only perform the actions that the creator of the API access token can perform. For example, if a user with a role owner creates a token, that token will be able to access and modify every employee’s profile. But if a user with role user creates a token, that token will only be able to access the public company information and their own profile details.

Roles

Owner

Has full access to read and modify all employees and data.
Admin

Can access and edit all profiles.
Finance

Can access all profiles and manage the subscription.
Tech

View limited data for all profiles. Manage equipment. No access to documents or sensitive data by default.
Manager

Can access some profile data for their reports. Unlike the other roles, Manager is inferred from reporting lines and cannot be assigned directly.
User

Can access their own profile data.

Note that access to compensation is only available to owner and finance roles (and the employee) by default. Access to personal documents is only available to owner (and the employee) by default. You can set custom permissions to allow admin and finance roles and managers to access compensation and documents.

Structure

You will find the structure of the API to be highly uniform and consistent. Typically every resource can be accessed via a top level endpoint, such as /api/people. For every such resource, you can perform some of the following operations:

Operations

GET /api/:resource

List all objects of this type
GET /api/:resource/:id

Retrieve a resource by id
POST /api/:resource

Create a resource of this type
PATCH /api/:resource/:id

Update the resource by id
DELETE /api/:resource/:id

Delete the resource by id

In terms of the information hierarchy, at the center we have a company. The company has a set of resources such as people, locations and time away policies. Each person has further resources, such as job roles, bank accounts and documents.

Pagination

Almost all resources have support for listing all the records by paging over them. These list API methods share a common structure and can optionally take two parameters: $limit and $skip.

$limitnumber

Limit the number of results. Default value is 100. Maximum allowed value is 250.
$skipnumber

Skip the specified number of results.

Here’s an example of how you’d fetch all people from the API:

curl 'https://app.humaans.io/api/people' -g \
  -H 'Authorization: Bearer <your_api_access_token>'
# -> { "total": 152, "limit": 100, "skip": 0, "data": [.. 100 items ..] }

curl 'https://app.humaans.io/api/people?$skip=100' -g \
  -H 'Authorization: Bearer <your_api_access_token>'
# -> { "total": 152, "limit": 100, "skip": 100, "data": [.. 52 items ..] }

Note: the -g, --globoff argument and single quotes '' are used in some of the curl examples, to allow usage of $ and [] commonly used in Humaans API.

Filtering

Some list endpoints allow you to filter results by certain conditions. Refer to specific resources to find out what criteria are allowed. Below is a list of the different types of conditions.

In resource type labels, value types appear before · and supported filter operators appear after it. When operator groups accept different value types, / separates each group from its accepted types.

`string`, `number`, `boolean`

Find all results matching the attribute value specified.

GET /api/example?personId=IL3vne

`$in`, `$nin`

Find all results matching ($in) or not matching ($nin) any of the attribute values specified.

GET /api/example?personId[$in]=IL3vne&personId[$in]=5dPtfT

`$gt`, `$gte`

Find results where the value is greater than ($gt) or greater than or equal to ($gte) a given value.

GET /api/example?startDate[$gte]=2020-01-01

`$lt`, `$lte`

Find results where the value is less than ($lt) or less than or equal to ($lte) a given value.

GET /api/example?startDate[$lte]=2020-12-31

`$or`

Find results using multiple conditions.

GET /api/example?$or[0][personId]=IL3vne&$or[1][startDate][$gte]=2020-01-01

Data warehouse

To load Humaans data into a data warehouse, start with a full import of each resource. Request the maximum page size of 250 records, then increase $skip until the response contains no more records.

Offset pagination reads live data. For a consistent initial load, run the import while the source data is stable; records created or deleted during the import can shift later pages.

curl 'https://app.humaans.io/api/people?$limit=250&$skip=0' -g \
  -H 'Authorization: Bearer <your_api_access_token>'

For later imports, record the start time of each run. Fetch records whose updatedAt value is greater than or equal to the previous run’s start time, paginate through the results, and upsert each record by id.

curl 'https://app.humaans.io/api/people?updatedAt[$gte]=2026-08-27T10:00:00.000Z&$limit=250&$skip=0' -g \
  -H 'Authorization: Bearer <your_api_access_token>'

Use $gte to overlap consecutive runs and avoid missing records that share the cursor timestamp. After the resource import succeeds, save the current run’s start time as the next cursor.

For list endpoints that support includeDeleted, run a separate query for deleted records. Deleted records are returned as minimal tombstones containing an id and deletedAt. Remove the matching record from the warehouse.

curl 'https://app.humaans.io/api/people?includeDeleted=true&deletedAt[$gte]=2026-08-27T10:00:00.000Z&$sort[deletedAt]=1&$sort[id]=1&$limit=250&$skip=0' -g \
  -H 'Authorization: Bearer <your_api_access_token>'

The API returns only records deleted within the last 30 days. Run an incremental import more often than every 30 days. Check each list endpoint to confirm that it supports updatedAt and includeDeleted.

Rate limiting

Each API access token has its own rate limit, so no single integration can overwhelm the platform. Requests made from within the Humaans app are not affected. The limit supports roughly 400 requests per minute under a steady request pattern.

The limit uses a token bucket: each token gets a bucket of 40 requests that refills at 7 per second. Every request spends one token and once the bucket is empty requests are rejected until it refills. So you can burst up to 40 requests at once, then settle to the steady refill rate.

When rate limiting is active for a token, responses include headers describing the current allowance so you can adapt before hitting the limit:

Rate limit headers

X-RateLimit-Limit

The maximum number of requests the token bucket can hold, i.e. the largest burst you can make when the bucket is full.
X-RateLimit-Remaining

The number of requests you can still make right now before being rate limited.
X-RateLimit-Policy

The active policy, formatted as <limit>;refill=<tokens per second>. For example 40;refill=7 means a bucket of 40 that refills at 7 requests per second.
Retry-After

Only present on 429 responses. The number of seconds to wait before retrying the request.

When you exceed the limit, the API responds with a 429 Too Many Requests error and a Retry-After header telling you how many seconds to wait before retrying:

curl -i 'https://app.humaans.io/api/people' -g \
  -H 'Authorization: Bearer <your_api_access_token>'
# -> HTTP/1.1 429 Too Many Requests
# -> X-RateLimit-Limit: 40
# -> X-RateLimit-Remaining: 0
# -> X-RateLimit-Policy: 40;refill=7
# -> Retry-After: 1

Avoiding rate limits

The most reliable way to stay within the limit is to make fewer, larger requests rather than polling the API with many small ones:

Combine requests. Fetch records in bulk from the list endpoints instead of requesting them one at a time.
Use larger pages. Raise $limit (up to a maximum of 250) so you retrieve more records per request when paginating.
Filter server side. Use filtering to request only the records you need, instead of fetching everything and filtering in your own code.
Prefer webhooks over polling. Subscribe to webhooks to be notified of changes as they happen, rather than repeatedly polling for updates.
Respect Retry-After. When you receive a 429, wait for the number of seconds given in the Retry-After header and back off, rather than retrying immediately.

Errors

Humaans uses conventional HTTP status codes to indicate whether an API request succeeded. Codes in the 2xx range indicate success. Codes in the 4xx range mean the request could not be completed as sent, for example because a required parameter was omitted or the token lacks permission. Codes in the 5xx range mean Humaans could not complete a valid request.

Error object

idstring

Unique identifier for this specific error instance, useful when provided in support queries.
codenumber

The numeric code of the error, e.g. 401 or 422.
namestring

The string name of the code, e.g. NotAuthenticated or ValidationError.
messagestring

A human-readable description of the issue.
traceIdstring

An identifier used to correlate the error with a server trace. This field is omitted when no trace is available.
subTypestring

A more specific error classification. This field is omitted when no subtype is available.
issuesobject[]

Details for validation, permission, or request errors. This field is omitted when no details are available.
issues[].namestring

The name of the field that failed validation.
issues[].reasonstring

The reason why this field was invalid.
issues[].indexnumber

The index of the item that this issue applies to in cases where the input is a list of objects.
issues[].entityIdstring

The identifier of the entity associated with a nested group of issues.
issues[].entityPathstring[]

The path to the entity associated with a nested group of issues.
issues[].issuesobject[]

A nested list of issues for the associated entity.

Error codes

400BadRequest

The request is invalid
401NotAuthenticated

Missing or invalid access token
403Forbidden

The provided access token does not have sufficient privileges
404NotFound

The requested resource could not be found
405MethodNotAllowed

The operation is not allowed for this resource
409Conflict

The request conflicts with the current state of the resource
413PayloadTooLarge

The request payload is too large
422ValidationError

The request parameters are invalid
422Unprocessable

The request is well-formed but cannot be processed
422EmailTaken

Returned when a user is being re-onboarded, but their email is already taken
429TooManyRequests

The access token has exceeded its rate limit. See rate limiting for details
500GeneralError

An unexpected server error occurred
502GeneralError

A temporary upstream availability issue occurred
503GeneralError

A temporary availability issue occurred

Versioning

Humaans API currently does not use versioning. We are committed to not introducing any backward incompatible changes outside possible feature removal. If we do remove certain features, we will make sure that the API for such features continues returning the correct response structure. We might remove some APIs in cases where they are not being actively used. And if we have to introduce versioning, it will be done without breaking the existing API.

Webhooks

Webhooks allow you listen to events happening in Humaans, as they happen. A webhook may be created by an Owner on the webhooks page. Once a webhook is created, it must be published to be made active and for the endpoint to receive events from the Humaans platform. Webhooks can be created programmatically by interacting with the webhooks service.

Webhook events have a generic wrapper, with event specific data contained within, this is documented below.

The validity of a webhook event can be confirmed by it’s signature, this can be confirmed by using the secret provided to you when test and production urls are set. The signature is a HMAC SHA-256 encoded string consisting of the webhook id, timestamp and body, and can be verified by creating your own signature to compare:

import { createHmac } from 'crypto'

const body = await getBody(request)

const {
  'webhook-id': id,
  'webhook-signature': receivedSignature,
  'webhook-timestamp': timestamp,
} = request.headers
const signature = receivedSignature.replace('v1,', '')

const signedContent = `${id}.${timestamp}.${body}`
// Looks like whsec_vwbddlgH8lyKqHEDzn3EUpmk
const secret = process.env.HUMAANS_WEBHOOK_SECRET

const secretBytes = Buffer.from(secret.split('_')[1], 'base64')
const generatedSignature = createHmac('sha256', secretBytes)
  .update(signedContent)
  .digest('base64')

if (signature === generatedSignature) {
  console.log('Good Sig')
} else {
  console.log('Bad Sig')
}

For more information on checking the webhook signature and why it’s important please follow this link.

You can also confirm the validity of a webhook from it’s source, events will only come from these addresses:

52.215.16.239
54.216.8.72
63.33.109.123
2a05:d028:17:8000::/52

When you consume a webhook, your response code will be important, any 2xx status code will be treated as a success. Any non 2xx response codes will be treated as a failure and will be reattempted after an exponential backoff.

If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled. The clock only starts after multiple deliveries have failed within a 24 hour span, with at least 12 hours between the first and the last failure.

Bank accounts

An object representing the bank account details of an employee. Commonly used for payroll. At most one bank account can be created per employee.

Endpoints

   GET /api/bank-accounts

   GET /api/bank-accounts/:id

  POST /api/bank-accounts

 PATCH /api/bank-accounts/:id

DELETE /api/bank-accounts/:id

Required scopes

private:read

private:write

Bank account object

Attributes

idstring

Unique identifier for the object.
personIdstring

ID of the person that this object is associated to.
bankNamestring

The name of the bank.
nameOnAccountstring

The name on the bank account.
accountNumberstring

Bank account number.
swiftCodestring

The swift code of the bank account if relevant.
sortCodestring

The sort code of the bank account if relevant.
routingNumberstring

The routing number of the bank account if relevant.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.

bank account object

{
  "id": "Ivl8mvdLO8ux7T1h1DjGtClc",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "bankName": "Mondo",
  "nameOnAccount": "Kelsey Wicks",
  "accountNumber": "12345678",
  "swiftCode": null,
  "sortCode": "00-00-00",
  "routingNumber": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all bank accounts

Returns a list of bank accounts.

Parameters

includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
personIdstring · $in

The person to filter queries by.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit bank accounts. The response skips the first $skip results. Each entry is a separate bank account object. If no bank accounts are available, data is empty.

GET /api/bank-accounts

curl https://app.humaans.io/api/bank-accounts \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "Ivl8mvdLO8ux7T1h1DjGtClc",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "bankName": "Mondo",
      "nameOnAccount": "Kelsey Wicks",
      "accountNumber": "12345678",
      "swiftCode": null,
      "sortCode": "00-00-00",
      "routingNumber": null,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a bank account

Retrieves the bank account with the given ID.

Parameters

No parameters

Returns

Returns a bank account object if a valid identifier was provided.

GET /api/bank-accounts/:id

curl https://app.humaans.io/api/bank-accounts/Ivl8mvdLO8ux7T1h1DjGtClc \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "Ivl8mvdLO8ux7T1h1DjGtClc",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "bankName": "Mondo",
  "nameOnAccount": "Kelsey Wicks",
  "accountNumber": "12345678",
  "swiftCode": null,
  "sortCode": "00-00-00",
  "routingNumber": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a bank account

Parameters

personIdstring required

ID of the person that this object is associated to.
bankNamestring | null

The name of the bank.
nameOnAccountstring | null

The name on the bank account.
accountNumberstring | null

Bank account number.
swiftCodestring | null

The swift code of the bank account if relevant.
sortCodestring | null

The sort code of the bank account if relevant.
routingNumberstring | null

The routing number of the bank account if relevant.

Returns

Returns a bank account if the call succeeded. The call returns an error if parameters are invalid.

POST /api/bank-accounts

curl https://app.humaans.io/api/bank-accounts \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW"}'

Response

{
  "id": "Ivl8mvdLO8ux7T1h1DjGtClc",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "bankName": "Mondo",
  "nameOnAccount": "Kelsey Wicks",
  "accountNumber": "12345678",
  "swiftCode": null,
  "sortCode": "00-00-00",
  "routingNumber": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a bank account

Parameters

bankNamestring | null

The name of the bank.
nameOnAccountstring | null

The name on the bank account.
accountNumberstring | null

Bank account number.
swiftCodestring | null

The swift code of the bank account if relevant.
sortCodestring | null

The sort code of the bank account if relevant.
routingNumberstring | null

The routing number of the bank account if relevant.

Returns

Returns the bank account if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/bank-accounts/:id

curl https://app.humaans.io/api/bank-accounts/Ivl8mvdLO8ux7T1h1DjGtClc \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"bankName":"N1"}'

Response

{
  "id": "Ivl8mvdLO8ux7T1h1DjGtClc",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "bankName": "N1",
  "nameOnAccount": "Kelsey Wicks",
  "accountNumber": "12345678",
  "swiftCode": null,
  "sortCode": "00-00-00",
  "routingNumber": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a bank account

Permanently deletes a bank account. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/bank-accounts/:id

curl https://app.humaans.io/api/bank-accounts/Ivl8mvdLO8ux7T1h1DjGtClc \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "Ivl8mvdLO8ux7T1h1DjGtClc",
  "deleted": true
}

Companies

An object representing the company. Every user belongs to a single company and all of the resources accessible via the API are linked to this company (unless stated otherwise, such as public holidays).

Endpoints

  GET /api/companies

  GET /api/companies/:id

PATCH /api/companies/:id

Required scopes

private:read

public:read

private:write

Company object

Attributes

idstring

Unique identifier for the object.
namestring

Company name.
domainsobject[]

The list of domains owned by the company.
domains.domainstring

The domain
trialEndDatedate

The last date of trial.
statusstring

One of terms, trialing, expired, active, suspended.
paymentStatusstring

One of requires_action, past_due, ok.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
isTimesheetEnabledboolean

Describes whether the timesheet functionality is enabled.
logoobject

When a logo file is uploaded, it gets resized to several predefined sizes and uploaded to a CDN. The URLs of those files are provided in this object. Note, that you can still access the original un-resized file via api/files.
logo.idstring

Unique identifier for the object.
logo.filenamestring
logo.variantsobject

A map of the predefined logo sizes. Some used in 2x displays, some used in 3x displays.
logo.variants.64string

URL of one of the predefined 2x logo sizes.
logo.variants.96string

URL of one of the predefined 3x logo sizes.
logo.variants.104string

URL of one of the predefined 2x logo sizes.
logo.variants.136string

URL of one of the predefined 2x logo sizes.
logo.variants.156string

URL of one of the predefined 3x logo sizes.
logo.variants.204string

URL of one of the predefined 3x logo sizes.
logo.variants.320string

URL of one of the predefined 2x logo sizes.
logo.variants.480string

URL of one of the predefined 3x logo sizes.
autogenerateEmployeeIdboolean

Whether employee IDs are automatically generated
autogenerateEmployeeIdForNewHiresboolean

Whether employee IDs are automatically generated for new hires
nextEmployeeIdstring

The employee ID of the next employee to be created.
autogenerateEmployeeIdFiltersobject[]

Filters that gate automatic employee ID generation. A person must match all filters to receive a generated ID.
autogenerateEmployeeIdFilters.fieldstring
autogenerateEmployeeIdFilters.operatorstring
autogenerateEmployeeIdFilters.valuestring[]

company object

{
  "id": "uoWtfpDIMI2IZ8doGK7kkCwS",
  "name": "Acme",
  "domains": [],
  "trialEndDate": "2020-01-30",
  "status": "active",
  "paymentStatus": "ok",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "isTimesheetEnabled": true,
  "logo": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "autogenerateEmployeeIdFilters": [
    {}
  ]
}

List all companies

Returns a list of companies.

Parameters

createdAtdate | date-time · $gt $gte $lt $lte

Filter companies by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter companies by updated at date.
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit companies. The response skips the first $skip results. Each entry is a separate company object. If no companies are available, data is empty.

GET /api/companies

curl https://app.humaans.io/api/companies \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "uoWtfpDIMI2IZ8doGK7kkCwS",
      "name": "Acme",
      "domains": [],
      "trialEndDate": "2020-01-30",
      "status": "active",
      "paymentStatus": "ok",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z",
      "isTimesheetEnabled": true,
      "logo": {
        "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
        "filename": "image-file.jpg",
        "variants": {
          "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
          "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
          "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
          "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
          "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
          "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
          "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
          "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
        }
      },
      "autogenerateEmployeeIdFilters": [
        {}
      ]
    }
  ]
}

Retrieve a company

Retrieves the company with the given ID.

Parameters

No parameters

Returns

Returns a company object if a valid identifier was provided.

GET /api/companies/:id

curl https://app.humaans.io/api/companies/uoWtfpDIMI2IZ8doGK7kkCwS \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "uoWtfpDIMI2IZ8doGK7kkCwS",
  "name": "Acme",
  "domains": [],
  "trialEndDate": "2020-01-30",
  "status": "active",
  "paymentStatus": "ok",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "isTimesheetEnabled": true,
  "logo": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "autogenerateEmployeeIdFilters": [
    {}
  ]
}

Update a company

Parameters

namestring

Company name.
isTimesheetEnabledboolean

Describes whether the timesheet functionality is enabled.
autogenerateEmployeeIdboolean

Whether employee IDs are automatically generated
autogenerateEmployeeIdForNewHiresboolean

Whether employee IDs are automatically generated for new hires
nextEmployeeIdstring | null

The employee ID of the next employee to be created.
autogenerateEmployeeIdFiltersobject[]

Filters that gate automatic employee ID generation. A person must match all filters to receive a generated ID.
autogenerateEmployeeIdFilters.fieldstring required
autogenerateEmployeeIdFilters.operatorstring required
autogenerateEmployeeIdFilters.valuestring[] required

Returns

Returns the company if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/companies/:id

curl https://app.humaans.io/api/companies/uoWtfpDIMI2IZ8doGK7kkCwS \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"name":"Meac"}'

Response

{
  "id": "uoWtfpDIMI2IZ8doGK7kkCwS",
  "name": "Meac",
  "domains": [],
  "trialEndDate": "2020-01-30",
  "status": "active",
  "paymentStatus": "ok",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "isTimesheetEnabled": true,
  "logo": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "autogenerateEmployeeIdFilters": [
    {}
  ]
}

Compensation types

An object representing a compensation type. Types are the set of compensations that can be given to people. Examples of types are “Salary”, “Bonus”, “Commission” and so on. Custom types can be created in addition to the standard types provided by Humaans.

Endpoints

GET /api/compensation-types

GET /api/compensation-types/:id

Required scopes

public:read

private:write

Compensation type object

Attributes

idstring

Unique identifier for the object.
companyIdstring

ID of the company that this object is associated to.
namestring

The name of the compensation type.
baseTypestring

The base type of the compensation type. One of salary, bonus, commission, equity, custom
formulaobject

Used to calculate compensation values for this type. Available for custom types only. It can only be edited if set, but not added or removed.
formula.formulastring

The formula expression as plain text.
formula.valueTypestring

The output type of the formula. One of number, percentage, money
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time
filtersobject[]

Filters restricting who this compensation type can be created for. An empty array means unrestricted. Only custom compensation types can have filters.
filters.fieldstring

The field to filter on. Available fields for type enum: spaceId, payrollProvider, department, contractType, locationId, placeOfWorkCountry, placeOfWorkCity, orgLevel, reportingTo. Available fields for type array: teams, reportsUpTo.
filters.operatorstring

The operator to use when filtering. Available operators for field type string: eq, ne, contains, ncontains, exists, nexists. Available operators for field type enum: in, nin, exists, nexists. Available operators for field type array: all, any, nany, nall, exists, nexists. Available operators for field type number: eq, ne, gt, gte, lt, lte, exists, nexists. Available operators for field type date: eq, lt, gt, lte, gte, exists, nexists. Available operators for field type boolean: eq, exists, nexists.
filters.value

The value(s) of the field to check

compensation type object

{
  "id": "ldOQU3pLI5i8Y9k2rJbrXbFc",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Salary",
  "baseType": "salary",
  "formula": {
    "formula": "salary.amount * 0.05"
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "filters": [
    {
      "field": "department",
      "operator": "in",
      "value": [
        "Engineering"
      ]
    }
  ]
}

List all compensation types

Returns a list of compensation types.

Parameters

companyIdstring
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
createdAtdate | date-time · $gt $gte $lt $lte

Filter compensation types by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit compensation types. The response skips the first $skip results. Each entry is a separate compensation type object. If no compensation types are available, data is empty.

GET /api/compensation-types

curl https://app.humaans.io/api/compensation-types \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "ldOQU3pLI5i8Y9k2rJbrXbFc",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "Salary",
      "baseType": "salary",
      "formula": {
        "formula": "salary.amount * 0.05"
      },
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z",
      "filters": [
        {
          "field": "department",
          "operator": "in",
          "value": [
            "Engineering"
          ]
        }
      ]
    }
  ]
}

Retrieve a compensation type

Retrieves the compensation type with the given ID.

Parameters

No parameters

Returns

Returns a compensation type object if a valid identifier was provided.

GET /api/compensation-types/:id

curl https://app.humaans.io/api/compensation-types/ldOQU3pLI5i8Y9k2rJbrXbFc \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "ldOQU3pLI5i8Y9k2rJbrXbFc",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Salary",
  "baseType": "salary",
  "formula": {
    "formula": "salary.amount * 0.05"
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "filters": [
    {
      "field": "department",
      "operator": "in",
      "value": [
        "Engineering"
      ]
    }
  ]
}

Compensations

An object representing compensation of an employee. Compensations come in several types: salary, bonus, commission, equity, and custom. Employees can have multiple compensations of each type. Only one compensation of each type with the latest effectiveDate value that is not in the future is considered to be currently in effect.

Endpoints

   GET /api/compensations

   GET /api/compensations/:id

  POST /api/compensations

 PATCH /api/compensations/:id

DELETE /api/compensations/:id

Required scopes

compensations:read

compensations:write

Compensation object

Attributes

idstring

Unique identifier for the object.
personIdstring

ID of the person that this object is associated to.
compensationTypeIdstring

ID of the Compensation type this compensation is related to.
amountstring

Compensation amount, can be a number (e.g. 70000 or 8.5), or a percentage (e.g. 12.5%). The fraction should be separated with a dot.
currencystring

Currency in 3 letter format (ISO 4217), e.g. EUR, USD, GBP, BTC.
periodstring

The period over which this compensation amount is paid. One of annual, biannual, quarterly, monthly, semimonthly, biweekly, weekly, daily, hourly, fixed, sale.
notestring

An optional note about this particular compensation entry.
effectiveDatedate

The date when this compensation took effect. Can be a past or future date.
endDatedate

Compensations of type bonus, commission and custom can have an endDate to indicate they are no longer in effect.
endReasonstring

Compensations of type bonus, commission and custom can have an endDate to indicate they are no longer in effect. In that case, the endReason can be used to indicate why the compensation was ended.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

The date and time the compensation was deleted. Only present on deleted compensations, which are only returned when querying with includeDeleted.

compensation object

{
  "id": "m54mmpqDwthFwiiMcY0ptJdz",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "compensationTypeId": "aejf1oD4bZWNtEEnbFwrYGVg",
  "amount": "70000",
  "currency": "EUR",
  "period": "annual",
  "note": "Promotion",
  "effectiveDate": "2020-02-15",
  "endDate": null,
  "endReason": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all compensations

Returns a list of compensations.

Parameters

compensationTypeIdstring · $eq $ne $in $nin

ID of the Compensation type this compensation is related to.
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
personIdstring · $in

The person to filter queries by.
createdAtdate | date-time · $gt $gte $lt $lte

Filter compensations by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$asOfdate

Filter the list of compensations to only one of each type per employee, finding the compensation of each type that was in effect on the provided date. Cannot be combined with includeDeleted.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit compensations. The response skips the first $skip results. Each entry is a separate compensation object. If no compensations are available, data is empty.

GET /api/compensations

curl https://app.humaans.io/api/compensations \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "m54mmpqDwthFwiiMcY0ptJdz",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "compensationTypeId": "aejf1oD4bZWNtEEnbFwrYGVg",
      "amount": "70000",
      "currency": "EUR",
      "period": "annual",
      "note": "Promotion",
      "effectiveDate": "2020-02-15",
      "endDate": null,
      "endReason": null,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a compensation

Retrieves the compensation with the given ID.

Parameters

No parameters

Returns

Returns a compensation object if a valid identifier was provided.

GET /api/compensations/:id

curl https://app.humaans.io/api/compensations/m54mmpqDwthFwiiMcY0ptJdz \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "m54mmpqDwthFwiiMcY0ptJdz",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "compensationTypeId": "aejf1oD4bZWNtEEnbFwrYGVg",
  "amount": "70000",
  "currency": "EUR",
  "period": "annual",
  "note": "Promotion",
  "effectiveDate": "2020-02-15",
  "endDate": null,
  "endReason": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a compensation

Any number of compensations can be created per each employee, but only the compensation with the highest effectiveDate that is not in the future will be considered as the active compensation of that compensation type. Note, that to preserve accurate records and history typically you want to create new compensations instead of editing existing ones when amounts, periods or other aspects of the compensation change.

Parameters

personIdstring required

ID of the person that this object is associated to.
compensationTypeIdstring one of type or compensationTypeId required

ID of the Compensation type this compensation is related to.
amountstring required

Compensation amount, can be a number (e.g. 70000 or 8.5), or a percentage (e.g. 12.5%). The fraction should be separated with a dot.
currencystring | null

Currency in 3 letter format (ISO 4217), e.g. EUR, USD, GBP, BTC.
periodstring required

The period over which this compensation amount is paid. One of annual, biannual, quarterly, monthly, semimonthly, biweekly, weekly, daily, hourly, fixed, sale.
notestring | null

An optional note about this particular compensation entry.
effectiveDatedate required

The date when this compensation took effect. Can be a past or future date.
endDatedate | null

Compensations of type bonus, commission and custom can have an endDate to indicate they are no longer in effect.
endReasonstring | null

Compensations of type bonus, commission and custom can have an endDate to indicate they are no longer in effect. In that case, the endReason can be used to indicate why the compensation was ended.

Returns

Returns a compensation if the call succeeded. The call returns an error if parameters are invalid.

POST /api/compensations

curl https://app.humaans.io/api/compensations \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","amount":"70000","period":"annual","effectiveDate":"2020-02-15","compensationTypeId":"aejf1oD4bZWNtEEnbFwrYGVg"}'

Response

{
  "id": "m54mmpqDwthFwiiMcY0ptJdz",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "compensationTypeId": "aejf1oD4bZWNtEEnbFwrYGVg",
  "amount": "70000",
  "currency": "EUR",
  "period": "annual",
  "note": "Promotion",
  "effectiveDate": "2020-02-15",
  "endDate": null,
  "endReason": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a compensation

Updates the compensation object. Note, that to preserve accurate records and history typically you want to create new compensations instead of editing existing ones when amounts, periods or other aspects of the compensation change.

Parameters

compensationTypeIdstring at most one of type or compensationTypeId

ID of the Compensation type this compensation is related to.
amountstring

Compensation amount, can be a number (e.g. 70000 or 8.5), or a percentage (e.g. 12.5%). The fraction should be separated with a dot.
currencystring | null

Currency in 3 letter format (ISO 4217), e.g. EUR, USD, GBP, BTC.
periodstring

The period over which this compensation amount is paid. One of annual, biannual, quarterly, monthly, semimonthly, biweekly, weekly, daily, hourly, fixed, sale.
notestring | null

An optional note about this particular compensation entry.
effectiveDatedate

The date when this compensation took effect. Can be a past or future date.
endDatedate | null

Compensations of type bonus, commission and custom can have an endDate to indicate they are no longer in effect.
endReasonstring | null

Compensations of type bonus, commission and custom can have an endDate to indicate they are no longer in effect. In that case, the endReason can be used to indicate why the compensation was ended.

Returns

Returns the compensation if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/compensations/:id

curl https://app.humaans.io/api/compensations/m54mmpqDwthFwiiMcY0ptJdz \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"amount":"70000"}'

Response

{
  "id": "m54mmpqDwthFwiiMcY0ptJdz",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "compensationTypeId": "aejf1oD4bZWNtEEnbFwrYGVg",
  "amount": "70000",
  "currency": "EUR",
  "period": "annual",
  "note": "Promotion",
  "effectiveDate": "2020-02-15",
  "endDate": null,
  "endReason": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a compensation

Permanently deletes a compensation. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/compensations/:id

curl https://app.humaans.io/api/compensations/m54mmpqDwthFwiiMcY0ptJdz \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "m54mmpqDwthFwiiMcY0ptJdz",
  "deleted": true
}

Custom fields

An object representing a custom field and its configuration.

Endpoints

   GET /api/custom-fields

   GET /api/custom-fields/:id

  POST /api/custom-fields

 PATCH /api/custom-fields/:id

DELETE /api/custom-fields/:id

Required scopes

private:read

private:write

Custom field object

Attributes

idstring

Unique identifier for the object.
companyIdstring

ID of the company that this object is associated to.
namestring

The name of the custom field.
sectionstring

The profile section where the custom field will appear in. One of basics, health, diversity, banking, equipment, social, employment, jobRole, compensation, offboarding
resourceIdstring

The ID of the resource this field belongs. This is an ID of a compensation type in the case where section is compensation
typestring

Custom field type. One of text, longText, select, multiSelect, link, date, person. If section is diversity, this is limited to text, select, multiSelect
configobject

Extra configuration for the custom field, differs based on the type. For fields of type text the options are { "autocomplete": boolean }, and for fields of type select the options are { "choices": string[] }
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

custom field object

{
  "id": "ZpbLXlJRpBJQOre5kbFQqYf4",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Payroll code",
  "section": "employment",
  "resourceId": "s6KZm4xNCvzBlCYeBSSCKDcH",
  "type": "text",
  "config": {},
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all custom fields

Returns a list of custom fields.

Parameters

idstring · $eq $ne $in $nin
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
sectionstring · $eq $ne $in $nin

The profile section where the custom field will appear in. One of basics, health, diversity, banking, equipment, social, employment, jobRole, compensation, offboarding
typestring · $eq $ne $in $nin

Custom field type. One of text, longText, select, multiSelect, link, date, person. If section is diversity, this is limited to text, select, multiSelect
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit custom fields. The response skips the first $skip results. Each entry is a separate custom field object. If no custom fields are available, data is empty.

GET /api/custom-fields

curl https://app.humaans.io/api/custom-fields \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "ZpbLXlJRpBJQOre5kbFQqYf4",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "Payroll code",
      "section": "employment",
      "resourceId": "s6KZm4xNCvzBlCYeBSSCKDcH",
      "type": "text",
      "config": {},
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a custom field

Retrieves the custom field with the given ID.

Parameters

No parameters

Returns

Returns a custom field object if a valid identifier was provided.

GET /api/custom-fields/:id

curl https://app.humaans.io/api/custom-fields/ZpbLXlJRpBJQOre5kbFQqYf4 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "ZpbLXlJRpBJQOre5kbFQqYf4",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Payroll code",
  "section": "employment",
  "resourceId": "s6KZm4xNCvzBlCYeBSSCKDcH",
  "type": "text",
  "config": {},
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a custom field

Parameters

namestring required

The name of the custom field.
sectionstring required

The profile section where the custom field will appear in. One of basics, health, diversity, banking, equipment, social, employment, jobRole, compensation, offboarding
resourceIdstring | null

The ID of the resource this field belongs. This is an ID of a compensation type in the case where section is compensation
typestring required

Custom field type. One of text, longText, select, multiSelect, link, date, person. If section is diversity, this is limited to text, select, multiSelect
configobject

Extra configuration for the custom field, differs based on the type. For fields of type text the options are { "autocomplete": boolean }, and for fields of type select the options are { "choices": string[] }

Returns

Returns a custom field if the call succeeded. The call returns an error if parameters are invalid.

POST /api/custom-fields

curl https://app.humaans.io/api/custom-fields \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"Payroll code","type":"text","section":"employment"}'

Response

{
  "id": "ZpbLXlJRpBJQOre5kbFQqYf4",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Payroll code",
  "section": "employment",
  "resourceId": "s6KZm4xNCvzBlCYeBSSCKDcH",
  "type": "text",
  "config": {},
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a custom field

Parameters

namestring

The name of the custom field.
configobject

Extra configuration for the custom field, differs based on the type. For fields of type text the options are { "autocomplete": boolean }, and for fields of type select the options are { "choices": string[] }

Returns

Returns the custom field if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/custom-fields/:id

curl https://app.humaans.io/api/custom-fields/ZpbLXlJRpBJQOre5kbFQqYf4 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"name":"Payroll number"}'

Response

{
  "id": "ZpbLXlJRpBJQOre5kbFQqYf4",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Payroll number",
  "section": "employment",
  "resourceId": "s6KZm4xNCvzBlCYeBSSCKDcH",
  "type": "text",
  "config": {},
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a custom field

Permanently deletes a custom field. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/custom-fields/:id

curl https://app.humaans.io/api/custom-fields/ZpbLXlJRpBJQOre5kbFQqYf4 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "ZpbLXlJRpBJQOre5kbFQqYf4",
  "deleted": true
}

Custom values

An object representing a custom field value.

Endpoints

   GET /api/custom-values

   GET /api/custom-values/:id

  POST /api/custom-values

 PATCH /api/custom-values/:id

DELETE /api/custom-values/:id

Required scopes

private:read

private:write

Custom value object

Attributes

idstring

Unique identifier for the object.
personIdstring

ID of the person that this object is associated to.
customFieldIdstring

The ID of the custom field this value is for.
resourceIdstring

The ID of the resource this field belongs to in case it is a subresource of a person. This is an ID of a Bank account in case section is banking. It’s an ID of an Equipment in case section is equipment.
valuestring | string[] | null

The value of the custom field.

If customField.type is text, longText, or select this should be a string.

If customField.type is multiSelect this should be an array of string.

If customField.type is date this should be a string formatted as a date.

If customField.type is person this should person.id.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

custom value object

{
  "id": "gk1P9Iidto7eh2ygaYD865P2",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "customFieldId": "ZzYipWn8ilL2lIxaFLhOeb7d",
  "resourceId": "X2O5IvAMDl3a88p7rbOiKImc",
  "value": "C8899754",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all custom values

Returns a list of custom values.

Parameters

customFieldIdstring · $eq $ne $in $nin

The custom field to filter queries by.
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
personIdstring · $eq $ne $in $nin

The person to filter queries by.
resourceIdstring · $eq $ne $in $nin

The ID of the resource this field belongs to in case it is a subresource of a person. This is an ID of a Bank account in case section is banking. It’s an ID of an Equipment in case section is equipment.
createdAtdate | date-time · $gt $gte $lt $lte

Filter custom values by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$orobject[]
$or.resourceIdstring · $eq $ne $in $nin
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit custom values. The response skips the first $skip results. Each entry is a separate custom value object. If no custom values are available, data is empty.

GET /api/custom-values

curl https://app.humaans.io/api/custom-values \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "gk1P9Iidto7eh2ygaYD865P2",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "customFieldId": "ZzYipWn8ilL2lIxaFLhOeb7d",
      "resourceId": "X2O5IvAMDl3a88p7rbOiKImc",
      "value": "C8899754",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a custom value

Retrieves the custom value with the given ID.

Parameters

No parameters

Returns

Returns a custom value object if a valid identifier was provided.

GET /api/custom-values/:id

curl https://app.humaans.io/api/custom-values/gk1P9Iidto7eh2ygaYD865P2 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "gk1P9Iidto7eh2ygaYD865P2",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "customFieldId": "ZzYipWn8ilL2lIxaFLhOeb7d",
  "resourceId": "X2O5IvAMDl3a88p7rbOiKImc",
  "value": "C8899754",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a custom value

Parameters

valuestring | string[] | null required

The value of the custom field.

If customField.type is text, longText, or select this should be a string.

If customField.type is multiSelect this should be an array of string.

If customField.type is date this should be a string formatted as a date.

If customField.type is person this should person.id.
personIdstring required

ID of the person that this object is associated to.
customFieldIdstring required

The ID of the custom field this value is for.
resourceIdstring | null

The ID of the resource this field belongs to in case it is a subresource of a person. This is an ID of a Bank account in case section is banking. It’s an ID of an Equipment in case section is equipment.

Returns

Returns a custom value if the call succeeded. The call returns an error if parameters are invalid.

POST /api/custom-values

curl https://app.humaans.io/api/custom-values \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","customFieldId":"ZzYipWn8ilL2lIxaFLhOeb7d","value":"C8899754"}'

Response

{
  "id": "gk1P9Iidto7eh2ygaYD865P2",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "customFieldId": "ZzYipWn8ilL2lIxaFLhOeb7d",
  "resourceId": "X2O5IvAMDl3a88p7rbOiKImc",
  "value": "C8899754",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a custom value

Parameters

valuestring | string[] | null

The value of the custom field.

If customField.type is text, longText, or select this should be a string.

If customField.type is multiSelect this should be an array of string.

If customField.type is date this should be a string formatted as a date.

If customField.type is person this should person.id.

Returns

Returns the custom value if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/custom-values/:id

curl https://app.humaans.io/api/custom-values/gk1P9Iidto7eh2ygaYD865P2 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"value":"C7864654"}'

Response

{
  "id": "gk1P9Iidto7eh2ygaYD865P2",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "customFieldId": "ZzYipWn8ilL2lIxaFLhOeb7d",
  "resourceId": "X2O5IvAMDl3a88p7rbOiKImc",
  "value": "C7864654",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a custom value

Permanently deletes a custom value. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/custom-values/:id

curl https://app.humaans.io/api/custom-values/gk1P9Iidto7eh2ygaYD865P2 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "gk1P9Iidto7eh2ygaYD865P2",
  "deleted": true
}

Data exports

Data export API can be used to quickly export a large set of data about all of the employees.

Endpoints

   GET /api/data-exports/:id

  POST /api/data-exports

DELETE /api/data-exports/:id

Required scopes

Multiple scopes are allowed. Depending on which fields you’d like to export, use one of public:read, private:read, or compensations:read.

Data export object

Attributes

idstring

Unique identifier for the object.
companyIdstring

ID of the company that this object is associated to.
urlstring

The URL from which exported data file can be downloaded.
dataExportTemplateIdstring

Data export template used for this export
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
filtersobject[]

Filters to control the data included in the export
filters.fieldstring

The field to filter on. Available fields for type enum: spaceId, payrollProvider, department, contractType, locationId, placeOfWorkCountry, placeOfWorkCity, orgLevel, reportingTo. Available fields for type array: teams, reportsUpTo.
filters.operatorstring

The operator to use when filtering. Available operators for field type string: eq, ne, contains, ncontains, exists, nexists. Available operators for field type enum: in, nin, exists, nexists. Available operators for field type array: all, any, nany, nall, exists, nexists. Available operators for field type number: eq, ne, gt, gte, lt, lte, exists, nexists. Available operators for field type date: eq, lt, gt, lte, gte, exists, nexists. Available operators for field type boolean: eq, exists, nexists.
filters.value

The value(s) of the field to check

data export object

{
  "id": "yQYtUaI6LeTc1Ss5S0FgInPo",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "url": "/data-exports/dPnhSGDoq9UUR9Bf1BwPPkjC",
  "dataExportTemplateId": "pGsUdvAqXqZJWE6krhvceLNa",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "filters": [
    {
      "field": "department",
      "operator": "in",
      "value": [
        "Engineering",
        "Sales"
      ]
    }
  ]
}

Retrieve a data export

Retrieves the data export with the given ID. Note that this only retrieves the metadata about the data export. To download the actual data, you need to resolve the url and download the data from that URL.

Parameters

No parameters

Returns

Returns a data export object if a valid identifier was provided.

GET /api/data-exports/:id

curl https://app.humaans.io/api/data-exports/yQYtUaI6LeTc1Ss5S0FgInPo \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "yQYtUaI6LeTc1Ss5S0FgInPo",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "url": "/data-exports/dPnhSGDoq9UUR9Bf1BwPPkjC",
  "dataExportTemplateId": "pGsUdvAqXqZJWE6krhvceLNa",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "filters": [
    {
      "field": "department",
      "operator": "in",
      "value": [
        "Engineering",
        "Sales"
      ]
    }
  ]
}

Create a data export

Note that once the data export is created the exported data needs to be downloaded separately. This can be done by resolving the url field and downloading data from that URL.

Parameters

compensationTypesstring[]

The list of compensation type IDs that should be included in the data export.
customFieldsstring[]

The list of custom field IDs that should be included in the data export.
customIdentifierFieldsstring[]

The list of custom field IDs that should be treated as identifier fields in changes report
dataExportTemplateIdstring

Data export template used for this export
downloadboolean

By default, the resulting payload of creating an export includes a URL from which exported data file can be downloaded, set this to true to immediately get the generated result in the same request.
endDatestring | null

The end date of the data export.
fieldsstring[] | null

The list of fields that should be included in the data export. Available fields for export type people: companyName, firstName, preferredName, preferredNameOrFirstName, middleName, lastName, fullName, pronouns, birthday, shortBirthday, nationality, spokenLanguages, gender, email, phoneNumber, personalEmail, personalPhoneNumber, fullAddress, country, countryCode, dietaryPreference, foodAllergies, idExpiryDates, emergencyContacts, timezone, jobTitle, department, manager, managerPreferredName, managerEmail, roleEffectiveDate, lastPerformanceRating, teams, placeOfWork, fullPlaceOfWork, placeOfWorkCity, placeOfWorkCountry, isRemote, space, payrollProvider, contractType, employeeId, taxId, taxCode, employeeStatus, employmentStartDate, firstWorkingDay, firstActiveAt, workingDays, workingPattern, fte, unroundedFte, probationEndDate, employmentEndDate, lastWorkingDay, leavingReason, turnoverImpact, leavingNote, bankName, nameOnAccount, accountNumber, swiftCode, sortCode, routingNumber, remoteCountryCode, salary, bonus, equity, commission, paidTimeOff, unpaidLeave, sickLeave, parentalLeave, workingFromHome, otherTimeAway, approvalFlow, allowance, fromPrevAccrualPeriod, fromPrevAccrualPeriodExpired, carriedOver, carriedOverExpired, adjustments, accrued, upcoming, balance, endOfYearBalance, ptoPolicy, social, diversity. Available fields for export type equipment: firstName, preferredName, middleName, lastName, gender, email, phoneNumber, personalEmail, personalPhoneNumber, fullAddress, country, jobTitle, department, manager, managerPreferredName, managerEmail, roleEffectiveDate, lastPerformanceRating, teams, placeOfWork, fullPlaceOfWork, isRemote, space, payrollProvider, contractType, employeeId, employeeStatus, employmentStartDate, firstWorkingDay, firstActiveAt, workingDays, workingPattern, fte, unroundedFte, probationEndDate, employmentEndDate, lastWorkingDay, leavingReason, turnoverImpact, leavingNote, type, name, serialNumber, cost, currency, note, attachment, issueDate, receiptDate, collectionDate. Available fields for export type timeAway: firstName, preferredName, middleName, lastName, gender, email, phoneNumber, personalEmail, personalPhoneNumber, fullAddress, country, isTimeOff, jobTitle, department, manager, managerPreferredName, managerEmail, roleEffectiveDate, lastPerformanceRating, teams, placeOfWork, fullPlaceOfWork, isRemote, space, payrollProvider, contractType, employeeId, employeeStatus, employmentStartDate, firstWorkingDay, firstActiveAt, workingDays, workingPattern, fte, unroundedFte, probationEndDate, employmentEndDate, lastWorkingDay, leavingReason, turnoverImpact, leavingNote, timeAwayType, startDate, endDate, startPeriod, endPeriod, days, note, registeredOn, requestStatus, reviewer, reviewerEmail, reviewedAt, publicHolidayCalendar, approvalFlow, ptoPolicy. Available fields for export type timesheet: firstName, preferredName, middleName, lastName, gender, email, phoneNumber, personalEmail, personalPhoneNumber, fullAddress, country, jobTitle, department, manager, managerPreferredName, managerEmail, roleEffectiveDate, lastPerformanceRating, teams, placeOfWork, fullPlaceOfWork, isRemote, space, payrollProvider, contractType, employeeId, employeeStatus, employmentStartDate, firstWorkingDay, firstActiveAt, workingDays, workingPattern, fte, unroundedFte, probationEndDate, employmentEndDate, lastWorkingDay, leavingReason, turnoverImpact, leavingNote, startDate, endDate, submittedAt, totalTime, totalDays, status, reviewer, reviewerEmail, reviewedAt. Available fields for export type document: firstName, preferredName, middleName, lastName, gender, email, phoneNumber, personalEmail, personalPhoneNumber, fullAddress, country, jobTitle, department, manager, managerPreferredName, managerEmail, roleEffectiveDate, lastPerformanceRating, teams, placeOfWork, fullPlaceOfWork, isRemote, space, payrollProvider, contractType, employeeId, employeeStatus, employmentStartDate, firstWorkingDay, firstActiveAt, workingDays, workingPattern, fte, unroundedFte, probationEndDate, employmentEndDate, lastWorkingDay, leavingReason, turnoverImpact, leavingNote, type, name, issueDate, link, documentLink, uploader, uploaderEmail. Available fields for export type identityDocument: firstName, preferredName, middleName, lastName, nationality, gender, email, phoneNumber, personalEmail, personalPhoneNumber, fullAddress, country, jobTitle, department, manager, managerPreferredName, managerEmail, roleEffectiveDate, lastPerformanceRating, teams, placeOfWork, fullPlaceOfWork, isRemote, space, payrollProvider, contractType, employeeId, employeeStatus, employmentStartDate, firstWorkingDay, firstActiveAt, workingDays, workingPattern, fte, unroundedFte, probationEndDate, employmentEndDate, lastWorkingDay, leavingReason, turnoverImpact, leavingNote, type, number, expiryDate, note, issueCountry, link, verifier, verifierEmail. Available fields for export type changes: firstName, preferredName, middleName, lastName, pronouns, birthday, shortBirthday, nationality, spokenLanguages, gender, email, phoneNumber, personalEmail, personalPhoneNumber, fullAddress, country, dietaryPreference, foodAllergies, idExpiryDates, emergencyContacts, jobTitle, department, managerPreferredName, managerEmail, roleEffectiveDate, lastPerformanceRating, teams, isRemote, space, placeOfWork, payrollProvider, contractType, employeeId, taxId, taxCode, employeeStatus, employmentStartDate, firstWorkingDay, firstActiveAt, workingDays, workingPattern, fte, unroundedFte, probationEndDate, employmentEndDate, lastWorkingDay, leavingReason, turnoverImpact, leavingNote, bankName, nameOnAccount, accountNumber, swiftCode, sortCode, routingNumber, social, diversity. Available fields for export type events: firstName, preferredName, middleName, lastName, pronouns, birthday, shortBirthday, nationality, spokenLanguages, gender, email, phoneNumber, personalEmail, personalPhoneNumber, fullAddress, country, dietaryPreference, foodAllergies, idExpiryDates, emergencyContacts, jobTitle, department, managerPreferredName, managerEmail, roleEffectiveDate, lastPerformanceRating, teams, fullPlaceOfWork, space, payrollProvider, contractType, employeeId, taxId, taxCode, employeeStatus, employmentStartDate, firstWorkingDay, firstActiveAt, workingDays, workingPattern, fte, unroundedFte, probationEndDate, employmentEndDate, lastWorkingDay, leavingReason, turnoverImpact, leavingNote, event, date, anniversaryLength.
identifierFieldsstring[]

The list of fields that should be treated as identifier fields in changes report. Available fields: firstName, preferredName, middleName, lastName, pronouns, birthday, nationality, gender, email, phoneNumber, personalEmail, personalPhoneNumber, country, fullAddress, jobTitle, department, teams, payrollProvider, contractType, employeeId, employeeStatus, employmentStartDate, firstWorkingDay, firstActiveAt, probationEndDate, employmentEndDate, lastWorkingDay.
includeAdjustmentsboolean

Set to true to include time away adjustments. Only applies to exports of type timeAway
includeUnsubmittedHoursboolean

Set to true to include recorded hours that have not been submitted yet. Only applies to exports of type timesheet
includeAllDocumentVersionsboolean

Set to true to include all document versions. Only applies to exports of type identityDocument
includeAnniversariesboolean

Set to true to include work anniversary events. Only applies to exports of type events. Defaults to false.
includeArchivedWorkflowsboolean

Set to true to include archived workflow instances. Only applies to exports of type workflowActivity
includeBirthdaysboolean

Set to true to include birthday events. Only applies to exports of type events. Defaults to false.
includeCompensationHistoryboolean

Set to true to include every compensation that was in effect within the filtered date range. This will output multiple rows of data per each employee.
includeJoinersboolean

Set to true to include joiner events. Only applies to exports of type events. Defaults to false.
includeLeaversboolean

Set to true to include leaver events. Only applies to exports of type events. Defaults to false.
includeProbationEndboolean

Set to true to include probation end events. Only applies to exports of type events. Defaults to false.
includeOffboardedboolean

Set to true to include offboarded people in the data export.
includeNewHiresboolean
includeRoleHistoryboolean

Set to true to include every job role that was in effect within the filtered date range. This will output multiple rows of data per each employee.
includeWithoutDocumentsboolean

Set to true to include employees without any documents. Only applies to exports of type document or identityDocument
includeWithoutEquipmentboolean

Set to true to include employees without any equipment. Only applies to exports of type equipment
includeWithoutGoalsboolean

Set to true to include employees without any goals. Only applies to exports of type goals
jsonboolean

Generate the output in JSON format instead of CSV
startDatestring | null

The start date of the data export. This is used to include only the people that were active after this date. It is also used when rolling up time away taken totals.
timeAwayTypesstring[]

The list of time away type IDs that should be included in the data export.
typestring

The type of export, one of people, equipment, timesheet, timeAway, document, identityDocument, workflowActivity, changes, payroll, requests, goals, events, performance. Default: people.
filtersobject[]

Filters to control the data included in the export
filters.fieldstring required

The field to filter on. Available fields for type enum: spaceId, payrollProvider, department, contractType, locationId, placeOfWorkCountry, placeOfWorkCity, orgLevel, reportingTo. Available fields for type array: teams, reportsUpTo.
filters.operatorstring required

The operator to use when filtering. Available operators for field type string: eq, ne, contains, ncontains, exists, nexists. Available operators for field type enum: in, nin, exists, nexists. Available operators for field type array: all, any, nany, nall, exists, nexists. Available operators for field type number: eq, ne, gt, gte, lt, lte, exists, nexists. Available operators for field type date: eq, lt, gt, lte, gte, exists, nexists. Available operators for field type boolean: eq, exists, nexists.
filters.value

The value(s) of the field to check

Returns

Returns a data export if the call succeeded. The call returns an error if parameters are invalid.

POST /api/data-exports

curl https://app.humaans.io/api/data-exports \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"fields":["firstName","lastName","email","jobTitle"]}'

Response

{
  "id": "yQYtUaI6LeTc1Ss5S0FgInPo",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "url": "/data-exports/dPnhSGDoq9UUR9Bf1BwPPkjC",
  "dataExportTemplateId": "pGsUdvAqXqZJWE6krhvceLNa",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "filters": [
    {
      "field": "department",
      "operator": "in",
      "value": [
        "Engineering",
        "Sales"
      ]
    }
  ]
}

Delete a data export

Permanently deletes a data export. It cannot be undone. Note that data exports expire automatically after a short period of time.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/data-exports/:id

curl https://app.humaans.io/api/data-exports/yQYtUaI6LeTc1Ss5S0FgInPo \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "yQYtUaI6LeTc1Ss5S0FgInPo",
  "deleted": true
}

Document types

An object representing a type of a document. This resource is used to find out the list of all document types that are in use in the account.

Endpoints

   GET /api/document-types

  POST /api/document-types

 PATCH /api/document-types/:id

DELETE /api/document-types/:id

Required scopes

documents:read

documents:write

Document type object

Attributes

idstring

Unique identifier for the object.
namestring

The label of the document type. Types are used to organise the documents and to restrict access. Document permissions found in the Admin area can be used to set access level for each document type.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

document type object

{
  "id": "Ozcv1Wea2yfUhSm8fsj0ziIf",
  "name": "Employment agreement",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all document types

Returns a list of document types.

Parameters

includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
createdAtdate | date-time · $gt $gte $lt $lte

Filter document types by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit document types. The response skips the first $skip results. Each entry is a separate document type object. If no document types are available, data is empty.

GET /api/document-types

curl https://app.humaans.io/api/document-types \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "Ozcv1Wea2yfUhSm8fsj0ziIf",
      "name": "Employment agreement",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Create a document type

Parameters

namestring required

The label of the document type. Types are used to organise the documents and to restrict access. Document permissions found in the Admin area can be used to set access level for each document type.

Returns

Returns a document type if the call succeeded. The call returns an error if parameters are invalid.

POST /api/document-types

curl https://app.humaans.io/api/document-types \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"Employment agreement"}'

Response

{
  "id": "Ozcv1Wea2yfUhSm8fsj0ziIf",
  "name": "Employment agreement",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a document type

Parameters

namestring required

The label of the document type. Types are used to organise the documents and to restrict access. Document permissions found in the Admin area can be used to set access level for each document type.

Returns

Returns the document type if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/document-types/:id

curl https://app.humaans.io/api/document-types/Ozcv1Wea2yfUhSm8fsj0ziIf \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"name":"Employment agreement"}'

Response

{
  "id": "Ozcv1Wea2yfUhSm8fsj0ziIf",
  "name": "Employment agreement",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a document type

Permanently deletes a document type. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/document-types/:id

curl https://app.humaans.io/api/document-types/Ozcv1Wea2yfUhSm8fsj0ziIf \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "Ozcv1Wea2yfUhSm8fsj0ziIf",
  "deleted": true
}

Documents

An object representing a document that can be attached to an employee or the company.

Endpoints

   GET /api/documents

   GET /api/documents/:id

  POST /api/documents

 PATCH /api/documents/:id

DELETE /api/documents/:id

Required scopes

documents:read

documents:write

Document object

Attributes

idstring

Unique identifier for the object.
personIdstring

ID of the person that this object is associated to.
namestring

The name of the document
documentTypeIdstring

The ID of the document type.
linkstring

Documents must have either a link or a file attached.
fileIdstring

Documents must have either a link or a file attached.
fileobject

A subset of the file object attached to this document. The full file object can be retrieved using the Files endpoint.
file.idstring

Unique identifier for the object.
file.urlstring

The URL from which the attached file can be downloaded.
file.filenamestring

The name of the file attached.
sourcestring

The external service from which the document has been imported
sourceIdstring

The unique identifier of the document in the remote service
issueDatedate

The date when the document was issued.
createdBystring

ID of the user who created the document
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.

document object

{
  "id": "j5nMguwlwQeNYkk9Jie8u1Q2",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "name": "Employment agreement 2020 (Initial)",
  "link": "https://drive.google.com/docs/KMjibfqIQC3hiZK2tFItQetm",
  "fileId": null,
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "source": null,
  "sourceId": null,
  "issueDate": "2020-01-28",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all documents

Returns a list of documents.

Parameters

includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
personIdstring · $eq $ne $in $nin

ID of the person that this object is associated to. Pass null or no value for company documents only (personId is null). Use personId[$ne]=null for personal docs only, personId[$in][]=id for multiple.
createdAtdate | date-time · $gt $gte $lt $lte

Filter documents by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$orobject[]

Filter by multiple conditions.
$or.personIdstring | empty

Useful for fetching personal documents for a single person and company wide documents at the same time. E.g. GET /api/documents?$or[0][personId]=j5nMguwlw&$or[1][personId]=
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit documents. The response skips the first $skip results. Each entry is a separate document object. If no documents are available, data is empty.

GET /api/documents

curl https://app.humaans.io/api/documents \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "j5nMguwlwQeNYkk9Jie8u1Q2",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "name": "Employment agreement 2020 (Initial)",
      "link": "https://drive.google.com/docs/KMjibfqIQC3hiZK2tFItQetm",
      "fileId": null,
      "file": {
        "id": "51YzMOYrc9rU0lNGn1QtgSv0",
        "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
        "filename": "passport-scan.pdf"
      },
      "source": null,
      "sourceId": null,
      "issueDate": "2020-01-28",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a document

Retrieves the document with the given ID.

Parameters

No parameters

Returns

Returns a document object if a valid identifier was provided.

GET /api/documents/:id

curl https://app.humaans.io/api/documents/j5nMguwlwQeNYkk9Jie8u1Q2 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "j5nMguwlwQeNYkk9Jie8u1Q2",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "name": "Employment agreement 2020 (Initial)",
  "link": "https://drive.google.com/docs/KMjibfqIQC3hiZK2tFItQetm",
  "fileId": null,
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "source": null,
  "sourceId": null,
  "issueDate": "2020-01-28",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a document

Parameters

personIdstring | null

ID of the person that this object is associated to.
namestring required

The name of the document
documentTypeIdstring | null

The ID of the document type.
linkstring | null one of link or fileId required

Documents must have either a link or a file attached.
fileIdstring | null one of link or fileId required

Documents must have either a link or a file attached.
issueDatedate

The date when the document was issued.
typestring

The document type.

Returns

Returns a document if the call succeeded. The call returns an error if parameters are invalid.

POST /api/documents

curl https://app.humaans.io/api/documents \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"Employment agreement 2020 (Initial)","link":"https://drive.google.com/docs/KMjibfqIQC3hiZK2tFItQetm"}'

Response

{
  "id": "j5nMguwlwQeNYkk9Jie8u1Q2",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "name": "Employment agreement 2020 (Initial)",
  "link": "https://drive.google.com/docs/KMjibfqIQC3hiZK2tFItQetm",
  "fileId": null,
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "source": null,
  "sourceId": null,
  "issueDate": "2020-01-28",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a document

Parameters

namestring

The name of the document
documentTypeIdstring | null

The ID of the document type.
issueDatedate

The date when the document was issued.
typestring

The document type.

Returns

Returns the document if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/documents/:id

curl https://app.humaans.io/api/documents/j5nMguwlwQeNYkk9Jie8u1Q2 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"link":"https://intranet/doc/2"}'

Response

{
  "id": "j5nMguwlwQeNYkk9Jie8u1Q2",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "name": "Employment agreement 2020 (Initial)",
  "link": "https://intranet/doc/2",
  "fileId": null,
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "source": null,
  "sourceId": null,
  "issueDate": "2020-01-28",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a document

Permanently deletes a document. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/documents/:id

curl https://app.humaans.io/api/documents/j5nMguwlwQeNYkk9Jie8u1Q2 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "j5nMguwlwQeNYkk9Jie8u1Q2",
  "deleted": true
}

Emergency contacts

An object representing an emergency contact of an employee. Up to 2 emergency contacts can be created per employee. One of them must be marked as primary.

Endpoints

   GET /api/emergency-contacts

   GET /api/emergency-contacts/:id

  POST /api/emergency-contacts

 PATCH /api/emergency-contacts/:id

DELETE /api/emergency-contacts/:id

Required scopes

private:read

private:write

Emergency contact object

Attributes

idstring

Unique identifier for the object.
personIdstring

ID of the person that this object is associated to.
namestring

The name of the emergency contact.
emailstring

The email of the emergency contact.
phoneNumberstring

The phone number of the emergency contact.
formattedPhoneNumberstring

This holds the value of the phoneNumber field but formatted for display.
relationshipstring

The relationship of the emergency contact to the employee.
isPrimaryboolean

Indicates the primary emergency contact. Only one emergency can be primary.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.

emergency contact object

{
  "id": "QmzB8xCTAG7IIHcsM1DKdpZe",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "name": "Sean Reese",
  "email": "sean@example.com",
  "phoneNumber": "+4479460000",
  "formattedPhoneNumber": "+44 7946 0000",
  "relationship": "Partner ❤️",
  "isPrimary": true,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all emergency contacts

Returns a list of emergency contacts.

Parameters

includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
isPrimaryboolean

Indicates the primary emergency contact. Only one emergency can be primary.
personIdstring · $in

The person to filter queries by.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit emergency contacts. The response skips the first $skip results. Each entry is a separate emergency contact object. If no emergency contacts are available, data is empty.

GET /api/emergency-contacts

curl https://app.humaans.io/api/emergency-contacts \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "QmzB8xCTAG7IIHcsM1DKdpZe",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "name": "Sean Reese",
      "email": "sean@example.com",
      "phoneNumber": "+4479460000",
      "formattedPhoneNumber": "+44 7946 0000",
      "relationship": "Partner ❤️",
      "isPrimary": true,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve an emergency contact

Retrieves the emergency contact with the given ID.

Parameters

No parameters

Returns

Returns an emergency contact object if a valid identifier was provided.

GET /api/emergency-contacts/:id

curl https://app.humaans.io/api/emergency-contacts/QmzB8xCTAG7IIHcsM1DKdpZe \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "QmzB8xCTAG7IIHcsM1DKdpZe",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "name": "Sean Reese",
  "email": "sean@example.com",
  "phoneNumber": "+4479460000",
  "formattedPhoneNumber": "+44 7946 0000",
  "relationship": "Partner ❤️",
  "isPrimary": true,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create an emergency contact

Parameters

namestring | null

The name of the emergency contact.
emailstring | null

The email of the emergency contact.
phoneNumberstring | null

The phone number of the emergency contact.
relationshipstring | null

The relationship of the emergency contact to the employee.
personIdstring required

ID of the person that this object is associated to.
isPrimaryboolean required

Indicates the primary emergency contact. Only one emergency can be primary.

Returns

Returns an emergency contact if the call succeeded. The call returns an error if parameters are invalid.

POST /api/emergency-contacts

curl https://app.humaans.io/api/emergency-contacts \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","isPrimary":true}'

Response

{
  "id": "QmzB8xCTAG7IIHcsM1DKdpZe",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "name": "Sean Reese",
  "email": "sean@example.com",
  "phoneNumber": "+4479460000",
  "formattedPhoneNumber": "+44 7946 0000",
  "relationship": "Partner ❤️",
  "isPrimary": true,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update an emergency contact

Parameters

namestring | null

The name of the emergency contact.
emailstring | null

The email of the emergency contact.
phoneNumberstring | null

The phone number of the emergency contact.
relationshipstring | null

The relationship of the emergency contact to the employee.

Returns

Returns the emergency contact if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/emergency-contacts/:id

curl https://app.humaans.io/api/emergency-contacts/QmzB8xCTAG7IIHcsM1DKdpZe \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"email":"sean.reese@example.com"}'

Response

{
  "id": "QmzB8xCTAG7IIHcsM1DKdpZe",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "name": "Sean Reese",
  "email": "sean.reese@example.com",
  "phoneNumber": "+4479460000",
  "formattedPhoneNumber": "+44 7946 0000",
  "relationship": "Partner ❤️",
  "isPrimary": true,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete an emergency contact

Permanently deletes an emergency contact. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/emergency-contacts/:id

curl https://app.humaans.io/api/emergency-contacts/QmzB8xCTAG7IIHcsM1DKdpZe \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "QmzB8xCTAG7IIHcsM1DKdpZe",
  "deleted": true
}

Equipment

An object representing a piece of equipment issued to an employee. It can be used for things like company issued laptops, screens, other accessories, key cards, chairs and so on.

Endpoints

   GET /api/equipment

   GET /api/equipment/:id

  POST /api/equipment

 PATCH /api/equipment/:id

DELETE /api/equipment/:id

Required scopes

private:read

private:write

Equipment object

Attributes

idstring

Unique identifier for the object.
personIdstring

ID of the person that this object is associated to.
typestring

The type of the equipment.
namestring

The name / model on the equipment.
serialNumberstring

The serial number.
coststring

Cost, the fraction should be separated with a dot.
currencystring

Currency in 3 letter format (ISO 4217), e.g. EUR, USD, GBP, BTC.
notestring

Any additional notes.
fileIdstring

A file attachment.
fileobject

A subset of the file object attached to this document. The full file object can be retrieved using the Files endpoint.
file.idstring

Unique identifier for the object.
file.urlstring

The URL from which the attached file can be downloaded.
file.filenamestring

The name of the file attached.
issueDatedate

The date when the equipment was issued.
receiptDatedate

The date when the equipment was received by the employee, if different from issue date.
collectionDatedate

The date when the equipment was collected from the employee.
collectedBystring

The person that marked the equipment as collected.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

equipment object

{
  "id": "W1Uisa336KrC6Rt55pEBkTNZ",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "Laptop",
  "name": "MacBook Pro (13-inch, 2017)",
  "serialNumber": "C012345678",
  "cost": "1299",
  "currency": "EUR",
  "note": "Refurbished.",
  "fileId": null,
  "file": null,
  "issueDate": "2020-01-28",
  "receiptDate": "2020-01-28",
  "collectionDate": null,
  "collectedBy": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all equipment

Returns a list of equipment.

Parameters

includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
personIdstring

The person to filter queries by.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit equipment. The response skips the first $skip results. Each entry is a separate equipment object. If no equipment are available, data is empty.

GET /api/equipment

curl https://app.humaans.io/api/equipment \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "W1Uisa336KrC6Rt55pEBkTNZ",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "type": "Laptop",
      "name": "MacBook Pro (13-inch, 2017)",
      "serialNumber": "C012345678",
      "cost": "1299",
      "currency": "EUR",
      "note": "Refurbished.",
      "fileId": null,
      "file": null,
      "issueDate": "2020-01-28",
      "receiptDate": "2020-01-28",
      "collectionDate": null,
      "collectedBy": null,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve an equipment

Retrieves the equipment with the given ID.

Parameters

No parameters

Returns

Returns an equipment object if a valid identifier was provided.

GET /api/equipment/:id

curl https://app.humaans.io/api/equipment/W1Uisa336KrC6Rt55pEBkTNZ \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "W1Uisa336KrC6Rt55pEBkTNZ",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "Laptop",
  "name": "MacBook Pro (13-inch, 2017)",
  "serialNumber": "C012345678",
  "cost": "1299",
  "currency": "EUR",
  "note": "Refurbished.",
  "fileId": null,
  "file": null,
  "issueDate": "2020-01-28",
  "receiptDate": "2020-01-28",
  "collectionDate": null,
  "collectedBy": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create an equipment

Parameters

personIdstring required

ID of the person that this object is associated to.
typestring required

The type of the equipment.
namestring required

The name / model on the equipment.
serialNumberstring | null

The serial number.
coststring | null

Cost, the fraction should be separated with a dot.
currencystring | null

Currency in 3 letter format (ISO 4217), e.g. EUR, USD, GBP, BTC.
notestring | null

Any additional notes.
fileIdstring | null

A file attachment.
issueDatedate required

The date when the equipment was issued.
receiptDatedate | null

The date when the equipment was received by the employee, if different from issue date.
collectionDatedate | null

The date when the equipment was collected from the employee.

Returns

Returns an equipment if the call succeeded. The call returns an error if parameters are invalid.

POST /api/equipment

curl https://app.humaans.io/api/equipment \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","type":"Laptop","name":"MacBook Pro (13-inch, 2017)","issueDate":"2020-01-28"}'

Response

{
  "id": "W1Uisa336KrC6Rt55pEBkTNZ",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "Laptop",
  "name": "MacBook Pro (13-inch, 2017)",
  "serialNumber": "C012345678",
  "cost": "1299",
  "currency": "EUR",
  "note": "Refurbished.",
  "fileId": null,
  "file": null,
  "issueDate": "2020-01-28",
  "receiptDate": "2020-01-28",
  "collectionDate": null,
  "collectedBy": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update an equipment

Parameters

typestring

The type of the equipment.
namestring

The name / model on the equipment.
serialNumberstring | null

The serial number.
coststring | null

Cost, the fraction should be separated with a dot.
currencystring | null

Currency in 3 letter format (ISO 4217), e.g. EUR, USD, GBP, BTC.
notestring | null

Any additional notes.
fileIdstring | null

A file attachment.
issueDatedate

The date when the equipment was issued.
receiptDatedate | null

The date when the equipment was received by the employee, if different from issue date.
collectionDatedate | null

The date when the equipment was collected from the employee.

Returns

Returns the equipment if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/equipment/:id

curl https://app.humaans.io/api/equipment/W1Uisa336KrC6Rt55pEBkTNZ \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"name":"MacBook Pro (13-inch, 2020)"}'

Response

{
  "id": "W1Uisa336KrC6Rt55pEBkTNZ",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "Laptop",
  "name": "MacBook Pro (13-inch, 2020)",
  "serialNumber": "C012345678",
  "cost": "1299",
  "currency": "EUR",
  "note": "Refurbished.",
  "fileId": null,
  "file": null,
  "issueDate": "2020-01-28",
  "receiptDate": "2020-01-28",
  "collectionDate": null,
  "collectedBy": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete an equipment

Permanently deletes an equipment. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/equipment/:id

curl https://app.humaans.io/api/equipment/W1Uisa336KrC6Rt55pEBkTNZ \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "W1Uisa336KrC6Rt55pEBkTNZ",
  "deleted": true
}

Equipment names

An object representing a name of some equipment. This resource is used to find out the list of all equipment names that are in use in the account.

Endpoints

GET /api/equipment-names

Required scopes

private:read

Equipment name object

Attributes

idstring

Unique identifier for the object.
companyIdstring

ID of the company that this object is associated to.
valuestring

The label of the equipment name.
isDefaultboolean

Whether this name is the default name provided by Humaans.
isUsedboolean

Whether this name is used for some equipment.

equipment name object

{
  "id": "j9541EU55Ru2fJ50WGWjPkod",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "value": "Laptop",
  "isDefault": true,
  "isUsed": true
}

List all equipment names

Returns a list of equipment names.

Parameters

typestring

Filter the equipment names by equipment type.
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit equipment names. The response skips the first $skip results. Each entry is a separate equipment name object. If no equipment names are available, data is empty.

GET /api/equipment-names

curl https://app.humaans.io/api/equipment-names \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "j9541EU55Ru2fJ50WGWjPkod",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "value": "Laptop",
      "isDefault": true,
      "isUsed": true
    }
  ]
}

Equipment types

An object representing a type of equipment. This resource is used to find out the list of all equipment types that are in use in the account.

Endpoints

GET /api/equipment-types

Required scopes

private:read

Equipment type object

Attributes

idstring

Unique identifier for the object.
companyIdstring

ID of the company that this object is associated to.
valuestring

The label of the equipment type.
isDefaultboolean

Whether this type is the default type provided by Humaans.
isUsedboolean

Whether this type is used for some equipment.

equipment type object

{
  "id": "mK6SIWfNdZWb4x9dRmTYtn7g",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "value": "Laptop",
  "isDefault": true,
  "isUsed": true
}

List all equipment types

Returns a list of equipment types.

Parameters

$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit equipment types. The response skips the first $skip results. Each entry is a separate equipment type object. If no equipment types are available, data is empty.

GET /api/equipment-types

curl https://app.humaans.io/api/equipment-types \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "mK6SIWfNdZWb4x9dRmTYtn7g",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "value": "Laptop",
      "isDefault": true,
      "isUsed": true
    }
  ]
}

Files

An object representing a file uploaded to Humaans. The files API is used for uploading profile photos as well as files that are attached to identity documents, documents and offboarded people.

Endpoints

 GET /api/files/:id

POST /api/files

Required scopes

Multiple scopes allowed. The scope required for creating or accessing a particular file depends on the type attribute of the file.

File object

Attributes

idstring

Unique identifier for the object.
companyIdstring

ID of the company that this object is associated to.
personIdstring

ID of the person that this object is associated to. Set to the ID of the person that this file will be attached to. Set to null if it’s a company wide document.
typestring

The type of resource that uses the file. For uploads through the public API, use one of profilePhoto, document, identityDocument, equipmentFile, leavingFile.
uploadedBystring

The ID of the person who uploaded this file.
filenamestring

The original filename of the uploaded file.
urlstring

The URL from which the file can be downloaded. Note, the api/files is only used for creating the files and retrieving their metadata. Use this URL to retrieve the actual uploaded file.
isPublicboolean

Can the original file be accessed without authentication.
variantsobject

When a photo file is uploaded, it gets resized to several predefined sizes and uploaded to a CDN. The URLs of those files are provided in this object. Note, that you can still access the original unresized file via the api/files. See the Person object for an example.
variants.64string

URL of one of the predefined 2x photo sizes.
variants.96string

URL of one of the predefined 3x photo sizes.
variants.104string

URL of one of the predefined 2x photo sizes.
variants.136string

URL of one of the predefined 2x photo sizes.
variants.156string

URL of one of the predefined 3x photo sizes.
variants.204string

URL of one of the predefined 3x photo sizes.
variants.320string

URL of one of the predefined 2x photo sizes.
variants.480string

URL of one of the predefined 3x photo sizes.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.

file object

{
  "id": "UJx97ZPPgz2EncFbxXIQkxEq",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "document",
  "uploadedBy": "AfcpS6HbVjoXdMLZ6aF4Sfad",
  "filename": "employment-agreement-kw-2020.pdf",
  "url": "https://app.humaans.io/file/UJx97ZPPgz2EncFbxXIQkxEq",
  "isPublic": false,
  "variants": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Retrieve a file

Retrieves the file with the given ID.

Parameters

No parameters

Returns

Returns a file object if a valid identifier was provided.

GET /api/files/:id

curl https://app.humaans.io/api/files/UJx97ZPPgz2EncFbxXIQkxEq \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "UJx97ZPPgz2EncFbxXIQkxEq",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "document",
  "uploadedBy": "AfcpS6HbVjoXdMLZ6aF4Sfad",
  "filename": "employment-agreement-kw-2020.pdf",
  "url": "https://app.humaans.io/file/UJx97ZPPgz2EncFbxXIQkxEq",
  "isPublic": false,
  "variants": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a file

The file create API must be used as a multipart form data instead of content type JSON in order to upload the files. Once the file is uploaded, it is typically then attached to the target object, such as person’s profilePhotoId field, document’s fileId field and so on. Files that are not attached to any resource get periodically deleted.

Parameters

personIdstring | null

ID of the person that this object is associated to. Set to the ID of the person that this file will be attached to. Set to null if it’s a company wide document.
typestring required

The type of resource that uses the file. For uploads through the public API, use one of profilePhoto, document, identityDocument, equipmentFile, leavingFile.
isPublicboolean

Can the original file be accessed without authentication.

Returns

Returns a file if the call succeeded. The call returns an error if parameters are invalid.

POST /api/files

curl https://app.humaans.io/api/files \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X POST \
  -F personId=NF28Pg0RN4xdDjZcocDiL9lz \
  -F type=document \
  -F @employment-agreement.pdf

Response

{
  "id": "UJx97ZPPgz2EncFbxXIQkxEq",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "document",
  "uploadedBy": "AfcpS6HbVjoXdMLZ6aF4Sfad",
  "filename": "employment-agreement-kw-2020.pdf",
  "url": "https://app.humaans.io/file/UJx97ZPPgz2EncFbxXIQkxEq",
  "isPublic": false,
  "variants": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Identity document types

An object representing a type of an identity document. This resource is used to find out the list of all identity types that are in use in the account.

Endpoints

GET /api/identity-document-types

Required scopes

documents:read

Identity document type object

Attributes

idstring

Unique identifier for the object.
valuestring

The label of the identity document type.

identity document type object

{
  "id": "yI3rZlTcWBvn3F4ChC5d1X2b",
  "value": "Passport"
}

List all identity document types

Returns a list of identity document types.

Parameters

$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit identity document types. The response skips the first $skip results. Each entry is a separate identity document type object. If no identity document types are available, data is empty.

GET /api/identity-document-types

curl https://app.humaans.io/api/identity-document-types \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "yI3rZlTcWBvn3F4ChC5d1X2b",
      "value": "Passport"
    }
  ]
}

Identity documents

An object representing an identity (or identification) document of an employee.

Endpoints

   GET /api/identity-documents

   GET /api/identity-documents/:id

  POST /api/identity-documents

 PATCH /api/identity-documents/:id

DELETE /api/identity-documents/:id

Required scopes

documents:read

documents:write

Identity document object

Attributes

idstring

Unique identifier for the object.
personIdstring

ID of the person that this object is associated to.
typestring

A type of the identity document. Typically set to Passport, Driving License, Passport or Visa, but can be set to any value.
numberstring

The number of the identification document as specified on the document.
countryCodestring

Country of issue code in in ISO 3166-2 format, e.g. GB for United Kingdom.
expiryDatedate

Expiry date of the document.
notestring

An optional note about the identity document.
fileIdstring

The ID of the file attached to this identity document.
fileobject

A subset of the file object attached to this identity document. The full file object can be retrieved using the Files endpoint.
file.idstring

Unique identifier for the object.
file.urlstring

The URL from which the attached file can be downloaded.
file.filenamestring

The name of the file attached.
verifiedBystring

The ID of the person that varified the legitimacy of this identity document.
verifiedAtdate-time

The date and time when this this identity document was verified.
isVerifiedboolean

The flag indicating that the document has been verified. This can be useful for non admin users, since non admin users do not see who verified the document.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.

identity document object

{
  "id": "a0M0OIrmNIQe7UP5AaPxv9jN",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "Passport",
  "number": "12345678",
  "countryCode": "GB",
  "expiryDate": "2050-06-24",
  "note": null,
  "fileId": "51YzMOYrc9rU0lNGn1QtgSv0",
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "verifiedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "verifiedAt": "ob4xPcVpGGZm043C7xGMfP1U",
  "isVerified": true,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all identity documents

Returns a list of identity documents.

Parameters

includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
personIdstring · $eq $ne $in $nin

The person to filter queries by.
createdAtdate | date-time · $gt $gte $lt $lte

Filter identity documents by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit identity documents. The response skips the first $skip results. Each entry is a separate identity document object. If no identity documents are available, data is empty.

GET /api/identity-documents

curl https://app.humaans.io/api/identity-documents \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "a0M0OIrmNIQe7UP5AaPxv9jN",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "type": "Passport",
      "number": "12345678",
      "countryCode": "GB",
      "expiryDate": "2050-06-24",
      "note": null,
      "fileId": "51YzMOYrc9rU0lNGn1QtgSv0",
      "file": {
        "id": "51YzMOYrc9rU0lNGn1QtgSv0",
        "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
        "filename": "passport-scan.pdf"
      },
      "verifiedBy": "ob4xPcVpGGZm043C7xGMfP1U",
      "verifiedAt": "ob4xPcVpGGZm043C7xGMfP1U",
      "isVerified": true,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve an identity document

Retrieves the identity document with the given ID.

Parameters

No parameters

Returns

Returns an identity document object if a valid identifier was provided.

GET /api/identity-documents/:id

curl https://app.humaans.io/api/identity-documents/a0M0OIrmNIQe7UP5AaPxv9jN \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "a0M0OIrmNIQe7UP5AaPxv9jN",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "Passport",
  "number": "12345678",
  "countryCode": "GB",
  "expiryDate": "2050-06-24",
  "note": null,
  "fileId": "51YzMOYrc9rU0lNGn1QtgSv0",
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "verifiedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "verifiedAt": "ob4xPcVpGGZm043C7xGMfP1U",
  "isVerified": true,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create an identity document

Parameters

personIdstring required

ID of the person that this object is associated to.
typestring required

A type of the identity document. Typically set to Passport, Driving License, Passport or Visa, but can be set to any value.
numberstring | null

The number of the identification document as specified on the document.
countryCodestring | null

Country of issue code in in ISO 3166-2 format, e.g. GB for United Kingdom.
expiryDatedate | null

Expiry date of the document.
notestring | null

An optional note about the identity document.
fileIdstring required

The ID of the file attached to this identity document.
verifiedBystring | null

The ID of the person that varified the legitimacy of this identity document.

Returns

Returns an identity document if the call succeeded. The call returns an error if parameters are invalid.

POST /api/identity-documents

curl https://app.humaans.io/api/identity-documents \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","type":"Passport","fileId":"51YzMOYrc9rU0lNGn1QtgSv0"}'

Response

{
  "id": "a0M0OIrmNIQe7UP5AaPxv9jN",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "Passport",
  "number": "12345678",
  "countryCode": "GB",
  "expiryDate": "2050-06-24",
  "note": null,
  "fileId": "51YzMOYrc9rU0lNGn1QtgSv0",
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "verifiedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "verifiedAt": "ob4xPcVpGGZm043C7xGMfP1U",
  "isVerified": true,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update an identity document

Parameters

typestring

A type of the identity document. Typically set to Passport, Driving License, Passport or Visa, but can be set to any value.
numberstring | null

The number of the identification document as specified on the document.
countryCodestring | null

Country of issue code in in ISO 3166-2 format, e.g. GB for United Kingdom.
expiryDatedate | null

Expiry date of the document.
notestring | null

An optional note about the identity document.
fileIdstring

The ID of the file attached to this identity document.
verifiedBystring | null

The ID of the person that varified the legitimacy of this identity document.

Returns

Returns the identity document if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/identity-documents/:id

curl https://app.humaans.io/api/identity-documents/a0M0OIrmNIQe7UP5AaPxv9jN \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"expiryDate":"2050-05-01"}'

Response

{
  "id": "a0M0OIrmNIQe7UP5AaPxv9jN",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "Passport",
  "number": "12345678",
  "countryCode": "GB",
  "expiryDate": "2050-05-01",
  "note": null,
  "fileId": "51YzMOYrc9rU0lNGn1QtgSv0",
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "verifiedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "verifiedAt": "ob4xPcVpGGZm043C7xGMfP1U",
  "isVerified": true,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete an identity document

Permanently deletes an identity document. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/identity-documents/:id

curl https://app.humaans.io/api/identity-documents/a0M0OIrmNIQe7UP5AaPxv9jN \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "a0M0OIrmNIQe7UP5AaPxv9jN",
  "deleted": true
}

Job library levels

A job library level is a seniority or rank within a career track, for example “Senior”. Levels in different tracks that share the same grade are considered equivalent. Levels are combined with roles to form job library profiles.

Endpoints

   GET /api/job-library-levels

   GET /api/job-library-levels/:id

  POST /api/job-library-levels

 PATCH /api/job-library-levels/:id

DELETE /api/job-library-levels/:id

Required scopes

jobLibrary:read

jobLibrary:write

Job library level object

Attributes

idstring

Unique identifier for the object.
trackstring

The career track this level belongs to, e.g. “Professional”.
namestring

The name of the level, e.g. “Senior”.
codestring

A short code for the level, e.g. “L5” or “M3”.
gradeinteger

A company-wide grade shared across tracks. Levels in different tracks with the same grade are considered equivalent (e.g. “M1” and “L3”).
statusstring

Whether the level is active or archived.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

The date and time the level was deleted. Only present on deleted levels, which are only returned when querying with includeDeleted.

job library level object

{
  "id": "y03tuSYgIN4v9R3eNQCrw31i",
  "track": "Professional",
  "name": "Senior",
  "code": "L5",
  "grade": 5,
  "status": "active",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

List all job library levels

Returns a list of job library levels.

Parameters

idstring · $in

The ID of the level.
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
statusstring

Filter levels by status.
createdAtdate | date-time · $gt $gte $lt $lte

Filter levels by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$selectstring[]
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit job library levels. The response skips the first $skip results. Each entry is a separate job library level object. If no job library levels are available, data is empty.

GET /api/job-library-levels

curl https://app.humaans.io/api/job-library-levels \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "y03tuSYgIN4v9R3eNQCrw31i",
      "track": "Professional",
      "name": "Senior",
      "code": "L5",
      "grade": 5,
      "status": "active",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z",
      "deletedAt": null
    }
  ]
}

Retrieve a job library level

Retrieves the job library level with the given ID.

Parameters

No parameters

Returns

Returns a job library level object if a valid identifier was provided.

GET /api/job-library-levels/:id

curl https://app.humaans.io/api/job-library-levels/y03tuSYgIN4v9R3eNQCrw31i \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "y03tuSYgIN4v9R3eNQCrw31i",
  "track": "Professional",
  "name": "Senior",
  "code": "L5",
  "grade": 5,
  "status": "active",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

Create a job library level

Parameters

trackstring required

The career track this level belongs to, e.g. “Professional”.
namestring required

The name of the level, e.g. “Senior”.
codestring | null

A short code for the level, e.g. “L5” or “M3”.
gradeinteger required

A company-wide grade shared across tracks. Levels in different tracks with the same grade are considered equivalent (e.g. “M1” and “L3”).
statusstring

Whether the level is active or archived.

Returns

Returns a job library level if the call succeeded. The call returns an error if parameters are invalid.

POST /api/job-library-levels

curl https://app.humaans.io/api/job-library-levels \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"track":"Professional","name":"Senior","grade":5}'

Response

{
  "id": "y03tuSYgIN4v9R3eNQCrw31i",
  "track": "Professional",
  "name": "Senior",
  "code": "L5",
  "grade": 5,
  "status": "active",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

Update a job library level

Parameters

trackstring

The career track this level belongs to, e.g. “Professional”.
namestring

The name of the level, e.g. “Senior”.
codestring | null

A short code for the level, e.g. “L5” or “M3”.
gradeinteger

A company-wide grade shared across tracks. Levels in different tracks with the same grade are considered equivalent (e.g. “M1” and “L3”).
statusstring

Whether the level is active or archived.

Returns

Returns the job library level if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/job-library-levels/:id

curl https://app.humaans.io/api/job-library-levels/y03tuSYgIN4v9R3eNQCrw31i \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'

Response

{
  "id": "y03tuSYgIN4v9R3eNQCrw31i",
  "track": "Professional",
  "name": "Senior",
  "code": "L5",
  "grade": 5,
  "status": "active",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

Delete a job library level

Permanently deletes a job library level. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/job-library-levels/:id

curl https://app.humaans.io/api/job-library-levels/y03tuSYgIN4v9R3eNQCrw31i \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "y03tuSYgIN4v9R3eNQCrw31i",
  "deleted": true
}

Job library profiles

A job library profile joins one job library role and one job library level into an assignable job profile, for example “Senior Software Engineer”. A profile can be linked to a person via the jobLibraryProfileId field on their job role.

Endpoints

   GET /api/job-library-profiles

   GET /api/job-library-profiles/:id

  POST /api/job-library-profiles

 PATCH /api/job-library-profiles/:id

DELETE /api/job-library-profiles/:id

Required scopes

jobLibrary:read

jobLibrary:write

Job library profile object

Attributes

idstring

Unique identifier for the object.
jobLibraryRoleIdstring

The job library role this profile is based on.
jobLibraryLevelIdstring

The job library level this profile is based on.
codestring

Stable profile code.
jobTitlestring

Main display title shown in the directory.
externalTitlestring

Public/recruiting title.
descriptionstring

Optional profile description.
statusstring

Current status of the job profile.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

The date and time the profile was deleted. Only present on deleted profiles, which are only returned when querying with includeDeleted.

job library profile object

{
  "id": "QQX6J5Mu8wgmBjlDH6FLqnX0",
  "jobLibraryRoleId": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
  "jobLibraryLevelId": "Kx2mR8nQvT5wY7bH3cF6dJ9p",
  "code": "SSE",
  "jobTitle": "Senior Software Engineer",
  "externalTitle": "Senior Software Engineer",
  "description": "Designs and builds core product features end to end.",
  "status": "active",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

List all job library profiles

Returns a list of job library profiles.

Parameters

idstring · $in

The ID of the profile.
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
jobLibraryLevelIdstring

The job library level this profile is based on.
jobLibraryRoleIdstring

The job library role this profile is based on.
statusstring

Current status of the job profile.
createdAtdate | date-time · $gt $gte $lt $lte

Filter profiles by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$selectstring[]
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit job library profiles. The response skips the first $skip results. Each entry is a separate job library profile object. If no job library profiles are available, data is empty.

GET /api/job-library-profiles

curl https://app.humaans.io/api/job-library-profiles \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "QQX6J5Mu8wgmBjlDH6FLqnX0",
      "jobLibraryRoleId": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
      "jobLibraryLevelId": "Kx2mR8nQvT5wY7bH3cF6dJ9p",
      "code": "SSE",
      "jobTitle": "Senior Software Engineer",
      "externalTitle": "Senior Software Engineer",
      "description": "Designs and builds core product features end to end.",
      "status": "active",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z",
      "deletedAt": null
    }
  ]
}

Retrieve a job library profile

Retrieves the job library profile with the given ID.

Parameters

No parameters

Returns

Returns a job library profile object if a valid identifier was provided.

GET /api/job-library-profiles/:id

curl https://app.humaans.io/api/job-library-profiles/QQX6J5Mu8wgmBjlDH6FLqnX0 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "QQX6J5Mu8wgmBjlDH6FLqnX0",
  "jobLibraryRoleId": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
  "jobLibraryLevelId": "Kx2mR8nQvT5wY7bH3cF6dJ9p",
  "code": "SSE",
  "jobTitle": "Senior Software Engineer",
  "externalTitle": "Senior Software Engineer",
  "description": "Designs and builds core product features end to end.",
  "status": "active",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

Create a job library profile

Parameters

jobLibraryRoleIdstring required

The job library role this profile is based on.
jobLibraryLevelIdstring required

The job library level this profile is based on.
codestring required

Stable profile code.
jobTitlestring required

Main display title shown in the directory.
externalTitlestring | null

Public/recruiting title.
descriptionstring | null

Optional profile description.
statusstring

Current status of the job profile.

Returns

Returns a job library profile if the call succeeded. The call returns an error if parameters are invalid.

POST /api/job-library-profiles

curl https://app.humaans.io/api/job-library-profiles \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"jobLibraryRoleId":"6iJcJ6aKIj1H4ubC4Zp0LlT6","jobLibraryLevelId":"Kx2mR8nQvT5wY7bH3cF6dJ9p","code":"SSE","jobTitle":"Senior Software Engineer"}'

Response

{
  "id": "QQX6J5Mu8wgmBjlDH6FLqnX0",
  "jobLibraryRoleId": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
  "jobLibraryLevelId": "Kx2mR8nQvT5wY7bH3cF6dJ9p",
  "code": "SSE",
  "jobTitle": "Senior Software Engineer",
  "externalTitle": "Senior Software Engineer",
  "description": "Designs and builds core product features end to end.",
  "status": "active",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

Update a job library profile

Parameters

jobLibraryRoleIdstring

The job library role this profile is based on.
jobLibraryLevelIdstring

The job library level this profile is based on.
codestring

Stable profile code.
jobTitlestring

Main display title shown in the directory.
externalTitlestring | null

Public/recruiting title.
descriptionstring | null

Optional profile description.
statusstring

Current status of the job profile.

Returns

Returns the job library profile if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/job-library-profiles/:id

curl https://app.humaans.io/api/job-library-profiles/QQX6J5Mu8wgmBjlDH6FLqnX0 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'

Response

{
  "id": "QQX6J5Mu8wgmBjlDH6FLqnX0",
  "jobLibraryRoleId": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
  "jobLibraryLevelId": "Kx2mR8nQvT5wY7bH3cF6dJ9p",
  "code": "SSE",
  "jobTitle": "Senior Software Engineer",
  "externalTitle": "Senior Software Engineer",
  "description": "Designs and builds core product features end to end.",
  "status": "active",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

Delete a job library profile

Permanently deletes a job library profile. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/job-library-profiles/:id

curl https://app.humaans.io/api/job-library-profiles/QQX6J5Mu8wgmBjlDH6FLqnX0 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "QQX6J5Mu8wgmBjlDH6FLqnX0",
  "deleted": true
}

Job library roles

A job library role is a job function or family, for example “Software Engineer” within the “Engineering” function. Roles are combined with levels to form job library profiles.

Endpoints

   GET /api/job-library-roles

   GET /api/job-library-roles/:id

  POST /api/job-library-roles

 PATCH /api/job-library-roles/:id

DELETE /api/job-library-roles/:id

Required scopes

jobLibrary:read

jobLibrary:write

Job library role object

Attributes

idstring

Unique identifier for the object.
codestring

A stable code identifier for the role, e.g. “SWE”.
namestring

The name of the role, e.g. “Software Engineer”.
jobFunctionstring

The job function this role belongs to, e.g. “Engineering”.
jobFamilystring

The job family this role belongs to, e.g. “Software Engineering”.
statusstring

Whether the role is active or archived.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

The date and time the role was deleted. Only present on deleted roles, which are only returned when querying with includeDeleted.

job library role object

{
  "id": "nEi45tsrWdbcJqxzaH8lA36H",
  "code": "SWE",
  "name": "Software Engineer",
  "jobFunction": "Engineering",
  "jobFamily": "Software Engineering",
  "status": "active",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

List all job library roles

Returns a list of job library roles.

Parameters

idstring · $in

The ID of the role.
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
statusstring

Filter roles by status.
createdAtdate | date-time · $gt $gte $lt $lte

Filter roles by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$selectstring[]
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit job library roles. The response skips the first $skip results. Each entry is a separate job library role object. If no job library roles are available, data is empty.

GET /api/job-library-roles

curl https://app.humaans.io/api/job-library-roles \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "nEi45tsrWdbcJqxzaH8lA36H",
      "code": "SWE",
      "name": "Software Engineer",
      "jobFunction": "Engineering",
      "jobFamily": "Software Engineering",
      "status": "active",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z",
      "deletedAt": null
    }
  ]
}

Retrieve a job library role

Retrieves the job library role with the given ID.

Parameters

No parameters

Returns

Returns a job library role object if a valid identifier was provided.

GET /api/job-library-roles/:id

curl https://app.humaans.io/api/job-library-roles/nEi45tsrWdbcJqxzaH8lA36H \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "nEi45tsrWdbcJqxzaH8lA36H",
  "code": "SWE",
  "name": "Software Engineer",
  "jobFunction": "Engineering",
  "jobFamily": "Software Engineering",
  "status": "active",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

Create a job library role

Parameters

codestring required

A stable code identifier for the role, e.g. “SWE”.
namestring required

The name of the role, e.g. “Software Engineer”.
jobFunctionstring required

The job function this role belongs to, e.g. “Engineering”.
jobFamilystring required

The job family this role belongs to, e.g. “Software Engineering”.
statusstring

Whether the role is active or archived.

Returns

Returns a job library role if the call succeeded. The call returns an error if parameters are invalid.

POST /api/job-library-roles

curl https://app.humaans.io/api/job-library-roles \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"code":"SWE","name":"Software Engineer","jobFunction":"Engineering","jobFamily":"Software Engineering"}'

Response

{
  "id": "nEi45tsrWdbcJqxzaH8lA36H",
  "code": "SWE",
  "name": "Software Engineer",
  "jobFunction": "Engineering",
  "jobFamily": "Software Engineering",
  "status": "active",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

Update a job library role

Parameters

codestring

A stable code identifier for the role, e.g. “SWE”.
namestring

The name of the role, e.g. “Software Engineer”.
jobFunctionstring

The job function this role belongs to, e.g. “Engineering”.
jobFamilystring

The job family this role belongs to, e.g. “Software Engineering”.
statusstring

Whether the role is active or archived.

Returns

Returns the job library role if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/job-library-roles/:id

curl https://app.humaans.io/api/job-library-roles/nEi45tsrWdbcJqxzaH8lA36H \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'

Response

{
  "id": "nEi45tsrWdbcJqxzaH8lA36H",
  "code": "SWE",
  "name": "Software Engineer",
  "jobFunction": "Engineering",
  "jobFamily": "Software Engineering",
  "status": "active",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

Delete a job library role

Permanently deletes a job library role. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/job-library-roles/:id

curl https://app.humaans.io/api/job-library-roles/nEi45tsrWdbcJqxzaH8lA36H \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "nEi45tsrWdbcJqxzaH8lA36H",
  "deleted": true
}

Job roles

An object representing the role of an employee at a company. Employees always have a role that is currently in effect and optionally some past roles.

Endpoints

   GET /api/job-roles

   GET /api/job-roles/:id

  POST /api/job-roles

 PATCH /api/job-roles/:id

DELETE /api/job-roles/:id

Required scopes

private:read

public:read

private:write

Job role object

Attributes

idstring

Unique identifier for the object.
personIdstring

ID of the person that this object is associated to.
jobTitlestring

Job title.
departmentstring

The name of the department.
effectiveDatedate

The date when this role took effect. Can be a past or future date.
endDatedate

The date when this role finished, null if this is the last role.
isFirstboolean

Whether this is the first job role for this person.
reportingTostring

The ID of the manager.
notestring

An optional note about this particular job role entry.
jobLibraryProfileIdstring

The job library profile this role is linked to.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

The date and time this job role was deleted. Only present on deleted job roles, which are only returned when querying with includeDeleted.

job role object

{
  "id": "hmA5GnUq9ojK86LLKKWbiuKG",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "jobTitle": "Software Engineer",
  "department": "Engineering",
  "effectiveDate": "2020-02-15",
  "endDate": "2020-02-22",
  "reportingTo": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
  "note": "Switched departments",
  "jobLibraryProfileId": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

List all job roles

Returns a list of job roles.

Parameters

departmentstring | empty

Filter job roles by department name, or null to find roles with no department. Each role is matched against the department in effect on $asOf, or on the role’s own effectiveDate when $asOf is omitted. Where departments form a hierarchy, a role in a sub-department also matches its parent. Use with $asOf to get current roles in a department.
effectiveDatedate | date-time · $gt $gte $lt $lte

Filter job roles by the date the role takes or took effect. Dates may be past or future.
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
personIdstring · $in

The person to filter queries by.
createdAtdate | date-time · $gt $gte $lt $lte

Filter job roles by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$asOfdate

Filter the list to at most one role per employee, finding the job role that was in effect on the provided date. Cannot be combined with includeDeleted.
$sortobject
$sort.deletedAtnumber
$sort.effectiveDatenumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit job roles. The response skips the first $skip results. Each entry is a separate job role object. If no job roles are available, data is empty.

GET /api/job-roles

curl https://app.humaans.io/api/job-roles \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "hmA5GnUq9ojK86LLKKWbiuKG",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "jobTitle": "Software Engineer",
      "department": "Engineering",
      "effectiveDate": "2020-02-15",
      "endDate": "2020-02-22",
      "reportingTo": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
      "note": "Switched departments",
      "jobLibraryProfileId": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z",
      "deletedAt": null
    }
  ]
}

Retrieve a job role

Retrieves the job role with the given ID.

Parameters

No parameters

Returns

Returns a job role object if a valid identifier was provided.

GET /api/job-roles/:id

curl https://app.humaans.io/api/job-roles/hmA5GnUq9ojK86LLKKWbiuKG \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "hmA5GnUq9ojK86LLKKWbiuKG",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "jobTitle": "Software Engineer",
  "department": "Engineering",
  "effectiveDate": "2020-02-15",
  "endDate": "2020-02-22",
  "reportingTo": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
  "note": "Switched departments",
  "jobLibraryProfileId": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

Create a job role

Any number of job roles can be created per each employee, but only the role with the highest effectiveDate that is not in the future will be considered as the active role. Note, that to preserve accurate records and history typically you want to create new roles instead of editing existing ones when job titles, managers or other aspects of the role change.

Parameters

personIdstring required

ID of the person that this object is associated to.
jobTitlestring required

Job title.
departmentstring | null

The name of the department.
effectiveDatedate required

The date when this role took effect. Can be a past or future date.
notestring | null

An optional note about this particular job role entry.
reportingTostring | null

The ID of the manager.
jobLibraryProfileIdstring | null

The job library profile this role is linked to.
customValuesobject[]
customValues.customFieldIdstring required
customValues.valuestring | string[] required
customValues.resourceId

Returns

Returns a job role if the call succeeded. The call returns an error if parameters are invalid.

POST /api/job-roles

curl https://app.humaans.io/api/job-roles \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"jobTitle":"Product Engineer"}'

Response

{
  "id": "hmA5GnUq9ojK86LLKKWbiuKG",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "jobTitle": "Product Engineer",
  "department": "Engineering",
  "effectiveDate": "2020-02-15",
  "endDate": "2020-02-22",
  "reportingTo": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
  "note": "Switched departments",
  "jobLibraryProfileId": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

Update a job role

Updates the job role object. Note, that to preserve accurate records and history typically you want to create new roles instead of editing existing ones when job titles, managers or other aspects of the role change.

Parameters

jobTitlestring

Job title.
departmentstring | null

The name of the department.
effectiveDatedate

The date when this role took effect. Can be a past or future date.
notestring | null

An optional note about this particular job role entry.
reportingTostring | null

The ID of the manager.
jobLibraryProfileIdstring | null

The job library profile this role is linked to.

Returns

Returns the job role if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/job-roles/:id

curl https://app.humaans.io/api/job-roles/hmA5GnUq9ojK86LLKKWbiuKG \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"jobTitle":"Product Engineer"}'

Response

{
  "id": "hmA5GnUq9ojK86LLKKWbiuKG",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "jobTitle": "Product Engineer",
  "department": "Engineering",
  "effectiveDate": "2020-02-15",
  "endDate": "2020-02-22",
  "reportingTo": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
  "note": "Switched departments",
  "jobLibraryProfileId": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

Delete a job role

Permanently deletes a job role. It cannot be undone. Note that every employee must have at least one job role, deleting the last job role is going to return an error.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/job-roles/:id

curl https://app.humaans.io/api/job-roles/hmA5GnUq9ojK86LLKKWbiuKG \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "hmA5GnUq9ojK86LLKKWbiuKG",
  "deleted": true
}

Locations

An object representing a place of work - such as an office, a store, warehouse, etc. Each employee within the company must be added to a location or marked as remote employee by setting their locationId to remote.

Endpoints

   GET /api/locations

   GET /api/locations/:id

  POST /api/locations

 PATCH /api/locations/:id

DELETE /api/locations/:id

Required scopes

public:read

private:write

Location object

Attributes

idstring

Unique identifier for the object.
companyIdstring

ID of the company that this object is associated to.
labelstring

A label for this location that is used to refer to the location.
displayNamestring
codestring

A short unique code for this location, e.g. an identifier used in payroll or other external systems.
addressstring

A street address of the location.
postcodestring

Postcode.
citystring

City.
statestring

State.
countrystring

Country name, infered from the countryCode.
regionCodestring

Region code in ISO 3166-2 format e.g. CA-QC for Quebec.
countryCodestring

Country code in in ISO 3166-2 format, e.g. GB for United Kingdom.
timezonestring

Timezone, infered from the city and country.
isAddressInvalidboolean

If the address, or some component of it is not valid, this will be set to true.
timeAwayPolicyIdstring

The time away policy to be applied to everyone added to this location. Note: changing this will also update everyone that works at this location to a new policy.
timeAwayPolicyEffectiveDatedate

When provided, time away policy changes will be effective from this date.
workingPatternIdstring

The working pattern to be applied to everyone added to this location. Note: changing this will also update everyone that works at this location to a new working pattern.
workingPatternEffectiveDatedate

When provided, working pattern changes will be effective from this date.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

location object

{
  "id": "oIBBB436k2YCOY5gzVhC5idx",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "label": "Acme HQ",
  "displayName": "Acme HQ",
  "code": "LON",
  "address": "Uncommon, 22 Curved Road",
  "postcode": "SE1 5AG",
  "city": "London",
  "state": null,
  "country": "United Kingdom",
  "regionCode": null,
  "countryCode": "GB",
  "timezone": "Europe/London",
  "isAddressInvalid": false,
  "timeAwayPolicyId": "lQhHxduYbvq0TRIJq2IPN3hH",
  "timeAwayPolicyEffectiveDate": "2024-01-30",
  "workingPatternId": "lQhHxduYbvq0TRIJq2IPN3hH",
  "workingPatternEffectiveDate": "2024-04-06",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all locations

Returns a list of locations.

Parameters

codestring · $in

Filter locations by code.
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
createdAtdate | date-time · $gt $gte $lt $lte

Filter locations by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit locations. The response skips the first $skip results. Each entry is a separate location object. If no locations are available, data is empty.

GET /api/locations

curl https://app.humaans.io/api/locations \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "oIBBB436k2YCOY5gzVhC5idx",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "label": "Acme HQ",
      "displayName": "Acme HQ",
      "code": "LON",
      "address": "Uncommon, 22 Curved Road",
      "postcode": "SE1 5AG",
      "city": "London",
      "state": null,
      "country": "United Kingdom",
      "regionCode": null,
      "countryCode": "GB",
      "timezone": "Europe/London",
      "isAddressInvalid": false,
      "timeAwayPolicyId": "lQhHxduYbvq0TRIJq2IPN3hH",
      "timeAwayPolicyEffectiveDate": "2024-01-30",
      "workingPatternId": "lQhHxduYbvq0TRIJq2IPN3hH",
      "workingPatternEffectiveDate": "2024-04-06",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a location

Retrieves the location with the given ID.

Parameters

No parameters

Returns

Returns a location object if a valid identifier was provided.

GET /api/locations/:id

curl https://app.humaans.io/api/locations/oIBBB436k2YCOY5gzVhC5idx \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "oIBBB436k2YCOY5gzVhC5idx",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "label": "Acme HQ",
  "displayName": "Acme HQ",
  "code": "LON",
  "address": "Uncommon, 22 Curved Road",
  "postcode": "SE1 5AG",
  "city": "London",
  "state": null,
  "country": "United Kingdom",
  "regionCode": null,
  "countryCode": "GB",
  "timezone": "Europe/London",
  "isAddressInvalid": false,
  "timeAwayPolicyId": "lQhHxduYbvq0TRIJq2IPN3hH",
  "timeAwayPolicyEffectiveDate": "2024-01-30",
  "workingPatternId": "lQhHxduYbvq0TRIJq2IPN3hH",
  "workingPatternEffectiveDate": "2024-04-06",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a location

Parameters

addressstring | null

A street address of the location.
citystring required

City.
statestring | null

State.
postcodestring | null

Postcode.
countryCodestring required

Country code in in ISO 3166-2 format, e.g. GB for United Kingdom.
labelstring | null

A label for this location that is used to refer to the location.
codestring | null

A short unique code for this location, e.g. an identifier used in payroll or other external systems.
timeAwayPolicyIdstring required

The time away policy to be applied to everyone added to this location. Note: changing this will also update everyone that works at this location to a new policy.
timeAwayPolicyEffectiveDatedate | null

When provided, time away policy changes will be effective from this date.
workingPatternIdstring | null

The working pattern to be applied to everyone added to this location. Note: changing this will also update everyone that works at this location to a new working pattern.
workingPatternEffectiveDatedate | null

When provided, working pattern changes will be effective from this date.

Returns

Returns a location if the call succeeded. The call returns an error if parameters are invalid.

POST /api/locations

curl https://app.humaans.io/api/locations \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"city":"London","countryCode":"GB","timeAwayPolicyId":"lQhHxduYbvq0TRIJq2IPN3hH"}'

Response

{
  "id": "oIBBB436k2YCOY5gzVhC5idx",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "label": "Acme HQ",
  "displayName": "Acme HQ",
  "code": "LON",
  "address": "Uncommon, 22 Curved Road",
  "postcode": "SE1 5AG",
  "city": "London",
  "state": null,
  "country": "United Kingdom",
  "regionCode": null,
  "countryCode": "GB",
  "timezone": "Europe/London",
  "isAddressInvalid": false,
  "timeAwayPolicyId": "lQhHxduYbvq0TRIJq2IPN3hH",
  "timeAwayPolicyEffectiveDate": "2024-01-30",
  "workingPatternId": "lQhHxduYbvq0TRIJq2IPN3hH",
  "workingPatternEffectiveDate": "2024-04-06",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a location

Parameters

addressstring | null

A street address of the location.
citystring

City.
statestring | null

State.
postcodestring | null

Postcode.
countryCodestring

Country code in in ISO 3166-2 format, e.g. GB for United Kingdom.
labelstring | null

A label for this location that is used to refer to the location.
codestring | null

A short unique code for this location, e.g. an identifier used in payroll or other external systems.
timeAwayPolicyIdstring

The time away policy to be applied to everyone added to this location. Note: changing this will also update everyone that works at this location to a new policy.
timeAwayPolicyEffectiveDatedate | null

When provided, time away policy changes will be effective from this date.
workingPatternIdstring | null

The working pattern to be applied to everyone added to this location. Note: changing this will also update everyone that works at this location to a new working pattern.
workingPatternEffectiveDatedate | null

When provided, working pattern changes will be effective from this date.
updateExistingPeopleTimeAwayPolicyboolean

When true (default), changing the time away policy will also update existing employees at this location. Set to false to only affect new employees.
updateExistingPeopleWorkingPatternboolean

When true (default), changing the working pattern will also update existing employees at this location. Set to false to only affect new employees.

Returns

Returns the location if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/locations/:id

curl https://app.humaans.io/api/locations/oIBBB436k2YCOY5gzVhC5idx \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"city":"Quebec"}'

Response

{
  "id": "oIBBB436k2YCOY5gzVhC5idx",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "label": "Acme HQ",
  "displayName": "Acme HQ",
  "code": "LON",
  "address": "Uncommon, 22 Curved Road",
  "postcode": "SE1 5AG",
  "city": "Quebec",
  "state": null,
  "country": "United Kingdom",
  "regionCode": null,
  "countryCode": "GB",
  "timezone": "Europe/London",
  "isAddressInvalid": false,
  "timeAwayPolicyId": "lQhHxduYbvq0TRIJq2IPN3hH",
  "timeAwayPolicyEffectiveDate": "2024-01-30",
  "workingPatternId": "lQhHxduYbvq0TRIJq2IPN3hH",
  "workingPatternEffectiveDate": "2024-04-06",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a location

Permanently deletes a location. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/locations/:id

curl https://app.humaans.io/api/locations/oIBBB436k2YCOY5gzVhC5idx \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "oIBBB436k2YCOY5gzVhC5idx",
  "deleted": true
}

Me

An endpoint that returns the person object representing the currently logged in user, or the owner of the access token. This method proxies to api/people to retrieve this object.

Endpoints

GET /api/me

Required scopes

private:read

public:read

Me object

Attributes

idstring

Unique identifier for the object.
companyIdstring

ID of the company that this object is associated to.
spaceIdstring

ID of the Space this person belongs to.
firstNamestring

First name.
middleNamestring

Middle name.
lastNamestring

Last name.
preferredNamestring

Preferred first name that the person goes by. This will be shown in Humaans instead of the first name if set.
pronounsstring

Preferred pronouns that the person goes by
emailstring

The work email of the person. The email they use to log in.
locationIdstring

The ID of the location this person works at. It can be either the ID of a location or the string literal remote, in which case it indicates this person works remotely and the working location can be found in the remoteCity, remoteRegionCode and remoteCountryCode fields.
remoteCitystring

When locationId is set to remote, this indicates the city that this person works in.
remoteRegionCodestring

When locationId is set to remote, this indicates the region that this person works in. Region code in ISO 3166-2 format e.g. CA-QC for Quebec.
remoteCountryCodestring

When locationId is set to remote, this indicates the country that this person works in. Country code in in ISO 3166-2 format, e.g. GB for United Kingdom.
remoteTimezonestring

When locationId is set to remote, this indicates the timezone that this person works in. The timezone is infered from the city and country code.
timeAwayApprovalFlowIdstring

The Id of the time away approval flow this person works under.
personalEmailstring

Personal email of the person.
phoneNumberstring

Work phone number of the person.
formattedPhoneNumberstring

Work phone number of the person formatted for display.
personalPhoneNumberstring

Personal phone number of the person.
formattedPersonalPhoneNumberstring

Personal phone number of the person formatted for display.
genderstring

Person’s gender. It’s a free form field, any value is allowed.
birthdaystring

Person’s date of birth. Only disclosed to users with owner, admin and finance roles.
profilePhotoIdstring

ID of the profile picture file.
profilePhotoobject

When a profile photo file is uploaded, it gets resized to several predefined sizes and uploaded to a CDN. The URLs of those files are provided in this object. Note, that you can still access the original un-resized file via api/files.
profilePhoto.idstring

Unique identifier for the object.
profilePhoto.filenamestring
profilePhoto.variantsobject

A map of the predefined profile photo sizes. Some used in 2x displays, some used in 3x displays.
profilePhoto.variants.64string

URL of one of the predefined 2x profile photo sizes.
profilePhoto.variants.96string

URL of one of the predefined 3x profile photo sizes.
profilePhoto.variants.104string

URL of one of the predefined 2x profile photo sizes.
profilePhoto.variants.136string

URL of one of the predefined 2x profile photo sizes.
profilePhoto.variants.156string

URL of one of the predefined 3x profile photo sizes.
profilePhoto.variants.204string

URL of one of the predefined 3x profile photo sizes.
profilePhoto.variants.320string

URL of one of the predefined 2x profile photo sizes.
profilePhoto.variants.480string

URL of one of the predefined 3x profile photo sizes.
nationalitystring

Nationality.
nationalitiesstring[]

Nationalities.
spokenLanguagesstring[]

Spoken languages.
dietaryPreferencestring

Dietary preference. One of: No preference, Pescetarian, Vegetarian, Vegan, Halal, Jain, Kosher, Diabetic.
foodAllergiesstring[]

A list of food allergies.
addressstring

Street address component of the person’s home address.
citystring

City component of the persons home address.
statestring

Optional state component of the persons home address.
postcodestring

Postcode component of the persons home address.
countryCodestring

Country code in in ISO 3166-2 format, e.g. GB for United Kingdom.
countrystring

Country name, infered from the countryCode.
biostring

An optional description about the person.
linkedInstring

LinkedIn handle
twitterstring

Twitter handle
githubstring

GitHub handle
employmentStartDatedate

Employment start date.
firstWorkingDaydate

The first day at work. Defaults to employmentStartDate if not specified.
employmentEndDatedate

Employment end date. If this date is in the past, this employee is considered to be offboarded and inactive.
lastWorkingDaydate

The last day at work. Defaults to employmentEndDate if not specified.
probationEndDatedate

Probation end date.
turnoverImpactstring

Turnover impact set for offboarded people. One of regrettable, non-regrettable or “not applicable”.
isManagerboolean

Whether this person is a manager (has direct reports). Only present when requested by ?include[]=isManager query parameter.
workingDaysobject[]

A list of days worked by the employee.
workingDays.daystring

A day of the week. One of: monday, tuesday, wednesday, thursday, friday, saturday, sunday,
publicHolidayCalendarIdstring

The ID of the public holiday calendar this person uses, can be a country code, a country-region code or a regular id.
leavingReasonstring

Leaving reason set for offboarded people. One of dismissed, resigned, redundancy, contractEnded, other.
leavingNotestring

Leaving note set for offboarded people.
leavingFileIdstring

Leaving file id attached to offboarded people.
contractTypestring

The employment contract type. Commonly set to Full time, Part time, Contractor or Internship, but can be set to any value.
employeeIdstring

Employee ID as used by the company.
taxIdstring

The local tax ID frequently used for payroll purposes. For example, National Insurance Number in UK or Social Security Number in US.
taxCodestring

The local tax code / tax number frequently used for payroll purposes.
teamsobject[]

A list of teams. Often used for noting the cross functional team(s) the person is part of. Maximum of 12 items.
teams.namestring

Name of the team
statusstring

One of active, offboarded or newHire.
isVerifiedboolean

If false, it means this person has never logged in.
isWorkEmailHiddenboolean

If true, work email of this person will be visible to admins and their managers.
calendarFeedTokenstring

The calendar feed access token used in Calendar Feed URL. Only available to requesting user’s account. Set to reset to reset the value of the token.
rolestring
seenDocumentsAtdate-time

The last time the person has looked at their personal documents.
sourcestring

When the person is imported as a new hire, this field indicates what system (e.g. the name of the Applicant Tracking System) this person was imported from.
sourceIdstring

Unique identifier of the person in the system this person was imported from (e.g. the ID in the Applicant Tracking System).
timezonestring

Timezone, derived from the remote timezone, location timezone, or company timezone.
payrollProviderstring

The label or identifier of the payroll provider used to process payroll for this employee.
firstActiveAtdate-time

Timestamp the person became an active member
isBirthdayHiddenboolean

Whether this person has opted out from birthday announcements.
demoboolean

Whether this user is a demo user
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.

me object

{
  "id": "vHS9r3ZBBx1IWO3kUbEoCmmd",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "spaceId": "z9KCj9O97FC2QtHhlB02Njnx",
  "firstName": "Kelsey",
  "middleName": null,
  "lastName": "Wicks",
  "preferredName": null,
  "email": "kelsey@acme.com",
  "locationId": "FnAjNOIyLRsmZGRohZsHApiE",
  "remoteCity": null,
  "remoteRegionCode": null,
  "remoteCountryCode": null,
  "remoteTimezone": null,
  "personalEmail": "kwicks@example.com",
  "phoneNumber": "+4479460001",
  "formattedPhoneNumber": "+44 7946 0001",
  "personalPhoneNumber": null,
  "formattedPersonalPhoneNumber": null,
  "gender": "Female",
  "birthday": "1989-07-28",
  "profilePhotoId": "Hgi5auXaKsjn2MjuYo1PDk3W",
  "profilePhoto": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "nationality": "British",
  "nationalities": [
    "British"
  ],
  "spokenLanguages": [
    "English"
  ],
  "dietaryPreference": "Pescetarian",
  "foodAllergies": [
    "Peanuts"
  ],
  "address": "58 Stroude Road",
  "city": "Siddington",
  "state": null,
  "postcode": "SK11 1EN",
  "countryCode": "GB",
  "country": "United Kingdom",
  "bio": "All about that filter coffee.",
  "linkedIn": null,
  "twitter": null,
  "github": null,
  "employmentStartDate": "2018-03-10",
  "firstWorkingDay": "2018-03-10",
  "employmentEndDate": null,
  "lastWorkingDay": "2018-03-10",
  "probationEndDate": null,
  "turnoverImpact": null,
  "isManager": true,
  "workingDays": [
    {
      "day": "monday"
    },
    {
      "day": "tuesday"
    },
    {
      "day": "wednesday"
    },
    {
      "day": "thursday"
    },
    {
      "day": "friday"
    }
  ],
  "publicHolidayCalendarId": "ES-MD",
  "leavingReason": null,
  "leavingNote": null,
  "leavingFileId": null,
  "contractType": "Full time",
  "employeeId": null,
  "taxId": "QQ123456C",
  "taxCode": "123456C",
  "teams": [
    {
      "name": "Moonshot"
    },
    {
      "name": "Growth Pod"
    }
  ],
  "status": "active",
  "isVerified": true,
  "isWorkEmailHidden": false,
  "calendarFeedToken": "bb6LCUqG4BAOZWKXQQB9a8H9",
  "role": "user",
  "seenDocumentsAt": "2020-02-21T17:09:29.290Z",
  "source": null,
  "sourceId": null,
  "timezone": "Europe/London",
  "payrollProvider": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Retrieve me

Retrieves the currently logged in user.

Parameters

No parameters

Returns

Returns the currently logged in person object.

GET /api/me

curl https://app.humaans.io/api/me \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "vHS9r3ZBBx1IWO3kUbEoCmmd",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "spaceId": "z9KCj9O97FC2QtHhlB02Njnx",
  "firstName": "Kelsey",
  "middleName": null,
  "lastName": "Wicks",
  "preferredName": null,
  "email": "kelsey@acme.com",
  "locationId": "FnAjNOIyLRsmZGRohZsHApiE",
  "remoteCity": null,
  "remoteRegionCode": null,
  "remoteCountryCode": null,
  "remoteTimezone": null,
  "personalEmail": "kwicks@example.com",
  "phoneNumber": "+4479460001",
  "formattedPhoneNumber": "+44 7946 0001",
  "personalPhoneNumber": null,
  "formattedPersonalPhoneNumber": null,
  "gender": "Female",
  "birthday": "1989-07-28",
  "profilePhotoId": "Hgi5auXaKsjn2MjuYo1PDk3W",
  "profilePhoto": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "nationality": "British",
  "nationalities": [
    "British"
  ],
  "spokenLanguages": [
    "English"
  ],
  "dietaryPreference": "Pescetarian",
  "foodAllergies": [
    "Peanuts"
  ],
  "address": "58 Stroude Road",
  "city": "Siddington",
  "state": null,
  "postcode": "SK11 1EN",
  "countryCode": "GB",
  "country": "United Kingdom",
  "bio": "All about that filter coffee.",
  "linkedIn": null,
  "twitter": null,
  "github": null,
  "employmentStartDate": "2018-03-10",
  "firstWorkingDay": "2018-03-10",
  "employmentEndDate": null,
  "lastWorkingDay": "2018-03-10",
  "probationEndDate": null,
  "turnoverImpact": null,
  "isManager": true,
  "workingDays": [
    {
      "day": "monday"
    },
    {
      "day": "tuesday"
    },
    {
      "day": "wednesday"
    },
    {
      "day": "thursday"
    },
    {
      "day": "friday"
    }
  ],
  "publicHolidayCalendarId": "ES-MD",
  "leavingReason": null,
  "leavingNote": null,
  "leavingFileId": null,
  "contractType": "Full time",
  "employeeId": null,
  "taxId": "QQ123456C",
  "taxCode": "123456C",
  "teams": [
    {
      "name": "Moonshot"
    },
    {
      "name": "Growth Pod"
    }
  ],
  "status": "active",
  "isVerified": true,
  "isWorkEmailHidden": false,
  "calendarFeedToken": "bb6LCUqG4BAOZWKXQQB9a8H9",
  "role": "user",
  "seenDocumentsAt": "2020-02-21T17:09:29.290Z",
  "source": null,
  "sourceId": null,
  "timezone": "Europe/London",
  "payrollProvider": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Org hierarchies

An org hierarchy is a way of grouping people in your organisation, for example by department or by team. Each hierarchy is made up of one or more org unit types (its layers).

Endpoints

GET /api/org-hierarchies

GET /api/org-hierarchies/:id

Required scopes

orgModel:read

Org hierarchy object

Attributes

idstring

Unique identifier for the object.
namestring

The name of the hierarchy.
codestring

A user specified code for the hierarchy, null if not set.
isPrimaryboolean

Whether this is the primary hierarchy for the company. Exactly one hierarchy is primary.
orgUnitTypesobject[]

The types of org units which can appear in this hierarchy, returned in hierarchical order.
orgUnitTypes.idstring

Unique identifier for the org unit type.
orgUnitTypes.codestring

A user specified code for the org unit type.
orgUnitTypes.namestring

The name of the org unit type.
reportingRolestring

The name of the role people report up to in this hierarchy. null when the hierarchy has no lead field.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

The date and time the hierarchy was deleted. Only present on deleted hierarchies, which are only returned when querying with includeDeleted.

org hierarchy object

{
  "id": "Nyilss56MOoMjRDgXz2SNQWW",
  "name": "Departments",
  "code": "department",
  "isPrimary": true,
  "orgUnitTypes": [
    {
      "id": "T7uqPFK7am4lFTZm39AmNuay",
      "code": "department",
      "name": "Department"
    }
  ],
  "reportingRole": "Manager",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all org hierarchies

Returns a list of org hierarchies.

Parameters

includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
isPrimaryboolean

Whether this is the primary hierarchy for the company. Exactly one hierarchy is primary.
createdAtdate | date-time · $gt $gte $lt $lte

Filter by createdAt.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit org hierarchies. The response skips the first $skip results. Each entry is a separate org hierarchy object. If no org hierarchies are available, data is empty.

GET /api/org-hierarchies

curl https://app.humaans.io/api/org-hierarchies \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "Nyilss56MOoMjRDgXz2SNQWW",
      "name": "Departments",
      "code": "department",
      "isPrimary": true,
      "orgUnitTypes": [
        {
          "id": "T7uqPFK7am4lFTZm39AmNuay",
          "code": "department",
          "name": "Department"
        }
      ],
      "reportingRole": "Manager",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve an org hierarchy

Retrieves the org hierarchy with the given ID.

Parameters

No parameters

Returns

Returns an org hierarchy object if a valid identifier was provided.

GET /api/org-hierarchies/:id

curl https://app.humaans.io/api/org-hierarchies/Nyilss56MOoMjRDgXz2SNQWW \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "Nyilss56MOoMjRDgXz2SNQWW",
  "name": "Departments",
  "code": "department",
  "isPrimary": true,
  "orgUnitTypes": [
    {
      "id": "T7uqPFK7am4lFTZm39AmNuay",
      "code": "department",
      "name": "Department"
    }
  ],
  "reportingRole": "Manager",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Org unit assignments

An org unit assignment records that a person belongs to an org unit over a period of time. Listing them returns the full timeline by default, including past and future assignments — pass $asOf to narrow to a given date.

Endpoints

GET /api/org-unit-assignments

GET /api/org-unit-assignments/:id

Required scopes

orgModel:read

Org unit assignment object

Attributes

idstring

Unique identifier for the object.
personIdstring

The id of the person this assignment belongs to.
orgUnitIdstring

The id of the org unit the person is assigned to.
effectiveDatedate

The date when this assignment took effect. Can be a past or future date.
endDatedate

The date when this assignment ends, null if this is the last assignment.
orgHierarchyIdstring

The id of the hierarchy this assignment belongs to.
isPrimaryHierarchyboolean

Whether this assignment belongs to the company’s primary hierarchy.
isPrimaryAssignmentboolean

Whether this is the person’s primary assignment within this hierarchy. At most one assignment is primary per person per hierarchy at any point in time.
reportingTostring

The id of the person this assignment reports into. See reportingRelationship below for more details.
reportingRelationshipobject

Details on the reporting role this assignment reports into, and how that role was resolved. null when the hierarchy has no reporting role.
reportingRelationship.namestring

The name of the reporting role.
reportingRelationship.sourceobject

Where reportingTo resolved from. null when there is no reporting leader.
reportingRelationship.source.typestring

direct when reportingTo is specified by the org unit, inherited when it comes from an ancestor org unit, and individualOverride when this person has their own value for the reporting role.
reportingRelationship.source.orgUnitIdstring

The org unit the value applies to. The assigned unit itself for direct and individualOverride, otherwise the ancestor the value was inherited from.
createdAtdate-time

The date and time this assignment was created.
updatedAtdate-time

The date and time this assignment was last updated.
deletedAtdate-time

The date and time this assignment was deleted. Only present on deleted assignments, which are only returned when querying with includeDeleted.

org unit assignment object

{
  "id": "x3F5Q3cPpSHg1p53bAwZPVFv",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "orgUnitId": "Nyilss56MOoMjRDgXz2SNQWW",
  "effectiveDate": "2020-02-15",
  "endDate": null,
  "orgHierarchyId": "Nyilss56MOoMjRDgXz2SNQWW",
  "isPrimaryHierarchy": true,
  "isPrimaryAssignment": true,
  "reportingTo": "IL3vneCYhIx0xrR6um2sy2nW",
  "reportingRelationship": {
    "source": {}
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all org unit assignments

Returns a list of org unit assignments.

Parameters

effectiveDatedate | date-time · $gt $gte $lt $lte

The date when this assignment took effect. Can be a past or future date.
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
isPrimaryAssignmentboolean

Restrict the assignments to only the primary ones, or only the non-primary ones.
isPrimaryHierarchyboolean at most one of orgHierarchyId or isPrimaryHierarchy

Restrict the assignments to the company’s primary hierarchy, or to every hierarchy except it. Cannot be combined with orgHierarchyId.
orgHierarchyIdstring · $eq $ne $in $nin at most one of orgHierarchyId or isPrimaryHierarchy

The id of the hierarchy this assignment belongs to.
orgUnitIdstring · $eq $ne $in $nin

The id of the org unit the person is assigned to.
personIdstring · $in

The id of the person this assignment belongs to.
createdAtdate | date-time · $gt $gte $lt $lte

Filter by createdAt.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$asOfdate | empty

Restrict the assignments to those in effect on the given date. Cannot be combined with includeDeleted.
$sortobject
$sort.deletedAtnumber
$sort.effectiveDatenumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit org unit assignments. The response skips the first $skip results. Each entry is a separate org unit assignment object. If no org unit assignments are available, data is empty.

GET /api/org-unit-assignments

curl https://app.humaans.io/api/org-unit-assignments \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "x3F5Q3cPpSHg1p53bAwZPVFv",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "orgUnitId": "Nyilss56MOoMjRDgXz2SNQWW",
      "effectiveDate": "2020-02-15",
      "endDate": null,
      "orgHierarchyId": "Nyilss56MOoMjRDgXz2SNQWW",
      "isPrimaryHierarchy": true,
      "isPrimaryAssignment": true,
      "reportingTo": "IL3vneCYhIx0xrR6um2sy2nW",
      "reportingRelationship": {
        "source": {}
      },
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve an org unit assignment

Retrieves the org unit assignment with the given ID.

Parameters

No parameters

Returns

Returns an org unit assignment object if a valid identifier was provided.

GET /api/org-unit-assignments/:id

curl https://app.humaans.io/api/org-unit-assignments/x3F5Q3cPpSHg1p53bAwZPVFv \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "x3F5Q3cPpSHg1p53bAwZPVFv",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "orgUnitId": "Nyilss56MOoMjRDgXz2SNQWW",
  "effectiveDate": "2020-02-15",
  "endDate": null,
  "orgHierarchyId": "Nyilss56MOoMjRDgXz2SNQWW",
  "isPrimaryHierarchy": true,
  "isPrimaryAssignment": true,
  "reportingTo": "IL3vneCYhIx0xrR6um2sy2nW",
  "reportingRelationship": {
    "source": {}
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Org units

An org unit is a node in an org hierarchy, for example a specific department or team. The list is flat: parentId carries the tree shape within a hierarchy.

Endpoints

GET /api/org-units

GET /api/org-units/:id

Required scopes

orgModel:read

Org unit object

Attributes

idstring

Unique identifier for the object.
orgUnitTypeIdstring

The id of org unit type this unit belongs to
namestring

The name of the org unit.
codestring

A user specified code for the org unit. null when not set.
descriptionstring

Free text description of the org unit.
parentIdstring

The id of the parent org unit. null if this is a top level org unit.
orgHierarchyIdstring

The id of the org hierarchy this unit belongs to.
reportingLeaderIdstring

The id of the reporting lead for this org unit.
reportingRelationshipobject

The reporting role this unit reports into, and where the reporting leader resolved from. null when the hierarchy has no reporting role, in which case it produces no reporting at all.
reportingRelationship.namestring

The name of the reporting role.
reportingRelationship.sourceobject

Where reportingLeaderId resolved from. null when there is no reporting leader.
reportingRelationship.source.typestring

direct when reportingTo is specified by the org unit and inherited when it comes from an ancestor org unit.
reportingRelationship.source.orgUnitIdstring

The org unit the value applies to. The org unit itself for direct, or otherwise the ancestor the value was inherited from.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

The date and time the org unit was deleted. Only present on deleted units, which are only returned when querying with includeDeleted.

org unit object

{
  "id": "buMfTrl9M65AHakPANgNqfzP",
  "name": "Engineering",
  "code": "engineering",
  "parentId": null,
  "orgHierarchyId": "Nyilss56MOoMjRDgXz2SNQWW",
  "reportingLeaderId": "IL3vneCYhIx0xrR6um2sy2nW",
  "reportingRelationship": {
    "name": "Manager",
    "source": {
      "type": "direct",
      "orgUnitId": "Nyilss56MOoMjRDgXz2SNQWW"
    }
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

List all org units

Returns a list of org units.

Parameters

idstring · $eq $ne $in $nin
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
isPrimaryHierarchyboolean at most one of orgHierarchyId or isPrimaryHierarchy

Restrict the units to the company’s primary hierarchy, or to every hierarchy except it. Cannot be combined with orgHierarchyId.
orgHierarchyIdstring at most one of orgHierarchyId or isPrimaryHierarchy

Restrict the units to a single org hierarchy. Units in every hierarchy are returned when omitted. Cannot be combined with isPrimaryHierarchy.
orgUnitTypeIdstring · $eq $ne $in $nin

The id of org unit type this unit belongs to
parentIdstring | empty

Restrict the units to the direct children of the given org unit. Pass an empty value to return only the top level units.
createdAtdate | date-time · $gt $gte $lt $lte

Filter by createdAt.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit org units. The response skips the first $skip results. Each entry is a separate org unit object. If no org units are available, data is empty.

GET /api/org-units

curl https://app.humaans.io/api/org-units \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "buMfTrl9M65AHakPANgNqfzP",
      "name": "Engineering",
      "code": "engineering",
      "parentId": null,
      "orgHierarchyId": "Nyilss56MOoMjRDgXz2SNQWW",
      "reportingLeaderId": "IL3vneCYhIx0xrR6um2sy2nW",
      "reportingRelationship": {
        "name": "Manager",
        "source": {
          "type": "direct",
          "orgUnitId": "Nyilss56MOoMjRDgXz2SNQWW"
        }
      },
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z",
      "deletedAt": null
    }
  ]
}

Retrieve an org unit

Retrieves the org unit with the given ID.

Parameters

No parameters

Returns

Returns an org unit object if a valid identifier was provided.

GET /api/org-units/:id

curl https://app.humaans.io/api/org-units/buMfTrl9M65AHakPANgNqfzP \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "buMfTrl9M65AHakPANgNqfzP",
  "name": "Engineering",
  "code": "engineering",
  "parentId": null,
  "orgHierarchyId": "Nyilss56MOoMjRDgXz2SNQWW",
  "reportingLeaderId": "IL3vneCYhIx0xrR6um2sy2nW",
  "reportingRelationship": {
    "name": "Manager",
    "source": {
      "type": "direct",
      "orgUnitId": "Nyilss56MOoMjRDgXz2SNQWW"
    }
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "deletedAt": null
}

People

An object representing an an employee at a company. The most important object in Humaans.

Endpoints

   GET /api/people

   GET /api/people/:id

  POST /api/people

 PATCH /api/people/:id

DELETE /api/people/:id

Required scopes

private:read

public:read

private:write

Person object

Attributes

idstring

Unique identifier for the object.
companyIdstring

ID of the company that this object is associated to.
spaceIdstring

ID of the Space this person belongs to.
firstNamestring

First name.
middleNamestring

Middle name.
lastNamestring

Last name.
preferredNamestring

Preferred first name that the person goes by. This will be shown in Humaans instead of the first name if set.
pronounsstring

Preferred pronouns that the person goes by
emailstring

The work email of the person. The email they use to log in.
jobRoleobject

The job role details of this person.
locationIdstring

The ID of the location this person works at. It can be either the ID of a location or the string literal remote, in which case it indicates this person works remotely and the working location can be found in the remoteCity, remoteRegionCode and remoteCountryCode fields.
remoteCitystring

When locationId is set to remote, this indicates the city that this person works in.
remoteRegionCodestring

When locationId is set to remote, this indicates the region that this person works in. Region code in ISO 3166-2 format e.g. CA-QC for Quebec.
remoteCountryCodestring

When locationId is set to remote, this indicates the country that this person works in. Country code in in ISO 3166-2 format, e.g. GB for United Kingdom.
remoteTimezonestring

When locationId is set to remote, this indicates the timezone that this person works in. The timezone is infered from the city and country code.
timeAwayApprovalFlowIdstring

The Id of the time away approval flow this person works under.
personalEmailstring

Personal email of the person.
phoneNumberstring

Work phone number of the person.
formattedPhoneNumberstring

Work phone number of the person formatted for display.
personalPhoneNumberstring

Personal phone number of the person.
formattedPersonalPhoneNumberstring

Personal phone number of the person formatted for display.
genderstring

Person’s gender. It’s a free form field, any value is allowed.
birthdaystring

Person’s date of birth. Only disclosed to users with owner, admin and finance roles.
profilePhotoIdstring

ID of the profile picture file.
profilePhotoobject

When a profile photo file is uploaded, it gets resized to several predefined sizes and uploaded to a CDN. The URLs of those files are provided in this object. Note, that you can still access the original un-resized file via api/files.
profilePhoto.idstring

Unique identifier for the object.
profilePhoto.filenamestring
profilePhoto.variantsobject

A map of the predefined profile photo sizes. Some used in 2x displays, some used in 3x displays.
profilePhoto.variants.64string

URL of one of the predefined 2x profile photo sizes.
profilePhoto.variants.96string

URL of one of the predefined 3x profile photo sizes.
profilePhoto.variants.104string

URL of one of the predefined 2x profile photo sizes.
profilePhoto.variants.136string

URL of one of the predefined 2x profile photo sizes.
profilePhoto.variants.156string

URL of one of the predefined 3x profile photo sizes.
profilePhoto.variants.204string

URL of one of the predefined 3x profile photo sizes.
profilePhoto.variants.320string

URL of one of the predefined 2x profile photo sizes.
profilePhoto.variants.480string

URL of one of the predefined 3x profile photo sizes.
nationalitystring

Nationality.
nationalitiesstring[]

Nationalities.
spokenLanguagesstring[]

Spoken languages.
dietaryPreferencestring

Dietary preference. One of: No preference, Pescetarian, Vegetarian, Vegan, Halal, Jain, Kosher, Diabetic.
foodAllergiesstring[]

A list of food allergies.
addressstring

Street address component of the person’s home address.
citystring

City component of the persons home address.
statestring

Optional state component of the persons home address.
postcodestring

Postcode component of the persons home address.
countryCodestring

Country code in in ISO 3166-2 format, e.g. GB for United Kingdom.
countrystring

Country name, infered from the countryCode.
biostring

An optional description about the person.
linkedInstring

LinkedIn handle
twitterstring

Twitter handle
githubstring

GitHub handle
employmentStartDatedate

Employment start date.
firstWorkingDaydate

The first day at work. Defaults to employmentStartDate if not specified.
employmentEndDatedate

Employment end date. If this date is in the past, this employee is considered to be offboarded and inactive.
lastWorkingDaydate

The last day at work. Defaults to employmentEndDate if not specified.
probationEndDatedate

Probation end date.
turnoverImpactstring

Turnover impact set for offboarded people. One of regrettable, non-regrettable or “not applicable”.
isManagerboolean

Whether this person is a manager (has direct reports). Only present when requested by ?include[]=isManager query parameter.
workingDaysobject[]

A list of days worked by the employee.
workingDays.daystring

A day of the week. One of: monday, tuesday, wednesday, thursday, friday, saturday, sunday,
publicHolidayCalendarIdstring

The ID of the public holiday calendar this person uses, can be a country code, a country-region code or a regular id.
leavingReasonstring

Leaving reason set for offboarded people. One of dismissed, resigned, redundancy, contractEnded, other.
leavingNotestring

Leaving note set for offboarded people.
leavingFileIdstring

Leaving file id attached to offboarded people.
contractTypestring

The employment contract type. Commonly set to Full time, Part time, Contractor or Internship, but can be set to any value.
employeeIdstring

Employee ID as used by the company.
taxIdstring

The local tax ID frequently used for payroll purposes. For example, National Insurance Number in UK or Social Security Number in US.
taxCodestring

The local tax code / tax number frequently used for payroll purposes.
teamsobject[]

A list of teams. Often used for noting the cross functional team(s) the person is part of. Maximum of 12 items.
teams.namestring

Name of the team
statusstring

One of active, offboarded or newHire.
isVerifiedboolean

If false, it means this person has never logged in.
isWorkEmailHiddenboolean

If true, work email of this person will be visible to admins and their managers.
calendarFeedTokenstring

The calendar feed access token used in Calendar Feed URL. Only available to requesting user’s account. Set to reset to reset the value of the token.
rolestring
seenDocumentsAtdate-time

The last time the person has looked at their personal documents.
sourcestring

When the person is imported as a new hire, this field indicates what system (e.g. the name of the Applicant Tracking System) this person was imported from.
sourceIdstring

Unique identifier of the person in the system this person was imported from (e.g. the ID in the Applicant Tracking System).
timezonestring

Timezone, derived from the remote timezone, location timezone, or company timezone.
payrollProviderstring

The label or identifier of the payroll provider used to process payroll for this employee.
firstActiveAtdate-time

Timestamp the person became an active member
isBirthdayHiddenboolean

Whether this person has opted out from birthday announcements.
demoboolean

Whether this user is a demo user
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.

person object

{
  "id": "VMB1yzL5uL8VvNNCJc9rykJz",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "spaceId": "z9KCj9O97FC2QtHhlB02Njnx",
  "firstName": "Kelsey",
  "middleName": null,
  "lastName": "Wicks",
  "preferredName": null,
  "email": "kelsey@acme.com",
  "locationId": "FnAjNOIyLRsmZGRohZsHApiE",
  "remoteCity": null,
  "remoteRegionCode": null,
  "remoteCountryCode": null,
  "remoteTimezone": null,
  "personalEmail": "kwicks@example.com",
  "phoneNumber": "+4479460001",
  "formattedPhoneNumber": "+44 7946 0001",
  "personalPhoneNumber": null,
  "formattedPersonalPhoneNumber": null,
  "gender": "Female",
  "birthday": "1989-07-28",
  "profilePhotoId": "Hgi5auXaKsjn2MjuYo1PDk3W",
  "profilePhoto": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "nationality": "British",
  "nationalities": [
    "British"
  ],
  "spokenLanguages": [
    "English"
  ],
  "dietaryPreference": "Pescetarian",
  "foodAllergies": [
    "Peanuts"
  ],
  "address": "58 Stroude Road",
  "city": "Siddington",
  "state": null,
  "postcode": "SK11 1EN",
  "countryCode": "GB",
  "country": "United Kingdom",
  "bio": "All about that filter coffee.",
  "linkedIn": null,
  "twitter": null,
  "github": null,
  "employmentStartDate": "2018-03-10",
  "firstWorkingDay": "2018-03-10",
  "employmentEndDate": null,
  "lastWorkingDay": "2018-03-10",
  "probationEndDate": null,
  "turnoverImpact": null,
  "isManager": true,
  "workingDays": [
    {
      "day": "monday"
    },
    {
      "day": "tuesday"
    },
    {
      "day": "wednesday"
    },
    {
      "day": "thursday"
    },
    {
      "day": "friday"
    }
  ],
  "publicHolidayCalendarId": "ES-MD",
  "leavingReason": null,
  "leavingNote": null,
  "leavingFileId": null,
  "contractType": "Full time",
  "employeeId": null,
  "taxId": "QQ123456C",
  "taxCode": "123456C",
  "teams": [
    {
      "name": "Moonshot"
    },
    {
      "name": "Growth Pod"
    }
  ],
  "status": "active",
  "isVerified": true,
  "isWorkEmailHidden": false,
  "calendarFeedToken": "bb6LCUqG4BAOZWKXQQB9a8H9",
  "role": "user",
  "seenDocumentsAt": "2020-02-21T17:09:29.290Z",
  "source": null,
  "sourceId": null,
  "timezone": "Europe/London",
  "payrollProvider": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all people

Returns a list of people.

By default, only people with status active are returned. These are people that are actively employed at the company. Note that people that have already started and people that have the employment start date in the future are considered to be active.

If the last working day is set and is in the past, the status changes to offboarded. Fetch only offboarded people with ?status=offboarded.

People that are imported from Applicant Tracking Systems (ATS) have the status of newHire. New hires is a way to add people into the system with limited data (e.g. without work email or place of work). Once the missing data is available and is populated, the new hires can be promoted to active status. Fetch only new hires with ?status=newHire.

To fetch all people at once, use ?status=all. Note: be cautious when fetching all people, as new statuses might get introduced in the future.

It is also possible to fetch multiple statuses at once, e.g. ?status[$in]=active&status[$in]=offboarded. Refer to Filtering documentation for further details on usage of $in.

Parameters

emailstring

Filter people by work email address.
employmentEndDatedate | date-time · $gt $gte $lt $lte

Filter people by employment end date.
employmentStartDatedate | date-time · $gt $gte $lt $lte

Filter people by employment start date.
firstNamestring · $ilike

Filter people by first name. Supports $ilike for case-insensitive matching.
firstWorkingDaydate | date-time · $gt $gte $lt $lte

Filter people by first working day.
genderstring · $eq $ne $in $nin $ilike

Filter people by gender (free-form value). Pass a string for an exact match, { “$in”: […] } for several values, or { “$ilike”: “…” } for case-insensitive matching.
includestring[]

Additional fields to include, not provided as part of the default payload. Supported values are: isManager.
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
lastNamestring · $ilike

Filter people by last name. Supports $ilike for case-insensitive matching.
lastWorkingDaydate | date-time · $gt $gte $lt $lte

Filter people by last working day.
payrollProviderstring · $eq $ne $in $nin

Filter people by payroll provider.
personalEmailstring

Filter people by personal email address.
preferredNamestring · $ilike

Filter people by preferred name. Supports $ilike for case-insensitive matching.
probationEndDatedate | date-time · $gt $gte $lt $lte

Filter people by probation end date.
spaceIdstring · $eq $ne $in $nin

Filter people by the ID of the Space they belong to.
statusstring · $in $nin

Filter people by status, one of all, newHire, active, offboarded. Default: active.
teamsstring · $any $not

Filter people by team.
createdAtdate | date-time · $gt $gte $lt $lte

Filter people by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
$orobject[]

Filter by multiple conditions using OR logic. Supports firstName, lastName, preferredName.
$or.firstNamestring · $ilike
$or.lastNamestring · $ilike
$or.preferredNamestring · $ilike
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit people. The response skips the first $skip results. Each entry is a separate person object. If no people are available, data is empty.

GET /api/people

curl https://app.humaans.io/api/people \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "VMB1yzL5uL8VvNNCJc9rykJz",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "spaceId": "z9KCj9O97FC2QtHhlB02Njnx",
      "firstName": "Kelsey",
      "middleName": null,
      "lastName": "Wicks",
      "preferredName": null,
      "email": "kelsey@acme.com",
      "locationId": "FnAjNOIyLRsmZGRohZsHApiE",
      "remoteCity": null,
      "remoteRegionCode": null,
      "remoteCountryCode": null,
      "remoteTimezone": null,
      "personalEmail": "kwicks@example.com",
      "phoneNumber": "+4479460001",
      "formattedPhoneNumber": "+44 7946 0001",
      "personalPhoneNumber": null,
      "formattedPersonalPhoneNumber": null,
      "gender": "Female",
      "birthday": "1989-07-28",
      "profilePhotoId": "Hgi5auXaKsjn2MjuYo1PDk3W",
      "profilePhoto": {
        "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
        "filename": "image-file.jpg",
        "variants": {
          "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
          "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
          "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
          "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
          "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
          "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
          "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
          "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
        }
      },
      "nationality": "British",
      "nationalities": [
        "British"
      ],
      "spokenLanguages": [
        "English"
      ],
      "dietaryPreference": "Pescetarian",
      "foodAllergies": [
        "Peanuts"
      ],
      "address": "58 Stroude Road",
      "city": "Siddington",
      "state": null,
      "postcode": "SK11 1EN",
      "countryCode": "GB",
      "country": "United Kingdom",
      "bio": "All about that filter coffee.",
      "linkedIn": null,
      "twitter": null,
      "github": null,
      "employmentStartDate": "2018-03-10",
      "firstWorkingDay": "2018-03-10",
      "employmentEndDate": null,
      "lastWorkingDay": "2018-03-10",
      "probationEndDate": null,
      "turnoverImpact": null,
      "isManager": true,
      "workingDays": [
        {
          "day": "monday"
        },
        {
          "day": "tuesday"
        },
        {
          "day": "wednesday"
        },
        {
          "day": "thursday"
        },
        {
          "day": "friday"
        }
      ],
      "publicHolidayCalendarId": "ES-MD",
      "leavingReason": null,
      "leavingNote": null,
      "leavingFileId": null,
      "contractType": "Full time",
      "employeeId": null,
      "taxId": "QQ123456C",
      "taxCode": "123456C",
      "teams": [
        {
          "name": "Moonshot"
        },
        {
          "name": "Growth Pod"
        }
      ],
      "status": "active",
      "isVerified": true,
      "isWorkEmailHidden": false,
      "calendarFeedToken": "bb6LCUqG4BAOZWKXQQB9a8H9",
      "role": "user",
      "seenDocumentsAt": "2020-02-21T17:09:29.290Z",
      "source": null,
      "sourceId": null,
      "timezone": "Europe/London",
      "payrollProvider": null,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a person

Retrieves the person with the given ID.

Parameters

No parameters

Returns

Returns a person object if a valid identifier was provided.

GET /api/people/:id

curl https://app.humaans.io/api/people/VMB1yzL5uL8VvNNCJc9rykJz \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "VMB1yzL5uL8VvNNCJc9rykJz",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "spaceId": "z9KCj9O97FC2QtHhlB02Njnx",
  "firstName": "Kelsey",
  "middleName": null,
  "lastName": "Wicks",
  "preferredName": null,
  "email": "kelsey@acme.com",
  "locationId": "FnAjNOIyLRsmZGRohZsHApiE",
  "remoteCity": null,
  "remoteRegionCode": null,
  "remoteCountryCode": null,
  "remoteTimezone": null,
  "personalEmail": "kwicks@example.com",
  "phoneNumber": "+4479460001",
  "formattedPhoneNumber": "+44 7946 0001",
  "personalPhoneNumber": null,
  "formattedPersonalPhoneNumber": null,
  "gender": "Female",
  "birthday": "1989-07-28",
  "profilePhotoId": "Hgi5auXaKsjn2MjuYo1PDk3W",
  "profilePhoto": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "nationality": "British",
  "nationalities": [
    "British"
  ],
  "spokenLanguages": [
    "English"
  ],
  "dietaryPreference": "Pescetarian",
  "foodAllergies": [
    "Peanuts"
  ],
  "address": "58 Stroude Road",
  "city": "Siddington",
  "state": null,
  "postcode": "SK11 1EN",
  "countryCode": "GB",
  "country": "United Kingdom",
  "bio": "All about that filter coffee.",
  "linkedIn": null,
  "twitter": null,
  "github": null,
  "employmentStartDate": "2018-03-10",
  "firstWorkingDay": "2018-03-10",
  "employmentEndDate": null,
  "lastWorkingDay": "2018-03-10",
  "probationEndDate": null,
  "turnoverImpact": null,
  "isManager": true,
  "workingDays": [
    {
      "day": "monday"
    },
    {
      "day": "tuesday"
    },
    {
      "day": "wednesday"
    },
    {
      "day": "thursday"
    },
    {
      "day": "friday"
    }
  ],
  "publicHolidayCalendarId": "ES-MD",
  "leavingReason": null,
  "leavingNote": null,
  "leavingFileId": null,
  "contractType": "Full time",
  "employeeId": null,
  "taxId": "QQ123456C",
  "taxCode": "123456C",
  "teams": [
    {
      "name": "Moonshot"
    },
    {
      "name": "Growth Pod"
    }
  ],
  "status": "active",
  "isVerified": true,
  "isWorkEmailHidden": false,
  "calendarFeedToken": "bb6LCUqG4BAOZWKXQQB9a8H9",
  "role": "user",
  "seenDocumentsAt": "2020-02-21T17:09:29.290Z",
  "source": null,
  "sourceId": null,
  "timezone": "Europe/London",
  "payrollProvider": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a person

People can be created in 2 ways - with status active or newHire.

By default, when not specified otherwise, employees get created with active status. In this case, all of the required fields as specified below must be provided.

It is possible to create people with status set to newHire. This is typically done in Applicant Tracking System (ATS) integrations. When creating a person as a new hire only one of email or personalEmail is required and all of the other fields are optional. When creating new hires, you can make use of the source and sourceId fields to specify extra metadata about where the new hire was imported from. New hires are only visible to Owner and Admin roles. Their full profiles can not be opened until their status is updated to active. To do so, use the patch method, set the status to active and provide any of the missing required fields that were not provided when creating the new hire.

Parameters

firstNamestring required

First name.
middleNamestring | null

Middle name.
lastNamestring required

Last name.
preferredNamestring | null

Preferred first name that the person goes by. This will be shown in Humaans instead of the first name if set.
pronounsstring | null

Preferred pronouns that the person goes by
emailstring required

The work email of the person. The email they use to log in.
personalEmailstring | null

Personal email of the person.
phoneNumberstring | null

Work phone number of the person.
personalPhoneNumberstring | null

Personal phone number of the person.
genderstring | null

Person’s gender. It’s a free form field, any value is allowed.
birthdaydate | null

Person’s date of birth. Only disclosed to users with owner, admin and finance roles.
isBirthdayHiddenboolean

Whether this person has opted out from birthday announcements.
profilePhotoIdstring | null

ID of the profile picture file.
nationalitystring | null

Nationality.
nationalitiesstring[] | null

Nationalities.
spokenLanguagesstring[] | null

Spoken languages.
dietaryPreferencestring | null

Dietary preference. One of: No preference, Pescetarian, Vegetarian, Vegan, Halal, Jain, Kosher, Diabetic.
foodAllergiesstring[]

A list of food allergies.
addressstring | null

Street address component of the person’s home address.
citystring | null

City component of the persons home address.
statestring | null

Optional state component of the persons home address.
postcodestring | null

Postcode component of the persons home address.
countryCodestring | null

Country code in in ISO 3166-2 format, e.g. GB for United Kingdom.
biostring | null

An optional description about the person.
linkedInstring | null

LinkedIn handle
twitterstring | null

Twitter handle
githubstring | null

GitHub handle
employmentStartDatedate required

Employment start date.
firstWorkingDaydate

The first day at work. Defaults to employmentStartDate if not specified.
employmentEndDatedate | null

Employment end date. If this date is in the past, this employee is considered to be offboarded and inactive.
lastWorkingDaydate | null

The last day at work. Defaults to employmentEndDate if not specified.
probationEndDatedate | null

Probation end date.
workingDaysobject[] | null

A list of days worked by the employee.
workingDays.daystring

A day of the week. One of: monday, tuesday, wednesday, thursday, friday, saturday, sunday,
turnoverImpactstring | null

Turnover impact set for offboarded people. One of regrettable, non-regrettable or “not applicable”.
leavingReasonstring | null

Leaving reason set for offboarded people. One of dismissed, resigned, redundancy, contractEnded, other.
leavingNotestring | null

Leaving note set for offboarded people.
leavingFileIdstring | null

Leaving file id attached to offboarded people.
contractTypestring | null

The employment contract type. Commonly set to Full time, Part time, Contractor or Internship, but can be set to any value.
payrollProviderstring | null

The label or identifier of the payroll provider used to process payroll for this employee.
employeeIdstring | null

Employee ID as used by the company.
taxIdstring | null

The local tax ID frequently used for payroll purposes. For example, National Insurance Number in UK or Social Security Number in US.
taxCodestring | null

The local tax code / tax number frequently used for payroll purposes.
locationIdstring required

The ID of the location this person works at. It can be either the ID of a location or the string literal remote, in which case it indicates this person works remotely and the working location can be found in the remoteCity, remoteRegionCode and remoteCountryCode fields.
remoteCitystring | null

When locationId is set to remote, this indicates the city that this person works in.
remoteCountryCodestring | null

When locationId is set to remote, this indicates the country that this person works in. Country code in in ISO 3166-2 format, e.g. GB for United Kingdom.
timeAwayApprovalFlowIdstring

The Id of the time away approval flow this person works under.
spaceIdstring

ID of the Space this person belongs to.
teamsobject[]

A list of teams. Often used for noting the cross functional team(s) the person is part of. Maximum of 12 items.
teams.namestring required

Name of the team
statusstring

One of active, offboarded or newHire.
isWorkEmailHiddenboolean

If true, work email of this person will be visible to admins and their managers.
calendarFeedTokenstring

The calendar feed access token used in Calendar Feed URL. Only available to requesting user’s account. Set to reset to reset the value of the token.
seenDocumentsAtdate-time

The last time the person has looked at their personal documents.
publicHolidayCalendarIdstring | null

The ID of the public holiday calendar this person uses, can be a country code, a country-region code or a regular id.
jobRoleobject required

The job role details of this person.
jobRole.jobTitlestring required

Job title.
jobRole.jobLibraryProfileIdstring | null
jobRole.departmentstring | null

Department name.
jobRole.reportingTostring | null

The ID of the user this person reports to.
customValuesobject[]
customValues.customFieldIdstring required
customValues.valuestring required
timeAwayAllocationobject

The time away policy for this person.
timeAwayAllocation.timeAwayPolicyIdstring required

The ID of the timeaway policy.

Returns

Returns a person if the call succeeded. The call returns an error if parameters are invalid.

POST /api/people

curl https://app.humaans.io/api/people \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"firstName":"Kelsey","lastName":"Wicks","email":"kelsey@acme.com","locationId":"FnAjNOIyLRsmZGRohZsHApiE","jobRole":{"jobTitle":"Software Engineer","department":"Engineering","reportingTo":"OfcRvv174ir3Y6mNA5bPXqeY"},"employmentStartDate":"2018-03-10"}'

Response

{
  "id": "VMB1yzL5uL8VvNNCJc9rykJz",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "spaceId": "z9KCj9O97FC2QtHhlB02Njnx",
  "firstName": "Kelsey",
  "middleName": null,
  "lastName": "Wicks",
  "preferredName": null,
  "email": "kelsey@acme.com",
  "locationId": "FnAjNOIyLRsmZGRohZsHApiE",
  "remoteCity": null,
  "remoteRegionCode": null,
  "remoteCountryCode": null,
  "remoteTimezone": null,
  "personalEmail": "kwicks@example.com",
  "phoneNumber": "+4479460001",
  "formattedPhoneNumber": "+44 7946 0001",
  "personalPhoneNumber": null,
  "formattedPersonalPhoneNumber": null,
  "gender": "Female",
  "birthday": "1989-07-28",
  "profilePhotoId": "Hgi5auXaKsjn2MjuYo1PDk3W",
  "profilePhoto": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "nationality": "British",
  "nationalities": [
    "British"
  ],
  "spokenLanguages": [
    "English"
  ],
  "dietaryPreference": "Pescetarian",
  "foodAllergies": [
    "Peanuts"
  ],
  "address": "58 Stroude Road",
  "city": "Siddington",
  "state": null,
  "postcode": "SK11 1EN",
  "countryCode": "GB",
  "country": "United Kingdom",
  "bio": "All about that filter coffee.",
  "linkedIn": null,
  "twitter": null,
  "github": null,
  "employmentStartDate": "2018-03-10",
  "firstWorkingDay": "2018-03-10",
  "employmentEndDate": null,
  "lastWorkingDay": "2018-03-10",
  "probationEndDate": null,
  "turnoverImpact": null,
  "isManager": true,
  "workingDays": [
    {
      "day": "monday"
    },
    {
      "day": "tuesday"
    },
    {
      "day": "wednesday"
    },
    {
      "day": "thursday"
    },
    {
      "day": "friday"
    }
  ],
  "publicHolidayCalendarId": "ES-MD",
  "leavingReason": null,
  "leavingNote": null,
  "leavingFileId": null,
  "contractType": "Full time",
  "employeeId": null,
  "taxId": "QQ123456C",
  "taxCode": "123456C",
  "teams": [
    {
      "name": "Moonshot"
    },
    {
      "name": "Growth Pod"
    }
  ],
  "status": "active",
  "isVerified": true,
  "isWorkEmailHidden": false,
  "calendarFeedToken": "bb6LCUqG4BAOZWKXQQB9a8H9",
  "role": "user",
  "seenDocumentsAt": "2020-02-21T17:09:29.290Z",
  "source": null,
  "sourceId": null,
  "timezone": "Europe/London",
  "payrollProvider": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a person

To offboard a person, set the employmentEndDate (and if relevant lastWorkingDay) to some past or future date. Once that date is in the past (with respect to the UTC timezone), the employee is considered to be offboarded, and their status field will switch to offboarded.

Parameters

firstNamestring

First name.
middleNamestring | null

Middle name.
lastNamestring

Last name.
preferredNamestring | null

Preferred first name that the person goes by. This will be shown in Humaans instead of the first name if set.
pronounsstring | null

Preferred pronouns that the person goes by
emailstring | null

The work email of the person. The email they use to log in.
personalEmailstring | null

Personal email of the person.
phoneNumberstring | null

Work phone number of the person.
personalPhoneNumberstring | null

Personal phone number of the person.
genderstring | null

Person’s gender. It’s a free form field, any value is allowed.
birthdaydate | null

Person’s date of birth. Only disclosed to users with owner, admin and finance roles.
isBirthdayHiddenboolean

Whether this person has opted out from birthday announcements.
profilePhotoIdstring | null

ID of the profile picture file.
nationalitystring | null

Nationality.
nationalitiesstring[] | null

Nationalities.
spokenLanguagesstring[] | null

Spoken languages.
dietaryPreferencestring | null

Dietary preference. One of: No preference, Pescetarian, Vegetarian, Vegan, Halal, Jain, Kosher, Diabetic.
foodAllergiesstring[]

A list of food allergies.
addressstring | null

Street address component of the person’s home address.
citystring | null

City component of the persons home address.
statestring | null

Optional state component of the persons home address.
postcodestring | null

Postcode component of the persons home address.
countryCodestring | null

Country code in in ISO 3166-2 format, e.g. GB for United Kingdom.
biostring | null

An optional description about the person.
linkedInstring | null

LinkedIn handle
twitterstring | null

Twitter handle
githubstring | null

GitHub handle
employmentStartDatedate

Employment start date.
firstWorkingDaydate

The first day at work. Defaults to employmentStartDate if not specified.
employmentEndDatedate | null

Employment end date. If this date is in the past, this employee is considered to be offboarded and inactive.
lastWorkingDaydate | null

The last day at work. Defaults to employmentEndDate if not specified.
probationEndDatedate | null

Probation end date.
workingDaysobject[] | null

A list of days worked by the employee.
workingDays.daystring

A day of the week. One of: monday, tuesday, wednesday, thursday, friday, saturday, sunday,
turnoverImpactstring | null

Turnover impact set for offboarded people. One of regrettable, non-regrettable or “not applicable”.
leavingReasonstring | null

Leaving reason set for offboarded people. One of dismissed, resigned, redundancy, contractEnded, other.
leavingNotestring | null

Leaving note set for offboarded people.
leavingFileIdstring | null

Leaving file id attached to offboarded people.
contractTypestring | null

The employment contract type. Commonly set to Full time, Part time, Contractor or Internship, but can be set to any value.
payrollProviderstring | null

The label or identifier of the payroll provider used to process payroll for this employee.
employeeIdstring | null

Employee ID as used by the company.
taxIdstring | null

The local tax ID frequently used for payroll purposes. For example, National Insurance Number in UK or Social Security Number in US.
taxCodestring | null

The local tax code / tax number frequently used for payroll purposes.
locationIdstring

The ID of the location this person works at. It can be either the ID of a location or the string literal remote, in which case it indicates this person works remotely and the working location can be found in the remoteCity, remoteRegionCode and remoteCountryCode fields.
remoteCitystring | null

When locationId is set to remote, this indicates the city that this person works in.
remoteCountryCodestring | null

When locationId is set to remote, this indicates the country that this person works in. Country code in in ISO 3166-2 format, e.g. GB for United Kingdom.
timeAwayApprovalFlowIdstring

The Id of the time away approval flow this person works under.
spaceIdstring

ID of the Space this person belongs to.
teamsobject[]

A list of teams. Often used for noting the cross functional team(s) the person is part of. Maximum of 12 items.
teams.namestring required

Name of the team
statusstring

One of active, offboarded or newHire.
isWorkEmailHiddenboolean

If true, work email of this person will be visible to admins and their managers.
calendarFeedTokenstring

The calendar feed access token used in Calendar Feed URL. Only available to requesting user’s account. Set to reset to reset the value of the token.
seenDocumentsAtdate-time

The last time the person has looked at their personal documents.
publicHolidayCalendarIdstring | null

The ID of the public holiday calendar this person uses, can be a country code, a country-region code or a regular id.

Returns

Returns the person if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/people/:id

curl https://app.humaans.io/api/people/VMB1yzL5uL8VvNNCJc9rykJz \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'

Response

{
  "id": "VMB1yzL5uL8VvNNCJc9rykJz",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "spaceId": "z9KCj9O97FC2QtHhlB02Njnx",
  "firstName": "Kelsey",
  "middleName": null,
  "lastName": "Wicks",
  "preferredName": null,
  "email": "kelsey@acme.com",
  "locationId": "FnAjNOIyLRsmZGRohZsHApiE",
  "remoteCity": null,
  "remoteRegionCode": null,
  "remoteCountryCode": null,
  "remoteTimezone": null,
  "personalEmail": "kwicks@example.com",
  "phoneNumber": "+4479460001",
  "formattedPhoneNumber": "+44 7946 0001",
  "personalPhoneNumber": null,
  "formattedPersonalPhoneNumber": null,
  "gender": "Female",
  "birthday": "1989-07-28",
  "profilePhotoId": "Hgi5auXaKsjn2MjuYo1PDk3W",
  "profilePhoto": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "nationality": "British",
  "nationalities": [
    "British"
  ],
  "spokenLanguages": [
    "English"
  ],
  "dietaryPreference": "Pescetarian",
  "foodAllergies": [
    "Peanuts"
  ],
  "address": "58 Stroude Road",
  "city": "Siddington",
  "state": null,
  "postcode": "SK11 1EN",
  "countryCode": "GB",
  "country": "United Kingdom",
  "bio": "All about that filter coffee.",
  "linkedIn": null,
  "twitter": null,
  "github": null,
  "employmentStartDate": "2018-03-10",
  "firstWorkingDay": "2018-03-10",
  "employmentEndDate": null,
  "lastWorkingDay": "2018-03-10",
  "probationEndDate": null,
  "turnoverImpact": null,
  "isManager": true,
  "workingDays": [
    {
      "day": "monday"
    },
    {
      "day": "tuesday"
    },
    {
      "day": "wednesday"
    },
    {
      "day": "thursday"
    },
    {
      "day": "friday"
    }
  ],
  "publicHolidayCalendarId": "ES-MD",
  "leavingReason": null,
  "leavingNote": null,
  "leavingFileId": null,
  "contractType": "Full time",
  "employeeId": null,
  "taxId": "QQ123456C",
  "taxCode": "123456C",
  "teams": [
    {
      "name": "Moonshot"
    },
    {
      "name": "Growth Pod"
    }
  ],
  "status": "active",
  "isVerified": true,
  "isWorkEmailHidden": false,
  "calendarFeedToken": "bb6LCUqG4BAOZWKXQQB9a8H9",
  "role": "user",
  "seenDocumentsAt": "2020-02-21T17:09:29.290Z",
  "source": null,
  "sourceId": null,
  "timezone": "Europe/London",
  "payrollProvider": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a person

Permanently deletes a person. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/people/:id

curl https://app.humaans.io/api/people/VMB1yzL5uL8VvNNCJc9rykJz \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "VMB1yzL5uL8VvNNCJc9rykJz",
  "deleted": true
}

Performance instances Preview

An object representing a specific person’s review packet in a performance cycle. Each instance tracks the release status and other details for an individual employee within a performance cycle.

Endpoints

GET /api/performance-cycle-instances

GET /api/performance-cycle-instances/:id

Required scopes

performance:read

Performance instance object

Attributes

idstring

Unique identifier for the object.
performanceCycleIdstring

The ID of the performance cycle this instance belongs to.
personIdstring

ID of the person that this object is associated to.
releasedAtdate-time

The time at which the performance cycle instance was released. Null if not yet released.
releasedBystring

The ID of the person who released the performance cycle instance.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.

performance instance object

{
  "id": "0I5qP2OqcopXEPRv3qz3LVXP",
  "performanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "releasedAt": "2026-03-01T12:00:00.000Z",
  "releasedBy": "T7uqPFK7am4lFTZm39AmNuBQ",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all performance instances

Returns a list of performance instances.

Parameters

performanceCycleIdstring · $eq $ne $in $nin

The ID of the performance cycle this instance belongs to.
performanceCycleStatusstring · $eq $ne $in $nin at most one of status or performanceCycleStatus

Filter by the status of the parent performance cycle. One of draft, upcoming, active, completed, cancelled.
personIdstring · $eq $ne $in $nin

The person to filter queries by.
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit performance instances. The response skips the first $skip results. Each entry is a separate performance instance object. If no performance instances are available, data is empty.

GET /api/performance-cycle-instances

curl https://app.humaans.io/api/performance-cycle-instances \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "0I5qP2OqcopXEPRv3qz3LVXP",
      "performanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "releasedAt": "2026-03-01T12:00:00.000Z",
      "releasedBy": "T7uqPFK7am4lFTZm39AmNuBQ",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a performance instance

Retrieves the performance instance with the given ID.

Parameters

No parameters

Returns

Returns a performance instance object if a valid identifier was provided.

GET /api/performance-cycle-instances/:id

curl https://app.humaans.io/api/performance-cycle-instances/0I5qP2OqcopXEPRv3qz3LVXP \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "0I5qP2OqcopXEPRv3qz3LVXP",
  "performanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "releasedAt": "2026-03-01T12:00:00.000Z",
  "releasedBy": "T7uqPFK7am4lFTZm39AmNuBQ",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Performance templates Preview

An object representing a review template within a performance cycle. Each template defines the form fields and configuration for a specific type of review.

Endpoints

GET /api/performance-cycle-review-templates

GET /api/performance-cycle-review-templates/:id

Required scopes

Performance template object

Attributes

idstring

Unique identifier for the object.
performanceCycleIdstring

The ID of the performance cycle this review template belongs to.
titlestring

The title of the review template.
templateTypestring

The type of review this template is for. One of peer, self, upward, manager.
fieldsobject[]

An array of form field objects that define the structure of the review. Each field has a type property determining its kind. One of text (short text input), longText (longer text input), textArea (rich text editor), select (single choice from a list), multiSelect (multiple choices from a list), rating (rating scale with predefined choices), scale (numeric scale with a range), heading (section heading), divider (visual separator). Each field has an id that uniquely identifies it within the template. These IDs are used as keys in the responses object of performance reviews. Input fields support label, hint, placeholder, required, and hideFromReviewee properties. A template may contain at most one rating field.
fields.idstring

Unique identifier for this field. Used as the key in the responses object of performance reviews.
fields.typestring
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.

performance template object

{
  "id": "PJIqTfdojEAWs8M4shG1x4eJ",
  "performanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
  "title": "Manager Review",
  "templateType": "manager",
  "fields": [
    {
      "id": "nB3xOmaAl0hx7FkGi2OBSqEp",
      "type": "heading",
      "content": "Performance Assessment"
    },
    {
      "id": "qR9yPzCdk2jv8WnHt5KDUfXm",
      "type": "longText",
      "label": "What are this person's key strengths?",
      "required": true,
      "hideFromReviewee": true
    },
    {
      "id": "xT4wLmNpR8kv2QjHs6YBUcAe",
      "type": "multiSelect",
      "label": "Which company values does this person demonstrate?",
      "choices": [
        "Ownership",
        "Collaboration",
        "Innovation",
        "Integrity"
      ],
      "required": false
    }
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all performance templates

Returns a list of performance templates.

Parameters

performanceCycleIdstring

The ID of the performance cycle this review template belongs to.
createdAtdate | date-time · $gt $gte $lt $lte

Filter performance cycle review templates by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter performance cycle review templates by updated at date.
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit performance templates. The response skips the first $skip results. Each entry is a separate performance template object. If no performance templates are available, data is empty.

GET /api/performance-cycle-review-templates

curl https://app.humaans.io/api/performance-cycle-review-templates \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "PJIqTfdojEAWs8M4shG1x4eJ",
      "performanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
      "title": "Manager Review",
      "templateType": "manager",
      "fields": [
        {
          "id": "nB3xOmaAl0hx7FkGi2OBSqEp",
          "type": "heading",
          "content": "Performance Assessment"
        },
        {
          "id": "qR9yPzCdk2jv8WnHt5KDUfXm",
          "type": "longText",
          "label": "What are this person's key strengths?",
          "required": true,
          "hideFromReviewee": true
        },
        {
          "id": "xT4wLmNpR8kv2QjHs6YBUcAe",
          "type": "multiSelect",
          "label": "Which company values does this person demonstrate?",
          "choices": [
            "Ownership",
            "Collaboration",
            "Innovation",
            "Integrity"
          ],
          "required": false
        }
      ],
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a performance template

Retrieves the performance template with the given ID.

Parameters

No parameters

Returns

Returns a performance template object if a valid identifier was provided.

GET /api/performance-cycle-review-templates/:id

curl https://app.humaans.io/api/performance-cycle-review-templates/PJIqTfdojEAWs8M4shG1x4eJ \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "PJIqTfdojEAWs8M4shG1x4eJ",
  "performanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
  "title": "Manager Review",
  "templateType": "manager",
  "fields": [
    {
      "id": "nB3xOmaAl0hx7FkGi2OBSqEp",
      "type": "heading",
      "content": "Performance Assessment"
    },
    {
      "id": "qR9yPzCdk2jv8WnHt5KDUfXm",
      "type": "longText",
      "label": "What are this person's key strengths?",
      "required": true,
      "hideFromReviewee": true
    },
    {
      "id": "xT4wLmNpR8kv2QjHs6YBUcAe",
      "type": "multiSelect",
      "label": "Which company values does this person demonstrate?",
      "choices": [
        "Ownership",
        "Collaboration",
        "Innovation",
        "Integrity"
      ],
      "required": false
    }
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Performance reviews Preview

An object representing a single review within a performance cycle. Each review captures a reviewer’s responses about a subject, the review type, and submission status.

Endpoints

GET /api/performance-cycle-reviews

GET /api/performance-cycle-reviews/:id

Required scopes

performance:read

Performance review object

Attributes

idstring

Unique identifier for the object.
performanceCycleInstanceIdstring

The ID of the performance cycle instance this review belongs to.
subjectIdstring

The ID of the person being reviewed.
reviewerIdstring

The ID of the person conducting the review.
reviewTypestring

The type of review. One of peer, self, upward, manager.
responsesobject

An object containing the responses to the review form fields, keyed by the field id from the corresponding performance template field.
submittedAtdate-time

The time at which this review was submitted. Null if not yet submitted or if changes have been requested.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.

performance review object

{
  "id": "aegY8UfWbpDonPFKhx6Z027o",
  "performanceCycleInstanceId": "IL19tIwMP2Hs7cpNHFOzNMeX",
  "subjectId": "wYW0B4dIbzyjm4FlJPv3cOS4",
  "reviewerId": "T7uqPFK7am4lFTZm39AmNuBQ",
  "reviewType": "manager",
  "responses": {
    "nB3xOmaAl0hx7FkGi2OBSqEp": "Great team player",
    "qR9yPzCdk2jv8WnHt5KDUfXm": {
      "value": 4,
      "furtherComments": "Consistently exceeds expectations"
    }
  },
  "submittedAt": "2026-03-15T10:30:00.000Z",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all performance reviews

Returns a list of performance reviews.

Parameters

performanceCycleInstanceIdstring · $eq $ne $in $nin

The ID of the performance cycle instance this review belongs to.
performanceCycleStatusstring · $eq $ne $in $nin

Filter by the status of the parent performance cycle. One of draft, upcoming, active, completed, cancelled.
subjectIdstring · $eq $ne $in $nin

The ID of the person being reviewed.
submittedAtdate-time · $ne

The time at which this review was submitted. Null if not yet submitted or if changes have been requested.
createdAtdate | date-time · $gt $gte $lt $lte

Filter performance cycle reviews by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter performance cycle reviews by updated at date.
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit performance reviews. The response skips the first $skip results. Each entry is a separate performance review object. If no performance reviews are available, data is empty.

GET /api/performance-cycle-reviews

curl https://app.humaans.io/api/performance-cycle-reviews \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "aegY8UfWbpDonPFKhx6Z027o",
      "performanceCycleInstanceId": "IL19tIwMP2Hs7cpNHFOzNMeX",
      "subjectId": "wYW0B4dIbzyjm4FlJPv3cOS4",
      "reviewerId": "T7uqPFK7am4lFTZm39AmNuBQ",
      "reviewType": "manager",
      "responses": {
        "nB3xOmaAl0hx7FkGi2OBSqEp": "Great team player",
        "qR9yPzCdk2jv8WnHt5KDUfXm": {
          "value": 4,
          "furtherComments": "Consistently exceeds expectations"
        }
      },
      "submittedAt": "2026-03-15T10:30:00.000Z",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a performance review

Retrieves the performance review with the given ID.

Parameters

No parameters

Returns

Returns a performance review object if a valid identifier was provided.

GET /api/performance-cycle-reviews/:id

curl https://app.humaans.io/api/performance-cycle-reviews/aegY8UfWbpDonPFKhx6Z027o \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "aegY8UfWbpDonPFKhx6Z027o",
  "performanceCycleInstanceId": "IL19tIwMP2Hs7cpNHFOzNMeX",
  "subjectId": "wYW0B4dIbzyjm4FlJPv3cOS4",
  "reviewerId": "T7uqPFK7am4lFTZm39AmNuBQ",
  "reviewType": "manager",
  "responses": {
    "nB3xOmaAl0hx7FkGi2OBSqEp": "Great team player",
    "qR9yPzCdk2jv8WnHt5KDUfXm": {
      "value": 4,
      "furtherComments": "Consistently exceeds expectations"
    }
  },
  "submittedAt": "2026-03-15T10:30:00.000Z",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Performance cycles Preview

An object representing a performance review cycle. Performance cycles define the schedule, scope, and configuration for running performance reviews across the company.

Endpoints

GET /api/performance-cycles

GET /api/performance-cycles/:id

Required scopes

performance:read

Performance cycle object

Attributes

idstring

Unique identifier for the object.
companyIdstring

ID of the company that this object is associated to.
titlestring

The title of the performance cycle.
statusstring

The current status of the performance cycle. One of draft, upcoming, active, completed, cancelled.
previousPerformanceCycleIdstring

ID of the previous performance cycle (if the cycle is on a recurring schedule).
completedAtdate-time

Time at which the performance cycle was completed.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

performance cycle object

{
  "id": "vxRe1WOEJP2KxKCBBaad9NFM",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "title": "Q1 2026 Performance Review",
  "status": "active",
  "previousPerformanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
  "completedAt": "2026-04-01T12:00:00.000Z",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all performance cycles

Returns a list of performance cycles.

Parameters

statusstring · $eq $ne $in $nin

The current status of the performance cycle. One of draft, upcoming, active, completed, cancelled.
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit performance cycles. The response skips the first $skip results. Each entry is a separate performance cycle object. If no performance cycles are available, data is empty.

GET /api/performance-cycles

curl https://app.humaans.io/api/performance-cycles \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "vxRe1WOEJP2KxKCBBaad9NFM",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "title": "Q1 2026 Performance Review",
      "status": "active",
      "previousPerformanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
      "completedAt": "2026-04-01T12:00:00.000Z",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a performance cycle

Retrieves the performance cycle with the given ID.

Parameters

No parameters

Returns

Returns a performance cycle object if a valid identifier was provided.

GET /api/performance-cycles/:id

curl https://app.humaans.io/api/performance-cycles/vxRe1WOEJP2KxKCBBaad9NFM \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "vxRe1WOEJP2KxKCBBaad9NFM",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "title": "Q1 2026 Performance Review",
  "status": "active",
  "previousPerformanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
  "completedAt": "2026-04-01T12:00:00.000Z",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Public holiday calendar days

A resource representing a public holiday for a particular public holiday calendar day

Endpoints

  GET /api/public-holiday-calendar-days

  GET /api/public-holiday-calendar-days/:id

 POST /api/public-holiday-calendar-days

PATCH /api/public-holiday-calendar-days/:id

Required scopes

public:read

Public holiday calendar day object

Attributes

idstring

Unique identifier for the object.
companyIdstring

ID of the company that this object is associated to.
publicHolidayCalendarIdstring

The ID of the public holiday calendar this public holiday is part of.
namestring

The name of the public holiday.
datedate

The date of the public holiday.
enabledboolean

The toggle state of the public holiday
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

Public holiday calendar day object

{
  "id": "MVvOIW2o1NLLtYga0REVbeeK",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Christmas Day",
  "date": "2022-12-25",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all Public holiday calendar days

List all public holiday calendar days

Parameters

date

The date of the public holiday.
enabled

The toggle state of the public holiday
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
publicHolidayCalendarIdstring · $eq $ne $in $nin

Filter by the public holiday calendar ID.
createdAtdate | date-time · $gt $gte $lt $lte

Filter public holiday calendar days by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit Public holiday calendar days. The response skips the first $skip results. Each entry is a separate Public holiday calendar day object. If no Public holiday calendar days are available, data is empty.

GET /api/public-holiday-calendar-days

curl https://app.humaans.io/api/public-holiday-calendar-days \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "MVvOIW2o1NLLtYga0REVbeeK",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "Christmas Day",
      "date": "2022-12-25",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a Public holiday calendar day

Get a specific public holiday calendar day

Parameters

No parameters

Returns

Returns a Public holiday calendar day object if a valid identifier was provided.

GET /api/public-holiday-calendar-days/:id

curl https://app.humaans.io/api/public-holiday-calendar-days/MVvOIW2o1NLLtYga0REVbeeK \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "MVvOIW2o1NLLtYga0REVbeeK",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Christmas Day",
  "date": "2022-12-25",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a Public holiday calendar day

Create a custom public holiday calendar day

Parameters

namestring required

The name of the public holiday.
datedate required

The date of the public holiday.
enabledboolean

The toggle state of the public holiday
publicHolidayCalendarIdstring required

The ID of the public holiday calendar this public holiday is part of.

Returns

Returns a Public holiday calendar day if the call succeeded. The call returns an error if parameters are invalid.

POST /api/public-holiday-calendar-days

curl https://app.humaans.io/api/public-holiday-calendar-days \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"Christmas Day","date":"2022-12-25"}'

Response

{
  "id": "MVvOIW2o1NLLtYga0REVbeeK",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Christmas Day",
  "date": "2022-12-25",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a Public holiday calendar day

Update a public holiday calendar day

Parameters

namestring

The name of the public holiday.
datedate

The date of the public holiday.
enabledboolean

The toggle state of the public holiday
publicHolidayCalendarIdstring

The ID of the public holiday calendar this public holiday is part of.

Returns

Returns the Public holiday calendar day if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/public-holiday-calendar-days/:id

curl https://app.humaans.io/api/public-holiday-calendar-days/MVvOIW2o1NLLtYga0REVbeeK \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'

Response

{
  "id": "MVvOIW2o1NLLtYga0REVbeeK",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Christmas Day",
  "date": "2022-12-25",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Public holiday calendars

A resource representing a public holiday calendar for a specific country or in some cases a region of a country.

Endpoints

GET /api/public-holiday-calendars

Required scopes

public:read

Public holiday calendar object

Attributes

idstring

Unique identifier for the object.
companyIdstring

ID of the company that this object is associated to.
namestring

The name of the calendar, combination of country and region.
countryCodestring

The country code.
countrystring

The country label.
regionCodestring

The region code.
regionstring

The country label.
dayCountnumber

The number of public holidays in this calendar in the current calendar year.
sourcePublicHolidayCalendarIdstring

The ID of the calendar used to initially populate this calendar
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

public holiday calendar object

{
  "id": "J2zFVTiH0fduJ0p5639GNRBh",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "France",
  "countryCode": "FR",
  "country": "France",
  "regionCode": null,
  "region": null,
  "dayCount": 11,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all public holiday calendars

Parameters

idstring · $eq $ne $in $nin

Filter by the public holiday calendar ID.
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
createdAtdate | date-time · $gt $gte $lt $lte

Filter public holiday calendars by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit public holiday calendars. The response skips the first $skip results. Each entry is a separate public holiday calendar object. If no public holiday calendars are available, data is empty.

GET /api/public-holiday-calendars

curl https://app.humaans.io/api/public-holiday-calendars \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "J2zFVTiH0fduJ0p5639GNRBh",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "France",
      "countryCode": "FR",
      "country": "France",
      "regionCode": null,
      "region": null,
      "dayCount": 11,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Public holidays

An object representing a public holiday.

Endpoints

GET /api/public-holidays

Required scopes

public:read

Public holiday object

Attributes

idstring

Unique identifier for the object.
datestring

The date of the public holiday.
namestring

The name of the public holiday.
publicHolidayCalendarIdstring

The ID of the public holiday calendar this public holiday belongs to.

public holiday object

{
  "id": "nk1kio8XMzUXY5eplJq7PrbI",
  "date": "2020-01-01",
  "name": "New year"
}

List all public holidays

Returns a list of public holidays.

Parameters

datedate · $eq $ne $in $nin $gt $lt $gte $lte required

Filter holidays by date.
publicHolidayCalendarIdstring · $eq $ne $in $nin required

Filter by the public holiday calendar ID.
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit public holidays. The response skips the first $skip results. Each entry is a separate public holiday object. If no public holidays are available, data is empty.

GET /api/public-holidays

curl 'https://app.humaans.io/api/public-holidays?publicHolidayCalendarId=DE-BE&date[$gte]=2020-01-01' \
  -g \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "nk1kio8XMzUXY5eplJq7PrbI",
      "date": "2020-01-01",
      "name": "New year"
    }
  ]
}

Spaces

An object representing a space. Every user belongs to a single space.

Endpoints

   GET /api/spaces

   GET /api/spaces/:id

  POST /api/spaces

 PATCH /api/spaces/:id

DELETE /api/spaces/:id

Required scopes

public:read

Space object

Attributes

idstring

Unique identifier for the object.
companyIdstring

ID of the company that this object is associated to.
namestring
isDefaultboolean
logoobject

When a logo file is uploaded, it gets resized to several predefined sizes and uploaded to a CDN. The URLs of those files are provided in this object. Note, that you can still access the original un-resized file via api/files.
logo.idstring

Unique identifier for the object.
logo.filenamestring
logo.variantsobject

A map of the predefined logo sizes. Some used in 2x displays, some used in 3x displays.
logo.variants.64string

URL of one of the predefined 2x logo sizes.
logo.variants.96string

URL of one of the predefined 3x logo sizes.
logo.variants.104string

URL of one of the predefined 2x logo sizes.
logo.variants.136string

URL of one of the predefined 2x logo sizes.
logo.variants.156string

URL of one of the predefined 3x logo sizes.
logo.variants.204string

URL of one of the predefined 3x logo sizes.
logo.variants.320string

URL of one of the predefined 2x logo sizes.
logo.variants.480string

URL of one of the predefined 3x logo sizes.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

space object

{
  "id": "kxXqtnaI6J6203RFuzrfdB7C",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Contractors",
  "logo": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all spaces

Returns a list of spaces.

Parameters

companyIdstring · $eq $ne $in $nin
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
createdAtdate | date-time · $gt $gte $lt $lte

Filter spaces by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit spaces. The response skips the first $skip results. Each entry is a separate space object. If no spaces are available, data is empty.

GET /api/spaces

curl https://app.humaans.io/api/spaces \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "kxXqtnaI6J6203RFuzrfdB7C",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "Contractors",
      "logo": {
        "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
        "filename": "image-file.jpg",
        "variants": {
          "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
          "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
          "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
          "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
          "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
          "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
          "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
          "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
        }
      },
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a space

Retrieves the space with the given ID.

Parameters

No parameters

Returns

Returns a space object if a valid identifier was provided.

GET /api/spaces/:id

curl https://app.humaans.io/api/spaces/kxXqtnaI6J6203RFuzrfdB7C \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "kxXqtnaI6J6203RFuzrfdB7C",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Contractors",
  "logo": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a space

Parameters

namestring required

Returns

Returns a space if the call succeeded. The call returns an error if parameters are invalid.

POST /api/spaces

curl https://app.humaans.io/api/spaces \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"Contractors"}'

Response

{
  "id": "kxXqtnaI6J6203RFuzrfdB7C",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Contractors",
  "logo": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a space

Parameters

namestring

Returns

Returns the space if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/spaces/:id

curl https://app.humaans.io/api/spaces/kxXqtnaI6J6203RFuzrfdB7C \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"name":"Contractors"}'

Response

{
  "id": "kxXqtnaI6J6203RFuzrfdB7C",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Contractors",
  "logo": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a space

Permanently deletes a space. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/spaces/:id

curl https://app.humaans.io/api/spaces/kxXqtnaI6J6203RFuzrfdB7C \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "kxXqtnaI6J6203RFuzrfdB7C",
  "deleted": true
}

Time away

An object representing a time away entry of an employee. Time away can be a time off entry, e.g. paid time off, sick leave, paternity leave, etc. Or it can be a working away entry, e.g. working from home, travelling for work, etc.

Endpoints

   GET /api/time-away

   GET /api/time-away/:id

  POST /api/time-away

 PATCH /api/time-away/:id

DELETE /api/time-away/:id

Required scopes

private:read

public:read

private:write

Time away object

Attributes

idstring

Unique identifier for the object.
personIdstring

ID of the person that this object is associated to.
startTimestring

If defined, specifies the start time for the time away booking in HH:MM:SS format. Applicable for same day bookings
endTimestring

If defined, specifies the end time for the time away booking in HH:MM:SS format. Applicable for same day bookings
startDatedate

The first date of the time away entry (inclusive).
startPeriodstring

Indicates if the first date of the time away entry was taken in full or as half day. One of: full (when taking full day), am (when taking morning off) or pm (when taking afternoon off). Defaults to full.
endDatedate

The last date of the time away entry (inclusive).
endPeriodstring

Indicates if the last date of the time away entry was taken in full or as half day. One of: full (when taking full day) or am (when taking morning off only). If startDate and endDate are the same, this should be the same as startPeriod. Defaults to full.
timeAwayTypeIdstring

ID of the Time away type this entry is attached to.
namestring

A human readable label of the time away entry type.
isTimeOffboolean

true if the type is one of the time off types, as opposed to one of the working away types.
workingFromLocationIdstring

When type (or reason) of the time away entry is workingFromAnotherLocation this field indicates the id of the location the person was working from.
notestring

An optional note about the time off entry. Only visible to the employee, their manager and admins.
breakdownobject[]

A day by day breakdown of the time away entry. Useful for inspecting which days count towards the balance.
breakdown.datedate

The date.
breakdown.periodstring | number

One of: full, am, pm.
breakdown.hoursnumber
breakdown.weekendboolean

True if the day is on a non-working day as defined by person.workingDays.
breakdown.holidayboolean

True if the day is a public holiday.
breakdown.fteDaynumber

Amount of day accounted for FTE.
daysnumber

The number of total days this entry spans, taking into account half days, weekends and holidays based on the policy configuration.
requestStatusstring

If time away approvals are required, one of pending, approved, declined. Will be approved if time away approvals are not required.
requestedBystring

The ID of the person that made this request.
reviewedBystring

The ID of the person that reviewed this request.
reviewedAtdate-time

The date and time when this request was reviewed.
reviewNotestring

A note to accompany a time away review.
publicHolidayCalendarIdstring

The public holiday calendar ID that was in use when creating this time away entry.
workingDaysobject[]

The person’s working days schedule at the time of booking time away
workingDays.daystring

A day of the week.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
timezonestring

The timezone of the personId when the booking was made

time away object

{
  "id": "YLlqHE4DLvGtFJ7L2qro6bTF",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startTime": "09:00:00",
  "endTime": "18:00:00",
  "startDate": "2020-01-24",
  "startPeriod": "full",
  "endDate": "2020-01-29",
  "endPeriod": "am",
  "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
  "name": "Paid time off",
  "isTimeOff": true,
  "workingFromLocationId": null,
  "note": "🏝 Trip to New Zealand",
  "breakdown": [
    {
      "date": "2020-01-24",
      "period": "full"
    },
    {
      "date": "2020-01-25",
      "period": "full",
      "weekend": true
    },
    {
      "date": "2020-01-26",
      "period": "full",
      "weekend": true,
      "holiday": true
    },
    {
      "date": "2020-01-27",
      "period": "full",
      "holiday": true
    },
    {
      "date": "2020-01-28",
      "period": "full"
    },
    {
      "date": "2020-01-29",
      "period": "am"
    }
  ],
  "days": 2.5,
  "requestStatus": "declined",
  "requestedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedAt": "2020-01-20",
  "reviewNote": "Dates clash with product launch.",
  "publicHolidayCalendarId": "AU-NSW",
  "workingDays": [
    {
      "day": "monday"
    },
    {
      "day": "tuesday"
    }
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "timezone": "America/Los_Angeles"
}

List all time away

Returns a list of time away entries.

The time away entries can be filtered using more complex filter conditions. Refer to Filtering documentation for more details on usage.

When syncing time away entries to another system, it can be useful to get all entries that were created or updated since a certain date. You can use the includeDeleted=true parameter to include deleted entries.

Include deleted entries, the shape of deleted items is { id, personId, deletedAt }:

GET /api/time-away?includeDeleted=true

Fetch only deleted entries:

GET /api/time-away?includeDeleted=true&deletedAt[$ne]=null

Fetch entries created or updated since the specified date:

GET /api/time-away?updatedAt[$gte]=2025-02-01

Parameters

endDatedate · $gt $gte $lt $lte

Filter by end date.
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
personIdstring · $in

The person to filter queries by.
personStatusstring · $in

The person status to filter queries by.
requestStatusstring · $in

Filter by request status. Useful when time away approvals are enabled.
startDatedate · $gt $gte $lt $lte

Filter by start date.
timeAwayTypeIdstring

Filter by the time away type
createdAtdate | date-time · $gt $gte $lt $lte

Filter by createdAt.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$orobject[]

Filter results by multiple criteria.
$or.createdAtdate | date-time · $gt $gte $lt $lte

Filter by createdAt.
$or.endDatedate · $gt $gte $lt $lte

Filter by end date.
$or.personIdstring · $in

The person to filter queries by.
$or.personStatusstring · $in

The person status to filter queries by.
$or.requestStatusstring · $in

Filter by request status. Useful when time away approvals are enabled.
$or.startDatedate · $gt $gte $lt $lte

Filter by start date.
$or.timeAwayTypeIdstring

Filter by the time away type
$or.typestring

Filter by time away type — one of the default type ids (workingFromAnotherLocation, workingFromHome, training, travellingForWork, pto, compassionate, emergency, juryDuty, mentalHealth, parental, sabbatical, sick, toil, unpaid, volunteering) or a company-specific time away type id. Unknown values match nothing.
$sortobject
$sort.createdAtnumber
$sort.deletedAtnumber
$sort.endDatenumber
$sort.startDatenumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit time away. The response skips the first $skip results. Each entry is a separate time away object. If no time away are available, data is empty.

GET /api/time-away

curl https://app.humaans.io/api/time-away \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "YLlqHE4DLvGtFJ7L2qro6bTF",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "startTime": "09:00:00",
      "endTime": "18:00:00",
      "startDate": "2020-01-24",
      "startPeriod": "full",
      "endDate": "2020-01-29",
      "endPeriod": "am",
      "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
      "name": "Paid time off",
      "isTimeOff": true,
      "workingFromLocationId": null,
      "note": "🏝 Trip to New Zealand",
      "breakdown": [
        {
          "date": "2020-01-24",
          "period": "full"
        },
        {
          "date": "2020-01-25",
          "period": "full",
          "weekend": true
        },
        {
          "date": "2020-01-26",
          "period": "full",
          "weekend": true,
          "holiday": true
        },
        {
          "date": "2020-01-27",
          "period": "full",
          "holiday": true
        },
        {
          "date": "2020-01-28",
          "period": "full"
        },
        {
          "date": "2020-01-29",
          "period": "am"
        }
      ],
      "days": 2.5,
      "requestStatus": "declined",
      "requestedBy": "ob4xPcVpGGZm043C7xGMfP1U",
      "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
      "reviewedAt": "2020-01-20",
      "reviewNote": "Dates clash with product launch.",
      "publicHolidayCalendarId": "AU-NSW",
      "workingDays": [
        {
          "day": "monday"
        },
        {
          "day": "tuesday"
        }
      ],
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z",
      "timezone": "America/Los_Angeles"
    }
  ]
}

Retrieve a time away

Retrieves the time away with the given ID.

Parameters

No parameters

Returns

Returns a time away object if a valid identifier was provided.

GET /api/time-away/:id

curl https://app.humaans.io/api/time-away/YLlqHE4DLvGtFJ7L2qro6bTF \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "YLlqHE4DLvGtFJ7L2qro6bTF",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startTime": "09:00:00",
  "endTime": "18:00:00",
  "startDate": "2020-01-24",
  "startPeriod": "full",
  "endDate": "2020-01-29",
  "endPeriod": "am",
  "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
  "name": "Paid time off",
  "isTimeOff": true,
  "workingFromLocationId": null,
  "note": "🏝 Trip to New Zealand",
  "breakdown": [
    {
      "date": "2020-01-24",
      "period": "full"
    },
    {
      "date": "2020-01-25",
      "period": "full",
      "weekend": true
    },
    {
      "date": "2020-01-26",
      "period": "full",
      "weekend": true,
      "holiday": true
    },
    {
      "date": "2020-01-27",
      "period": "full",
      "holiday": true
    },
    {
      "date": "2020-01-28",
      "period": "full"
    },
    {
      "date": "2020-01-29",
      "period": "am"
    }
  ],
  "days": 2.5,
  "requestStatus": "declined",
  "requestedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedAt": "2020-01-20",
  "reviewNote": "Dates clash with product launch.",
  "publicHolidayCalendarId": "AU-NSW",
  "workingDays": [
    {
      "day": "monday"
    },
    {
      "day": "tuesday"
    }
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "timezone": "America/Los_Angeles"
}

Create a time away

Parameters

personIdstring required

ID of the person that this object is associated to.
startTimestring | null at most one of startTime or startPeriod

If defined, specifies the start time for the time away booking in HH:MM:SS format. Applicable for same day bookings
endTimestring | null at most one of endTime or startPeriod

If defined, specifies the end time for the time away booking in HH:MM:SS format. Applicable for same day bookings
startDatedate required

The first date of the time away entry (inclusive).
endDatedate required

The last date of the time away entry (inclusive).
startPeriodstring | null at most one of startPeriod or breakdown

Indicates if the first date of the time away entry was taken in full or as half day. One of: full (when taking full day), am (when taking morning off) or pm (when taking afternoon off). Defaults to full.
endPeriodstring | null at most one of startTime or endPeriod

Indicates if the last date of the time away entry was taken in full or as half day. One of: full (when taking full day) or am (when taking morning off only). If startDate and endDate are the same, this should be the same as startPeriod. Defaults to full.
notestring | null

An optional note about the time off entry. Only visible to the employee, their manager and admins.
workingFromLocationIdstring | null

When type (or reason) of the time away entry is workingFromAnotherLocation this field indicates the id of the location the person was working from.
timeAwayTypeIdstring at most one of type or timeAwayTypeId

ID of the Time away type this entry is attached to.
requestStatusstring

If time away approvals are required, one of pending, approved, declined. Will be approved if time away approvals are not required.
reviewNotestring

A note to accompany a time away review.

Returns

Returns a time away if the call succeeded. The call returns an error if parameters are invalid.

POST /api/time-away

curl https://app.humaans.io/api/time-away \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"note":"✈️ Trip to New Zealand"}'

Response

{
  "id": "YLlqHE4DLvGtFJ7L2qro6bTF",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startTime": "09:00:00",
  "endTime": "18:00:00",
  "startDate": "2020-01-24",
  "startPeriod": "full",
  "endDate": "2020-01-29",
  "endPeriod": "am",
  "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
  "name": "Paid time off",
  "isTimeOff": true,
  "workingFromLocationId": null,
  "note": "✈️ Trip to New Zealand",
  "breakdown": [
    {
      "date": "2020-01-24",
      "period": "full"
    },
    {
      "date": "2020-01-25",
      "period": "full",
      "weekend": true
    },
    {
      "date": "2020-01-26",
      "period": "full",
      "weekend": true,
      "holiday": true
    },
    {
      "date": "2020-01-27",
      "period": "full",
      "holiday": true
    },
    {
      "date": "2020-01-28",
      "period": "full"
    },
    {
      "date": "2020-01-29",
      "period": "am"
    }
  ],
  "days": 2.5,
  "requestStatus": "declined",
  "requestedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedAt": "2020-01-20",
  "reviewNote": "Dates clash with product launch.",
  "publicHolidayCalendarId": "AU-NSW",
  "workingDays": [
    {
      "day": "monday"
    },
    {
      "day": "tuesday"
    }
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "timezone": "America/Los_Angeles"
}

Update a time away

Parameters

startTimestring | null at most one of startTime or startPeriod

If defined, specifies the start time for the time away booking in HH:MM:SS format. Applicable for same day bookings
endTimestring | null at most one of endTime or startPeriod

If defined, specifies the end time for the time away booking in HH:MM:SS format. Applicable for same day bookings
startDatedate

The first date of the time away entry (inclusive).
endDatedate

The last date of the time away entry (inclusive).
startPeriodstring | null at most one of startPeriod or breakdown

Indicates if the first date of the time away entry was taken in full or as half day. One of: full (when taking full day), am (when taking morning off) or pm (when taking afternoon off). Defaults to full.
endPeriodstring | null at most one of startTime or endPeriod

Indicates if the last date of the time away entry was taken in full or as half day. One of: full (when taking full day) or am (when taking morning off only). If startDate and endDate are the same, this should be the same as startPeriod. Defaults to full.
notestring | null

An optional note about the time off entry. Only visible to the employee, their manager and admins.
workingFromLocationIdstring | null

When type (or reason) of the time away entry is workingFromAnotherLocation this field indicates the id of the location the person was working from.
timeAwayTypeIdstring at most one of type or timeAwayTypeId

ID of the Time away type this entry is attached to.
requestStatusstring

If time away approvals are required, one of pending, approved, declined. Will be approved if time away approvals are not required.
reviewNotestring

A note to accompany a time away review.

Returns

Returns the time away if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/time-away/:id

curl https://app.humaans.io/api/time-away/YLlqHE4DLvGtFJ7L2qro6bTF \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"note":"✈️ Trip to New Zealand"}'

Response

{
  "id": "YLlqHE4DLvGtFJ7L2qro6bTF",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startTime": "09:00:00",
  "endTime": "18:00:00",
  "startDate": "2020-01-24",
  "startPeriod": "full",
  "endDate": "2020-01-29",
  "endPeriod": "am",
  "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
  "name": "Paid time off",
  "isTimeOff": true,
  "workingFromLocationId": null,
  "note": "✈️ Trip to New Zealand",
  "breakdown": [
    {
      "date": "2020-01-24",
      "period": "full"
    },
    {
      "date": "2020-01-25",
      "period": "full",
      "weekend": true
    },
    {
      "date": "2020-01-26",
      "period": "full",
      "weekend": true,
      "holiday": true
    },
    {
      "date": "2020-01-27",
      "period": "full",
      "holiday": true
    },
    {
      "date": "2020-01-28",
      "period": "full"
    },
    {
      "date": "2020-01-29",
      "period": "am"
    }
  ],
  "days": 2.5,
  "requestStatus": "declined",
  "requestedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedAt": "2020-01-20",
  "reviewNote": "Dates clash with product launch.",
  "publicHolidayCalendarId": "AU-NSW",
  "workingDays": [
    {
      "day": "monday"
    },
    {
      "day": "tuesday"
    }
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "timezone": "America/Los_Angeles"
}

Delete a time away

Permanently deletes a time away. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/time-away/:id

curl https://app.humaans.io/api/time-away/YLlqHE4DLvGtFJ7L2qro6bTF \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "YLlqHE4DLvGtFJ7L2qro6bTF",
  "deleted": true
}

Time away adjustments

An object representing a time away adjustment. Adjustments are used to add or remove days to the available time off balance. They are one off and are applied in the time away period they fall in based on the date.

Endpoints

   GET /api/time-away-adjustments

   GET /api/time-away-adjustments/:id

  POST /api/time-away-adjustments

 PATCH /api/time-away-adjustments/:id

DELETE /api/time-away-adjustments/:id

Required scopes

private:read

private:write

Time away adjustment object

Attributes

idstring

Unique identifier for the object.
personIdstring

ID of the person that this object is associated to.
datedate

The date when the adjustment was granted.
deltaAmountnumber

The time that should be added to the allowance. Negative number will reduce the allowance.
unitstring

The unit of the time away adjustment. Negative number will reduce the allowance.
reasonstring

A note describing the reason for this adjustment.
validUntildate

The date when the adjustment expires.
timeAwayTypeIdstring

ID of the Time away type this adjustment is attached to.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

time away adjustment object

{
  "id": "BZJa63JpH4Bz25oM28zAbeoK",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "date": "2020-03-01",
  "deltaAmount": 2,
  "unit": "days",
  "reason": "For working over the weekend.",
  "validUntil": "2029-03-01",
  "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all time away adjustments

Returns a list of time away adjustments.

Parameters

datedate · $eq $ne $in $nin $gt $lt $gte $lte

Filter by end date.
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
personIdstring · $in

The person to filter queries by.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$sortobject
$sort.createdAtnumber
$sort.datenumber
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit time away adjustments. The response skips the first $skip results. Each entry is a separate time away adjustment object. If no time away adjustments are available, data is empty.

GET /api/time-away-adjustments

curl https://app.humaans.io/api/time-away-adjustments \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "BZJa63JpH4Bz25oM28zAbeoK",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "date": "2020-03-01",
      "deltaAmount": 2,
      "unit": "days",
      "reason": "For working over the weekend.",
      "validUntil": "2029-03-01",
      "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a time away adjustment

Retrieves the time away adjustment with the given ID.

Parameters

No parameters

Returns

Returns a time away adjustment object if a valid identifier was provided.

GET /api/time-away-adjustments/:id

curl https://app.humaans.io/api/time-away-adjustments/BZJa63JpH4Bz25oM28zAbeoK \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "BZJa63JpH4Bz25oM28zAbeoK",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "date": "2020-03-01",
  "deltaAmount": 2,
  "unit": "days",
  "reason": "For working over the weekend.",
  "validUntil": "2029-03-01",
  "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a time away adjustment

Parameters

personIdstring required

ID of the person that this object is associated to.
datedate required

The date when the adjustment was granted.
deltaAmountnumber

The time that should be added to the allowance. Negative number will reduce the allowance.
unitstring

The unit of the time away adjustment. Negative number will reduce the allowance.
reasonstring required

A note describing the reason for this adjustment.
validUntildate | null

The date when the adjustment expires.
timeAwayTypeIdstring required

ID of the Time away type this adjustment is attached to.

Returns

Returns a time away adjustment if the call succeeded. The call returns an error if parameters are invalid.

POST /api/time-away-adjustments

curl https://app.humaans.io/api/time-away-adjustments \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","date":"2020-03-01","reason":"For working over the weekend.","timeAwayTypeId":"7xGMobpxPcVfP1UGGZm043C4"}'

Response

{
  "id": "BZJa63JpH4Bz25oM28zAbeoK",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "date": "2020-03-01",
  "deltaAmount": 2,
  "unit": "days",
  "reason": "For working over the weekend.",
  "validUntil": "2029-03-01",
  "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a time away adjustment

Parameters

datedate

The date when the adjustment was granted.
deltaAmountnumber

The time that should be added to the allowance. Negative number will reduce the allowance.
unitstring

The unit of the time away adjustment. Negative number will reduce the allowance.
reasonstring

A note describing the reason for this adjustment.
validUntildate | null

The date when the adjustment expires.
timeAwayTypeIdstring

ID of the Time away type this adjustment is attached to.

Returns

Returns the time away adjustment if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/time-away-adjustments/:id

curl https://app.humaans.io/api/time-away-adjustments/BZJa63JpH4Bz25oM28zAbeoK \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'

Response

{
  "id": "BZJa63JpH4Bz25oM28zAbeoK",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "date": "2020-03-01",
  "deltaAmount": 2,
  "unit": "days",
  "reason": "For working over the weekend.",
  "validUntil": "2029-03-01",
  "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a time away adjustment

Permanently deletes a time away adjustment. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/time-away-adjustments/:id

curl https://app.humaans.io/api/time-away-adjustments/BZJa63JpH4Bz25oM28zAbeoK \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "BZJa63JpH4Bz25oM28zAbeoK",
  "deleted": true
}

Time away allocations

An object representing the mapping between an employee and a time away policy.

To assign a specific time away policy to an employee an allocation with an effectiveDate is created and linked to a person (personId) and a time away policy (timeAwayPolicyId). Each person will often have only one allocation throughout their lifetime, but they can have multiple consecutive allocations when the company changes its time off policy or when the employee moves to a country, office or role with a different time off policy.

Endpoints

   GET /api/time-away-allocations

   GET /api/time-away-allocations/:id

  POST /api/time-away-allocations

 PATCH /api/time-away-allocations/:id

DELETE /api/time-away-allocations/:id

Required scopes

private:read

private:write

Time away allocation object

Attributes

idstring

Unique identifier for the object.
personIdstring

ID of the person that this object is associated to.
typestring

The type of allocation. One of: placeOfWork, specific, custom. Setting allocation type to placeOfWork will apply the time away policy based on the place of work of the employee. Setting it to specific requires providing the timeAwayPolicyId that should be applied. Setting to custom requires passing policy object in the timeAwayPolicy field.
effectiveDatedate

The first day when the allocation is in effect.
timeAwayPolicyIdstring

The ID of the time away policy used by this allocation.
timeAwayPolicytime away policy

The time away policy used by this allocation. When the type of the allocation is custom, these attributes are writable and can be used to create custom inline per person policies. In case the type is placeOfWork or specific - only the timeAwayPolicyId is writable and must be used to assign an existing time away policy.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.

time away allocation object

{
  "id": "MfQQ2fWdXGD3hvZKrxm6zWE0",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "placeOfWork",
  "effectiveDate": "2020-04-01",
  "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I",
  "timeAwayPolicy": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "companyId": "T7uqPFK7am4lFTZm39AmNuay",
    "name": "UK Policy",
    "timeAwayPolicyVersion": {
      "id": "smIkoZZ0t4KlXbEka2UC9m7I",
      "bypassWorkingSchedule": false,
      "bypassPublicHolidays": false,
      "publicHolidayCalendarId": "GB",
      "visibleBalances": [
        "endOfYear"
      ],
      "rules": [
        {
          "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
          "limits": {
            "yearlyAllowance": 30,
            "maxCarryOver": 5,
            "yearStart": "01-01",
            "yearStartType": "employmentStartDate",
            "isUnlimited": false,
            "isProrated": false,
            "maxBalance": 30,
            "preventNegativeBalance": false,
            "maxNegativeBalance": 5,
            "usage": "upfront",
            "usagePeriod": 12,
            "carryOverUsagePeriod": 3,
            "roundingType": "halfUp"
          }
        }
      ]
    },
    "createdAt": "2020-01-28T08:44:42.000Z",
    "updatedAt": "2020-01-29T14:52:21.000Z"
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all time away allocations

Returns a list of time away allocations.

Parameters

includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
isCurrentboolean

Return the current allocation only.
personIdstring

The person to filter queries by.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit time away allocations. The response skips the first $skip results. Each entry is a separate time away allocation object. If no time away allocations are available, data is empty.

GET /api/time-away-allocations

curl https://app.humaans.io/api/time-away-allocations \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "MfQQ2fWdXGD3hvZKrxm6zWE0",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "type": "placeOfWork",
      "effectiveDate": "2020-04-01",
      "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I",
      "timeAwayPolicy": {
        "id": "smIkoZZ0t4KlXbEka2UC9m7I",
        "companyId": "T7uqPFK7am4lFTZm39AmNuay",
        "name": "UK Policy",
        "timeAwayPolicyVersion": {
          "id": "smIkoZZ0t4KlXbEka2UC9m7I",
          "bypassWorkingSchedule": false,
          "bypassPublicHolidays": false,
          "publicHolidayCalendarId": "GB",
          "visibleBalances": [
            "endOfYear"
          ],
          "rules": [
            {
              "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
              "limits": {
                "yearlyAllowance": 30,
                "maxCarryOver": 5,
                "yearStart": "01-01",
                "yearStartType": "employmentStartDate",
                "isUnlimited": false,
                "isProrated": false,
                "maxBalance": 30,
                "preventNegativeBalance": false,
                "maxNegativeBalance": 5,
                "usage": "upfront",
                "usagePeriod": 12,
                "carryOverUsagePeriod": 3,
                "roundingType": "halfUp"
              }
            }
          ]
        },
        "createdAt": "2020-01-28T08:44:42.000Z",
        "updatedAt": "2020-01-29T14:52:21.000Z"
      },
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a time away allocation

Retrieves the time away allocation with the given ID.

Parameters

No parameters

Returns

Returns a time away allocation object if a valid identifier was provided.

GET /api/time-away-allocations/:id

curl https://app.humaans.io/api/time-away-allocations/MfQQ2fWdXGD3hvZKrxm6zWE0 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "MfQQ2fWdXGD3hvZKrxm6zWE0",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "placeOfWork",
  "effectiveDate": "2020-04-01",
  "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I",
  "timeAwayPolicy": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "companyId": "T7uqPFK7am4lFTZm39AmNuay",
    "name": "UK Policy",
    "timeAwayPolicyVersion": {
      "id": "smIkoZZ0t4KlXbEka2UC9m7I",
      "bypassWorkingSchedule": false,
      "bypassPublicHolidays": false,
      "publicHolidayCalendarId": "GB",
      "visibleBalances": [
        "endOfYear"
      ],
      "rules": [
        {
          "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
          "limits": {
            "yearlyAllowance": 30,
            "maxCarryOver": 5,
            "yearStart": "01-01",
            "yearStartType": "employmentStartDate",
            "isUnlimited": false,
            "isProrated": false,
            "maxBalance": 30,
            "preventNegativeBalance": false,
            "maxNegativeBalance": 5,
            "usage": "upfront",
            "usagePeriod": 12,
            "carryOverUsagePeriod": 3,
            "roundingType": "halfUp"
          }
        }
      ]
    },
    "createdAt": "2020-01-28T08:44:42.000Z",
    "updatedAt": "2020-01-29T14:52:21.000Z"
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a time away allocation

Parameters

personIdstring required

ID of the person that this object is associated to.
typestring required

The type of allocation. One of: placeOfWork, specific, custom. Setting allocation type to placeOfWork will apply the time away policy based on the place of work of the employee. Setting it to specific requires providing the timeAwayPolicyId that should be applied. Setting to custom requires passing policy object in the timeAwayPolicy field.
effectiveDatedate | null required

The first day when the allocation is in effect.
timeAwayPolicyIdstring

The ID of the time away policy used by this allocation.
timeAwayPolicytime away policy

The time away policy used by this allocation. When the type of the allocation is custom, these attributes are writable and can be used to create custom inline per person policies. In case the type is placeOfWork or specific - only the timeAwayPolicyId is writable and must be used to assign an existing time away policy.
replaceInitialAllocationboolean

Must be true to change the initial (“from employment start”) allocation’s policy. That allocation has no effective date and applies across the person’s whole employment history, so replacing its policy rewrites all past leave.
removeAllocationsboolean

Returns

Returns a time away allocation if the call succeeded. The call returns an error if parameters are invalid.

POST /api/time-away-allocations

curl https://app.humaans.io/api/time-away-allocations \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"effectiveDate":"2020-04-30"}'

Response

{
  "id": "MfQQ2fWdXGD3hvZKrxm6zWE0",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "placeOfWork",
  "effectiveDate": "2020-04-30",
  "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I",
  "timeAwayPolicy": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "companyId": "T7uqPFK7am4lFTZm39AmNuay",
    "name": "UK Policy",
    "timeAwayPolicyVersion": {
      "id": "smIkoZZ0t4KlXbEka2UC9m7I",
      "bypassWorkingSchedule": false,
      "bypassPublicHolidays": false,
      "publicHolidayCalendarId": "GB",
      "visibleBalances": [
        "endOfYear"
      ],
      "rules": [
        {
          "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
          "limits": {
            "yearlyAllowance": 30,
            "maxCarryOver": 5,
            "yearStart": "01-01",
            "yearStartType": "employmentStartDate",
            "isUnlimited": false,
            "isProrated": false,
            "maxBalance": 30,
            "preventNegativeBalance": false,
            "maxNegativeBalance": 5,
            "usage": "upfront",
            "usagePeriod": 12,
            "carryOverUsagePeriod": 3,
            "roundingType": "halfUp"
          }
        }
      ]
    },
    "createdAt": "2020-01-28T08:44:42.000Z",
    "updatedAt": "2020-01-29T14:52:21.000Z"
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a time away allocation

Parameters

typestring

The type of allocation. One of: placeOfWork, specific, custom. Setting allocation type to placeOfWork will apply the time away policy based on the place of work of the employee. Setting it to specific requires providing the timeAwayPolicyId that should be applied. Setting to custom requires passing policy object in the timeAwayPolicy field.
effectiveDatedate | null

The first day when the allocation is in effect.
timeAwayPolicyIdstring

The ID of the time away policy used by this allocation.
timeAwayPolicytime away policy

The time away policy used by this allocation. When the type of the allocation is custom, these attributes are writable and can be used to create custom inline per person policies. In case the type is placeOfWork or specific - only the timeAwayPolicyId is writable and must be used to assign an existing time away policy.
replaceInitialAllocationboolean

Must be true to change the initial (“from employment start”) allocation’s policy. That allocation has no effective date and applies across the person’s whole employment history, so replacing its policy rewrites all past leave.

Returns

Returns the time away allocation if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/time-away-allocations/:id

curl https://app.humaans.io/api/time-away-allocations/MfQQ2fWdXGD3hvZKrxm6zWE0 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"effectiveDate":"2020-04-30"}'

Response

{
  "id": "MfQQ2fWdXGD3hvZKrxm6zWE0",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "placeOfWork",
  "effectiveDate": "2020-04-30",
  "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I",
  "timeAwayPolicy": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "companyId": "T7uqPFK7am4lFTZm39AmNuay",
    "name": "UK Policy",
    "timeAwayPolicyVersion": {
      "id": "smIkoZZ0t4KlXbEka2UC9m7I",
      "bypassWorkingSchedule": false,
      "bypassPublicHolidays": false,
      "publicHolidayCalendarId": "GB",
      "visibleBalances": [
        "endOfYear"
      ],
      "rules": [
        {
          "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
          "limits": {
            "yearlyAllowance": 30,
            "maxCarryOver": 5,
            "yearStart": "01-01",
            "yearStartType": "employmentStartDate",
            "isUnlimited": false,
            "isProrated": false,
            "maxBalance": 30,
            "preventNegativeBalance": false,
            "maxNegativeBalance": 5,
            "usage": "upfront",
            "usagePeriod": 12,
            "carryOverUsagePeriod": 3,
            "roundingType": "halfUp"
          }
        }
      ]
    },
    "createdAt": "2020-01-28T08:44:42.000Z",
    "updatedAt": "2020-01-29T14:52:21.000Z"
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a time away allocation

Permanently deletes a time away allocation. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/time-away-allocations/:id

curl https://app.humaans.io/api/time-away-allocations/MfQQ2fWdXGD3hvZKrxm6zWE0 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "MfQQ2fWdXGD3hvZKrxm6zWE0",
  "deleted": true
}

Time away periods

Time away periods is used to find employee’s time off allowance, remaining balance and many other useful attributes. Time away is sliced into periods and each period contains a summary.

Typically a period year long starting on 1st of January and ending on 31st of December. But it can also start and end mid year in case it is the first period and the employee started working mid year, if the time away allocation was changed mid year, or if the employee is offboarded. For example, consider an employee that started employment on 2018-08-01 and left on 2020-03-15. Such an employee would have 3 periods:

2018-08-01 - 2018-12-31
2019-01-01 - 2019-12-31
2020-01-01 - 2020-03-15

Each of these periods will contain allowance, accrued days, balance, adjustments, days taken and so on.

The last period for active employees has the isCurrentPeriod attribute set to true and can be used to find the current status of the employee’s time away.

Note, that a policy can be configured to have a different year start than January 1st, in which case each period under that policy would start on the day configured in the policy.

Endpoints

GET /api/time-away-periods

Required scopes

private:read

Time away period object

Attributes

idstring

Unique identifier for the object.
personIdstring

ID of the person that this object is associated to.
startDatedate

The start of the PTO accrual and usage periods. This can be either the start of a new year, the start of employment, or the date when a new policy was assigned. Note: the start of the year depends on the policy configuration.
endDatedate

The end of the PTO accrual period. This can be either the end of the year, the end of employment, or the day before a new policy was assigned. Note: the end of the year depends on the policy configuration.
usageEndDatedate

The end of the PTO usage period. This can be either the end of the year, the end of employment, or the day before a new policy was assigned. Note: the end of the year will be ptoUsagePeriod months from the yearStart.
timeAwayAllocationtime away allocation

The time away allocation used in this period.
timeAwayTypeIdstring

The id of the type this period data refers to
isCurrentPeriodboolean

true means this is the accrual period that the employee is currently in. Current periods are useful for finding the current accrual or balance of an employee.
isFinalPeriodboolean

true means this is the final period, which holds the final balance of an offboarded employee.
hasAllocationChangedboolean

true means that this period has a new time away allocation and policy compared to the previous period.
isCarriedOverInFullboolean

true means the remaining balance of the previous period has been carried over in full to the current period. This is done when allocation is changed mid year.
isProratedboolean

true means the allowance is prorated, because the period is partial. This happens for new employees that start accruing time off allowance mid year or when the policy is changed mid year.
accruednumber

Currently accrued allowance. The accrued balance as of today (or as of the endDate of the period for past periods). For the current period this indicates the accrued allowance as of today.
allowancenumber

End of year allowance. The accrued balance as of the endDate of the period. For the current period this indicates what the person is allowed to take in total by the end of the year.
fromPrevAccrualPeriodinteger

The number of days available from the prev accrual period that are still available to be used.
fromPrevAccrualPeriodValidUntilDatedate

The date at which fromPrevAccrualPeriod is valid until.
fromPrevAccrualPeriodExpiredinteger

The number of days from fromPrevAccrualPeriod that has expired in this period.
carriedOvernumber

The number of days that have been carried over from the previous period. Calculated based on the allocation assigned to this period.
carriedOverDatedate

The date at which carriedOver is applied.
carriedOverExpirednumber

The amount of carried-over balance that expired unused because it was not used within the carry-over usage period. 0 when the carry-over usage window has not closed yet or no window applies.
carryOverUsageEndDatedate

The date the carried-over balance stops being usable, derived from the policy’s carry-over usage period. Null when no carry-over usage window applies.
adjustmentsnumber

The sum of all adjustments (negative and positive) made in this period excluding upcoming adjustments in the case of the current period.
adjustmentsUpcomingnumber

The sum of all upcoming adjustments (negative and positive) made in this period. Always 0 if this is not the current period.
usednumber

The number of approved days already used up in this period, excluding upcoming days off.
pendingnumber

The number of pending days already used up in this period, excluding upcoming days off.
upcomingnumber

The number of approved days upcoming in this period. Always 0 if this is not the current period.
upcomingPendingnumber

The number of pending days upcoming in this period. Always 0 if this is not the current period.
balancenumber

Current balance. The remaining balance as of today (or as of the endDate of the period for past periods) excluding pending and upcoming time off entries.
endingBalancenumber

End of year balance. The remaining balance as of the endDate of the period.

time away period object

{
  "id": "X4XT4ZLOwT9GYbPyl90HztBu",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startDate": "2020-09-01",
  "endDate": "2021-08-31",
  "usageEndDate": "2021-12-31",
  "timeAwayAllocation": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "personId": "IL3vneCYhIx0xrR6um2sy2nW",
    "type": "placeOfWork",
    "effectiveDate": "2020-04-01",
    "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I",
    "timeAwayPolicy": {
      "id": "smIkoZZ0t4KlXbEka2UC9m7I",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "UK Policy",
      "timeAwayPolicyVersion": {
        "id": "smIkoZZ0t4KlXbEka2UC9m7I",
        "bypassWorkingSchedule": false,
        "bypassPublicHolidays": false,
        "publicHolidayCalendarId": "GB",
        "visibleBalances": [
          "endOfYear"
        ],
        "rules": [
          {
            "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
            "limits": {
              "yearlyAllowance": 30,
              "maxCarryOver": 5,
              "yearStart": "01-01",
              "yearStartType": "employmentStartDate",
              "isUnlimited": false,
              "isProrated": false,
              "maxBalance": 30,
              "preventNegativeBalance": false,
              "maxNegativeBalance": 5,
              "usage": "upfront",
              "usagePeriod": 12,
              "carryOverUsagePeriod": 3,
              "roundingType": "halfUp"
            }
          }
        ]
      },
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    },
    "createdAt": "2020-01-28T08:44:42.000Z",
    "updatedAt": "2020-01-29T14:52:21.000Z"
  },
  "timeAwayTypeId": "0defdigw4ayfQ0EP22HjZGiD",
  "isCurrentPeriod": true,
  "isFinalPeriod": false,
  "hasAllocationChanged": false,
  "isCarriedOverInFull": false,
  "isProrated": true,
  "accrued": 8.09,
  "allowance": 20,
  "fromPrevAccrualPeriod": 2,
  "fromPrevAccrualPeriodValidUntilDate": "2021-12-31",
  "fromPrevAccrualPeriodExpired": 2,
  "carriedOver": -0.17,
  "carriedOverDate": "2020-12-31",
  "carriedOverExpired": 0,
  "carryOverUsageEndDate": "2021-03-31",
  "adjustments": 0,
  "adjustmentsUpcoming": 0,
  "used": 2,
  "pending": 2,
  "upcoming": 0,
  "upcomingPending": 0,
  "balance": 5.92,
  "endingBalance": 17.83
}

List all time away periods

Returns a list of time away periods.

Parameters

datedate

If provided, the balances and accruals of the current period will be calculated based on this date. Defaults to today if not provided.
isCurrentPeriodboolean

Return the current period only.
isFinalPeriodboolean

Return the final period only.
personIdstring

The person to filter queries by.
timeAwayTypeIdstring

If a time away type is specified, returns the periods for that type. If set to ‘all’, the response includes periods for all time away types. Defaults to pto type if no type is provided.
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of time away periods.

GET /api/time-away-periods

curl https://app.humaans.io/api/time-away-periods \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "X4XT4ZLOwT9GYbPyl90HztBu",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "startDate": "2020-09-01",
      "endDate": "2021-08-31",
      "usageEndDate": "2021-12-31",
      "timeAwayAllocation": {
        "id": "smIkoZZ0t4KlXbEka2UC9m7I",
        "personId": "IL3vneCYhIx0xrR6um2sy2nW",
        "type": "placeOfWork",
        "effectiveDate": "2020-04-01",
        "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I",
        "timeAwayPolicy": {
          "id": "smIkoZZ0t4KlXbEka2UC9m7I",
          "companyId": "T7uqPFK7am4lFTZm39AmNuay",
          "name": "UK Policy",
          "timeAwayPolicyVersion": {
            "id": "smIkoZZ0t4KlXbEka2UC9m7I",
            "bypassWorkingSchedule": false,
            "bypassPublicHolidays": false,
            "publicHolidayCalendarId": "GB",
            "visibleBalances": [
              "endOfYear"
            ],
            "rules": [
              {
                "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
                "limits": {
                  "yearlyAllowance": 30,
                  "maxCarryOver": 5,
                  "yearStart": "01-01",
                  "yearStartType": "employmentStartDate",
                  "isUnlimited": false,
                  "isProrated": false,
                  "maxBalance": 30,
                  "preventNegativeBalance": false,
                  "maxNegativeBalance": 5,
                  "usage": "upfront",
                  "usagePeriod": 12,
                  "carryOverUsagePeriod": 3,
                  "roundingType": "halfUp"
                }
              }
            ]
          },
          "createdAt": "2020-01-28T08:44:42.000Z",
          "updatedAt": "2020-01-29T14:52:21.000Z"
        },
        "createdAt": "2020-01-28T08:44:42.000Z",
        "updatedAt": "2020-01-29T14:52:21.000Z"
      },
      "timeAwayTypeId": "0defdigw4ayfQ0EP22HjZGiD",
      "isCurrentPeriod": true,
      "isFinalPeriod": false,
      "hasAllocationChanged": false,
      "isCarriedOverInFull": false,
      "isProrated": true,
      "accrued": 8.09,
      "allowance": 20,
      "fromPrevAccrualPeriod": 2,
      "fromPrevAccrualPeriodValidUntilDate": "2021-12-31",
      "fromPrevAccrualPeriodExpired": 2,
      "carriedOver": -0.17,
      "carriedOverDate": "2020-12-31",
      "carriedOverExpired": 0,
      "carryOverUsageEndDate": "2021-03-31",
      "adjustments": 0,
      "adjustmentsUpcoming": 0,
      "used": 2,
      "pending": 2,
      "upcoming": 0,
      "upcomingPending": 0,
      "balance": 5.92,
      "endingBalance": 17.83
    }
  ]
}

Time away policies

An object representing a time away policy. Time away policies are applied to employees to assign a yearly paid time off allowance, carry over days and a number of other settings.

Endpoints

   GET /api/time-away-policies

   GET /api/time-away-policies/:id

  POST /api/time-away-policies

 PATCH /api/time-away-policies/:id

DELETE /api/time-away-policies/:id

Required scopes

private:read

public:read

private:write

Time away policy object

Attributes

idstring

Unique identifier for the object.
companyIdstring

ID of the company that this object is associated to.
namestring

The name of the policy.
timeAwayPolicyVersionobject

Time away policy version information
timeAwayPolicyVersion.idstring

Unique identifier for the object.
timeAwayPolicyVersion.bypassWorkingScheduleboolean

true means weekends will be treated as working days. Default is false and means that weekends do not use up the available balance.
timeAwayPolicyVersion.bypassPublicHolidaysboolean

true means public holidays will be treated as working days. Default is false and means that public holidays do not use up the available balance.
timeAwayPolicyVersion.publicHolidayCalendarIdstring

A specific public holiday calendar id for all employees on this policy. If null, this will default to the employee’s office or remote location.
timeAwayPolicyVersion.visibleBalancesstring[]

Which balances to show to employees. Available options are endOfYear or today.
timeAwayPolicyVersion.rulesobject[]

List of time away types that are available on this policy.
timeAwayPolicyVersion.rules.timeAwayTypeIdstring

ID of the time away type that this rule is associated to.
timeAwayPolicyVersion.rules.limitsobject

If null, balances will not be caluclated for this type but usage numbers will still be available.
timeAwayPolicyVersion.rules.limits.yearlyAllowancenumber

The number of paid time off days allowed per year.
timeAwayPolicyVersion.rules.limits.maxCarryOvernumber

The number of days to carry over into the next year. null carries over the entire balance (no cap), which is the default when a maxBalance is set.
timeAwayPolicyVersion.rules.limits.yearStartstring

The start of the time off year. The format is MM-DD.
timeAwayPolicyVersion.rules.limits.yearStartTypestring

Whether the policy starts on employment start date or a custom date.
timeAwayPolicyVersion.rules.limits.isUnlimitedboolean

true means the time off policy allows to take unlimited paid time off days.
timeAwayPolicyVersion.rules.limits.isProratedboolean

true means the allowance will be prorated based on FTE.
timeAwayPolicyVersion.rules.limits.maxBalancenumber

The maximum balance an employee can accrue. Once reached, accrual pauses until the balance drops below the cap, then resumes. Not valid for unlimited policies. Prorated by FTE when isProrated is true.
timeAwayPolicyVersion.rules.limits.preventNegativeBalanceboolean

true prevents booking more leave than currently available.
timeAwayPolicyVersion.rules.limits.maxNegativeBalancenumber

The maximum number of days the balance is allowed to go negative. Only applies when preventNegativeBalance is false. null means the balance can go negative without limit.
timeAwayPolicyVersion.rules.limits.usagestring

Whether the employee can use PTO days for the year upfront or after they’ve been accrued. One of upfront or accrued.
timeAwayPolicyVersion.rules.limits.usagePeriodinteger

The length of the period in months beginning on yearStart where the employees’ yearly PTO can be used. One of 12, 15, 16, or 18. null means carried over balance never expires, and goes hand in hand with a null maxCarryOver. Defaults to: 12.
timeAwayPolicyVersion.rules.limits.carryOverUsagePeriodinteger

The number of months, from the start of the year the balance is carried into, that carried-over balance stays usable before it expires. When booking time off, balance expiring soonest is used first. null means carried-over balance follows the same usage period as the yearly allowance (usagePeriod).
timeAwayPolicyVersion.rules.limits.roundingTypestring

The rounding method applied to the time away balance. Valid options are halfUp, wholeUp and noRounding.
archivedAtdate-time

When the policy was archived.
isArchivedboolean

Whether the policy is archived.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.

time away policy object

{
  "id": "dFCSrX1I3nzOZQMpblBclisO",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "UK Policy",
  "timeAwayPolicyVersion": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "bypassWorkingSchedule": false,
    "bypassPublicHolidays": false,
    "publicHolidayCalendarId": "GB",
    "visibleBalances": [
      "endOfYear"
    ],
    "rules": [
      {
        "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
        "limits": {
          "yearlyAllowance": 30,
          "maxCarryOver": 5,
          "yearStart": "01-01",
          "yearStartType": "employmentStartDate",
          "isUnlimited": false,
          "isProrated": false,
          "maxBalance": 30,
          "preventNegativeBalance": false,
          "maxNegativeBalance": 5,
          "usage": "upfront",
          "usagePeriod": 12,
          "carryOverUsagePeriod": 3,
          "roundingType": "halfUp"
        }
      }
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all time away policies

Returns a list of time away policies.

Parameters

includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit time away policies. The response skips the first $skip results. Each entry is a separate time away policy object. If no time away policies are available, data is empty.

GET /api/time-away-policies

curl https://app.humaans.io/api/time-away-policies \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "dFCSrX1I3nzOZQMpblBclisO",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "UK Policy",
      "timeAwayPolicyVersion": {
        "id": "smIkoZZ0t4KlXbEka2UC9m7I",
        "bypassWorkingSchedule": false,
        "bypassPublicHolidays": false,
        "publicHolidayCalendarId": "GB",
        "visibleBalances": [
          "endOfYear"
        ],
        "rules": [
          {
            "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
            "limits": {
              "yearlyAllowance": 30,
              "maxCarryOver": 5,
              "yearStart": "01-01",
              "yearStartType": "employmentStartDate",
              "isUnlimited": false,
              "isProrated": false,
              "maxBalance": 30,
              "preventNegativeBalance": false,
              "maxNegativeBalance": 5,
              "usage": "upfront",
              "usagePeriod": 12,
              "carryOverUsagePeriod": 3,
              "roundingType": "halfUp"
            }
          }
        ]
      },
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a time away policy

Retrieves the time away policy with the given ID.

Parameters

No parameters

Returns

Returns a time away policy object if a valid identifier was provided.

GET /api/time-away-policies/:id

curl https://app.humaans.io/api/time-away-policies/dFCSrX1I3nzOZQMpblBclisO \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "dFCSrX1I3nzOZQMpblBclisO",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "UK Policy",
  "timeAwayPolicyVersion": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "bypassWorkingSchedule": false,
    "bypassPublicHolidays": false,
    "publicHolidayCalendarId": "GB",
    "visibleBalances": [
      "endOfYear"
    ],
    "rules": [
      {
        "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
        "limits": {
          "yearlyAllowance": 30,
          "maxCarryOver": 5,
          "yearStart": "01-01",
          "yearStartType": "employmentStartDate",
          "isUnlimited": false,
          "isProrated": false,
          "maxBalance": 30,
          "preventNegativeBalance": false,
          "maxNegativeBalance": 5,
          "usage": "upfront",
          "usagePeriod": 12,
          "carryOverUsagePeriod": 3,
          "roundingType": "halfUp"
        }
      }
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a time away policy

Parameters

namestring required

The name of the policy.
timeAwayPolicyVersionobject one of yearlyPtoAllowance or timeAwayPolicyVersion or timeAwayPolicyTemplateId required

Time away policy version information
timeAwayPolicyVersion.bypassWorkingScheduleboolean

true means weekends will be treated as working days. Default is false and means that weekends do not use up the available balance.
timeAwayPolicyVersion.bypassPublicHolidaysboolean

true means public holidays will be treated as working days. Default is false and means that public holidays do not use up the available balance.
timeAwayPolicyVersion.publicHolidayCalendarIdstring | null

A specific public holiday calendar id for all employees on this policy. If null, this will default to the employee’s office or remote location.
timeAwayPolicyVersion.visibleBalancesstring[]

Which balances to show to employees. Available options are endOfYear or today.
timeAwayPolicyVersion.rulesobject[] required

List of time away types that are available on this policy.
timeAwayPolicyVersion.rules.timeAwayTypeIdstring one of timeAwayTypeId or timeAwayType required

ID of the time away type that this rule is associated to.
timeAwayPolicyVersion.rules.limitsobject | null required

If null, balances will not be caluclated for this type but usage numbers will still be available.
timeAwayPolicyVersion.rules.limits.yearlyAllowancenumber required

The number of paid time off days allowed per year.
timeAwayPolicyVersion.rules.limits.maxCarryOvernumber | null

The number of days to carry over into the next year. null carries over the entire balance (no cap), which is the default when a maxBalance is set.
timeAwayPolicyVersion.rules.limits.yearStartstring

The start of the time off year. The format is MM-DD.
timeAwayPolicyVersion.rules.limits.yearStartTypestring

Whether the policy starts on employment start date or a custom date.
timeAwayPolicyVersion.rules.limits.isUnlimitedboolean required

true means the time off policy allows to take unlimited paid time off days.
timeAwayPolicyVersion.rules.limits.isProratedboolean required

true means the allowance will be prorated based on FTE.
timeAwayPolicyVersion.rules.limits.maxBalancenumber | null

The maximum balance an employee can accrue. Once reached, accrual pauses until the balance drops below the cap, then resumes. Not valid for unlimited policies. Prorated by FTE when isProrated is true.
timeAwayPolicyVersion.rules.limits.preventNegativeBalanceboolean

true prevents booking more leave than currently available.
timeAwayPolicyVersion.rules.limits.maxNegativeBalancenumber | null

The maximum number of days the balance is allowed to go negative. Only applies when preventNegativeBalance is false. null means the balance can go negative without limit.
timeAwayPolicyVersion.rules.limits.usagestring required

Whether the employee can use PTO days for the year upfront or after they’ve been accrued. One of upfront or accrued.
timeAwayPolicyVersion.rules.limits.usagePeriodinteger | null

The length of the period in months beginning on yearStart where the employees’ yearly PTO can be used. One of 12, 15, 16, or 18. null means carried over balance never expires, and goes hand in hand with a null maxCarryOver. Defaults to: 12.
timeAwayPolicyVersion.rules.limits.carryOverUsagePeriodinteger | null

The number of months, from the start of the year the balance is carried into, that carried-over balance stays usable before it expires. When booking time off, balance expiring soonest is used first. null means carried-over balance follows the same usage period as the yearly allowance (usagePeriod).
timeAwayPolicyVersion.rules.limits.roundingTypestring

The rounding method applied to the time away balance. Valid options are halfUp, wholeUp and noRounding.
timeAwayPolicyTemplateIdstring one of yearlyPtoAllowance or timeAwayPolicyVersion or timeAwayPolicyTemplateId required

Returns

Returns a time away policy if the call succeeded. The call returns an error if parameters are invalid.

POST /api/time-away-policies

curl https://app.humaans.io/api/time-away-policies \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"UK Policy","timeAwayPolicyVersion":{"id":"smIkoZZ0t4KlXbEka2UC9m7I","bypassWorkingSchedule":false,"bypassPublicHolidays":false,"publicHolidayCalendarId":"GB","visibleBalances":["endOfYear"],"rules":[{"timeAwayTypeId":"awM6sG5O2eSBAX2CeVap0MZa","limits":{"yearlyAllowance":30,"maxCarryOver":5,"yearStart":"01-01","yearStartType":"employmentStartDate","isUnlimited":false,"isProrated":false,"maxBalance":30,"preventNegativeBalance":false,"maxNegativeBalance":5,"usage":"upfront","usagePeriod":12,"carryOverUsagePeriod":3,"roundingType":"halfUp"}}]}}'

Response

{
  "id": "dFCSrX1I3nzOZQMpblBclisO",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "UK Policy",
  "timeAwayPolicyVersion": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "bypassWorkingSchedule": false,
    "bypassPublicHolidays": false,
    "publicHolidayCalendarId": "GB",
    "visibleBalances": [
      "endOfYear"
    ],
    "rules": [
      {
        "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
        "limits": {
          "yearlyAllowance": 30,
          "maxCarryOver": 5,
          "yearStart": "01-01",
          "yearStartType": "employmentStartDate",
          "isUnlimited": false,
          "isProrated": false,
          "maxBalance": 30,
          "preventNegativeBalance": false,
          "maxNegativeBalance": 5,
          "usage": "upfront",
          "usagePeriod": 12,
          "carryOverUsagePeriod": 3,
          "roundingType": "halfUp"
        }
      }
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a time away policy

Parameters

namestring

The name of the policy.
isArchivedboolean

Whether the policy is archived.
timeAwayPolicyVersionobject

Time away policy version information
timeAwayPolicyVersion.bypassWorkingScheduleboolean

true means weekends will be treated as working days. Default is false and means that weekends do not use up the available balance.
timeAwayPolicyVersion.bypassPublicHolidaysboolean

true means public holidays will be treated as working days. Default is false and means that public holidays do not use up the available balance.
timeAwayPolicyVersion.publicHolidayCalendarIdstring | null

A specific public holiday calendar id for all employees on this policy. If null, this will default to the employee’s office or remote location.
timeAwayPolicyVersion.visibleBalancesstring[]

Which balances to show to employees. Available options are endOfYear or today.
timeAwayPolicyVersion.rulesobject[]

List of time away types that are available on this policy.
timeAwayPolicyVersion.rules.timeAwayTypeIdstring one of timeAwayTypeId or timeAwayType required

ID of the time away type that this rule is associated to.
timeAwayPolicyVersion.rules.limitsobject | null required

If null, balances will not be caluclated for this type but usage numbers will still be available.
timeAwayPolicyVersion.rules.limits.yearlyAllowancenumber required

The number of paid time off days allowed per year.
timeAwayPolicyVersion.rules.limits.maxCarryOvernumber | null

The number of days to carry over into the next year. null carries over the entire balance (no cap), which is the default when a maxBalance is set.
timeAwayPolicyVersion.rules.limits.yearStartstring

The start of the time off year. The format is MM-DD.
timeAwayPolicyVersion.rules.limits.yearStartTypestring

Whether the policy starts on employment start date or a custom date.
timeAwayPolicyVersion.rules.limits.isUnlimitedboolean required

true means the time off policy allows to take unlimited paid time off days.
timeAwayPolicyVersion.rules.limits.isProratedboolean required

true means the allowance will be prorated based on FTE.
timeAwayPolicyVersion.rules.limits.maxBalancenumber | null

The maximum balance an employee can accrue. Once reached, accrual pauses until the balance drops below the cap, then resumes. Not valid for unlimited policies. Prorated by FTE when isProrated is true.
timeAwayPolicyVersion.rules.limits.preventNegativeBalanceboolean

true prevents booking more leave than currently available.
timeAwayPolicyVersion.rules.limits.maxNegativeBalancenumber | null

The maximum number of days the balance is allowed to go negative. Only applies when preventNegativeBalance is false. null means the balance can go negative without limit.
timeAwayPolicyVersion.rules.limits.usagestring required

Whether the employee can use PTO days for the year upfront or after they’ve been accrued. One of upfront or accrued.
timeAwayPolicyVersion.rules.limits.usagePeriodinteger | null

The length of the period in months beginning on yearStart where the employees’ yearly PTO can be used. One of 12, 15, 16, or 18. null means carried over balance never expires, and goes hand in hand with a null maxCarryOver. Defaults to: 12.
timeAwayPolicyVersion.rules.limits.carryOverUsagePeriodinteger | null

The number of months, from the start of the year the balance is carried into, that carried-over balance stays usable before it expires. When booking time off, balance expiring soonest is used first. null means carried-over balance follows the same usage period as the yearly allowance (usagePeriod).
timeAwayPolicyVersion.rules.limits.roundingTypestring

The rounding method applied to the time away balance. Valid options are halfUp, wholeUp and noRounding.

Returns

Returns the time away policy if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/time-away-policies/:id

curl https://app.humaans.io/api/time-away-policies/dFCSrX1I3nzOZQMpblBclisO \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'

Response

{
  "id": "dFCSrX1I3nzOZQMpblBclisO",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "UK Policy",
  "timeAwayPolicyVersion": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "bypassWorkingSchedule": false,
    "bypassPublicHolidays": false,
    "publicHolidayCalendarId": "GB",
    "visibleBalances": [
      "endOfYear"
    ],
    "rules": [
      {
        "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
        "limits": {
          "yearlyAllowance": 30,
          "maxCarryOver": 5,
          "yearStart": "01-01",
          "yearStartType": "employmentStartDate",
          "isUnlimited": false,
          "isProrated": false,
          "maxBalance": 30,
          "preventNegativeBalance": false,
          "maxNegativeBalance": 5,
          "usage": "upfront",
          "usagePeriod": 12,
          "carryOverUsagePeriod": 3,
          "roundingType": "halfUp"
        }
      }
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a time away policy

Permanently deletes a time away policy. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/time-away-policies/:id

curl https://app.humaans.io/api/time-away-policies/dFCSrX1I3nzOZQMpblBclisO \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "dFCSrX1I3nzOZQMpblBclisO",
  "deleted": true
}

Time away types

An object representing a time away type. Types are the set of reasons people can book time away for. Examples of types are “Paid time off”, “Sick leave”, “Maternity leave” and so on. Custom types can be created in addition to the standard types provided by Humaans.

Endpoints

   GET /api/time-away-types

   GET /api/time-away-types/:id

  POST /api/time-away-types

 PATCH /api/time-away-types/:id

DELETE /api/time-away-types/:id

Required scopes

public:read

private:write

Time away type object

Attributes

idstring

Unique identifier for the object.
companyIdstring

ID of the company that this object is associated to.
namestring

The name of the time away type.
emojistring

An emoji for visualising the time away type.
emojiLabelstring

An emoji label for accessibility.
categorystring

Whether the type represents time off or working away. timeOff is a genuine absence such as holiday, sick, or parental leave; workingAway is time worked off-site, such as from home or another location.
baseTypestring

The base type of the time away type. One of pto, sick, workingFromHome, or workingFromAnotherLocation
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

time away type object

{
  "id": "4NJq5i7WwkUgHYzRqkLritrb",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Paid time off",
  "emoji": "🏝",
  "emojiLabel": "Beach",
  "category": "timeOff",
  "baseType": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all time away types

Returns a list of time away types.

Parameters

idstring · $in

The ID of the time away type.
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
createdAtdate | date-time · $gt $gte $lt $lte

Filter time away types by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$orobject[]

Filter results by multiple criteria.
$or.idstring · $in

The ID of the time away type.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit time away types. The response skips the first $skip results. Each entry is a separate time away type object. If no time away types are available, data is empty.

GET /api/time-away-types

curl https://app.humaans.io/api/time-away-types \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "4NJq5i7WwkUgHYzRqkLritrb",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "Paid time off",
      "emoji": "🏝",
      "emojiLabel": "Beach",
      "category": "timeOff",
      "baseType": null,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a time away type

Retrieves the time away type with the given ID.

Parameters

No parameters

Returns

Returns a time away type object if a valid identifier was provided.

GET /api/time-away-types/:id

curl https://app.humaans.io/api/time-away-types/4NJq5i7WwkUgHYzRqkLritrb \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "4NJq5i7WwkUgHYzRqkLritrb",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Paid time off",
  "emoji": "🏝",
  "emojiLabel": "Beach",
  "category": "timeOff",
  "baseType": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a time away type

Parameters

namestring required

The name of the time away type.
emojistring required

An emoji for visualising the time away type.
categorystring one of type or category required

Whether the type represents time off or working away. timeOff is a genuine absence such as holiday, sick, or parental leave; workingAway is time worked off-site, such as from home or another location.

Returns

Returns a time away type if the call succeeded. The call returns an error if parameters are invalid.

POST /api/time-away-types

curl https://app.humaans.io/api/time-away-types \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"Paid time off","emoji":"🏝","category":"timeOff"}'

Response

{
  "id": "4NJq5i7WwkUgHYzRqkLritrb",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Paid time off",
  "emoji": "🏝",
  "emojiLabel": "Beach",
  "category": "timeOff",
  "baseType": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a time away type

Parameters

namestring

The name of the time away type.
emojistring

An emoji for visualising the time away type.

Returns

Returns the time away type if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/time-away-types/:id

curl https://app.humaans.io/api/time-away-types/4NJq5i7WwkUgHYzRqkLritrb \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'

Response

{
  "id": "4NJq5i7WwkUgHYzRqkLritrb",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Paid time off",
  "emoji": "🏝",
  "emojiLabel": "Beach",
  "category": "timeOff",
  "baseType": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a time away type

Permanently deletes a time away type. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/time-away-types/:id

curl https://app.humaans.io/api/time-away-types/4NJq5i7WwkUgHYzRqkLritrb \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "4NJq5i7WwkUgHYzRqkLritrb",
  "deleted": true
}

Timesheet entries

An object representing a timesheet entry of an employee

Endpoints

   GET /api/timesheet-entries

   GET /api/timesheet-entries/:id

  POST /api/timesheet-entries

 PATCH /api/timesheet-entries/:id

DELETE /api/timesheet-entries/:id

Required scopes

private:read

private:write

Timesheet entry object

Attributes

idstring

Unique identifier for the object.
personIdstring

ID of the person that this object is associated to.
datedate

The date of this timesheet entry.
startTimestring

The start time of this timesheet entry.
endTimestring

The end time of this timesheet entry.
durationobject

The duration of this timesheet entry, as {hours, minutes}. To total it, combine both parts — e.g. duration.hours + duration.minutes / 60 for hours — since one part alone is only half the answer.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

timesheet entry object

{
  "id": "0vUGk85FkSDHXfeOTnXqkk4d",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "date": "2020-04-01",
  "startTime": "09:00:00",
  "endTime": "12:30:00",
  "duration": {
    "hours": 3,
    "minutes": 30
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all timesheet entries

Returns a list of timesheet entries.

The timesheet entries can be filtered using more complex filter conditions. Refer to Filtering documentation for more details on usage.

Parameters

idobject

The ID of an existing timesheet entry.
datedate · $eq $ne $in $nin $gt $lt $gte $lte

The date of this timesheet entry.
endTimestring | empty

The end time of this timesheet entry.
id.$instring[] required

An array of IDs of existing timesheet entries.
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
personIdstring

The person to filter queries by.
createdAtdate | date-time · $gt $gte $lt $lte

Filter timesheet entries by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit timesheet entries. The response skips the first $skip results. Each entry is a separate timesheet entry object. If no timesheet entries are available, data is empty.

GET /api/timesheet-entries

curl https://app.humaans.io/api/timesheet-entries \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "0vUGk85FkSDHXfeOTnXqkk4d",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "date": "2020-04-01",
      "startTime": "09:00:00",
      "endTime": "12:30:00",
      "duration": {
        "hours": 3,
        "minutes": 30
      },
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a timesheet entry

Retrieves the timesheet entry with the given ID.

Parameters

No parameters

Returns

Returns a timesheet entry object if a valid identifier was provided.

GET /api/timesheet-entries/:id

curl https://app.humaans.io/api/timesheet-entries/0vUGk85FkSDHXfeOTnXqkk4d \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "0vUGk85FkSDHXfeOTnXqkk4d",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "date": "2020-04-01",
  "startTime": "09:00:00",
  "endTime": "12:30:00",
  "duration": {
    "hours": 3,
    "minutes": 30
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a timesheet entry

Parameters

personIdstring required

ID of the person that this object is associated to.
datedate required

The date of this timesheet entry.
startTimestring required

The start time of this timesheet entry.
endTimestring

The end time of this timesheet entry.

Returns

Returns a timesheet entry if the call succeeded. The call returns an error if parameters are invalid.

POST /api/timesheet-entries

curl https://app.humaans.io/api/timesheet-entries \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","date":"2020-04-01","startTime":"09:00:00"}'

Response

{
  "id": "0vUGk85FkSDHXfeOTnXqkk4d",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "date": "2020-04-01",
  "startTime": "09:00:00",
  "endTime": "12:30:00",
  "duration": {
    "hours": 3,
    "minutes": 30
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a timesheet entry

Parameters

datedate

The date of this timesheet entry.
startTimestring

The start time of this timesheet entry.
endTimestring

The end time of this timesheet entry.

Returns

Returns the timesheet entry if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/timesheet-entries/:id

curl https://app.humaans.io/api/timesheet-entries/0vUGk85FkSDHXfeOTnXqkk4d \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'

Response

{
  "id": "0vUGk85FkSDHXfeOTnXqkk4d",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "date": "2020-04-01",
  "startTime": "09:00:00",
  "endTime": "12:30:00",
  "duration": {
    "hours": 3,
    "minutes": 30
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a timesheet entry

Permanently deletes a timesheet entry. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/timesheet-entries/:id

curl https://app.humaans.io/api/timesheet-entries/0vUGk85FkSDHXfeOTnXqkk4d \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "0vUGk85FkSDHXfeOTnXqkk4d",
  "deleted": true
}

Timesheet submissions

An object representing a timesheet submission of an employee

Endpoints

   GET /api/timesheet-submissions

   GET /api/timesheet-submissions/:id

  POST /api/timesheet-submissions

 PATCH /api/timesheet-submissions/:id

DELETE /api/timesheet-submissions/:id

Required scopes

private:read

private:write

Timesheet submission object

Attributes

idstring

Unique identifier for the object.
personIdstring

ID of the person that this object is associated to.
startDatedate

The start date of the month which this submission covers.
endDatedate

The end date of the month which this submission covers.
statusstring

One of pending, approved, rejected.
submittedAtdate-time

The date and time when this submission was last submitted.
reviewedBystring

The ID of the person that reviewed this submission.
reviewedAtdate-time

The date and time when this submission was reviewed.
changesRequestedstring

Changes requested to accompany a rejected submission.
durationAsTimeobject

The total time attached to this submission.
durationAsDaysnumber

The total days attached to this submission.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.
deletedAtdate-time

timesheet submission object

{
  "id": "Qh1bcl6baOIFPBgJjM0I9wNB",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startDate": "2020-04-01",
  "endDate": "2020-04-30",
  "status": "pending",
  "submittedAt": "2020-04-30T17:08:29.290Z",
  "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedAt": "2020-04-30T17:08:29.290Z",
  "changesRequested": "Missing hours from weekend shift.",
  "durationAsTime": {
    "hours": 127,
    "minutes": 30
  },
  "durationAsDays": 23,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all timesheet submissions

The timesheet submissions can be filtered using more complex filter conditions. Refer to Filtering documentation for more details on usage.

Parameters

includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
personIdstring

The person to filter queries by.
startDatestring

The start date of the month which this submission covers.
createdAtdate | date-time · $gt $gte $lt $lte

Filter timesheet submissions by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns a list of timesheet submissions.

GET /api/timesheet-submissions

curl https://app.humaans.io/api/timesheet-submissions \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "Qh1bcl6baOIFPBgJjM0I9wNB",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "startDate": "2020-04-01",
      "endDate": "2020-04-30",
      "status": "pending",
      "submittedAt": "2020-04-30T17:08:29.290Z",
      "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
      "reviewedAt": "2020-04-30T17:08:29.290Z",
      "changesRequested": "Missing hours from weekend shift.",
      "durationAsTime": {
        "hours": 127,
        "minutes": 30
      },
      "durationAsDays": 23,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a timesheet submission

Retrieves the timesheet submission with the given ID.

Parameters

No parameters

Returns

Returns a timesheet submission object if a valid identifier was provided.

GET /api/timesheet-submissions/:id

curl https://app.humaans.io/api/timesheet-submissions/Qh1bcl6baOIFPBgJjM0I9wNB \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "Qh1bcl6baOIFPBgJjM0I9wNB",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startDate": "2020-04-01",
  "endDate": "2020-04-30",
  "status": "pending",
  "submittedAt": "2020-04-30T17:08:29.290Z",
  "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedAt": "2020-04-30T17:08:29.290Z",
  "changesRequested": "Missing hours from weekend shift.",
  "durationAsTime": {
    "hours": 127,
    "minutes": 30
  },
  "durationAsDays": 23,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a timesheet submission

Parameters

personIdstring required

ID of the person that this object is associated to.
startDatedate required

The start date of the month which this submission covers.

Returns

Returns a timesheet submission if the call succeeded. The call returns an error if parameters are invalid.

POST /api/timesheet-submissions

curl https://app.humaans.io/api/timesheet-submissions \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","startDate":"2020-04-01"}'

Response

{
  "id": "Qh1bcl6baOIFPBgJjM0I9wNB",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startDate": "2020-04-01",
  "endDate": "2020-04-30",
  "status": "pending",
  "submittedAt": "2020-04-30T17:08:29.290Z",
  "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedAt": "2020-04-30T17:08:29.290Z",
  "changesRequested": "Missing hours from weekend shift.",
  "durationAsTime": {
    "hours": 127,
    "minutes": 30
  },
  "durationAsDays": 23,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a timesheet submission

Parameters

statusstring required

One of pending, approved, rejected.
changesRequestedstring

Changes requested to accompany a rejected submission.

Returns

Returns the timesheet submission if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/timesheet-submissions/:id

curl https://app.humaans.io/api/timesheet-submissions/Qh1bcl6baOIFPBgJjM0I9wNB \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"status":"pending"}'

Response

{
  "id": "Qh1bcl6baOIFPBgJjM0I9wNB",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startDate": "2020-04-01",
  "endDate": "2020-04-30",
  "status": "pending",
  "submittedAt": "2020-04-30T17:08:29.290Z",
  "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedAt": "2020-04-30T17:08:29.290Z",
  "changesRequested": "Missing hours from weekend shift.",
  "durationAsTime": {
    "hours": 127,
    "minutes": 30
  },
  "durationAsDays": 23,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a timesheet submission

Permanently deletes a timesheet submission. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/timesheet-submissions/:id

curl https://app.humaans.io/api/timesheet-submissions/Qh1bcl6baOIFPBgJjM0I9wNB \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "Qh1bcl6baOIFPBgJjM0I9wNB",
  "deleted": true
}

Token info

An object containing the scoped permissions of the current access token.

Endpoints

GET /api/token-info

Required scopes

*

Token info object

Attributes

scopesstring[]

token-info object

{
  "scopes": [
    "public:read",
    "documents:read"
  ]
}

Retrieve my token info

Retrieves the scopes assigned to the current token.

Parameters

No parameters

Returns

Returns the current token’s scopes.

GET /api/token-info

curl https://app.humaans.io/api/token-info \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "scopes": [
    "public:read",
    "documents:read"
  ]
}

Webhook events

An object representing an action triggered by a person, integration, the system or support.

Webhook event object

Attributes

id

The unique ID of the event
seq

A sortable sequence string
ts

The date time the event was created
action

The action type of the event sent. One of timeAway.created, timeAway.updated, timeAway.deleted, timeAway.approved, timeAway.rejected, timeAwayAdjustment.created, timeAwayAdjustment.updated, timeAwayAdjustment.deleted, person.created, person.updated, person.offboarded, person.reonboarded, person.deleted, bankAccount.created, bankAccount.updated, bankAccount.deleted, jobRole.created, jobRole.updated, jobRole.deleted, compensation.created, compensation.updated, compensation.deleted, emergencyContact.created, emergencyContact.updated, emergencyContact.deleted, equipment.created, equipment.updated, equipment.deleted.
subject

The affected participant of the event
actor

The affecting participant of the event, may be an integration
entity

The information that has been changed in the event
entity.id

The ID if the affected entity
entity.fieldsChanged

A list of all the fields changed, including the ids of any custom fields
entity.next

Any newly set information, will be null if unset in action
entity.prev

Any previously set information, will be null if set in action
entity.customFields

Any changed custom fields are listed here
entity.metadata

This is used to store additional information on the entity that may be useful, for example in the case of a compensation update it will contain the type of compensation that’s being updated

webhook event object

{
    "id": "qCNHkhApepOJf0eFHuPzQbDg",
    "seq": "01J4GSN4XYQ7401FXCYQPWH3V7",
    "ts": "2024-08-05T08:14:24.190Z",
    "action": "emergencyContact.created",
    "subject": {
      "id": "8Rc7dFxm7OFoiwxVBIFrLRAi",
      "type": "person"
    },
    "actor": {
      "personId": "8Rc7dFxm7OFoiwxVBIFrLRAi",
      "type": "person"
    },
    "entity": {
      "id": "OCPMqZtTcgFOuoc56TiKo9OT",
      "fieldsChanged": [
        "8Yzi4vi9SI43R5ubSAQOae5q",
        "name",
        "email",
        "isPrimary",
        "phoneNumber",
        "relationship"
      ],
      "next": {
        "email": "jd@humaans.io",
        "isPrimary": false,
        "name": "jane",
        "phoneNumber": "0123412345",
        "relationship": "doe"
      },
      "prev": {
        "email": null,
        "isPrimary": null,
        "name": null,
        "phoneNumber": null,
        "relationship": null
      },
      "customFields": [
        {
          "customFieldId": "8Yzi4vi9SI43R5ubSAQOae5q",
          "next": "[\"+447979512293\"]",
          "prev": null
        }
      ],
      "metadata": {}
    }
  }

Webhooks

An object representing a webhook and it’s configuration. If a webhook is created or patched with status equal to active then prodEndpointUrl and subscribedEvents become mandatory properties.

Endpoints

   GET /api/webhooks

   GET /api/webhooks/:id

  POST /api/webhooks

 PATCH /api/webhooks/:id

DELETE /api/webhooks/:id

Required scopes

webhooks:manage

Webhook object

Attributes

idstring

Unique identifier for the object.
namestring

A short name for the webhook.
descriptionstring

A longer description for the webhook.
prodEndpointUrlstring

The endpoint that will receive webhook events.
prodEndpointSignaturestring

This signature can be used to verify that the webhook message came from Humaans, read more about this in the webhooks section.
subscribedEventsstring[]

The list of webhook events that will be sent to the configured endpoint.
statusstring

The status of the webhook, can be one of draft, active or disabled.
createdBystring

The person who first created the webhook.
publishedBystring

The person who last published the webhook.
createdAtdate-time

Time at which the object was created.
updatedAtdate-time

Time at which the object was last updated.

webhook object

{
  "id": "2ehafnPohpOY49mlQx0i3SHL",
  "name": "Payroll integration",
  "description": "Integrates Humaans with the PayrollX system",
  "prodEndpointUrl": "https://myco.io/api/webhook/humaans",
  "prodEndpointSignature": "whsec_FZXyzQwEgwnENgbRDtLjBdoHcd",
  "subscribedEvents": [
    "person.created",
    "person.updated",
    "person.removed"
  ],
  "status": "active",
  "createdBy": "C6WWf6y0z7VEWlNWaSxUMntV",
  "publishedBy": "C6WWf6y0z7VEWlNWaSxUMntV",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all webhooks

Returns a list of webhooks.

Parameters

createdAtdate | date-time · $gt $gte $lt $lte

Filter webhooks by created at date.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter webhooks by updated at date.
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit webhooks. The response skips the first $skip results. Each entry is a separate webhook object. If no webhooks are available, data is empty.

GET /api/webhooks

curl https://app.humaans.io/api/webhooks \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "2ehafnPohpOY49mlQx0i3SHL",
      "name": "Payroll integration",
      "description": "Integrates Humaans with the PayrollX system",
      "prodEndpointUrl": "https://myco.io/api/webhook/humaans",
      "prodEndpointSignature": "whsec_FZXyzQwEgwnENgbRDtLjBdoHcd",
      "subscribedEvents": [
        "person.created",
        "person.updated",
        "person.removed"
      ],
      "status": "active",
      "createdBy": "C6WWf6y0z7VEWlNWaSxUMntV",
      "publishedBy": "C6WWf6y0z7VEWlNWaSxUMntV",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a webhook

Retrieves the webhook with the given ID.

Parameters

No parameters

Returns

Returns a webhook object if a valid identifier was provided.

GET /api/webhooks/:id

curl https://app.humaans.io/api/webhooks/2ehafnPohpOY49mlQx0i3SHL \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "2ehafnPohpOY49mlQx0i3SHL",
  "name": "Payroll integration",
  "description": "Integrates Humaans with the PayrollX system",
  "prodEndpointUrl": "https://myco.io/api/webhook/humaans",
  "prodEndpointSignature": "whsec_FZXyzQwEgwnENgbRDtLjBdoHcd",
  "subscribedEvents": [
    "person.created",
    "person.updated",
    "person.removed"
  ],
  "status": "active",
  "createdBy": "C6WWf6y0z7VEWlNWaSxUMntV",
  "publishedBy": "C6WWf6y0z7VEWlNWaSxUMntV",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a webhook

Parameters

namestring required

A short name for the webhook.
descriptionstring | null

A longer description for the webhook.
prodEndpointUrlstring | null

The endpoint that will receive webhook events.
subscribedEventsstring[]

The list of webhook events that will be sent to the configured endpoint.
statusstring

The status of the webhook, can be one of draft, active or disabled.

Returns

Returns a webhook if the call succeeded. The call returns an error if parameters are invalid.

POST /api/webhooks

curl https://app.humaans.io/api/webhooks \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"Payroll integration"}'

Response

{
  "id": "2ehafnPohpOY49mlQx0i3SHL",
  "name": "Payroll integration",
  "description": "Integrates Humaans with the PayrollX system",
  "prodEndpointUrl": "https://myco.io/api/webhook/humaans",
  "prodEndpointSignature": "whsec_FZXyzQwEgwnENgbRDtLjBdoHcd",
  "subscribedEvents": [
    "person.created",
    "person.updated",
    "person.removed"
  ],
  "status": "active",
  "createdBy": "C6WWf6y0z7VEWlNWaSxUMntV",
  "publishedBy": "C6WWf6y0z7VEWlNWaSxUMntV",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a webhook

Parameters

namestring

A short name for the webhook.
descriptionstring | null

A longer description for the webhook.
statusstring

The status of the webhook, can be one of draft, active or disabled.
subscribedEventsstring[]

The list of webhook events that will be sent to the configured endpoint.
prodEndpointUrlstring | null

The endpoint that will receive webhook events.

Returns

Returns the webhook if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/webhooks/:id

curl https://app.humaans.io/api/webhooks/2ehafnPohpOY49mlQx0i3SHL \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'

Response

{
  "id": "2ehafnPohpOY49mlQx0i3SHL",
  "name": "Payroll integration",
  "description": "Integrates Humaans with the PayrollX system",
  "prodEndpointUrl": "https://myco.io/api/webhook/humaans",
  "prodEndpointSignature": "whsec_FZXyzQwEgwnENgbRDtLjBdoHcd",
  "subscribedEvents": [
    "person.created",
    "person.updated",
    "person.removed"
  ],
  "status": "active",
  "createdBy": "C6WWf6y0z7VEWlNWaSxUMntV",
  "publishedBy": "C6WWf6y0z7VEWlNWaSxUMntV",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a webhook

Permanently deletes a webhook. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/webhooks/:id

curl https://app.humaans.io/api/webhooks/2ehafnPohpOY49mlQx0i3SHL \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "2ehafnPohpOY49mlQx0i3SHL",
  "deleted": true
}

Working pattern allocations

An object representing the assignment of a working pattern to an employee.

To assign a working pattern to an employee, create an allocation linking a person (personId) to either:

An existing company-wide working pattern via workingPatternId
A custom inline working pattern via the workingPattern object

Each employee typically has one allocation, but can have multiple with different effectiveDate values to track changes over time (e.g. when moving to part-time or changing offices with different schedules). The allocation with the most recent effectiveDate that is not in the future is considered currently active.

Endpoints

   GET /api/working-pattern-allocations

   GET /api/working-pattern-allocations/:id

  POST /api/working-pattern-allocations

 PATCH /api/working-pattern-allocations/:id

DELETE /api/working-pattern-allocations/:id

Required scopes

private:read

public:read

private:write

Working pattern allocation object

Attributes

idstring

Unique identifier for the object.
personIdstring

The ID of the person this working pattern allocation is for.
workingPatternIdstring

The ID of the working pattern being assigned. Must reference a company-wide working pattern (where personId is null). Either workingPatternId or workingPattern must be provided when creating an allocation.
effectiveDatedate

The date from which this working pattern allocation takes effect. If null, the allocation is effective from the employee’s start date. When multiple allocations exist, the most recent effective date determines the current working pattern.
effectiveEndDatedate

The date to which this working pattern allocation takes effect.
workingPatternobject

The full working pattern object associated with this allocation. When creating an allocation, you can provide an inline workingPattern object instead of a workingPatternId to create a custom pattern specific to this person.
workingPattern.idstring

Unique identifier for the object.
workingPattern.companyIdstring

ID of the company that this object is associated to.
workingPattern.personIdstring

The ID of the person this working pattern is created for. Only set for individual custom working patterns. When null, the working pattern is a company-wide template that can be assigned to any employee.
workingPattern.namestring

The name of the working pattern.
workingPattern.summarystring

A summary describing the working pattern schedule.
workingPattern.fullTimeHoursnumber

The number of hours that constitute full-time work over the specified periodType. Used as the reference for calculating the FTE (Full Time Equivalent).
workingPattern.standardDayHoursnumber

The standard number of working hours per day. Used for calculating time away allowances and working days.
workingPattern.periodTypestring

The time period over which fullTimeHours and workingHours are measured. One of week, day, or month.
workingPattern.workingHoursnumber

The total hours the employee is expected to work over the period. For fixed-hours patterns, this is calculated from the workingPattern array. For flexible patterns (where workingPattern contains booleans), this specifies the total hours to be distributed across working days.
workingPattern.workingPatternboolean[] | number[]
The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either:
- An array of numbers representing hours worked per day (e.g. [8,8,8,8,8,0,0] for Mon-Fri 8h)
- An array of booleans for flexible patterns where true indicates a working day (e.g. [true,true,true,true,true,false,false] for Mon-Fri flexible)
workingPattern.ftenumber

The Full Time Equivalent, calculated as workingHours / fullTimeHours. Rounded to 4 decimal places. A value of 1.0 represents full-time work.
workingPattern.unroundedFtenumber

The exact Full Time Equivalent before rounding. Useful for precise calculations.
workingPattern.archivedAtdate-time

When the working pattern was archived.
workingPattern.isArchivedboolean

Whether the working pattern is archived.
workingPattern.createdAtdate-time

Timestamp when the working pattern was created.
workingPattern.updatedAtdate-time

Timestamp when the working pattern was last updated.
createdAtdate-time

Timestamp when the allocation was created.
updatedAtdate-time

Timestamp when the allocation was last updated.
deletedAtdate-time

The date and time the allocation was deleted. Only present on deleted allocations, which are only returned when querying with includeDeleted.

working pattern allocation object

{
  "id": "wiyjmFuX79AGNiROhmIJFxHC",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "workingPatternId": "xzZJYmdPHDFSxfpWaamgVR7U",
  "effectiveDate": "2020-04-01",
  "effectiveEndDate": "2020-04-01",
  "workingPattern": {
    "fullTimeHours": 40,
    "standardDayHours": 8,
    "workingPattern": [
      8,
      8,
      8,
      8,
      8,
      0,
      0
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all working pattern allocations

Returns a list of working pattern allocations.

Parameters

includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
personIdstring · $eq $ne $in $nin

Filter by people ids
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
deletedAtnull · $ne / null | date-time · $gt $gte $lt $lte / date-time

Filter by deletion time. Use with includeDeleted and sort by deletedAt for incremental synchronization.
$asOfdate

Filter the list of working pattern allocations to the current one per employee in effect at the provided date. Cannot be combined with includeDeleted.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit working pattern allocations. The response skips the first $skip results. Each entry is a separate working pattern allocation object. If no working pattern allocations are available, data is empty.

GET /api/working-pattern-allocations

curl https://app.humaans.io/api/working-pattern-allocations \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "wiyjmFuX79AGNiROhmIJFxHC",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "workingPatternId": "xzZJYmdPHDFSxfpWaamgVR7U",
      "effectiveDate": "2020-04-01",
      "effectiveEndDate": "2020-04-01",
      "workingPattern": {
        "fullTimeHours": 40,
        "standardDayHours": 8,
        "workingPattern": [
          8,
          8,
          8,
          8,
          8,
          0,
          0
        ]
      },
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a working pattern allocation

Retrieves the working pattern allocation with the given ID.

Parameters

No parameters

Returns

Returns a working pattern allocation object if a valid identifier was provided.

GET /api/working-pattern-allocations/:id

curl https://app.humaans.io/api/working-pattern-allocations/wiyjmFuX79AGNiROhmIJFxHC \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "wiyjmFuX79AGNiROhmIJFxHC",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "workingPatternId": "xzZJYmdPHDFSxfpWaamgVR7U",
  "effectiveDate": "2020-04-01",
  "effectiveEndDate": "2020-04-01",
  "workingPattern": {
    "fullTimeHours": 40,
    "standardDayHours": 8,
    "workingPattern": [
      8,
      8,
      8,
      8,
      8,
      0,
      0
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a working pattern allocation

Parameters

personIdstring

The ID of the person this working pattern allocation is for.
effectiveDatedate | null

The date from which this working pattern allocation takes effect. If null, the allocation is effective from the employee’s start date. When multiple allocations exist, the most recent effective date determines the current working pattern.
workingPatternIdstring

The ID of the working pattern being assigned. Must reference a company-wide working pattern (where personId is null). Either workingPatternId or workingPattern must be provided when creating an allocation.
workingPatternobject

The full working pattern object associated with this allocation. When creating an allocation, you can provide an inline workingPattern object instead of a workingPatternId to create a custom pattern specific to this person.
workingPattern.namestring

The name of the working pattern.
workingPattern.fullTimeHoursnumber required

The number of hours that constitute full-time work over the specified periodType. Used as the reference for calculating the FTE (Full Time Equivalent).
workingPattern.standardDayHoursnumber required

The standard number of working hours per day. Used for calculating time away allowances and working days.
workingPattern.periodTypestring

The time period over which fullTimeHours and workingHours are measured. One of week, day, or month.
workingPattern.workingHoursnumber

The total hours the employee is expected to work over the period. For fixed-hours patterns, this is calculated from the workingPattern array. For flexible patterns (where workingPattern contains booleans), this specifies the total hours to be distributed across working days.
workingPattern.workingPattern(boolean | number)[] required
The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either:
- An array of numbers representing hours worked per day (e.g. [8,8,8,8,8,0,0] for Mon-Fri 8h)
- An array of booleans for flexible patterns where true indicates a working day (e.g. [true,true,true,true,true,false,false] for Mon-Fri flexible)
workingPattern.personIdstring | null

The ID of the person this working pattern is created for. Only set for individual custom working patterns. When null, the working pattern is a company-wide template that can be assigned to any employee.

Returns

Returns a working pattern allocation if the call succeeded. The call returns an error if parameters are invalid.

POST /api/working-pattern-allocations

curl https://app.humaans.io/api/working-pattern-allocations \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","workingPatternId":"xzZJYmdPHDFSxfpWaamgVR7U","effectiveDate":"2024-01-01"}'

Response

{
  "id": "wiyjmFuX79AGNiROhmIJFxHC",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "workingPatternId": "xzZJYmdPHDFSxfpWaamgVR7U",
  "effectiveDate": "2024-01-01",
  "effectiveEndDate": "2020-04-01",
  "workingPattern": {
    "fullTimeHours": 40,
    "standardDayHours": 8,
    "workingPattern": [
      8,
      8,
      8,
      8,
      8,
      0,
      0
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a working pattern allocation

Parameters

idstring

Unique identifier for the object.
workingPatternIdstring

The ID of the working pattern being assigned. Must reference a company-wide working pattern (where personId is null). Either workingPatternId or workingPattern must be provided when creating an allocation.
effectiveDatedate | null

The date from which this working pattern allocation takes effect. If null, the allocation is effective from the employee’s start date. When multiple allocations exist, the most recent effective date determines the current working pattern.
workingPatternobject

The full working pattern object associated with this allocation. When creating an allocation, you can provide an inline workingPattern object instead of a workingPatternId to create a custom pattern specific to this person.
workingPattern.namestring

The name of the working pattern.
workingPattern.fullTimeHoursnumber required

The number of hours that constitute full-time work over the specified periodType. Used as the reference for calculating the FTE (Full Time Equivalent).
workingPattern.standardDayHoursnumber required

The standard number of working hours per day. Used for calculating time away allowances and working days.
workingPattern.periodTypestring

The time period over which fullTimeHours and workingHours are measured. One of week, day, or month.
workingPattern.workingHoursnumber

The total hours the employee is expected to work over the period. For fixed-hours patterns, this is calculated from the workingPattern array. For flexible patterns (where workingPattern contains booleans), this specifies the total hours to be distributed across working days.
workingPattern.workingPattern(boolean | number)[] required
The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either:
- An array of numbers representing hours worked per day (e.g. [8,8,8,8,8,0,0] for Mon-Fri 8h)
- An array of booleans for flexible patterns where true indicates a working day (e.g. [true,true,true,true,true,false,false] for Mon-Fri flexible)
workingPattern.personIdstring | null

The ID of the person this working pattern is created for. Only set for individual custom working patterns. When null, the working pattern is a company-wide template that can be assigned to any employee.

Returns

Returns the working pattern allocation if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/working-pattern-allocations/:id

curl https://app.humaans.io/api/working-pattern-allocations/wiyjmFuX79AGNiROhmIJFxHC \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"effectiveDate":"2024-06-01"}'

Response

{
  "id": "wiyjmFuX79AGNiROhmIJFxHC",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "workingPatternId": "xzZJYmdPHDFSxfpWaamgVR7U",
  "effectiveDate": "2024-06-01",
  "effectiveEndDate": "2020-04-01",
  "workingPattern": {
    "fullTimeHours": 40,
    "standardDayHours": 8,
    "workingPattern": [
      8,
      8,
      8,
      8,
      8,
      0,
      0
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a working pattern allocation

Permanently deletes a working pattern allocation. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/working-pattern-allocations/:id

curl https://app.humaans.io/api/working-pattern-allocations/wiyjmFuX79AGNiROhmIJFxHC \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "wiyjmFuX79AGNiROhmIJFxHC",
  "deleted": true
}

Working patterns

A working pattern defines the schedule and hours an employee works. Working patterns can be company-wide templates (where personId is null) or custom patterns created for specific individuals.

Each pattern specifies the fullTimeHours (reference for FTE calculation), standardDayHours, and the actual workingPattern array which can be either:

Fixed hours: an array of numbers representing hours per day (e.g. [8,8,8,8,8,0,0] for Mon-Fri)
Flexible: an array of booleans indicating working days, with workingHours specifying total hours

To assign a working pattern to an employee, use the Working Pattern Allocations API.

Endpoints

   GET /api/working-patterns

   GET /api/working-patterns/:id

  POST /api/working-patterns

 PATCH /api/working-patterns/:id

DELETE /api/working-patterns/:id

Required scopes

private:read

private:write

Working pattern object

Attributes

idstring

Unique identifier for the object.
companyIdstring

ID of the company that this object is associated to.
personIdstring

The ID of the person this working pattern is created for. Only set for individual custom working patterns. When null, the working pattern is a company-wide template that can be assigned to any employee.
namestring

The name of the working pattern.
summarystring

A summary describing the working pattern schedule.
fullTimeHoursnumber

The number of hours that constitute full-time work over the specified periodType. Used as the reference for calculating the FTE (Full Time Equivalent).
standardDayHoursnumber

The standard number of working hours per day. Used for calculating time away allowances and working days.
periodTypestring

The time period over which fullTimeHours and workingHours are measured. One of week, day, or month.
workingHoursnumber

The total hours the employee is expected to work over the period. For fixed-hours patterns, this is calculated from the workingPattern array. For flexible patterns (where workingPattern contains booleans), this specifies the total hours to be distributed across working days.
workingPatternboolean[] | number[]
The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either:
- An array of numbers representing hours worked per day (e.g. [8,8,8,8,8,0,0] for Mon-Fri 8h)
- An array of booleans for flexible patterns where true indicates a working day (e.g. [true,true,true,true,true,false,false] for Mon-Fri flexible)
ftenumber

The Full Time Equivalent, calculated as workingHours / fullTimeHours. Rounded to 4 decimal places. A value of 1.0 represents full-time work.
unroundedFtenumber

The exact Full Time Equivalent before rounding. Useful for precise calculations.
archivedAtdate-time

When the working pattern was archived.
isArchivedboolean

Whether the working pattern is archived.
createdAtdate-time

Timestamp when the working pattern was created.
updatedAtdate-time

Timestamp when the working pattern was last updated.

working pattern object

{
  "id": "MLYRjj1YdpuQp5Qe6HQsvUys",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "personId": null,
  "name": "Mon-Fri 8h/day",
  "summary": "Mon-Fri (8h)",
  "fullTimeHours": 40,
  "standardDayHours": 8,
  "periodType": "week",
  "workingHours": 40,
  "workingPattern": [
    8,
    8,
    8,
    8,
    8,
    0,
    0
  ],
  "fte": 1,
  "unroundedFte": 1,
  "archivedAt": "2020-01-28T08:44:42.000Z",
  "isArchived": false,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all working patterns

Returns a list of working patterns.

Parameters

companyIdstring | empty
includeDeletedboolean

Include deleted records. For public API requests, only records deleted within the last 30 days are returned. Deleted records are returned as minimal tombstones.
personIdnull · $ne

The ID of the person this working pattern is created for. Only set for individual custom working patterns. When null, the working pattern is a company-wide template that can be assigned to any employee.
updatedAtdate | date-time · $gt $gte $lt $lte

Filter by update time. Sort by updatedAt for incremental synchronization.
$sortobject
$sort.deletedAtnumber
$sort.updatedAtnumber
$limitnumber

Limit number of results.
$skipnumber

Skip the specified number of results.

Returns

Returns an object whose data property contains up to $limit working patterns. The response skips the first $skip results. Each entry is a separate working pattern object. If no working patterns are available, data is empty.

GET /api/working-patterns

curl https://app.humaans.io/api/working-patterns \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "MLYRjj1YdpuQp5Qe6HQsvUys",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "personId": null,
      "name": "Mon-Fri 8h/day",
      "summary": "Mon-Fri (8h)",
      "fullTimeHours": 40,
      "standardDayHours": 8,
      "periodType": "week",
      "workingHours": 40,
      "workingPattern": [
        8,
        8,
        8,
        8,
        8,
        0,
        0
      ],
      "fte": 1,
      "unroundedFte": 1,
      "archivedAt": "2020-01-28T08:44:42.000Z",
      "isArchived": false,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a working pattern

Retrieves the working pattern with the given ID.

Parameters

No parameters

Returns

Returns a working pattern object if a valid identifier was provided.

GET /api/working-patterns/:id

curl https://app.humaans.io/api/working-patterns/MLYRjj1YdpuQp5Qe6HQsvUys \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "MLYRjj1YdpuQp5Qe6HQsvUys",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "personId": null,
  "name": "Mon-Fri 8h/day",
  "summary": "Mon-Fri (8h)",
  "fullTimeHours": 40,
  "standardDayHours": 8,
  "periodType": "week",
  "workingHours": 40,
  "workingPattern": [
    8,
    8,
    8,
    8,
    8,
    0,
    0
  ],
  "fte": 1,
  "unroundedFte": 1,
  "archivedAt": "2020-01-28T08:44:42.000Z",
  "isArchived": false,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a working pattern

Parameters

namestring

The name of the working pattern.
fullTimeHoursnumber required

The number of hours that constitute full-time work over the specified periodType. Used as the reference for calculating the FTE (Full Time Equivalent).
standardDayHoursnumber required

The standard number of working hours per day. Used for calculating time away allowances and working days.
periodTypestring

The time period over which fullTimeHours and workingHours are measured. One of week, day, or month.
workingHoursnumber

The total hours the employee is expected to work over the period. For fixed-hours patterns, this is calculated from the workingPattern array. For flexible patterns (where workingPattern contains booleans), this specifies the total hours to be distributed across working days.
workingPatternboolean[] | number[] required
The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either:
- An array of numbers representing hours worked per day (e.g. [8,8,8,8,8,0,0] for Mon-Fri 8h)
- An array of booleans for flexible patterns where true indicates a working day (e.g. [true,true,true,true,true,false,false] for Mon-Fri flexible)
personIdstring | null

The ID of the person this working pattern is created for. Only set for individual custom working patterns. When null, the working pattern is a company-wide template that can be assigned to any employee.

Returns

Returns a working pattern if the call succeeded. The call returns an error if parameters are invalid.

POST /api/working-patterns

curl https://app.humaans.io/api/working-patterns \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"fullTimeHours":40,"standardDayHours":8,"workingPattern":[8,8,8,8,8,0,0]}'

Response

{
  "id": "MLYRjj1YdpuQp5Qe6HQsvUys",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "personId": null,
  "name": "Mon-Fri 8h/day",
  "summary": "Mon-Fri (8h)",
  "fullTimeHours": 40,
  "standardDayHours": 8,
  "periodType": "week",
  "workingHours": 40,
  "workingPattern": [
    8,
    8,
    8,
    8,
    8,
    0,
    0
  ],
  "fte": 1,
  "unroundedFte": 1,
  "archivedAt": "2020-01-28T08:44:42.000Z",
  "isArchived": false,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a working pattern

Parameters

namestring

The name of the working pattern.
fullTimeHoursnumber

The number of hours that constitute full-time work over the specified periodType. Used as the reference for calculating the FTE (Full Time Equivalent).
standardDayHoursnumber

The standard number of working hours per day. Used for calculating time away allowances and working days.
periodTypestring

The time period over which fullTimeHours and workingHours are measured. One of week, day, or month.
workingHoursnumber

The total hours the employee is expected to work over the period. For fixed-hours patterns, this is calculated from the workingPattern array. For flexible patterns (where workingPattern contains booleans), this specifies the total hours to be distributed across working days.
workingPatternboolean[] | number[]
The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either:
- An array of numbers representing hours worked per day (e.g. [8,8,8,8,8,0,0] for Mon-Fri 8h)
- An array of booleans for flexible patterns where true indicates a working day (e.g. [true,true,true,true,true,false,false] for Mon-Fri flexible)
isArchivedboolean

Whether the working pattern is archived.

Returns

Returns the working pattern if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/working-patterns/:id

curl https://app.humaans.io/api/working-patterns/MLYRjj1YdpuQp5Qe6HQsvUys \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"name":"Mon-Fri 8h/day"}'

Response

{
  "id": "MLYRjj1YdpuQp5Qe6HQsvUys",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "personId": null,
  "name": "Mon-Fri 8h/day",
  "summary": "Mon-Fri (8h)",
  "fullTimeHours": 40,
  "standardDayHours": 8,
  "periodType": "week",
  "workingHours": 40,
  "workingPattern": [
    8,
    8,
    8,
    8,
    8,
    0,
    0
  ],
  "fte": 1,
  "unroundedFte": 1,
  "archivedAt": "2020-01-28T08:44:42.000Z",
  "isArchived": false,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a working pattern

Permanently deletes a working pattern. It cannot be undone.

Parameters

No parameters

Returns

Returns an object confirming the deletion on success. Otherwise returns an error.

DELETE /api/working-patterns/:id

curl https://app.humaans.io/api/working-patterns/MLYRjj1YdpuQp5Qe6HQsvUys \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE

Response

{
  "id": "MLYRjj1YdpuQp5Qe6HQsvUys",
  "deleted": true
}

API Reference

Introduction

Authentication

Scopes

Scopes

public:read

private:read

private:write

compensations:read

compensations:write

documents:read

documents:write

webhooks:manage

Roles

Roles

Owner

Admin

Finance

Tech

Manager

User

Structure

Operations

GET /api/:resource

GET /api/:resource/:id

POST /api/:resource

PATCH /api/:resource/:id

DELETE /api/:resource/:id

Pagination

$limitnumber

$skipnumber

Filtering

string, number, boolean

$in, $nin

$gt, $gte

$lt, $lte

$or

Data warehouse

Rate limiting

Rate limit headers

X-RateLimit-Limit

X-RateLimit-Remaining

X-RateLimit-Policy

Retry-After

Avoiding rate limits

Errors

Error object

idstring

codenumber

namestring

messagestring

traceIdstring

subTypestring

issuesobject[]

issues[].namestring

issues[].reasonstring

issues[].indexnumber

issues[].entityIdstring

issues[].entityPathstring[]

issues[].issuesobject[]

Error codes

400BadRequest

401NotAuthenticated

403Forbidden

404NotFound

405MethodNotAllowed

409Conflict

413PayloadTooLarge

422ValidationError

422Unprocessable

422EmailTaken

429TooManyRequests

500GeneralError

502GeneralError

503GeneralError

Versioning

Webhooks

Bank accounts

Bank account object

Attributes

`string`, `number`, `boolean`

`$in`, `$nin`

`$gt`, `$gte`

`$lt`, `$lte`

`$or`