Visit humaans.io Contact support Login to Humaans →

API Reference

Humaans API is currently in preview. This means that small, backward incompatible changes might be introduced while in preview. The changes will be documented and communicated.

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

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.

  • 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.com/api/people' -g \
  -H 'Authorization: Bearer <your_api_access_token>'
# -> { "total": 152, "limit": 100, "skip": 0, "data": [.. 100 items ..] }

curl 'https://app.humaans.com/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 after the API exits the preview phase. In some cases, if we remove underlying 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.

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

    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.

  • trialEndDate string, date

    The last date of trial.

  • status string

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

  • paymentStatus string

    One of requires_action, past_due, ok.

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

company object
{
  "id": "uoWtfpDIMI2IZ8doGK7kkCwS",
  "name": "Acme",
  "trialEndDate": "2020-01-30",
  "status": "active",
  "paymentStatus": "ok",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

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

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

Update a company

Parameters
  • name string

    Company name.

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

Compensations

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

Endpoints
   GET /api/compensations
   GET /api/compensations/:id
  POST /api/compensations
 PATCH /api/compensations/:id
DELETE /api/compensations/:id
Required scopes
compensations.read
compensations.write

Compensation object

Attributes
  • id string

    Unique identifier for the object.

  • personId string

    ID of the person that this object is associated to.

  • type string

    Type of compensation. One of: salary, bonus, commission, equity.

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

    The person to filter queries by.

  • type string

    The compensation type 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",
      "type": "salary",
      "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",
  "type": "salary",
  "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.

  • type string required

    Type of compensation. One of: salary, bonus, commission, equity.

  • 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, 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","type":"salary","amount":"70000","period":"annual","effectiveDate":"2020-02-15"}'
Response
{
  "id": "m54mmpqDwthFwiiMcY0ptJdz",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "salary",
  "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
  • type string

    Type of compensation. One of: salary, bonus, commission, equity.

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

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
private.read
private.write

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.

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[] required

    The list of fields that should be included in the data export. Available fields: firstName, lastName, preferredName, birthday, nationality, gender, email, phoneNumber, personalEmail, personalPhoneNumber, address, country, dietaryPreference, foodAllergies, idExpiryDates, emergencyContacts, jobTitle, department, manager, managerEmail, roleEffectiveDate, teams, placeOfWork, isRemote, contractType, employeeId, taxId, taxCode, employmentStartDate, firstWorkingDay, probationEndDate, employmentEndDate, lastWorkingDay, leavingReason, leavingNote, bankName, nameOnAccount, accountNumber, swiftCode, sortCode, routingNumber, salary, bonus, equity, commission, paidTimeOff, unpaidLeave, sickLeave, parentalLeave, otherLeave, paidTimeOffAdjustments, workingFromHome, balance, endOfYearBalance, accrualRate, ptoPolicy.

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

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
Required scopes
documents.read

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

  • isDefault boolean

    Whether this type is the default type provided by Humaans.

  • isUsed boolean

    Whether this type is applied to some document.

document type object
{
  "id": "Ozcv1Wea2yfUhSm8fsj0ziIf",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "value": "Employment agreement",
  "isDefault": true,
  "isUsed": true
}

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",
      "value": "Employment agreement",
      "isDefault": true,
      "isUsed": true
    }
  ]
}

Documents

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

Endpoints
   GET /api/documents
   GET /api/documents/:id
  POST /api/documents
 PATCH /api/documents/:id
DELETE /api/documents/:id
Required scopes
documents.read
documents.write

Document object

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

  • type string

    The type of the document. 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.

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

  • 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)",
  "type": "Employment agreements",
  "link": "https://drive.google.com/docs/KMjibfqIQC3hiZK2tFItQetm",
  "fileId": null,
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "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)",
      "type": "Employment agreements",
      "link": "https://drive.google.com/docs/KMjibfqIQC3hiZK2tFItQetm",
      "fileId": null,
      "file": {
        "id": "51YzMOYrc9rU0lNGn1QtgSv0",
        "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
        "filename": "passport-scan.pdf"
      },
      "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)",
  "type": "Employment agreements",
  "link": "https://drive.google.com/docs/KMjibfqIQC3hiZK2tFItQetm",
  "fileId": null,
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "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

  • type string | null

    The type of the document. 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.

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

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)",
  "type": "Employment agreements",
  "link": "https://drive.google.com/docs/KMjibfqIQC3hiZK2tFItQetm",
  "fileId": null,
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "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

  • type string | null

    The type of the document. 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.

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

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)",
  "type": "Employment agreements",
  "link": "https://intranet/doc/2",
  "fileId": null,
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "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
  • 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 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
  • 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.

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

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

  • publicVariants 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. See the Person object for an example.

  • publicVariants.id string

    Unique identifier for the object.

  • publicVariants.variants object

    A map of 3 predefined profile photo sizes.

  • publicVariants.variants.64 string

    URL of one of the predefined profile photo sizes.

  • publicVariants.variants.104 string

    URL of one of the predefined profile photo sizes.

  • publicVariants.variants.320 string

    URL of one of the predefined profile 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",
  "publicVariants": 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",
  "publicVariants": 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, or leavingFile.

  • file file required

    The file being uploaded.

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",
  "publicVariants": 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.

  • isDefault boolean

    Whether this type is the default type provided by Humaans.

