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 of their reports. Note, unlike other roles, this role can not be assigned to a user and is instead implied by the reporting lines.
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. And access to personal documents is only available to owner (and the employee) by default. Custom permissions can be set by to allow access to compensation and documents to admin and finance roles and managers.

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, offices and time away policies. And 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.

$limit number

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

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 of the list endpoints allow 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.

`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 all results where the value is more ($gt) or more and equal ($gte) to a given value.

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

`$lt`, `lte`

Find all results where the value is less ($lt) or less and equal ($lte) to 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

Errors

Humaans uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g. a required parameter was omitted). Codes in the 5xx range indicate an error with Humaans’s servers (these typically should not happen).

Error object

id string

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

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

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

A human readable description of the issue.
issues object[]

A list of validation errors. This key only exists for errors of type ValidationError.
issues[].name string

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

The reason why this field was invalid.
issues[].forbidden boolean

Indicates that this was an insufficient privilege issue.
issues[].index string

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

Error codes

401 NotAuthenticated

Missing or invalid access token
403 Forbidden

The provided access token does not have sufficient privileges
404 NotFound

The requested resource could not be found
405 MethodNotAllowed

The operation is not allowed for this resource
422 ValidationError

The request parameters are invalid
422 QueryParameterValidationError

The request query parameters are invalid
422 EmailTaken

Returned when a user is being re-onboarded, but their email is already taken
500 GeneralError

Unexpected issue, typically should not happen
502 BadGateway

Temporary availability issue
503 Unavailable

Temporary availability issue

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.

Resources

In the remaining sections of the documentation you will find a list of all resources you’ll find in Humaans API. For each resource we describe the list of endpoints available, the list of operations, their parameters, example payloads and response objects.

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

id string

Unique identifier for the object.
personId string

ID of the person that this object is associated to.
bankName string

The name of the bank.
nameOnAccount string

The name on the bank account.
accountNumber string

Bank account number.
swiftCode string

The swift code of the bank account if relevant.
sortCode string

The sort code of the bank account if relevant.
routingNumber string

The routing number of the bank account if relevant.
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-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

personId string | $in

The person to filter queries by.
$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of bank accounts. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate bank account object. If no bank accounts are available, the resulting list will be empty. This request should never return an error.

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

personId string required

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

The name of the bank.
nameOnAccount string | null

The name on the bank account.
accountNumber string | null

Bank account number.
swiftCode string | null

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

The sort code of the bank account if relevant.
routingNumber string | 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

bankName string | null

The name of the bank.
nameOnAccount string | null

The name on the bank account.
accountNumber string | null

Bank account number.
swiftCode string | null

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

The sort code of the bank account if relevant.
routingNumber string | 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

public.read

private.read

private.write

Company object

Attributes

id string

Unique identifier for the object.
name string

Company name.
domains object[]

The list of domains owned by the company.
domains.domain string

The domain
trialEndDate string, date

The last date of trial.
status string

One of terms, trialing, expired, active, suspended.
paymentStatus string

One of requires_action, past_due, ok.
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.
isTimesheetEnabled boolean

Describes whether the timesheet functionality is enabled.
logo file

The company logo
autogenerateEmployeeId boolean

Whether employee IDs are automatically generated
autogenerateEmployeeIdForNewHires boolean

Whether employee IDs are automatically generated for new hires
nextEmployeeId integer

The employee ID of the next employee to be created.

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
}

List all companies

Returns a list of companies.

Parameters

$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of companies. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate company object. If no companies are available, the resulting list will be empty. This request should never return an error.

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
    }
  ]
}

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
}

Update a company

Parameters

name string

Company name.
isTimesheetEnabled boolean

Describes whether the timesheet functionality is enabled.
autogenerateEmployeeId boolean

Whether employee IDs are automatically generated
autogenerateEmployeeIdForNewHires boolean

Whether employee IDs are automatically generated for new hires
nextEmployeeId integer | null

The employee ID of the next employee to be created.

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
}

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

id string

Unique identifier for the object.
companyId string

ID of the company that this object is associated to.
name string

The name of the compensation type.
baseType string

The base type of the compensation type. One of salary, bonus, commission, equity, custom
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.

compensation type object

{
  "id": "ldOQU3pLI5i8Y9k2rJbrXbFc",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Salary",
  "baseType": "salary",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all compensation types

Returns a list of compensation types.

Parameters

companyId string
$limit number

Limit number of results.
$skip number

Skip the specified number of results.
$sort object

Returns

Returns an object with a data property that contains a list of compensation types. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate compensation type object. If no compensation types are available, the resulting list will be empty. This request should never return an error.

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",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

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",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Compensations

An object representing compensation of an employee. Compensations come in several types: salary, bonus, commission and equity. 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

id string

Unique identifier for the object.
personId string

ID of the person that this object is associated to.
compensationTypeId string

ID of the Compensation type this compensation is related to.
amount string

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.
currency string

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

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

An optional note about this particular compensation entry.
effectiveDate string, date

The date when this compensation took effect. Can be a past or future date.
endDate string, date

Compensations of type bonus and commission can have an endDate to indicate they are no longer in effect.
endReason string

Compensations of type bonus and commission 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.
createdAt createdAt, date-time

Time at which the object was created.
updatedAt updatedAt, date-time

Time at which the object was last updated.

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

personId string | $in

The person to filter queries by.
compensationTypeId string

The compensation type’s id to filter the queries by.
$asOf string, date

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.
$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of compensations. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate compensation object. If no compensations are available, the resulting list will be empty. This request should never return an error.

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

personId string required

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

ID of the Compensation type this compensation is related to.
amount string 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.
currency string | null

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

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

An optional note about this particular compensation entry.
effectiveDate string, date required

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

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

Compensations of type bonus and commission 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 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

compensationTypeId string

ID of the Compensation type this compensation is related to.
amount string

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.
currency string | null

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

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

An optional note about this particular compensation entry.
effectiveDate string, date

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

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

Compensations of type bonus and commission 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 it’s 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

id string

Unique identifier for the object.
companyId string

ID of the company that this object is associated to.
name string

The name of the custom field.
section string

The profile section where the custom field will appear in.
type string

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

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[] }
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.

custom field object

{
  "id": "ZpbLXlJRpBJQOre5kbFQqYf4",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Payroll code",
  "section": "employment",
  "type": "Laptop",
  "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

section string | $in | $nin

The profile section where the custom field will appear in.
type string | $in | $nin

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

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of custom fields. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate custom field object. If no custom fields are available, the resulting list will be empty. This request should never return an error.

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",
      "type": "Laptop",
      "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",
  "type": "Laptop",
  "config": "{}",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a custom field

Parameters

name string required

The name of the custom field.
section string required

The profile section where the custom field will appear in.
type string required

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

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":"Laptop","section":"employment"}'

Response

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

Update a custom field

Parameters

name string

The name of the custom field.
config object

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",
  "type": "Laptop",
  "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

id string

Unique identifier for the object.
personId string

ID of the person that this object is associated to.
customFieldId string

The ID of the custom field this value is for.
resourceId string

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 sectionis equipment.
value string | 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.
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.

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

personId string

The person to filter queries by.
customFieldId string | $in | $nin

The custom field to filter queries by.
resourceId string | $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 sectionis equipment.
createdAt object

Filter custom values by created at date.
createdAt.$gt date | date-time
createdAt.$gte date | date-time
createdAt.$lt date | date-time
createdAt.$lte date | date-time
updatedAt object

Filter custom values by updated at date.
updatedAt.$gt date | date-time
updatedAt.$gte date | date-time
updatedAt.$lt date | date-time
updatedAt.$lte date | date-time
$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of custom values. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate custom value object. If no custom values are available, the resulting list will be empty. This request should never return an error.

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

value string | 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.
personId string required

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

The ID of the custom field this value is for.
resourceId string | 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 sectionis 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

value string | 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 allowed. Depending on which fields you’d like to export, use one of public.read, private.read or compensation.read.

Data export object

Attributes

id string

Unique identifier for the object.
companyId string

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

The URL from which exported data file can be downloaded.
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.
dataExportTemplateId

Data export template used for this export

data export object

{
  "id": "yQYtUaI6LeTc1Ss5S0FgInPo",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "url": "/data-exports/dPnhSGDoq9UUR9Bf1BwPPkjC",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

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",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

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

fields string[]

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, teams, placeOfWork, fullPlaceOfWork, isRemote, payrollProvider, contractType, employeeId, taxId, taxCode, employeeStatus, employmentStartDate, firstWorkingDay, workingDays, workingPattern, fte, probationEndDate, employmentEndDate, lastWorkingDay, leavingReason, turnoverImpact, leavingNote, bankName, nameOnAccount, accountNumber, swiftCode, sortCode, routingNumber, salary, bonus, equity, commission, paidTimeOff, unpaidLeave, sickLeave, parentalLeave, workingFromHome, otherTimeAway, approvalFlow, allowance, fromPrevAccrualPeriod, fromPrevAccrualPeriodExpired, carriedOver, adjustments, accrued, 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, teams, placeOfWork, isRemote, payrollProvider, contractType, employeeId, employeeStatus, employmentStartDate, firstWorkingDay, workingDays, workingPattern, fte, 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, jobTitle, department, manager, managerPreferredName, managerEmail, roleEffectiveDate, teams, placeOfWork, isRemote, payrollProvider, contractType, employeeId, employeeStatus, employmentStartDate, firstWorkingDay, workingDays, workingPattern, fte, 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, teams, placeOfWork, isRemote, payrollProvider, contractType, employeeId, employeeStatus, employmentStartDate, firstWorkingDay, workingDays, workingPattern, fte, 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, teams, placeOfWork, isRemote, payrollProvider, contractType, employeeId, employeeStatus, employmentStartDate, firstWorkingDay, workingDays, workingPattern, fte, probationEndDate, employmentEndDate, lastWorkingDay, leavingReason, turnoverImpact, leavingNote, type, name, issueDate, link, documentLink, uploader, uploaderEmail. Available fields for export type identityDocument: firstName, preferredName, middleName, lastName, gender, email, phoneNumber, personalEmail, personalPhoneNumber, fullAddress, country, jobTitle, department, manager, managerPreferredName, managerEmail, roleEffectiveDate, teams, placeOfWork, isRemote, payrollProvider, contractType, employeeId, employeeStatus, employmentStartDate, firstWorkingDay, workingDays, workingPattern, fte, probationEndDate, employmentEndDate, lastWorkingDay, leavingReason, turnoverImpact, leavingNote, type, number, expiryDate, note, issueCountry, link, verifier, verifierEmail.
customFields string[]

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

The list of time away type IDs that should be included in the data export.
compensationTypes string[]

The list of compensation type IDs that should be included in the data export.
startDate string, date

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.
endDate string, date

The end date of the data export.
includeOffboarded boolean

Set to true to include offboarded people in the data export.
includeRoleHistory boolean

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.
includeCompensationHistory boolean

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.
includeWithoutEquipment boolean

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

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

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

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

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

The type of export, one of people, equipment, timeAway, timesheet, document or identityDocument. Default: people.
json boolean

Generate the output in JSON format instead of CSV
download boolean

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.
dataExportTemplateId string

Data export template used for this export
includeNewHires

Set to false to exclude new hires in the data export. By default true

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",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

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

Required scopes

documents.read

documents.write

Document type object

Attributes

id string

Unique identifier for the object.
companyId string

ID of the company that this object is associated to.
name string

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.
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.

document type object

{
  "id": "Ozcv1Wea2yfUhSm8fsj0ziIf",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "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

$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of document types. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate document type object. If no document types are available, the resulting list will be empty. This request should never return an error.

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",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "Employment agreement",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Create a document type

Parameters

name string 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",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Employment agreement",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a document type

Parameters

name string 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",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Employment agreement",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

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

id string

Unique identifier for the object.
companyId string

ID of the company that this object is associated to.
personId string

ID of the person that this object is associated to.
name string

The name of the document
documentTypeId string

The ID of the document type.
link string

Documents must have either a link or a file attached.
fileId string

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

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

Unique identifier for the object.
file.url string

The URL from which the attached file can be downloaded.
file.filename string

The name of the file attached.
source string

The external service from which the document has been imported
sourceId string

The unique identifier of the document in the remote service
issueDate string, date

The date when the document was issued.
createdBy string

ID of the user who created the document
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.

document object

{
  "id": "j5nMguwlwQeNYkk9Jie8u1Q2",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "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

personId string | empty

ID of the person that this object is associated to. Pass the parameter with no value to retrieve company wide documents.
$or object[]

Filter by multiple conditions.
$or.personId string | 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]=
$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of documents. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate document object. If no documents are available, the resulting list will be empty. This request should never return an error.

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",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "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",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "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

personId string | null

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

The name of the document
documentTypeId string

The ID of the document type.
link string | null

Documents must have either a link or a file attached.
fileId string | null

Documents must have either a link or a file attached.
issueDate string, date

The date when the document was issued.
type string

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",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "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

name string

The name of the document
documentTypeId string

The ID of the document type.
issueDate string, date

The date when the document was issued.
type string

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",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "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

id string

Unique identifier for the object.
personId string

ID of the person that this object is associated to.
name string

The name of the emergency contact.
email string

The email of the emergency contact.
phoneNumber string

The phone number of the emergency contact.
formattedPhoneNumber string

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

The relationship of the emergency contact to the employee.
isPrimary boolean

Indicates the primary emergency contact. Only one emergency can be primary.
createdAt createdAt, date-time

Time at which the object was created.
updatedAt updatedAt, date-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

isPrimary boolean

Indicates the primary emergency contact. Only one emergency can be primary.
personId string | $in

The person to filter queries by.
$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of emergency contacts. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate emergency contact object. If no emergency contacts are available, the resulting list will be empty. This request should never return an error.

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

name string | null

The name of the emergency contact.
email string | null

The email of the emergency contact.
phoneNumber string | null

The phone number of the emergency contact.
relationship string | null

The relationship of the emergency contact to the employee.
personId string required

ID of the person that this object is associated to.
isPrimary boolean

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"}'

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

name string | null

The name of the emergency contact.
email string | null

The email of the emergency contact.
phoneNumber string | null

The phone number of the emergency contact.
relationship string | 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

id string

Unique identifier for the object.
personId string

ID of the person that this object is associated to.
type string

The type of the equipment.
name string

The name / model on the equipment.
serialNumber string

The serial number.
cost string

Cost, the fraction should be separated with a dot.
currency string

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

Any additional notes.
fileId string

A file attachment.
file

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

The URL from which the attached file can be downloaded.
file.filename string

The name of the file attached.
issueDate string, date

The date when the equipment was issued.
receiptDate string, date

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

The date when the equipment was collected from the employee.
collectedBy string

The person that marked the equipment as collected.
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.

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

personId string

The person to filter queries by.
$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of equipment. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate equipment object. If no equipment are available, the resulting list will be empty. This request should never return an error.

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

personId string required

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

The type of the equipment.
name string required

The name / model on the equipment.
serialNumber string | null

The serial number.
cost string | null

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

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

Any additional notes.
fileId string | null

A file attachment.
issueDate string, date required

The date when the equipment was issued.
receiptDate string, date | null

The date when the equipment was received by the employee, if different from issue date.
collectionDate string, date | 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

type string

The type of the equipment.
name string

The name / model on the equipment.
serialNumber string | null

The serial number.
cost string | null

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

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

Any additional notes.
fileId string | null

A file attachment.
issueDate string, date

The date when the equipment was issued.
receiptDate string, date | null

The date when the equipment was received by the employee, if different from issue date.
collectionDate string, date | 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

id string

Unique identifier for the object.
companyId string

ID of the company that this object is associated to.
value string

The label of the equipment name.
isDefault boolean

Whether this name is the default name provided by Humaans.
isUsed boolean

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

$limit number

Limit number of results.
$skip number

Skip the specified number of results.
type string

Filter the equipment names by equipment type.

Returns

Returns an object with a data property that contains a list of equipment names. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate equipment name object. If no equipment names are available, the resulting list will be empty. This request should never return an error.

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

id string

Unique identifier for the object.
companyId string

ID of the company that this object is associated to.
value string

The label of the equipment type.
isDefault boolean

Whether this type is the default type provided by Humaans.
isUsed boolean

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

$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of equipment types. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate equipment type object. If no equipment types are available, the resulting list will be empty. This request should never return an error.

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

id string

Unique identifier for the object.
companyId string

ID of the company that this object is associated to.
personId string

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.
type string

The type of the file indicating what kind or resource the file is attached to. One of profilePhoto, identityDocument, document, equipment or leavingFile.
uploadedBy string

The ID of the person who uploaded this file.
filename string

The original filename of the uploaded file.
url string

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.
variants object

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.64 string

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

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

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

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

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

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

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

URL of one of the predefined 3x photo sizes.
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.

file object

{
  "id": "UJx97ZPPgz2EncFbxXIQkxEq",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "document",
  "uploadedBy": "AfcpS6HbVjoXdMLZ6aF4Sfad",
  "filename": "employment-aggrement-kw-2020.pdf",
  "url": "https://app.humaans.io/file/UJx97ZPPgz2EncFbxXIQkxEq",
  "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-aggrement-kw-2020.pdf",
  "url": "https://app.humaans.io/file/UJx97ZPPgz2EncFbxXIQkxEq",
  "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

personId string | 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.
type string required

The type of the file indicating what kind or resource the file is attached to. One of profilePhoto, identityDocument, document, equipment or leavingFile.

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-aggrement-kw-2020.pdf",
  "url": "https://app.humaans.io/file/UJx97ZPPgz2EncFbxXIQkxEq",
  "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

id string

Unique identifier for the object.
companyId string

ID of the company that this object is associated to.
value string

The label of the identity document type.

identity document type object

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

List all identity document types

Returns a list of identity document types.

Parameters

$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of identity document types. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate identity document type object. If no identity document types are available, the resulting list will be empty. This request should never return an error.

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",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "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

id string

Unique identifier for the object.
personId string

ID of the person that this object is associated to.
type string

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

The number of the identification document as specified on the document.
countryCode string

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

Expiry date of the document.
note string

An optional note about the identity document.
fileId string

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

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

Unique identifier for the object.
file.url string

The URL from which the attached file can be downloaded.
file.filename string

The name of the file attached.
verifiedBy string

The ID of the person that varified the legitimacy of this identity document.
verifiedAt string, date-time

The date and time when this this identity document was verified.
isVerified boolean

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.
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-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

personId string

The person to filter queries by.
$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of identity documents. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate identity document object. If no identity documents are available, the resulting list will be empty. This request should never return an error.

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

personId string required

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

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

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

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

Expiry date of the document.
note string | null

An optional note about the identity document.
fileId string required

The ID of the file attached to this identity document.
verifiedBy string | 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

type string

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

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

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

Expiry date of the document.
note string | null

An optional note about the identity document.
fileId string

The ID of the file attached to this identity document.
verifiedBy string | 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 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

public.read

private.read

private.write

Job role object

Attributes

id string

Unique identifier for the object.
personId string

ID of the person that this object is associated to.
jobTitle string

Job title.
department string

The name of the department.
effectiveDate string, date

The date when this role took effect. Can be a past or future date.
endDate string, date

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

Whether this is the first job role for this person.
reportingTo string

The ID of the manager.
note string

An optional note about this particular job role entry.
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.

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",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all job roles

Returns a list of job roles.

Parameters

personId string

The person to filter queries by.
$asOf string, date

Filter the list of roles to only per employee, finding the job role that was in effect on the provided date.
$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of job roles. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate job role object. If no job roles are available, the resulting list will be empty. This request should never return an error.

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",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

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",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

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

personId string required

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

Job title.
department string | null

The name of the department.
effectiveDate string, date required

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

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

The ID of the manager.

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",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

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

jobTitle string

Job title.
department string | null

The name of the department.
effectiveDate string, date

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

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

The ID of the manager.

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",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

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

id string

Unique identifier for the object.
companyId string

ID of the company that this object is associated to.
label string

A label for this location that is used to refer to the location.
displayName string
address string

A street address of the location.
postcode string

Postcode.
city string

City.
state string

State.
country string

Country name, infered from the countryCode.
regionCode string

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

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

Timezone, infered from the city and country.
isAddressInvalid boolean

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

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.
timeAwayPolicyEffectiveDate string, date

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

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.
workingPatternEffectiveDate string, date

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

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.

location object

{
  "id": "oIBBB436k2YCOY5gzVhC5idx",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "label": "Acme HQ",
  "displayName": "Acme HQ",
  "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

$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of locations. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate location object. If no locations are available, the resulting list will be empty. This request should never return an error.

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",
      "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",
  "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

address string | null

A street address of the location.
city string required

City.
state string | null

State.
postcode string | null

Postcode.
countryCode string required

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

A label for this location that is used to refer to the location.
timeAwayPolicyId string 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.
timeAwayPolicyEffectiveDate string, date | null

When provided, time away policy changes will be effective from this date.
workingPatternId string | 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.
workingPatternEffectiveDate string, date | 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",
  "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

address string | null

A street address of the location.
city string

City.
state string | null

State.
postcode string | null

Postcode.
countryCode string

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

A label for this location that is used to refer to the location.
timeAwayPolicyId string

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.
timeAwayPolicyEffectiveDate string, date | null

When provided, time away policy changes will be effective from this date.
workingPatternId string | 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.
workingPatternEffectiveDate string, date | null

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

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",
  "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

public.read

private.read

Me object

Attributes

id string

Unique identifier for the object.
companyId string

ID of the company that this object is associated to.
firstName string

First name.
middleName string

Middle name.
lastName string

Last name.
preferredName string

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

Preferred pronouns that the person goes by
email string

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

The job role details of this person.
locationId string

The ID of the location this person works at. Note, it can be either and ID of the location or a 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.
remoteCity string

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

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.
remoteCountryCode string

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.
remoteTimezone string

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.
timeAwayApprovalFlowId string

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

Personal email of the person.
phoneNumber string

Work phone number of the person.
formattedPhoneNumber string

Work phone number of the person formatted for display.
personalPhoneNumber string

Personal phone number of the person.
formattedPersonalPhoneNumber string

Personal phone number of the person formatted for display.
gender string

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

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

ID of the profile picture file.
profilePhoto object

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 unresized file via the api/files.
profilePhoto.id string

Unique identifier for the object.
profilePhoto.variants object

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

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

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

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

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

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

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

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

URL of one of the predefined 3x profile photo sizes.
nationality string

Nationality.
nationalities string[]

Nationalities.
spokenLanguages string[]

Spoken languages.
dietaryPreference string

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

A list of food allergies.
address string

Street address component of the person’s home address.
city string

City component of the persons home address.
state string

Optional state component of the persons home address.
postcode string

Postcode component of the persons home address.
countryCode string

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

Country name, infered from the countryCode.
bio string

An optional description about the person.
linkedIn string

LinkedIn handle
twitter string

Twitter handle
github string

GitHub handle
employmentStartDate string, date

Employment start date.
firstWorkingDay string, date

The first day at work. Defaults to employmentStartDate if not specified.
employmentEndDate string, date

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

The last day at work. Defaults to employmentEndDate if not specified.
probationEndDate string, date

Probation end date.
turnoverImpact string

Turnover impact set for offboarded people. One of regrettable, non-regrettable or “not applicable”.
workingDays object[]

A list of days worked by the employee.
workingDays.day string

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

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

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

Leaving note set for offboarded people.
leavingFileId string

Leaving file id attached to offboarded people.
contractType string

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

Employee ID as used by the company.
taxId string

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

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

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

Name of the team
status string

One of active, offboarded or newHire.
isVerified boolean

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

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

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.
role string
seenDocumentsAt string, date-time

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

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.
sourceId string

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

Timezone, derived from the remote timezone, location timezone, or company timezone.
payrollProvider string

The label or identifier of the payroll provider used to process payroll for this employee.
firstActiveAt string, date-time

Timestamp the person became an active member
isBirthdayHidden boolean

Whether this person has opted out from birthday announcements.
demo boolean

Whether this user is a demo user
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.

me object

{
  "id": "vHS9r3ZBBx1IWO3kUbEoCmmd",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "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",
    "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,
  "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/vHS9r3ZBBx1IWO3kUbEoCmmd \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'

Response

{
  "id": "vHS9r3ZBBx1IWO3kUbEoCmmd",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "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",
    "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,
  "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"
}

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

public.read

private.read

private.write

Person object

Attributes

id string

Unique identifier for the object.
companyId string

ID of the company that this object is associated to.
firstName string

First name.
middleName string

Middle name.
lastName string

Last name.
preferredName string

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

Preferred pronouns that the person goes by
email string

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

The job role details of this person.
locationId string

The ID of the location this person works at. Note, it can be either and ID of the location or a 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.
remoteCity string

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

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.
remoteCountryCode string

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.
remoteTimezone string

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.
timeAwayApprovalFlowId string

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

Personal email of the person.
phoneNumber string

Work phone number of the person.
formattedPhoneNumber string

Work phone number of the person formatted for display.
personalPhoneNumber string

Personal phone number of the person.
formattedPersonalPhoneNumber string

Personal phone number of the person formatted for display.
gender string

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

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

ID of the profile picture file.
profilePhoto object

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 unresized file via the api/files.
profilePhoto.id string

Unique identifier for the object.
profilePhoto.variants object

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

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

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

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

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

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

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

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

URL of one of the predefined 3x profile photo sizes.
nationality string

Nationality.
nationalities string[]

Nationalities.
spokenLanguages string[]

Spoken languages.
dietaryPreference string

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

A list of food allergies.
address string

Street address component of the person’s home address.
city string

City component of the persons home address.
state string

Optional state component of the persons home address.
postcode string

Postcode component of the persons home address.
countryCode string

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

Country name, infered from the countryCode.
bio string

An optional description about the person.
linkedIn string

LinkedIn handle
twitter string

Twitter handle
github string

GitHub handle
employmentStartDate string, date

Employment start date.
firstWorkingDay string, date

The first day at work. Defaults to employmentStartDate if not specified.
employmentEndDate string, date

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

The last day at work. Defaults to employmentEndDate if not specified.
probationEndDate string, date

Probation end date.
turnoverImpact string

Turnover impact set for offboarded people. One of regrettable, non-regrettable or “not applicable”.
workingDays object[]

A list of days worked by the employee.
workingDays.day string

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

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

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

Leaving note set for offboarded people.
leavingFileId string

Leaving file id attached to offboarded people.
contractType string

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

Employee ID as used by the company.
taxId string

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

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

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

Name of the team
status string

One of active, offboarded or newHire.
isVerified boolean

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

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

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.
role string
seenDocumentsAt string, date-time

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

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.
sourceId string

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

Timezone, derived from the remote timezone, location timezone, or company timezone.
payrollProvider string

The label or identifier of the payroll provider used to process payroll for this employee.
firstActiveAt string, date-time

Timestamp the person became an active member
isBirthdayHidden boolean

Whether this person has opted out from birthday announcements.
demo boolean

Whether this user is a demo user
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.

person object

{
  "id": "VMB1yzL5uL8VvNNCJc9rykJz",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "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",
    "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,
  "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

email string

Filter people by work email address.
status string | $in

Filter people by status, one of all, newHire, active, offboarded. Default: active.
createdAt object

Filter people by created at date.
createdAt.$gt date | date-time
createdAt.$gte date | date-time
createdAt.$lt date | date-time
createdAt.$lte date | date-time
updatedAt object

Filter people by updated at date.
updatedAt.$gt date | date-time
updatedAt.$gte date | date-time
updatedAt.$lt date | date-time
updatedAt.$lte date | date-time
$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of people. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate person object. If no people are available, the resulting list will be empty. This request should never return an error.

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",
      "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",
        "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,
      "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",
  "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",
    "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,
  "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

firstName string required

First name.
middleName string | null

Middle name.
lastName string required

Last name.
preferredName string | null

Preferred first name that the person goes by. This will be shown Humaans instead of the first name if set.
pronouns string | null

Preferred pronouns that the person goes by
email string required

The work email of the person. The email they use to log in.
personalEmail string | null

Personal email of the person.
phoneNumber string | null

Work phone number of the person.
personalPhoneNumber string | null

Personal phone number of the person.
gender string | null

Person’s gender. It’s a free form field, any value is allowed.
birthday string, date | null

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

Whether this person has opted out from birthday announcements.
profilePhotoId string | null

ID of the profile picture file.
nationality string | null

Nationality.
nationalities string[] | null

Nationalities.
spokenLanguages string[] | null

Spoken languages.
dietaryPreference string | null

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

A list of food allergies.
address string | null

Street address component of the person’s home address.
city string | null

City component of the persons home address.
state string | null

Optional state component of the persons home address.
postcode string | null

Postcode component of the persons home address.
countryCode string | null

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

An optional description about the person.
linkedIn string | null

LinkedIn handle
twitter string | null

Twitter handle
github string | null

GitHub handle
employmentStartDate string, date required

Employment start date.
firstWorkingDay string, date

The first day at work. Defaults to employmentStartDate if not specified.
employmentEndDate string, date | null

Employment end date. If this date is in the past, this employee is considered to be offboarded and inactive.
lastWorkingDay string, date | null

The last day at work. Defaults to employmentEndDate if not specified.
probationEndDate string, date | null

Probation end date.
workingDays object[] | null

A list of days worked by the employee.
workingDays.day string

A day of the week. One of: monday, tuesday, wednesday, thursday, friday, saturday, sunday,
turnoverImpact string | null

Turnover impact set for offboarded people. One of regrettable, non-regrettable or “not applicable”.
leavingReason string | null

Leaving reason set for offboarded people. One of dismissed, resigned, redundancy, contractEnded, other.
leavingNote string | null

Leaving note set for offboarded people.
leavingFileId string | null

Leaving file id attached to offboarded people.
contractType string | null

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

The label or identifier of the payroll provider used to process payroll for this employee.
employeeId string | null

Employee ID as used by the company.
taxId string | null

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

The local tax code / tax number frequently used for payroll purposes.
locationId string required

The ID of the location this person works at. Note, it can be either and ID of the location or a 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.
remoteCity string | null

When locationId is set to remote, this indicates the city that this person works in.
remoteCountryCode string | 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.
timeAwayApprovalFlowId string

The Id of the time away approval flow this person works under.
teams object[]

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

Name of the team
status string

One of active, offboarded or newHire.
isWorkEmailHidden boolean

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

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.
seenDocumentsAt string, date-time

The last time the person has looked at their personal documents.
publicHolidayCalendarId string | null

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

The job role details of this person.
jobRole.jobTitle string required

Job title.
jobRole.department string | null

Department name.
jobRole.reportingTo string | null

The ID of the user this person reports to.
timeAwayAllocation object

The time away policy for this person.
timeAwayAllocation.timeAwayPolicyId string 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",
  "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",
    "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,
  "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

firstName string

First name.
middleName string | null

Middle name.
lastName string

Last name.
preferredName string | null

Preferred first name that the person goes by. This will be shown Humaans instead of the first name if set.
pronouns string | null

Preferred pronouns that the person goes by
email string | null

The work email of the person. The email they use to log in.
personalEmail string | null

Personal email of the person.
phoneNumber string | null

Work phone number of the person.
personalPhoneNumber string | null

Personal phone number of the person.
gender string | null

Person’s gender. It’s a free form field, any value is allowed.
birthday string, date | null

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

Whether this person has opted out from birthday announcements.
profilePhotoId string | null

ID of the profile picture file.
nationality string | null

Nationality.
nationalities string[] | null

Nationalities.
spokenLanguages string[] | null

Spoken languages.
dietaryPreference string | null

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

A list of food allergies.
address string | null

Street address component of the person’s home address.
city string | null

City component of the persons home address.
state string | null

Optional state component of the persons home address.
postcode string | null

Postcode component of the persons home address.
countryCode string | null

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

An optional description about the person.
linkedIn string | null

LinkedIn handle
twitter string | null

Twitter handle
github string | null

GitHub handle
employmentStartDate string, date

Employment start date.
firstWorkingDay string, date

The first day at work. Defaults to employmentStartDate if not specified.
employmentEndDate string, date | null

Employment end date. If this date is in the past, this employee is considered to be offboarded and inactive.
lastWorkingDay string, date | null

The last day at work. Defaults to employmentEndDate if not specified.
probationEndDate string, date | null

Probation end date.
workingDays object[] | null

A list of days worked by the employee.
workingDays.day string

A day of the week. One of: monday, tuesday, wednesday, thursday, friday, saturday, sunday,
turnoverImpact string | null

Turnover impact set for offboarded people. One of regrettable, non-regrettable or “not applicable”.
leavingReason string | null

Leaving reason set for offboarded people. One of dismissed, resigned, redundancy, contractEnded, other.
leavingNote string | null

Leaving note set for offboarded people.
leavingFileId string | null

Leaving file id attached to offboarded people.
contractType string | null

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

The label or identifier of the payroll provider used to process payroll for this employee.
employeeId string | null

Employee ID as used by the company.
taxId string | null

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

The local tax code / tax number frequently used for payroll purposes.
locationId string

The ID of the location this person works at. Note, it can be either and ID of the location or a 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.
remoteCity string | null

When locationId is set to remote, this indicates the city that this person works in.
remoteCountryCode string | 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.
timeAwayApprovalFlowId string

The Id of the time away approval flow this person works under.
teams object[]

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

Name of the team
status string

One of active, offboarded or newHire.
isWorkEmailHidden boolean

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

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.
seenDocumentsAt string, date-time

The last time the person has looked at their personal documents.
publicHolidayCalendarId string | 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",
  "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",
    "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,
  "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
}

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

id string

Unique identifier for the object.
companyId string

ID of the company that this object is associated to.
name string

The name of the calendar, combination of country and region.
countryCode string

The country code.
country string

The country label.
regionCode string

The region code.
region string

The country label.
dayCount number

The number of public holidays in this calendar in the current calendar year.
sourcePublicHolidayCalendarId string

The ID of the calendar used to initially populate this calendar
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.

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

id string | $in | $nin

Filter by the public holiday calendar ID.
$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of public holiday calendars. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate public holiday calendar object. If no public holiday calendars are available, the resulting list will be empty. This request should never return an error.

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

id string

Unique identifier for the object.
date string

The date of the public holiday.
name string

The name of the public holiday.
publicHolidayCalendarId string

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

publicHolidayCalendarId string | $in | $nin required

Filter by the public holiday calendar ID.
date date | $gt | $lt | $gte | $lte required

Filter holidays by date.
$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of public holidays. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate public holiday object. If no public holidays are available, the resulting list will be empty. This request should never return an error.

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"
    }
  ]
}

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

public.read

private.read

private.write

Time away object

Attributes

id string

Unique identifier for the object.
personId string

ID of the person that this object is associated to.
startDate string, date

The first date of the time away entry (inclusive).
startPeriod string

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.
endDate string, date

The last date of the time away entry (inclusive).
endPeriod string

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.
timeAwayTypeId string

ID of the Time away type this entry is attached to.
name string

A human readable label of the time away entry type.
isTimeOff boolean

true if the type is one of the time off types, as opposed to one of the working away types.
workingFromLocationId string

When type (or reason) of the time away entry is workingFromAnotherLocation this field indicates the id of the location the person was working from.
note string

An optional note about the time off entry. Only visible to the employee, their manager and admins.
breakdown object[]

A day by day breakdown of the time away entry. Useful for inspecting which days count towards the balance.
breakdown.date string, date

The date.
breakdown.period string | number

One of: full, am, pm.
breakdown.hours number
breakdown.weekend boolean

True if the day is on a non-working day as defined by person.workingDays.
breakdown.holiday boolean

True if the day is a public holiday.
breakdown.fteDay number

Amount of day accounted for FTE.
days number

The number of total days this entry spans, taking into account half days, weekends and holidays based on the policy configuration.
requestStatus string

If time away approvals are required, one of pending, approved, declined. Will be approved if time away approvals are not required.
requestedBy string

The ID of the person that made this request.
reviewedBy string

The ID of the person that reviewed this request.
reviewedAt string, date-time

The date and time when this request was reviewed.
reviewNote string

A note to accompany a time away review.
publicHolidayCalendarId string

The public holiday calendar ID that was in use when creating this time away entry.
workingDays object[]

The person’s working days schedule at the time of booking time away
workingDays.day string

A day of the week.
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.
timezone string

The timezone of the personId when the booking was made

time away object

{
  "id": "YLlqHE4DLvGtFJ7L2qro6bTF",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "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.

Parameters

personId string | $in

The person to filter queries by.
personStatus string | $in

The person status to filter queries by.
startDate date | $gt | $gte | $lt | $lte

Filter by start date.
endDate date | $gt | $gte | $lt | $lte

Filter by end date.
timeAwayTypeId string

Filter by the time away type
requestStatus string | $in

Filter by request status. Useful when time away approvals are enabled.
$sort object
$sort.startDate number
$sort.endDate number
$sort.createdAt number
$or object[]

Filter results by multiple criteria.
$or.personId string | $in

The person to filter queries by.
$or.personStatus string | $in

The person status to filter queries by.
$or.startDate date | $gt | $gte | $lt | $lte

Filter by start date.
$or.endDate date | $gt | $gte | $lt | $lte

Filter by end date.
$or.type string
$or.timeAwayTypeId string

Filter by the time away type
$or.requestStatus string | $in

Filter by request status. Useful when time away approvals are enabled.
$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of time away. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate time away object. If no time away are available, the resulting list will be empty. This request should never return an error.

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",
      "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",
  "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

personId string required

ID of the person that this object is associated to.
startDate string, date required

The first date of the time away entry (inclusive).
endDate string, date required

The last date of the time away entry (inclusive).
startPeriod string | null

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.
endPeriod string | null

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.
note string | null

An optional note about the time off entry. Only visible to the employee, their manager and admins.
workingFromLocationId string | 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.
timeAwayTypeId string required

ID of the Time away type this entry is attached to.
requestStatus string

If time away approvals are required, one of pending, approved, declined. Will be approved if time away approvals are not required.
reviewNote string

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",
  "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

startDate string, date

The first date of the time away entry (inclusive).
endDate string, date

The last date of the time away entry (inclusive).
startPeriod string | null

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.
endPeriod string | null

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.
note string | null

An optional note about the time off entry. Only visible to the employee, their manager and admins.
workingFromLocationId string | 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.
timeAwayTypeId string

ID of the Time away type this entry is attached to.
requestStatus string

If time away approvals are required, one of pending, approved, declined. Will be approved if time away approvals are not required.
reviewNote string

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",
  "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

id string

Unique identifier for the object.
personId string

ID of the person that this object is associated to.
date string, date

The date when the adjustment was granted.
deltaAmount number

The time that should be added to the allowance. Negative number will reduce the allowance.
unit string

The unit of the time away adjustment. Negative number will reduce the allowance.
reason string

A note describing the reason for this adjustment.
validUntil string, date

The date when the adjustment expires.
timeAwayTypeId string

ID of the Time away type this adjustment is attached to.
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.

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

$sort object
$sort.date number
$sort.createdAt number
personId string | $in

The person to filter queries by.
date date | $gt | $gte | $lt | $lte

Filter by end date.
$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of time away adjustments. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate time away adjustment object. If no time away adjustments are available, the resulting list will be empty. This request should never return an error.

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

personId string required

ID of the person that this object is associated to.
date string, date required

The date when the adjustment was granted.
deltaAmount number

The time that should be added to the allowance. Negative number will reduce the allowance.
unit string

The unit of the time away adjustment. Negative number will reduce the allowance.
reason string required

A note describing the reason for this adjustment.
validUntil string, date | null

The date when the adjustment expires.
timeAwayTypeId string 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

date string, date

The date when the adjustment was granted.
deltaAmount number

The time that should be added to the allowance. Negative number will reduce the allowance.
unit string

The unit of the time away adjustment. Negative number will reduce the allowance.
reason string

A note describing the reason for this adjustment.
validUntil string, date | null

The date when the adjustment expires.
timeAwayTypeId string

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 in cases when the company is changing it’s time of 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

id string

Unique identifier for the object.
personId string

ID of the person that this object is associated to.
type string

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.
effectiveDate string, date

The first day when the allocation is in effect.
timeAwayPolicyId string

The ID of the time away policy used by this allocation.
timeAwayPolicy time 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.
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-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,
            "usage": "upfront",
            "usagePeriod": 12,
            "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

personId string

The person to filter queries by.
isCurrent boolean

Return the current allocation only.
$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of time away allocations. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate time away allocation object. If no time away allocations are available, the resulting list will be empty. This request should never return an error.

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,
                "usage": "upfront",
                "usagePeriod": 12,
                "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,
            "usage": "upfront",
            "usagePeriod": 12,
            "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

personId string required

ID of the person that this object is associated to.
type string 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.
effectiveDate string, date | null required

The first day when the allocation is in effect.
timeAwayPolicyId string

The ID of the time away policy used by this allocation.
timeAwayPolicy time 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.
removeAllocations boolean

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,
            "usage": "upfront",
            "usagePeriod": 12,
            "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

type string

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.
effectiveDate string, date | null

The first day when the allocation is in effect.
timeAwayPolicyId string

The ID of the time away policy used by this allocation.
timeAwayPolicy time 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.

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,
            "usage": "upfront",
            "usagePeriod": 12,
            "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

id string

Unique identifier for the object.
personId string

ID of the person that this object is associated to.
startDate string, date

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.
endDate string, date

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.
usageEndDate string, date

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.
timeAwayAllocation time away allocation

The time away allocation used in this period.
timeAwayTypeId string

The id of the type this period data refers to
isCurrentPeriod boolean

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.
isFinalPeriod boolean

true means this is the final period, which holds the final balance of an offboarded employee.
hasAllocationChanged boolean

true means that this period has a new time away allocation and policy compared to the previous period.
isCarriedOverInFull boolean

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.
isProrated boolean

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.
accrued number

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.
allowance number

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.
fromPrevAccrualPeriod integer

The number of days available from the prev accrual period that are still available to be used.
fromPrevAccrualPeriodValidUntilDate string, date

The date at which fromPrevAccrualPeriod is valid until.
fromPrevAccrualPeriodExpired integer

The number of days from fromPrevAccrualPeriod that has expired in this period.
carriedOver number

The number of days that have been carried over from the previous period. Calculated based on the allocation assigned to this period.
carriedOverDate string, date

The date at which carriedOver is applied.
adjustments number

The sum of all adjustments (negative and positive) made in this period excluding upcoming adjustments in the case of the current period.
adjustmentsUpcoming number

The sum of all upcoming adjustments (negative and positive) made in this period. Always 0 if this is not the current period.
used number

The number of approved days already used up in this period, excluding upcoming days off.
pending number

The number of pending days already used up in this period, excluding upcoming days off.
upcoming number

The number of approved days upcoming in this period. Always 0 if this is not the current period.
upcomingPending number

The number of pending days upcoming in this period. Always 0 if this is not the current period.
balance number

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.
endingBalance number

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,
              "usage": "upfront",
              "usagePeriod": 12,
              "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",
  "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

personId string

The person to filter queries by.
isCurrentPeriod boolean

Return the current period only.
isFinalPeriod boolean

Return the final period only.
date string, date

If provided, the balances and accruals of the current period will be calculated based on this date. Defaults to today if not provided.

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,
                  "usage": "upfront",
                  "usagePeriod": 12,
                  "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",
      "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

public.read

private.read

private.write

Time away policy object

Attributes

id string

Unique identifier for the object.
companyId string

ID of the company that this object is associated to.
name string

The name of the policy.
timeAwayPolicyVersion object

Time away policy version information
timeAwayPolicyVersion.id string

Unique identifier for the object.
timeAwayPolicyVersion.bypassWorkingSchedule boolean

true means weekends will be treated as working days. Default is false and means that weekends do not use up the available balance.
timeAwayPolicyVersion.bypassPublicHolidays boolean

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.publicHolidayCalendarId string

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.visibleBalances string[]

Which balances to show to employees. Available options are endOfYear or today.
timeAwayPolicyVersion.rules object[]

List of time away types that are available on this policy.
timeAwayPolicyVersion.rules.timeAwayTypeId string

ID of the time away type that this rule is associated to.
timeAwayPolicyVersion.rules.limits object

If null, balances will not be caluclated for this type but usage numbers will still be available.
timeAwayPolicyVersion.rules.limits.yearlyAllowance number

The number of paid time off days allowed per year.
timeAwayPolicyVersion.rules.limits.maxCarryOver number

The number of days to carry over into the next year.
timeAwayPolicyVersion.rules.limits.yearStart string

The start of the time off year. The format is MM-DD.
timeAwayPolicyVersion.rules.limits.yearStartType string

Whether the policy starts on employment start date or a custom date.
timeAwayPolicyVersion.rules.limits.isUnlimited boolean

true means the time off policy allows to take unlimited paid time off days.
timeAwayPolicyVersion.rules.limits.isProrated boolean

true means the allowance will be prorated based on FTE.
timeAwayPolicyVersion.rules.limits.usage string

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.usagePeriod integer

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. Defaults to: 12.
timeAwayPolicyVersion.rules.limits.roundingType string

The rounding method applied to the time away balance. Valid options are halfUp, wholeUp and noRounding.
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-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,
          "usage": "upfront",
          "usagePeriod": 12,
          "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

$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of time away policies. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate time away policy object. If no time away policies are available, the resulting list will be empty. This request should never return an error.

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,
              "usage": "upfront",
              "usagePeriod": 12,
              "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,
          "usage": "upfront",
          "usagePeriod": 12,
          "roundingType": "halfUp"
        }
      }
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a time away policy

Parameters

name string required

The name of the policy.
timeAwayPolicyVersion object required

Time away policy version information
timeAwayPolicyVersion.bypassWorkingSchedule boolean

true means weekends will be treated as working days. Default is false and means that weekends do not use up the available balance.
timeAwayPolicyVersion.bypassPublicHolidays boolean

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.publicHolidayCalendarId string | 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.visibleBalances string[]

Which balances to show to employees. Available options are endOfYear or today.
timeAwayPolicyVersion.rules object[] required

List of time away types that are available on this policy.
timeAwayPolicyVersion.rules.timeAwayTypeId string required

ID of the time away type that this rule is associated to.
timeAwayPolicyVersion.rules.limits object | null required

If null, balances will not be caluclated for this type but usage numbers will still be available.
timeAwayPolicyVersion.rules.limits.yearlyAllowance number required

The number of paid time off days allowed per year.
timeAwayPolicyVersion.rules.limits.maxCarryOver number required

The number of days to carry over into the next year.
timeAwayPolicyVersion.rules.limits.yearStart string

The start of the time off year. The format is MM-DD.
timeAwayPolicyVersion.rules.limits.yearStartType string

Whether the policy starts on employment start date or a custom date.
timeAwayPolicyVersion.rules.limits.isUnlimited boolean required

true means the time off policy allows to take unlimited paid time off days.
timeAwayPolicyVersion.rules.limits.isProrated boolean required

true means the allowance will be prorated based on FTE.
timeAwayPolicyVersion.rules.limits.usage string 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.usagePeriod integer required

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. Defaults to: 12.
timeAwayPolicyVersion.rules.limits.roundingType string

The rounding method applied to the time away balance. Valid options are halfUp, wholeUp and noRounding.

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,"usage":"upfront","usagePeriod":12,"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,
          "usage": "upfront",
          "usagePeriod": 12,
          "roundingType": "halfUp"
        }
      }
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a time away policy

Parameters

name string

The name of the policy.
timeAwayPolicyVersion object

Time away policy version information
timeAwayPolicyVersion.bypassWorkingSchedule boolean

true means weekends will be treated as working days. Default is false and means that weekends do not use up the available balance.
timeAwayPolicyVersion.bypassPublicHolidays boolean

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.publicHolidayCalendarId string | 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.visibleBalances string[]

Which balances to show to employees. Available options are endOfYear or today.
timeAwayPolicyVersion.rules object[]

List of time away types that are available on this policy.
timeAwayPolicyVersion.rules.timeAwayTypeId string required

ID of the time away type that this rule is associated to.
timeAwayPolicyVersion.rules.limits object | null required

If null, balances will not be caluclated for this type but usage numbers will still be available.
timeAwayPolicyVersion.rules.limits.yearlyAllowance number required

The number of paid time off days allowed per year.
timeAwayPolicyVersion.rules.limits.maxCarryOver number required

The number of days to carry over into the next year.
timeAwayPolicyVersion.rules.limits.yearStart string

The start of the time off year. The format is MM-DD.
timeAwayPolicyVersion.rules.limits.yearStartType string

Whether the policy starts on employment start date or a custom date.
timeAwayPolicyVersion.rules.limits.isUnlimited boolean required

true means the time off policy allows to take unlimited paid time off days.
timeAwayPolicyVersion.rules.limits.isProrated boolean required

true means the allowance will be prorated based on FTE.
timeAwayPolicyVersion.rules.limits.usage string 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.usagePeriod integer required

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. Defaults to: 12.
timeAwayPolicyVersion.rules.limits.roundingType string

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,
          "usage": "upfront",
          "usagePeriod": 12,
          "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

id string

Unique identifier for the object.
companyId string

ID of the company that this object is associated to.
name string

The name of the time away type.
emoji string

An emoji for visualising the time away type.
emojiLabel string

An emoji label for accessibility.
category string

One of workingAway or timeOff.
baseType string

The base type of the time away type. One of pto, sick, workingFromHome, or workingFromAnotherLocation
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.

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

id string | $in

The ID of the time away type.
$or object[]

Filter results by multiple criteria.
$or.id string | $in

The ID of the time away type.
$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of time away types. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate time away type object. If no time away types are available, the resulting list will be empty. This request should never return an error.

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

name string required

The name of the time away type.
emoji string required

An emoji for visualising the time away type.
category string required

One of workingAway or timeOff.

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

name string

The name of the time away type.
emoji string

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

id string

Unique identifier for the object.
personId string

ID of the person that this object is associated to.
date string, date

The date of this timesheet entry.
startTime string

The start time of this timesheet entry.
endTime string

The end time of this timesheet entry.
duration object

The duration of this timesheet entry.
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.

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

personId string

The person to filter queries by.
date

The date of this timesheet entry.
endTime string | empty

The end time of this timesheet entry.
id object

The ID of an existing timesheet entry.
id.$in string[]

An array of IDs of existing timesheet entries.
$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of timesheet entries. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate timesheet entry object. If no timesheet entries are available, the resulting list will be empty. This request should never return an error.

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

personId string required

ID of the person that this object is associated to.
date string, date required

The date of this timesheet entry.
startTime string required

The start time of this timesheet entry.
endTime string

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

date string, date

The date of this timesheet entry.
startTime string

The start time of this timesheet entry.
endTime string

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

id string

Unique identifier for the object.
personId string

ID of the person that this object is associated to.
startDate string, date

The start date of the month which this submission covers.
endDate string, date

The end date of the month which this submission covers.
status string

One of pending, approved, rejected.
submittedAt string, date-time

The date and time when this submission was last submitted.
reviewedBy string

The ID of the person that reviewed this submission.
reviewedAt string, date-time

The date and time when this submission was reviewed.
changesRequested string

Changes requested to accompany a rejected submission.
durationAsTime object

The total time attached to this submission.
durationAsDays number

The total days attached to this submission.
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-time

Time at which the object was last updated.

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

Returns a list of timesheet submissions.

The timesheet submissions can be filtered using more complex filter conditions. Refer to Filtering documentation for more details on usage.

Parameters

personId string

The person to filter queries by.
startDate string

The start date of the month which this submission covers.
$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of timesheet submissions. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate timesheet submission object. If no timesheet submissions are available, the resulting list will be empty. This request should never return an error.

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

personId string required

ID of the person that this object is associated to.
startDate string, date 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

status string required

One of pending, approved, rejected.
changesRequested string

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

scopes string[]

token-info object

{
  "scopes": "['public:read', 'documents:read']"
}

Retrieve my token info

Retrieves the currently used token scopes.

Parameters

No parameters

Returns

Returns the current tokens` scopes.

