Visit humaans.io Contact support Login to Humaans →

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.

  • package string

    The product package the company is subscribed to.

  • 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",
  "package": "growth",
  "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",
      "package": "growth",
      "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",
  "package": "growth",
  "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",
  "package": "growth",
  "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
  POST /api/compensation-types
 PATCH /api/compensation-types/:id
DELETE /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"
}

Create a compensation type

Parameters
  • name string required

    The name of the compensation type.

Returns

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

POST /api/compensation-types
curl https://app.humaans.io/api/compensation-types \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"Salary"}'
Response
{
  "id": "ldOQU3pLI5i8Y9k2rJbrXbFc",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Salary",
  "baseType": "salary",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a compensation type

Parameters
  • name string

    The name of the compensation type.

Returns

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

PATCH /api/compensation-types/:id
curl https://app.humaans.io/api/compensation-types/ldOQU3pLI5i8Y9k2rJbrXbFc \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'
Response
{
  "id": "ldOQU3pLI5i8Y9k2rJbrXbFc",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Salary",
  "baseType": "salary",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a compensation type

Permanently deletes a compensation type. It cannot be undone.

Parameters
  • No parameters
Returns

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

DELETE /api/compensation-types/:id
curl https://app.humaans.io/api/compensation-types/ldOQU3pLI5i8Y9k2rJbrXbFc \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE
Response
{
  "id": "ldOQU3pLI5i8Y9k2rJbrXbFc",
  "deleted": true
}

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 '{"jobTitle":"Product Engineer"}'
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.

  • subsection string

    A further section i.e. compensation -> salary

  • 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",
  "subsection": "salary",
  "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",
      "subsection": "salary",
      "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",
  "subsection": "salary",
  "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.

  • subsection string | null

    A further section i.e. compensation -> salary

  • 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",
  "subsection": "salary",
  "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",
  "subsection": "salary",
  "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.

  • 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

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

    One of: full, am, pm.

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

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

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

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

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

    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

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

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

    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

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

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

  • unit string

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

  • unit string

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

  • unit string

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