identity document type object
{
  "id": "yI3rZlTcWBvn3F4ChC5d1X2b",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "value": "Passport",
  "isDefault": true
}

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",
      "isDefault": true
    }
  ]
}

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 identitifacition document as specified on the document.

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

  • 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",
  "expiryDate": "2050-06-24",
  "note": null,
  "fileId": "51YzMOYrc9rU0lNGn1QtgSv0",
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "verifiedBy": "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",
      "expiryDate": "2050-06-24",
      "note": null,
      "fileId": "51YzMOYrc9rU0lNGn1QtgSv0",
      "file": {
        "id": "51YzMOYrc9rU0lNGn1QtgSv0",
        "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
        "filename": "passport-scan.pdf"
      },
      "verifiedBy": "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",
  "expiryDate": "2050-06-24",
  "note": null,
  "fileId": "51YzMOYrc9rU0lNGn1QtgSv0",
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "verifiedBy": "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 identitifacition document as specified on the document.

  • expiryDate string, date | null

    Expiry date of the document.

  • note string | null

    An optional note about the identity document.

  • fileId string | null 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",
  "expiryDate": "2050-06-24",
  "note": null,
  "fileId": "51YzMOYrc9rU0lNGn1QtgSv0",
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "verifiedBy": "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 identitifacition document as specified on the document.

  • expiryDate string, date | null

    Expiry date of the document.

  • note string | null

    An optional note about the identity document.

  • fileId string | null

    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",
  "expiryDate": "2050-05-01",
  "note": null,
  "fileId": "51YzMOYrc9rU0lNGn1QtgSv0",
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "verifiedBy": "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.

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

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

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

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

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

    Middle name.

  • preferredName string

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

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

  • 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 3 predefined profile photo sizes.

  • profilePhoto.variants.64 string

    URL of one of the predefined profile photo sizes.

  • profilePhoto.variants.104 string

    URL of one of the predefined profile photo sizes.

  • profilePhoto.variants.320 string

    URL of one of the predefined profile photo sizes.

  • nationality string

    Nationality.

  • 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

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

  • leavingReason string

    Leaving reason set for offboarded people. One of dismissed, resigned, redundancy, 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 Intership, 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 3 items.

  • teams.name string

    Name of the team

  • isOffboarded boolean

    If true, the person no longer works at the company. Based on lastWorkingDay field.

  • isVerified boolean

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

  • 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

    The role of the user, which controls permissions. One of owner, admin, finance, user

  • seenDocumentsAt string, date-time

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

  • 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",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg"
    }
  },
  "nationality": "British",
  "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,
  "employmentStartDate": "2018-03-10",
  "firstWorkingDay": "2018-03-10",
  "employmentEndDate": null,
  "lastWorkingDay": "2018-03-10",
  "probationEndDate": null,
  "leavingReason": null,
  "leavingNote": null,
  "leavingFileId": null,
  "contractType": "Full time",
  "employeeId": null,
  "taxId": "QQ123456C",
  "taxCode": "123456C",
  "teams": [
    {
      "name": "Moonshot"
    },
    {
      "name": "Growth Pod"
    }
  ],
  "isOffboarded": false,
  "isVerified": true,
  "calendarFeedToken": "bb6LCUqG4BAOZWKXQQB9a8H9",
  "role": "user",
  "seenDocumentsAt": "2020-02-21T17:09:29.290Z",
  "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",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg"
    }
  },
  "nationality": "British",
  "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,
  "employmentStartDate": "2018-03-10",
  "firstWorkingDay": "2018-03-10",
  "employmentEndDate": null,
  "lastWorkingDay": "2018-03-10",
  "probationEndDate": null,
  "leavingReason": null,
  "leavingNote": null,
  "leavingFileId": null,
  "contractType": "Full time",
  "employeeId": null,
  "taxId": "QQ123456C",
  "taxCode": "123456C",
  "teams": [
    {
      "name": "Moonshot"
    },
    {
      "name": "Growth Pod"
    }
  ],
  "isOffboarded": false,
  "isVerified": true,
  "calendarFeedToken": "bb6LCUqG4BAOZWKXQQB9a8H9",
  "role": "user",
  "seenDocumentsAt": "2020-02-21T17:09:29.290Z",
  "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

    Middle name.

  • preferredName string

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

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

  • 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 3 predefined profile photo sizes.

  • profilePhoto.variants.64 string

    URL of one of the predefined profile photo sizes.

  • profilePhoto.variants.104 string

    URL of one of the predefined profile photo sizes.

  • profilePhoto.variants.320 string

    URL of one of the predefined profile photo sizes.

  • nationality string

    Nationality.

  • 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

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

  • leavingReason string

    Leaving reason set for offboarded people. One of dismissed, resigned, redundancy, 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 Intership, 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 3 items.

  • teams.name string

    Name of the team

  • isOffboarded boolean

    If true, the person no longer works at the company. Based on lastWorkingDay field.

  • isVerified boolean

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

  • 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

    The role of the user, which controls permissions. One of owner, admin, finance, user

  • seenDocumentsAt string, date-time

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

  • 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",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg"
    }
  },
  "nationality": "British",
  "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,
  "employmentStartDate": "2018-03-10",
  "firstWorkingDay": "2018-03-10",
  "employmentEndDate": null,
  "lastWorkingDay": "2018-03-10",
  "probationEndDate": null,
  "leavingReason": null,
  "leavingNote": null,
  "leavingFileId": null,
  "contractType": "Full time",
  "employeeId": null,
  "taxId": "QQ123456C",
  "taxCode": "123456C",
  "teams": [
    {
      "name": "Moonshot"
    },
    {
      "name": "Growth Pod"
    }
  ],
  "isOffboarded": false,
  "isVerified": true,
  "calendarFeedToken": "bb6LCUqG4BAOZWKXQQB9a8H9",
  "role": "user",
  "seenDocumentsAt": "2020-02-21T17:09:29.290Z",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all people