GET /api/token-info

curl https://app.humaans.io/api/token-info/undefined \
  -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

id string

Unique identifier for the object.
name string

A short name for the webhook.
description string

A longer description for the webhook.
prodEndpointUrl string

The endpoint that will receive webhook events.
prodEndpointSignature string

This signature can be used to verify that the webhook message came from Humaans, read more about this in the webhooks section.
subscribedEvents string[]

The list of webhook events that will be sent to the configured endpoint.
status string

The status of the webhook, can be one of draft, active or disabled.
createdBy string

The person who first created the webhook.
publishedBy string

The person who last published the webhook.
createdAt string, date-time

Time at which the object was created.
updatedAt string, date-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

$limit number

Limit number of results.
$skip number

Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of webhooks. The list is up to $limit length and a number of results specified by $skip are skipped. Each entry in the list is a separate webhook object. If no webhooks are available, the resulting list will be empty. This request should never return an error.

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

name string required

A short name for the webhook.
description string | null

A longer description for the webhook.
prodEndpointUrl string | null

The endpoint that will receive webhook events.
subscribedEvents string[]

The list of webhook events that will be sent to the configured endpoint.
status string

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

name string

A short name for the webhook.
description string | null

A longer description for the webhook.
status string

The status of the webhook, can be one of draft, active or disabled.
subscribedEvents string[]

The list of webhook events that will be sent to the configured endpoint.
prodEndpointUrl string | 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
}

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

$limit number

$skip number

Filtering

string, number, boolean

$in, $nin

$gt, gte

$lt, lte

$or

Errors

Error object

id string

code number

name string

message string

issues object[]

issues[].name string

issues[].reason string

issues[].forbidden boolean

issues[].index string

Error codes

401 NotAuthenticated

403 Forbidden

404 NotFound

405 MethodNotAllowed

422 ValidationError

422 QueryParameterValidationError

422 EmailTaken

500 GeneralError

502 BadGateway

503 Unavailable

Versioning

Webhooks

Resources

Bank accounts

Bank account object

Attributes

id string

personId string

bankName string

nameOnAccount string

accountNumber string

swiftCode string

sortCode string

routingNumber string

createdAt string, date-time

updatedAt string, date-time

List all bank accounts

Parameters

personId string | $in

$limit number

$skip number

`string`, `number`, `boolean`

`$in`, `$nin`

`$gt`, `gte`

`$lt`, `lte`

`$or`