Returns a list of people.

Parameters
  • email string

    Filter the people by person's work email address.

  • isOffboarded boolean

    Filter the people by whether they are currently active in the company.

  • $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",
          "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
          "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg"
        }
      },
      "nationality": "British",
      "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,
      "employmentStartDate": "2018-03-10",
      "firstWorkingDay": "2018-03-10",
      "employmentEndDate": null,
      "lastWorkingDay": "2018-03-10",
      "probationEndDate": null,
      "leavingReason": null,
      "leavingNote": null,
      "leavingFileId": null,
      "contractType": "Full time",
      "employeeId": null,
      "taxId": "QQ123456C",
      "taxCode": "123456C",
      "teams": [
        {
          "name": "Moonshot"
        },
        {
          "name": "Growth Pod"
        }
      ],
      "isOffboarded": false,
      "isVerified": true,
      "calendarFeedToken": "bb6LCUqG4BAOZWKXQQB9a8H9",
      "role": "user",
      "seenDocumentsAt": "2020-02-21T17:09:29.290Z",
      "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",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg"
    }
  },
  "nationality": "British",
  "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,
  "employmentStartDate": "2018-03-10",
  "firstWorkingDay": "2018-03-10",
  "employmentEndDate": null,
  "lastWorkingDay": "2018-03-10",
  "probationEndDate": null,
  "leavingReason": null,
  "leavingNote": null,
  "leavingFileId": null,
  "contractType": "Full time",
  "employeeId": null,
  "taxId": "QQ123456C",
  "taxCode": "123456C",
  "teams": [
    {
      "name": "Moonshot"
    },
    {
      "name": "Growth Pod"
    }
  ],
  "isOffboarded": false,
  "isVerified": true,
  "calendarFeedToken": "bb6LCUqG4BAOZWKXQQB9a8H9",
  "role": "user",
  "seenDocumentsAt": "2020-02-21T17:09:29.290Z",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a person

Parameters
  • firstName string required

    First name.

  • middleName string | null

    Middle name.

  • lastName string required

    Middle name.

  • preferredName string | null

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

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

  • profilePhotoId string | null

    ID of the profile picture file.

  • nationality string | null

    Nationality.

  • 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

  • slack string | null

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

  • leavingReason string | null

    Leaving reason set for offboarded people. One of dismissed, resigned, redundancy, 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 Intership, but can be set to any value.

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

  • teams object[]

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

  • teams.name string required

  • 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

    The role of the user, which controls permissions. One of owner, admin, finance, user

  • isWelcomed boolean

  • seenDocumentsAt string, date-time

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

  • jobRole object required

    The job role details of this person.

  • jobRole.jobTitle string required

  • jobRole.department string | null

  • jobRole.reportingTo string | null

  • timeAwayAllocation object

  • timeAwayAllocation.timeAwayPolicyId string required

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",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg"
    }
  },
  "nationality": "British",
  "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,
  "employmentStartDate": "2018-03-10",
  "firstWorkingDay": "2018-03-10",
  "employmentEndDate": null,
  "lastWorkingDay": "2018-03-10",
  "probationEndDate": null,
  "leavingReason": null,
  "leavingNote": null,
  "leavingFileId": null,
  "contractType": "Full time",
  "employeeId": null,
  "taxId": "QQ123456C",
  "taxCode": "123456C",
  "teams": [
    {
      "name": "Moonshot"
    },
    {
      "name": "Growth Pod"
    }
  ],
  "isOffboarded": false,
  "isVerified": true,
  "calendarFeedToken": "bb6LCUqG4BAOZWKXQQB9a8H9",
  "role": "user",
  "seenDocumentsAt": "2020-02-21T17:09:29.290Z",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a person

Parameters
  • firstName string

    First name.

  • middleName string | null

    Middle name.

  • lastName string

    Middle name.

  • preferredName string | null

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

  • email string

    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.

  • profilePhotoId string | null

    ID of the profile picture file.

  • nationality string | null

    Nationality.

  • 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

  • slack string | null

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

  • leavingReason string | null

    Leaving reason set for offboarded people. One of dismissed, resigned, redundancy, 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 Intership, but can be set to any value.

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

  • teams object[]

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

  • teams.name string required

  • 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

    The role of the user, which controls permissions. One of owner, admin, finance, user

  • isWelcomed boolean

  • seenDocumentsAt string, date-time

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

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",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg"
    }
  },
  "nationality": "British",
  "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,
  "employmentStartDate": "2018-03-10",
  "firstWorkingDay": "2018-03-10",
  "employmentEndDate": null,
  "lastWorkingDay": "2018-03-10",
  "probationEndDate": null,
  "leavingReason": null,
  "leavingNote": null,
  "leavingFileId": null,
  "contractType": "Full time",
  "employeeId": null,
  "taxId": "QQ123456C",
  "taxCode": "123456C",
  "teams": [
    {
      "name": "Moonshot"
    },
    {
      "name": "Growth Pod"
    }
  ],
  "isOffboarded": false,
  "isVerified": true,
  "calendarFeedToken": "bb6LCUqG4BAOZWKXQQB9a8H9",
  "role": "user",
  "seenDocumentsAt": "2020-02-21T17:09:29.290Z",
  "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
private.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.

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

  • 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",
  "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
  • No parameters
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",
      "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
private.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.

public holiday object
{
  "id": "DE-BE/2020-01-01",
  "date": "2020-01-01",
  "name": "New year"
}

List all public holidays

Returns a list of public holidays.

Parameters
  • publicHolidayCalendarId string required

    The ID of the public holiday calendar.

  • date $gt | $lt | $gte | $lte

    Filter holidays by date.

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": "DE-BE/2020-01-01",
      "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.

  • type

    The type of the time away entry. One of: workingFromAnotherLocation, workingFromHome, training, travellingForWork, pto, compassionate, emergency, juryDuty, mentalHealth, parental, sabbatical, sick, unpaid, volunteering.

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

  • 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). Ignored if startDate and endDate are the same, it is recommended to set endPeriod to full in that case. Defaults to full.

  • note string

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

  • 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. Only visible to the employee, their manager and admins.

  • days number

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

  • publicHolidayCalendarId string

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

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

    One of: weekday, weekend, holiday.

  • 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",
  "type": "pto",
  "name": "Paid time off",
  "isTimeOff": true,
  "startDate": "2020-01-24",
  "endDate": "2020-01-29",
  "startPeriod": "full",
  "endPeriod": "am",
  "note": "🏝 Trip to New Zealand",
  "workingFromLocationId": null,
  "days": 3.5,
  "publicHolidayCalendarId": "AU-NSW",
  "breakdown": [
    {
      "date": "2020-01-24",
      "kind": "weekday",
      "period": "full"
    },
    {
      "date": "2020-01-25",
      "kind": "weekend",
      "period": "full"
    },
    {
      "date": "2020-01-26",
      "kind": "holiday",
      "period": "full"
    },
    {
      "date": "2020-01-27",
      "kind": "holiday",
      "period": "full"
    },
    {
      "date": "2020-01-28",
      "kind": "weekday",
      "period": "full"
    },
    {
      "date": "2020-01-29",
      "kind": "weekday",
      "period": "am"
    }
  ],
  "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.

  • startDate string | $gt | $gte | $lt | $lte

    Filter by start date.

  • endDate string | $gt | $gte | $lt | $lte

    Filter by end date.

  • $or object[]

    Filter results by multiple criteria.

  • $or.personId string | $in

    The person to filter queries by.

  • $or.startDate string | $gt | $gte | $lt | $lte

    Filter by start date.

  • $or.endDate string | $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. 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",
      "type": "pto",
      "name": "Paid time off",
      "isTimeOff": true,
      "startDate": "2020-01-24",
      "endDate": "2020-01-29",
      "startPeriod": "full",
      "endPeriod": "am",
      "note": "🏝 Trip to New Zealand",
      "workingFromLocationId": null,
      "days": 3.5,
      "publicHolidayCalendarId": "AU-NSW",
      "breakdown": [
        {
          "date": "2020-01-24",
          "kind": "weekday",
          "period": "full"
        },
        {
          "date": "2020-01-25",
          "kind": "weekend",
          "period": "full"
        },
        {
          "date": "2020-01-26",
          "kind": "holiday",
          "period": "full"
        },
        {
          "date": "2020-01-27",
          "kind": "holiday",
          "period": "full"
        },
        {
          "date": "2020-01-28",
          "kind": "weekday",
          "period": "full"
        },
        {
          "date": "2020-01-29",
          "kind": "weekday",
          "period": "am"
        }
      ],
      "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",
  "type": "pto",
  "name": "Paid time off",
  "isTimeOff": true,
  "startDate": "2020-01-24",
  "endDate": "2020-01-29",
  "startPeriod": "full",
  "endPeriod": "am",
  "note": "🏝 Trip to New Zealand",
  "workingFromLocationId": null,
  "days": 3.5,
  "publicHolidayCalendarId": "AU-NSW",
  "breakdown": [
    {
      "date": "2020-01-24",
      "kind": "weekday",
      "period": "full"
    },
    {
      "date": "2020-01-25",
      "kind": "weekend",
      "period": "full"
    },
    {
      "date": "2020-01-26",
      "kind": "holiday",
      "period": "full"
    },
    {
      "date": "2020-01-27",
      "kind": "holiday",
      "period": "full"
    },
    {
      "date": "2020-01-28",
      "kind": "weekday",
      "period": "full"
    },
    {
      "date": "2020-01-29",
      "kind": "weekday",
      "period": "am"
    }
  ],
  "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.

  • type required

    The type of the time away entry. One of: workingFromAnotherLocation, workingFromHome, training, travellingForWork, pto, compassionate, emergency, juryDuty, mentalHealth, parental, sabbatical, sick, unpaid, volunteering.

  • 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). Ignored if startDate and endDate are the same, it is recommended to set endPeriod to full in that case. 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

    When type (or reason) of the time away entry is workingFromAnotherLocation this field indicates the id of the location the person was working from. Only visible to the employee, their manager and admins.

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",
  "type": "pto",
  "name": "Paid time off",
  "isTimeOff": true,
  "startDate": "2020-01-24",
  "endDate": "2020-01-29",
  "startPeriod": "full",
  "endPeriod": "am",
  "note": "✈️ Trip to New Zealand",
  "workingFromLocationId": null,
  "days": 3.5,
  "publicHolidayCalendarId": "AU-NSW",
  "breakdown": [
    {
      "date": "2020-01-24",
      "kind": "weekday",
      "period": "full"
    },
    {
      "date": "2020-01-25",
      "kind": "weekend",
      "period": "full"
    },
    {
      "date": "2020-01-26",
      "kind": "holiday",
      "period": "full"
    },
    {
      "date": "2020-01-27",
      "kind": "holiday",
      "period": "full"
    },
    {
      "date": "2020-01-28",
      "kind": "weekday",
      "period": "full"
    },
    {
      "date": "2020-01-29",
      "kind": "weekday",
      "period": "am"
    }
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a time away

Parameters
  • type

    The type of the time away entry. One of: workingFromAnotherLocation, workingFromHome, training, travellingForWork, pto, compassionate, emergency, juryDuty, mentalHealth, parental, sabbatical, sick, unpaid, volunteering.

  • 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). Ignored if startDate and endDate are the same, it is recommended to set endPeriod to full in that case. 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

    When type (or reason) of the time away entry is workingFromAnotherLocation this field indicates the id of the location the person was working from. Only visible to the employee, their manager and admins.

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",
  "type": "pto",
  "name": "Paid time off",
  "isTimeOff": true,
  "startDate": "2020-01-24",
  "endDate": "2020-01-29",
  "startPeriod": "full",
  "endPeriod": "am",
  "note": "✈️ Trip to New Zealand",
  "workingFromLocationId": null,
  "days": 3.5,
  "publicHolidayCalendarId": "AU-NSW",
  "breakdown": [
    {
      "date": "2020-01-24",
      "kind": "weekday",
      "period": "full"
    },
    {
      "date": "2020-01-25",
      "kind": "weekend",
      "period": "full"
    },
    {
      "date": "2020-01-26",
      "kind": "holiday",
      "period": "full"
    },
    {
      "date": "2020-01-27",
      "kind": "holiday",
      "period": "full"
    },
    {
      "date": "2020-01-28",
      "kind": "weekday",
      "period": "full"
    },
    {
      "date": "2020-01-29",
      "kind": "weekday",
      "period": "am"
    }
  ],
  "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.

  • deltaDays number

    The number of days that should be added to the allowance. Negative number will reduce the allowance.

  • reason string

    A note describing the reason for this adjustment.

  • 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",
  "deltaDays": 2,
  "reason": "For working over the weekend.",
  "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
  • personId string | $in

    The person to filter queries by.

  • date string | $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",
      "deltaDays": 2,
      "reason": "For working over the weekend.",
      "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",
  "deltaDays": 2,
  "reason": "For working over the weekend.",
  "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.

  • deltaDays number required

    The number of days that should be added to the allowance. Negative number will reduce the allowance.

  • reason string required

    A note describing the reason for this adjustment.

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","deltaDays":2,"reason":"For working over the weekend."}'
Response
{
  "id": "BZJa63JpH4Bz25oM28zAbeoK",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "date": "2020-03-01",
  "deltaDays": 2,
  "reason": "For working over the weekend.",
  "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.

  • deltaDays number

    The number of days that should be added to the allowance. Negative number will reduce the allowance.

  • reason string

    A note describing the reason for this adjustment.

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",
  "deltaDays": 2,
  "reason": "For working over the weekend.",
  "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 object

    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.

  • timeAwayPolicy.id string

    Unique identifier for the object.

  • timeAwayPolicy.companyId string

    ID of the company that this object is associated to.

  • timeAwayPolicy.name string

    The name of the policy.

  • timeAwayPolicy.yearlyPtoAllowance integer

    The number of paid time off days allowed per year.

  • timeAwayPolicy.maxPtoCarryOver integer

    The number of days to carry over into the next year.

  • timeAwayPolicy.yearStart string

    The start of the time off year. The format is MM-DD.

  • timeAwayPolicy.isUnlimited boolean

    true means the time off policy allows to take unlimited paid time off days.

  • timeAwayPolicy.workingWeekends boolean

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

  • timeAwayPolicy.workingPublicHolidays boolean

    true means public holidays will be treated as working days. Default is false and means that public holidays do not use up the available balance.

  • timeAwayPolicy.createdAt string, date-time

    Time at which the object was created.

  • timeAwayPolicy.updatedAt string, date-time

    Time at which the object was last updated.

  • 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",
    "yearlyPtoAllowance": 30,
    "maxPtoCarryOver": 5,
    "yearStart": "01-01",
    "isUnlimited": false,
    "workingWeekends": false,
    "workingPublicHolidays": false,
    "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",
        "yearlyPtoAllowance": 30,
        "maxPtoCarryOver": 5,
        "yearStart": "01-01",
        "isUnlimited": false,
        "workingWeekends": false,
        "workingPublicHolidays": false,
        "createdAt": "2020-01-28T08:44:42.000Z",
        "updatedAt": "2020-01-29T14:52:21.000Z"
      },
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a time away allocation

Retrieves the time away allocation with the given ID.

Parameters
  • No parameters
Returns

Returns a time away allocation object if a valid identifier was provided.

GET /api/time-away-allocations/:id
curl https://app.humaans.io/api/time-away-allocations/MfQQ2fWdXGD3hvZKrxm6zWE0 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "MfQQ2fWdXGD3hvZKrxm6zWE0",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "placeOfWork",
  "effectiveDate": "2020-04-01",
  "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I",
  "timeAwayPolicy": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "companyId": "T7uqPFK7am4lFTZm39AmNuay",
    "name": "UK Policy",
    "yearlyPtoAllowance": 30,
    "maxPtoCarryOver": 5,
    "yearStart": "01-01",
    "isUnlimited": false,
    "workingWeekends": false,
    "workingPublicHolidays": false,
    "createdAt": "2020-01-28T08:44:42.000Z",
    "updatedAt": "2020-01-29T14:52:21.000Z"
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a time away allocation

Parameters
  • personId string required

    ID of the person that this object is associated to.

  • type string required

    The type of allocation. One of: placeOfWork, specific, custom. Setting allocation type to placeOfWork will apply the time away policy based on the place of work of the employee. Setting it to specific requires providing the timeAwayPolicyId that should be applied. Setting to custom requires passing policy object in the timeAwayPolicy field.

  • effectiveDate string, date | null required

    The first day when the allocation is in effect.

  • timeAwayPolicyId string

    The ID of the time away policy used by this allocation.

  • timeAwayPolicy object

    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.

  • timeAwayPolicy.yearlyPtoAllowance integer required

    The number of paid time off days allowed per year.

  • timeAwayPolicy.maxPtoCarryOver integer

    The number of days to carry over into the next year.

  • timeAwayPolicy.yearStart string

    The start of the time off year. The format is MM-DD.

  • timeAwayPolicy.isUnlimited boolean

    true means the time off policy allows to take unlimited paid time off days.

  • timeAwayPolicy.workingWeekends boolean

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

  • timeAwayPolicy.workingPublicHolidays boolean

    true means public holidays will be treated as working days. Default is false and means that public holidays do not use up the available balance.

Returns

Returns a time away allocation if the call succeeded. The call returns an error if parameters are invalid.

POST /api/time-away-allocations
curl https://app.humaans.io/api/time-away-allocations \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"effectiveDate":"2020-04-30"}'
Response
{
  "id": "MfQQ2fWdXGD3hvZKrxm6zWE0",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "placeOfWork",
  "effectiveDate": "2020-04-30",
  "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I",
  "timeAwayPolicy": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "companyId": "T7uqPFK7am4lFTZm39AmNuay",
    "name": "UK Policy",
    "yearlyPtoAllowance": 30,
    "maxPtoCarryOver": 5,
    "yearStart": "01-01",
    "isUnlimited": false,
    "workingWeekends": false,
    "workingPublicHolidays": false,
    "createdAt": "2020-01-28T08:44:42.000Z",
    "updatedAt": "2020-01-29T14:52:21.000Z"
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a time away allocation

Parameters
  • type string

    The type of allocation. One of: placeOfWork, specific, custom. Setting allocation type to placeOfWork will apply the time away policy based on the place of work of the employee. Setting it to specific requires providing the timeAwayPolicyId that should be applied. Setting to custom requires passing policy object in the timeAwayPolicy field.

  • effectiveDate string, date | null

    The first day when the allocation is in effect.

  • timeAwayPolicyId string

    The ID of the time away policy used by this allocation.

  • timeAwayPolicy object

    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.

  • timeAwayPolicy.yearlyPtoAllowance integer required

    The number of paid time off days allowed per year.

  • timeAwayPolicy.maxPtoCarryOver integer

    The number of days to carry over into the next year.

  • timeAwayPolicy.yearStart string

    The start of the time off year. The format is MM-DD.

  • timeAwayPolicy.isUnlimited boolean

    true means the time off policy allows to take unlimited paid time off days.

  • timeAwayPolicy.workingWeekends boolean

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

  • timeAwayPolicy.workingPublicHolidays boolean

    true means public holidays will be treated as working days. Default is false and means that public holidays do not use up the available balance.

Returns

Returns the time away allocation if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/time-away-allocations/:id
curl https://app.humaans.io/api/time-away-allocations/MfQQ2fWdXGD3hvZKrxm6zWE0 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"effectiveDate":"2020-04-30"}'
Response
{
  "id": "MfQQ2fWdXGD3hvZKrxm6zWE0",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "placeOfWork",
  "effectiveDate": "2020-04-30",
  "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I",
  "timeAwayPolicy": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "companyId": "T7uqPFK7am4lFTZm39AmNuay",
    "name": "UK Policy",
    "yearlyPtoAllowance": 30,
    "maxPtoCarryOver": 5,
    "yearStart": "01-01",
    "isUnlimited": false,
    "workingWeekends": false,
    "workingPublicHolidays": false,
    "createdAt": "2020-01-28T08:44:42.000Z",
    "updatedAt": "2020-01-29T14:52:21.000Z"
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a time away allocation

Permanently deletes a time away allocation. It cannot be undone.

Parameters
  • No parameters
Returns

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

DELETE /api/time-away-allocations/:id
curl https://app.humaans.io/api/time-away-allocations/MfQQ2fWdXGD3hvZKrxm6zWE0 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE
Response
{
  "id": "MfQQ2fWdXGD3hvZKrxm6zWE0",
  "deleted": true
}

Time away periods

Time away periods is used to find employee's time off allowance, remaining balance and many other useful attributes. Time away is sliced into periods and each period contains a summary.

Typically a period year long starting on 1st of January and ending on 31st of December. But it can also start and end mid year in case it is the first period and the employee started working mid year, if the time away allocation was changed mid year, or if the employee is offboarded. For example, consider an employee that started employment on 2018-08-01 and left on 2020-03-15. Such an employee would have 3 periods:

  • 2018-08-01 - 2018-12-31
  • 2019-01-01 - 2019-12-31
  • 2020-01-01 - 2020-03-15

Each of these periods will contain allowance, accrued days, balance, adjustments, days taken and so on.

The last period for active employees has the isCurrentPeriod attribute set to true and can be used to find the current status of the employee's time away.

Note, that a policy can be configured to have a different year start than January 1st, in which case each period under that policy would start on the day configured in the policy.

Endpoints
GET /api/time-away-periods
Required scopes
private.read

Time away period object

Attributes
  • id string

    Unique identifier for the object.

  • personId string

    ID of the person that this object is associated to.

  • startDate string, date

    The start of the period. This can be either the start of employment, start of the year or the date when a new policy was assigned. Note: the start of the time away year depends on the policy configuration.

  • endDate string, date

    The end of the period. This can be either the end of employment, end of the year, the day before a new policy was assigned. Note: the end of the time away year depends on the policy configuration.

  • isCurrentPeriod boolean

    true means this is the period that the employee is currently in. Current periods are useful for finding the current accrual or balance of an employee.

  • isFinalPeriod boolean

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

  • hasAllocationChanged boolean

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

  • isProrated boolean

    true means the allowance is prorated, because the period is partial. This happens for new employees that start accruing time off allowance mid year or when the policy is changed mid year.

  • accrued number

    Currently accrued allowance. The accrued balance as of today (or as of the endDate of the period for past periods). For the current period this indicates the accrued allowance as of today.

  • allowance number

    End of year allowance. The accrued balance as of the endDate of the period. For the current period this indicates what the person is allowed to take in total by the end of the year.

  • balance number

    Current balance. The remaining balance as of today (or as of the endDate of the period for past periods) excluding upcoming time off entries.

  • endingBalance number

    End of year balance. The remaining balance as of the endDate of the period.

  • ptoUsed number

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

  • ptoUpcoming number

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

  • adjustments number

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

  • adjustmentsUpcoming number

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

  • ptoCarriedOver number

    How many days have been carried over from the previous period. Calculated based on the allocation assigned to this period.

  • isPtoCarriedOverInFull boolean

    true means the remaining balance of the previous period has been carried over in full to the current period. This is done when allocation is changed mid year.

  • timeAwayAllocation object

    The time away allocation used in this period. See Time away allocations for full details.

time away period object
{
  "id": "X4XT4ZLOwT9GYbPyl90HztBu",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startDate": "2020-01-01",
  "endDate": "2020-12-31",
  "isCurrentPeriod": true,
  "isFinalPeriod": false,
  "hasAllocationChanged": false,
  "isProrated": true,
  "accrued": 8.09,
  "allowance": 20,
  "balance": 5.92,
  "endingBalance": 17.83,
  "ptoUsed": 2,
  "ptoUpcoming": 0,
  "adjustments": 0,
  "adjustmentsUpcoming": 0,
  "ptoCarriedOver": -0.17,
  "isPtoCarriedOverInFull": false,
  "timeAwayAllocation": {}
}

List all time away periods

Returns a list of time away periods.

Parameters
  • personId string

    The person to filter queries by.

  • isCurrentPeriod boolean

    Return the current period only.

  • isFinalPeriod boolean

    Return he final period only.

  • date string, date

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

Returns

Returns an object with a data property that contains a list of time away periods.

GET /api/time-away-periods
curl https://app.humaans.io/api/time-away-periods \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "X4XT4ZLOwT9GYbPyl90HztBu",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "startDate": "2020-01-01",
      "endDate": "2020-12-31",
      "isCurrentPeriod": true,
      "isFinalPeriod": false,
      "hasAllocationChanged": false,
      "isProrated": true,
      "accrued": 8.09,
      "allowance": 20,
      "balance": 5.92,
      "endingBalance": 17.83,
      "ptoUsed": 2,
      "ptoUpcoming": 0,
      "adjustments": 0,
      "adjustmentsUpcoming": 0,
      "ptoCarriedOver": -0.17,
      "isPtoCarriedOverInFull": false,
      "timeAwayAllocation": {}
    }
  ]
}

Time away policies

An object representing a time away policy. Time away policies are applied to employees to assign a yearly paid time off allowance, carry over days and a number of other settings.

Endpoints
   GET /api/time-away-policies
   GET /api/time-away-policies/:id
  POST /api/time-away-policies
 PATCH /api/time-away-policies/:id
DELETE /api/time-away-policies/:id
Required scopes
private.read
private.write

Time away policy object

Attributes
  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • name string

    The name of the policy.

  • yearlyPtoAllowance integer

    The number of paid time off days allowed per year.

  • maxPtoCarryOver integer

    The number of days to carry over into the next year.

  • yearStart string

    The start of the time off year. The format is MM-DD.

  • isUnlimited boolean

    true means the time off policy allows to take unlimited paid time off days.

  • workingWeekends boolean

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

  • workingPublicHolidays boolean

    true means public holidays will be treated as working days. Default is false and means that public holidays do not use up the available balance.

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

time away policy object
{
  "id": "dFCSrX1I3nzOZQMpblBclisO",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "UK Policy",
  "yearlyPtoAllowance": 30,
  "maxPtoCarryOver": 5,
  "yearStart": "01-01",
  "isUnlimited": false,
  "workingWeekends": false,
  "workingPublicHolidays": false,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all time away policies

Returns a list of time away policies.

Parameters
  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/time-away-policies
curl https://app.humaans.io/api/time-away-policies \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "dFCSrX1I3nzOZQMpblBclisO",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "UK Policy",
      "yearlyPtoAllowance": 30,
      "maxPtoCarryOver": 5,
      "yearStart": "01-01",
      "isUnlimited": false,
      "workingWeekends": false,
      "workingPublicHolidays": false,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a time away policy

Retrieves the time away policy with the given ID.

Parameters
  • No parameters
Returns

Returns a time away policy object if a valid identifier was provided.

GET /api/time-away-policies/:id
curl https://app.humaans.io/api/time-away-policies/dFCSrX1I3nzOZQMpblBclisO \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "dFCSrX1I3nzOZQMpblBclisO",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "UK Policy",
  "yearlyPtoAllowance": 30,
  "maxPtoCarryOver": 5,
  "yearStart": "01-01",
  "isUnlimited": false,
  "workingWeekends": false,
  "workingPublicHolidays": false,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a time away policy

Parameters
  • name string required

    The name of the policy.

  • yearlyPtoAllowance integer required

    The number of paid time off days allowed per year.

  • maxPtoCarryOver integer

    The number of days to carry over into the next year.

  • yearStart string

    The start of the time off year. The format is MM-DD.

  • isUnlimited boolean

    true means the time off policy allows to take unlimited paid time off days.

  • workingWeekends boolean

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

  • workingPublicHolidays boolean

    true means public holidays will be treated as working days. Default is false and means that public holidays do not use up the available balance.

Returns

Returns a time away policy if the call succeeded. The call returns an error if parameters are invalid.

POST /api/time-away-policies
curl https://app.humaans.io/api/time-away-policies \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"UK Policy","yearlyPtoAllowance":30}'
Response
{
  "id": "dFCSrX1I3nzOZQMpblBclisO",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "UK Policy",
  "yearlyPtoAllowance": 30,
  "maxPtoCarryOver": 5,
  "yearStart": "01-01",
  "isUnlimited": false,
  "workingWeekends": false,
  "workingPublicHolidays": false,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a time away policy

Parameters
  • name string

    The name of the policy.

  • yearlyPtoAllowance integer

    The number of paid time off days allowed per year.

  • maxPtoCarryOver integer

    The number of days to carry over into the next year.

  • yearStart string

    The start of the time off year. The format is MM-DD.

  • isUnlimited boolean

    true means the time off policy allows to take unlimited paid time off days.

  • workingWeekends boolean

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

  • workingPublicHolidays boolean

    true means public holidays will be treated as working days. Default is false and means that public holidays do not use up the available balance.

Returns

Returns the time away policy if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/time-away-policies/:id
curl https://app.humaans.io/api/time-away-policies/dFCSrX1I3nzOZQMpblBclisO \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'
Response
{
  "id": "dFCSrX1I3nzOZQMpblBclisO",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "UK Policy",
  "yearlyPtoAllowance": 30,
  "maxPtoCarryOver": 5,
  "yearStart": "01-01",
  "isUnlimited": false,
  "workingWeekends": false,
  "workingPublicHolidays": false,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a time away policy

Permanently deletes a time away policy. It cannot be undone.

Parameters
  • No parameters
Returns

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

DELETE /api/time-away-policies/:id
curl https://app.humaans.io/api/time-away-policies/dFCSrX1I3nzOZQMpblBclisO \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE
Response
{
  "id": "dFCSrX1I3nzOZQMpblBclisO",
  "deleted": true
}