Visit humaans.io Contact support Login to Humaans →

API Reference

Introduction

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

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

Authentication

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

Access Token Management

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

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

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

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

Scopes

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

Scopes

  • public:read

    Allow view access to data that is public to the entire company

  • private:read

    Allow view access to all data except compensations and documents

  • private:write

    Allow modifying all data except compensations and documents

  • compensations:read

    Allow view access to compensation data

  • compensations:write

    Allow modifying compensation data

  • documents:read

    Allow view access to personal documents and identity documents

  • documents:write

    Allow modifying personal documents and identity documents

  • webhooks:manage

    Allow view and modifying access to webhooks

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

Roles

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

Roles

  • Owner

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

  • Admin

    Can access and edit all profiles.

  • Finance

    Can access all profiles and manage the subscription.

  • Tech

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

  • Manager

    Can access some profile data of their reports. Note, unlike other roles, this role can not be assigned to a user and is instead implied by the reporting lines.

  • User

    Can access their own profile data.

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

Structure

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

Operations

  • GET /api/:resource

    List all objects of this type

  • GET /api/:resource/:id

    Retrieve a resource by id

  • POST /api/:resource

    Create a resource of this type

  • PATCH /api/:resource/:id

    Update the resource by id

  • DELETE /api/:resource/:id

    Delete the resource by id

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

Pagination

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

  • $limit number

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

  • $skip number

    Skip the specified number of results.

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

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

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

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

Filtering

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

string, number, boolean

Find all results matching the attribute value specified.

GET /api/example?personId=IL3vne

$in, $nin

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

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

$gt, gte

Find all results where the value is more ($gt) or more and equal ($gte) to a given value.

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

$lt, lte

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

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

$or

Find results using multiple conditions.

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

Errors

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

Error object

  • id string

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

  • code number

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

  • name string

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

  • message string

    A human readable description of the issue.

  • issues object[]

    A list of validation errors. This key only exists for errors of type ValidationError.

  • issues[].name string

    The name of the field that failed validation.

  • issues[].reason string

    The reason why this field was invalid.

  • issues[].forbidden boolean

    Indicates that this was an insufficient privilege issue.

  • issues[].index string

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

Error codes

  • 401 NotAuthenticated

    Missing or invalid access token

  • 403 Forbidden

    The provided access token does not have sufficient privileges

  • 404 NotFound

    The requested resource could not be found

  • 405 MethodNotAllowed

    The operation is not allowed for this resource

  • 422 ValidationError

    The request parameters are invalid

  • 422 QueryParameterValidationError

    The request query parameters are invalid

  • 422 EmailTaken

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

  • 500 GeneralError

    Unexpected issue, typically should not happen

  • 502 BadGateway

    Temporary availability issue

  • 503 Unavailable

    Temporary availability issue

Versioning

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

Webhooks

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

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

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

import { createHmac } from 'crypto'

const body = await getBody(request)

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

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

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

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

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

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

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

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

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

Resources

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

Access tokens

An API access token used to authenticate requests on behalf of a user. Tokens have configurable OAuth scopes that control which resources they can access.

Endpoints
Required scopes
security.read

Access token object

Attributes

  • id string

    Unique identifier for the object.

  • personId string

    The ID of the person this token authenticates as.

  • label string

    A human-readable label to identify the token (e.g. “CI pipeline”, “MCP client”).

  • scopes string[]

    OAuth scopes granted to this token. Controls which API resources it can access.

  • lastUsedAt string, date-time

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

  • accessToken string

  • companyId string

    ID of the company that this object is associated to.

  • anonymised boolean

    When true, the token cannot access PII-sensitive scopes (personal data, documents, performance reviews).

  • scopeVersion integer

    Scope format version. Use 2 for fine-grained v2 scopes (e.g. “employment:read”). Version 1 uses legacy scopes (“public:read”, “private:write”).

access token object
{
  "id": "QMoQrcTEiYj68z6Z5QKT8jpY",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay"
}

Audit events

A read-only log entry recording a change made in the system. Each event captures who made the change, what was changed, and the before/after values.

Endpoints
Required scopes
auditLog.read

Audit event object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • seq string

  • ts string, date-time

  • request object

  • request.id string

    Unique identifier for the object.

  • request.path string

  • request.method string

  • request.ip string

  • request.location string

  • request.source string

  • request.tokenId string

  • request.tokenType string

  • request.oauthClientId string

  • request.oauthGrantId string

  • request.caller object

  • request.caller.tabId string

  • request.caller.type string

  • request.caller.tabId string

  • request.caller.type string

  • action string

  • actor object

  • actor.type string

  • actor.personId string

    ID of the person that this object is associated to.

  • actor.integrationId string

  • actor.integrationType string

  • actor.type string

  • actor.personId string

  • actor.integrationId string

  • actor.integrationType string

  • entity object

  • entity.id string

    Unique identifier for the object.

  • entity.fieldsChanged string[]

  • entity.prev object

  • entity.next object

  • entity.customFields object[]

  • entity.customFields.customFieldId string

  • entity.customFields.prev string

  • entity.customFields.next string

  • entity.metadata object

  • subject object

  • subject.type string

  • subject.id string

    Unique identifier for the object.

  • subject.email string

  • subject.spaceId string

audit event object
{
  "id": "eUnH07JqwwvqO8taeyVIDGAN",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "request": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "caller": {}
  },
  "actor": {
    "personId": "IL3vneCYhIx0xrR6um2sy2nW"
  },
  "entity": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "prev": {},
    "next": {},
    "customFields": [
      {}
    ],
    "metadata": {}
  },
  "subject": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I"
  }
}

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

Bank account object

Attributes

  • id string

    Unique identifier for the object.

  • personId string

    ID of the person that this object is associated to.

  • bankName string

    The name of the bank.

  • nameOnAccount string

    The name on the bank account.

  • accountNumber string

    Bank account number.

  • swiftCode string

    The swift code of the bank account if relevant.

  • sortCode string

    The sort code of the bank account if relevant.

  • routingNumber string

    The routing number of the bank account if relevant.

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

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

List all bank accounts

Returns a list of bank accounts.

Parameters

  • personId string | $in

    The person to filter queries by.

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/bank-accounts
curl https://app.humaans.io/api/bank-accounts \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "Ivl8mvdLO8ux7T1h1DjGtClc",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "bankName": "Mondo",
      "nameOnAccount": "Kelsey Wicks",
      "accountNumber": "12345678",
      "swiftCode": null,
      "sortCode": "00-00-00",
      "routingNumber": null,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a bank account

Retrieves the bank account with the given ID.

Parameters
  • No parameters
Returns

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

GET /api/bank-accounts/:id
curl https://app.humaans.io/api/bank-accounts/Ivl8mvdLO8ux7T1h1DjGtClc \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "Ivl8mvdLO8ux7T1h1DjGtClc",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "bankName": "Mondo",
  "nameOnAccount": "Kelsey Wicks",
  "accountNumber": "12345678",
  "swiftCode": null,
  "sortCode": "00-00-00",
  "routingNumber": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a bank account

Parameters

  • personId string required

    ID of the person that this object is associated to.

  • bankName string | null

    The name of the bank.

  • nameOnAccount string | null

    The name on the bank account.

  • accountNumber string | null

    Bank account number.

  • swiftCode string | null

    The swift code of the bank account if relevant.

  • sortCode string | null

    The sort code of the bank account if relevant.

  • routingNumber string | null

    The routing number of the bank account if relevant.

Returns

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

POST /api/bank-accounts
curl https://app.humaans.io/api/bank-accounts \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW"}'
Response
{
  "id": "Ivl8mvdLO8ux7T1h1DjGtClc",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "bankName": "Mondo",
  "nameOnAccount": "Kelsey Wicks",
  "accountNumber": "12345678",
  "swiftCode": null,
  "sortCode": "00-00-00",
  "routingNumber": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a bank account

Parameters

  • bankName string | null

    The name of the bank.

  • nameOnAccount string | null

    The name on the bank account.

  • accountNumber string | null

    Bank account number.

  • swiftCode string | null

    The swift code of the bank account if relevant.

  • sortCode string | null

    The sort code of the bank account if relevant.

  • routingNumber string | null

    The routing number of the bank account if relevant.

Returns

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

PATCH /api/bank-accounts/:id
curl https://app.humaans.io/api/bank-accounts/Ivl8mvdLO8ux7T1h1DjGtClc \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"bankName":"N1"}'
Response
{
  "id": "Ivl8mvdLO8ux7T1h1DjGtClc",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "bankName": "N1",
  "nameOnAccount": "Kelsey Wicks",
  "accountNumber": "12345678",
  "swiftCode": null,
  "sortCode": "00-00-00",
  "routingNumber": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a bank account

Permanently deletes a bank account. It cannot be undone.

Parameters
  • No parameters
Returns

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

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

Collection values

A cell value within a collection item. Each value belongs to a collectionField (column) and a collectionItem (row).

Endpoints
Required scopes

Collection value object

Attributes

  • id string

    Unique identifier for the object.

  • collectionFieldId string

  • collectionItemId string

  • value string | string[]

    The value of the collection field.

    If collectionField.fieldType is text, longText, or select this should be a string.

    If collectionField.fieldType is multiSelect this should be an array of string.

    If collectionField.fieldType is date this should be a string formatted as a date.

    If collectionField.fieldType is link this should be a valid URL string.

    If collectionField.fieldType is relation this should be a relationEntity.id, or an array of relationEntity.id

  • createdAt string, date-time

    Time at which the object was created.

collection value object
{
  "id": "jhb9crXFnSVrXLybbiqE7wC8",
  "createdAt": "2020-01-28T08:44:42.000Z"
}

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

Company object

Attributes

  • id string

    Unique identifier for the object.

  • name string

    Company name.

  • domains object[]

    The list of domains owned by the company.

  • domains.domain string

    The domain

  • trialEndDate string, date

    The last date of trial.

  • status string

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

  • paymentStatus string

    One of requires_action, past_due, ok.

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

  • isTimesheetEnabled boolean

    Describes whether the timesheet functionality is enabled.

  • logo object

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

  • logo.id string

    Unique identifier for the object.

  • logo.filename string

  • logo.variants object

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

  • logo.variants.64 string

    URL of one of the predefined 2x logo sizes.

  • logo.variants.96 string

    URL of one of the predefined 3x logo sizes.

  • logo.variants.104 string

    URL of one of the predefined 2x logo sizes.

  • logo.variants.136 string

    URL of one of the predefined 2x logo sizes.

  • logo.variants.156 string

    URL of one of the predefined 3x logo sizes.

  • logo.variants.204 string

    URL of one of the predefined 3x logo sizes.

  • logo.variants.320 string

    URL of one of the predefined 2x logo sizes.

  • logo.variants.480 string

    URL of one of the predefined 3x logo sizes.

  • autogenerateEmployeeId boolean

    Whether employee IDs are automatically generated

  • autogenerateEmployeeIdForNewHires boolean

    Whether employee IDs are automatically generated for new hires

  • nextEmployeeId string

    The employee ID of the next employee to be created.

  • autogenerateEmployeeIdFilters object[]

    Filters that gate automatic employee ID generation. A person must match all filters to receive a generated ID.

  • autogenerateEmployeeIdFilters.field string

  • autogenerateEmployeeIdFilters.operator string

  • autogenerateEmployeeIdFilters.value string[]

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

List all companies

Returns a list of companies.

Parameters

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

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

Retrieve a company

Retrieves the company with the given ID.

Parameters
  • No parameters
Returns

Returns a company object if a valid identifier was provided.

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

Update a company

Parameters

  • name string

    Company name.

  • isTimesheetEnabled boolean

    Describes whether the timesheet functionality is enabled.

  • autogenerateEmployeeId boolean

    Whether employee IDs are automatically generated

  • autogenerateEmployeeIdForNewHires boolean

    Whether employee IDs are automatically generated for new hires

  • nextEmployeeId string | null

    The employee ID of the next employee to be created.

  • autogenerateEmployeeIdFilters object[]

    Filters that gate automatic employee ID generation. A person must match all filters to receive a generated ID.

  • autogenerateEmployeeIdFilters.field string required

  • autogenerateEmployeeIdFilters.operator string required

  • autogenerateEmployeeIdFilters.value string[] required

Returns

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

PATCH /api/companies/:id
curl https://app.humaans.io/api/companies/uoWtfpDIMI2IZ8doGK7kkCwS \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"name":"Meac"}'
Response
{
  "id": "uoWtfpDIMI2IZ8doGK7kkCwS",
  "name": "Meac",
  "domains": [],
  "trialEndDate": "2020-01-30",
  "status": "active",
  "paymentStatus": "ok",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "isTimesheetEnabled": true,
  "logo": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "autogenerateEmployeeIdFilters": [
    {}
  ]
}

Compensation types

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

Endpoints
GET /api/compensation-types
GET /api/compensation-types/:id
Required scopes
public.read
private.write
settings.write

Compensation type object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • name string

    The name of the compensation type.

  • baseType string

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

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

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

List all compensation types

Returns a list of compensation types.

Parameters

  • companyId string

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

  • $sort object

Returns

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

GET /api/compensation-types
curl https://app.humaans.io/api/compensation-types \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "ldOQU3pLI5i8Y9k2rJbrXbFc",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "Salary",
      "baseType": "salary",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a compensation type

Retrieves the compensation type with the given ID.

Parameters
  • No parameters
Returns

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

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

Compensations

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

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

Compensation object

Attributes

  • id string

    Unique identifier for the object.

  • personId string

    ID of the person that this object is associated to.

  • compensationTypeId string

    ID of the Compensation type this compensation is related to.

  • amount string

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

  • currency string

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

  • period string

    The period over which this compensation amount is paid. One of annual, biannual, quarterly, monthly, semimonthly, 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, commission and custom can have an endDate to indicate they are no longer in effect.

  • endReason string

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

  • createdAt createdAt, date-time

    Time at which the object was created.

  • updatedAt updatedAt, date-time

    Time at which the object was last updated.

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

List all compensations

Returns a list of compensations.

Parameters

  • personId string | $in

    The person to filter queries by.

  • compensationTypeId string

    The compensation type’s id to filter the queries by.

  • $asOf string, date

    Filter the list of compensations to only one of each type per employee, finding the compensation of each type that was in effect on the provided date.

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/compensations
curl https://app.humaans.io/api/compensations \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "m54mmpqDwthFwiiMcY0ptJdz",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "compensationTypeId": "aejf1oD4bZWNtEEnbFwrYGVg",
      "amount": "70000",
      "currency": "EUR",
      "period": "annual",
      "note": "Promotion",
      "effectiveDate": "2020-02-15",
      "endDate": null,
      "endReason": null,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a compensation

Retrieves the compensation with the given ID.

Parameters
  • No parameters
Returns

Returns a compensation object if a valid identifier was provided.

GET /api/compensations/:id
curl https://app.humaans.io/api/compensations/m54mmpqDwthFwiiMcY0ptJdz \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "m54mmpqDwthFwiiMcY0ptJdz",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "compensationTypeId": "aejf1oD4bZWNtEEnbFwrYGVg",
  "amount": "70000",
  "currency": "EUR",
  "period": "annual",
  "note": "Promotion",
  "effectiveDate": "2020-02-15",
  "endDate": null,
  "endReason": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a compensation

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

Parameters

  • personId string required

    ID of the person that this object is associated to.

  • compensationTypeId string required

    ID of the Compensation type this compensation is related to.

  • amount string required

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

  • currency string | null

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

  • period string required

    The period over which this compensation amount is paid. One of annual, biannual, quarterly, monthly, semimonthly, 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, commission and custom can have an endDate to indicate they are no longer in effect.

  • endReason string | null

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

Returns

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

POST /api/compensations
curl https://app.humaans.io/api/compensations \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","amount":"70000","period":"annual","effectiveDate":"2020-02-15","compensationTypeId":"aejf1oD4bZWNtEEnbFwrYGVg"}'
Response
{
  "id": "m54mmpqDwthFwiiMcY0ptJdz",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "compensationTypeId": "aejf1oD4bZWNtEEnbFwrYGVg",
  "amount": "70000",
  "currency": "EUR",
  "period": "annual",
  "note": "Promotion",
  "effectiveDate": "2020-02-15",
  "endDate": null,
  "endReason": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a compensation

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

Parameters

  • compensationTypeId string

    ID of the Compensation type this compensation is related to.

  • amount string

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

  • currency string | null

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

  • period string

    The period over which this compensation amount is paid. One of annual, biannual, quarterly, monthly, semimonthly, 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, commission and custom can have an endDate to indicate they are no longer in effect.

  • endReason string | null

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

Returns

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

PATCH /api/compensations/:id
curl https://app.humaans.io/api/compensations/m54mmpqDwthFwiiMcY0ptJdz \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"amount":"70000"}'
Response
{
  "id": "m54mmpqDwthFwiiMcY0ptJdz",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "compensationTypeId": "aejf1oD4bZWNtEEnbFwrYGVg",
  "amount": "70000",
  "currency": "EUR",
  "period": "annual",
  "note": "Promotion",
  "effectiveDate": "2020-02-15",
  "endDate": null,
  "endReason": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a compensation

Permanently deletes a compensation. It cannot be undone.

Parameters
  • No parameters
Returns

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

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

Custom fields

An object representing a custom field and it’s configuration.

Endpoints
   GET /api/custom-fields
   GET /api/custom-fields/:id
  POST /api/custom-fields
 PATCH /api/custom-fields/:id
DELETE /api/custom-fields/:id
Required scopes
compensations.read
employment.read
personal.read
private.read
public.read
private.write
settings.write

Custom field object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • name string

    The name of the custom field.

  • section string

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

  • resourceId string

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

  • type string

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

  • config object

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

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

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

List all custom fields

Returns a list of custom fields.

Parameters

  • section string | $in | $nin

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

  • type string | $in | $nin

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

  • id string | $in | $nin

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/custom-fields
curl https://app.humaans.io/api/custom-fields \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "ZpbLXlJRpBJQOre5kbFQqYf4",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "Payroll code",
      "section": "employment",
      "resourceId": "s6KZm4xNCvzBlCYeBSSCKDcH",
      "type": "text",
      "config": "{}",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a custom field

Retrieves the custom field with the given ID.

Parameters
  • No parameters
Returns

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

GET /api/custom-fields/:id
curl https://app.humaans.io/api/custom-fields/ZpbLXlJRpBJQOre5kbFQqYf4 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "ZpbLXlJRpBJQOre5kbFQqYf4",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Payroll code",
  "section": "employment",
  "resourceId": "s6KZm4xNCvzBlCYeBSSCKDcH",
  "type": "text",
  "config": "{}",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a custom field

Parameters

  • name string required

    The name of the custom field.

  • section string required

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

  • resourceId string | null

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

  • type string required

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

  • config object

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

Returns

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

POST /api/custom-fields
curl https://app.humaans.io/api/custom-fields \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"Payroll code","type":"text","section":"employment"}'
Response
{
  "id": "ZpbLXlJRpBJQOre5kbFQqYf4",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Payroll code",
  "section": "employment",
  "resourceId": "s6KZm4xNCvzBlCYeBSSCKDcH",
  "type": "text",
  "config": "{}",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a custom field

Parameters

  • name string

    The name of the custom field.

  • config object

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

Returns

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

PATCH /api/custom-fields/:id
curl https://app.humaans.io/api/custom-fields/ZpbLXlJRpBJQOre5kbFQqYf4 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"name":"Payroll number"}'
Response
{
  "id": "ZpbLXlJRpBJQOre5kbFQqYf4",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Payroll number",
  "section": "employment",
  "resourceId": "s6KZm4xNCvzBlCYeBSSCKDcH",
  "type": "text",
  "config": "{}",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a custom field

Permanently deletes a custom field. It cannot be undone.

Parameters
  • No parameters
Returns

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

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

Custom values

An object representing a custom field value.

Endpoints
   GET /api/custom-values
   GET /api/custom-values/:id
  POST /api/custom-values
 PATCH /api/custom-values/:id
DELETE /api/custom-values/:id
Required scopes
compensations.read
employment.read
personal.read
private.read
public.read
compensations.write
employment.write
personal.write
private.write

Custom value object

Attributes

  • id string

    Unique identifier for the object.

  • personId string

    ID of the person that this object is associated to.

  • customFieldId string

    The ID of the custom field this value is for.

  • resourceId string

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

  • value string | string[] | null

    The value of the custom field.

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

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

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

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

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

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

List all custom values

Returns a list of custom values.

Parameters

  • personId string | $in | $nin

    The person to filter queries by.

  • customFieldId string | $in | $nin

    The custom field to filter queries by.

  • resourceId string | $in | $nin

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

  • createdAt object

    Filter custom values by created at date.

  • createdAt.$gt date | date-time

  • createdAt.$gte date | date-time

  • createdAt.$lt date | date-time

  • createdAt.$lte date | date-time

  • updatedAt object

    Filter custom values by updated at date.

  • updatedAt.$gt date | date-time

  • updatedAt.$gte date | date-time

  • updatedAt.$lt date | date-time

  • updatedAt.$lte date | date-time

  • $or object[]

  • $or.resourceId string | $in | $nin

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/custom-values
curl https://app.humaans.io/api/custom-values \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "gk1P9Iidto7eh2ygaYD865P2",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "customFieldId": "ZzYipWn8ilL2lIxaFLhOeb7d",
      "resourceId": "X2O5IvAMDl3a88p7rbOiKImc",
      "value": "C8899754",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a custom value

Retrieves the custom value with the given ID.

Parameters
  • No parameters
Returns

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

GET /api/custom-values/:id
curl https://app.humaans.io/api/custom-values/gk1P9Iidto7eh2ygaYD865P2 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "gk1P9Iidto7eh2ygaYD865P2",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "customFieldId": "ZzYipWn8ilL2lIxaFLhOeb7d",
  "resourceId": "X2O5IvAMDl3a88p7rbOiKImc",
  "value": "C8899754",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a custom value

Parameters

  • value string | string[] | null required

    The value of the custom field.

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

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

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

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

  • personId string required

    ID of the person that this object is associated to.

  • customFieldId string required

    The ID of the custom field this value is for.

  • resourceId string | null

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

Returns

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

POST /api/custom-values
curl https://app.humaans.io/api/custom-values \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","customFieldId":"ZzYipWn8ilL2lIxaFLhOeb7d","value":"C8899754"}'
Response
{
  "id": "gk1P9Iidto7eh2ygaYD865P2",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "customFieldId": "ZzYipWn8ilL2lIxaFLhOeb7d",
  "resourceId": "X2O5IvAMDl3a88p7rbOiKImc",
  "value": "C8899754",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a custom value

Parameters

  • value string | string[] | null

    The value of the custom field.

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

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

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

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

Returns

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

PATCH /api/custom-values/:id
curl https://app.humaans.io/api/custom-values/gk1P9Iidto7eh2ygaYD865P2 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"value":"C7864654"}'
Response
{
  "id": "gk1P9Iidto7eh2ygaYD865P2",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "customFieldId": "ZzYipWn8ilL2lIxaFLhOeb7d",
  "resourceId": "X2O5IvAMDl3a88p7rbOiKImc",
  "value": "C7864654",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a custom value

Permanently deletes a custom value. It cannot be undone.

Parameters
  • No parameters
Returns

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

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

Document folders

An object representing a document folder. Document folders are used to organize company documents and control which employees can access them through audience rules.

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

Document folder object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • name string

  • audience object

  • audience.type string

  • audience.rules object[]

  • audience.rules.field string

  • audience.rules.operator string

  • audience.rules.value string

  • createdBy string

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

  • deletedAt string, date-time

document folder object
{
  "id": "7X4FVa9BZN1yutoROqX2LWiP",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "audience": {
    "rules": [
      {}
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all document folders

Returns a list of document folders.

Parameters

  • id string | $in | $nin

  • name string | $in | $nin

  • $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 folders. 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 folder object. If no document folders are available, the resulting list will be empty. This request should never return an error.

GET /api/document-folders
curl https://app.humaans.io/api/document-folders \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "7X4FVa9BZN1yutoROqX2LWiP",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "audience": {
        "rules": [
          {}
        ]
      },
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a document folder

Retrieves the document folder with the given ID.

Parameters
  • No parameters
Returns

Returns a document folder object if a valid identifier was provided.

GET /api/document-folders/:id
curl https://app.humaans.io/api/document-folders/7X4FVa9BZN1yutoROqX2LWiP \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "7X4FVa9BZN1yutoROqX2LWiP",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "audience": {
    "rules": [
      {}
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a document folder

Parameters

  • name string required

  • audience object

  • audience.type string required

  • audience.rules object[] required

  • audience.rules.field string required

  • audience.rules.operator string required

  • audience.rules.value string required

Returns

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

POST /api/document-folders
curl https://app.humaans.io/api/document-folders \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{}'
Response
{
  "id": "7X4FVa9BZN1yutoROqX2LWiP",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "audience": {
    "rules": [
      {}
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a document folder

Parameters

  • name string

  • audience object

  • audience.type string required

  • audience.rules object[] required

  • audience.rules.field string required

  • audience.rules.operator string required

  • audience.rules.value string required

Returns

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

PATCH /api/document-folders/:id
curl https://app.humaans.io/api/document-folders/7X4FVa9BZN1yutoROqX2LWiP \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'
Response
{
  "id": "7X4FVa9BZN1yutoROqX2LWiP",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "audience": {
    "rules": [
      {}
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a document folder

Permanently deletes a document folder. It cannot be undone.

Parameters
  • No parameters
Returns

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

DELETE /api/document-folders/:id
curl https://app.humaans.io/api/document-folders/7X4FVa9BZN1yutoROqX2LWiP \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE
Response
{
  "id": "7X4FVa9BZN1yutoROqX2LWiP",
  "deleted": true
}

Document types

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

Endpoints
  GET /api/document-types
 POST /api/document-types
PATCH /api/document-types/:id
Required scopes
documents.read
public.read
documents.write
settings.write

Document type object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • name string

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

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

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

List all document types

Returns a list of document types.

Parameters

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/document-types
curl https://app.humaans.io/api/document-types \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "Ozcv1Wea2yfUhSm8fsj0ziIf",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "Employment agreement",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Create a document type

Parameters

  • name string required

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

Returns

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

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

Update a document type

Parameters

  • name string required

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

Returns

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

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

Documents

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

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

Document object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • personId string

    ID of the person that this object is associated to.

  • name string

    The name of the document

  • documentTypeId string

    The ID of the document type.

  • folderId string

  • link string

    Documents must have either a link or a file attached.

  • fileId string

    Documents must have either a link or a file attached.

  • file object

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

  • file.id string

    Unique identifier for the object.

  • file.url string

    The URL from which the attached file can be downloaded.

  • file.filename string

    The name of the file attached.

  • source string

    The external service from which the document has been imported

  • sourceId string

    The unique identifier of the document in the remote service

  • issueDate string, date

    The date when the document was issued.

  • createdBy string

    ID of the user who created the document

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

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

List all documents

Returns a list of documents.

Parameters

  • personId string | $ne | $in

    ID of the person that this object is associated to. Pass null or no value for company documents only (personId is null). Use personId[$ne]=null for personal docs only, personId[$in][]=id for multiple.

  • $or object[]

    Filter by multiple conditions.

  • $or.personId string | empty

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

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

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

Retrieve a document

Retrieves the document with the given ID.

Parameters
  • No parameters
Returns

Returns a document object if a valid identifier was provided.

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

Create a document

Parameters

  • personId string | null

    ID of the person that this object is associated to.

  • name string required

    The name of the document

  • documentTypeId string | null

    The ID of the document type.

  • folderId string | null

  • link string | null

    Documents must have either a link or a file attached.

  • fileId string | null

    Documents must have either a link or a file attached.

  • issueDate string, date

    The date when the document was issued.

  • type string

    The document type.

Returns

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

POST /api/documents
curl https://app.humaans.io/api/documents \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"Employment agreement 2020 (Initial)","link":"https://drive.google.com/docs/KMjibfqIQC3hiZK2tFItQetm"}'
Response
{
  "id": "j5nMguwlwQeNYkk9Jie8u1Q2",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "name": "Employment agreement 2020 (Initial)",
  "link": "https://drive.google.com/docs/KMjibfqIQC3hiZK2tFItQetm",
  "fileId": null,
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "source": null,
  "sourceId": null,
  "issueDate": "2020-01-28",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a document

Parameters

  • name string

    The name of the document

  • documentTypeId string | null

    The ID of the document type.

  • folderId string | null

  • issueDate string, date

    The date when the document was issued.

  • type string

    The document type.

Returns

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

PATCH /api/documents/:id
curl https://app.humaans.io/api/documents/j5nMguwlwQeNYkk9Jie8u1Q2 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"link":"https://intranet/doc/2"}'
Response
{
  "id": "j5nMguwlwQeNYkk9Jie8u1Q2",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "name": "Employment agreement 2020 (Initial)",
  "link": "https://intranet/doc/2",
  "fileId": null,
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "source": null,
  "sourceId": null,
  "issueDate": "2020-01-28",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a document

Permanently deletes a document. It cannot be undone.

Parameters
  • No parameters
Returns

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

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

Emergency contacts

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

Endpoints
   GET /api/emergency-contacts
   GET /api/emergency-contacts/:id
  POST /api/emergency-contacts
 PATCH /api/emergency-contacts/:id
DELETE /api/emergency-contacts/:id
Required scopes
personal.read
private.read
personal.write
private.write

Emergency contact object

Attributes

  • id string

    Unique identifier for the object.

  • personId string

    ID of the person that this object is associated to.

  • name string

    The name of the emergency contact.

  • email string

    The email of the emergency contact.

  • phoneNumber string

    The phone number of the emergency contact.

  • formattedPhoneNumber string

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

  • relationship string

    The relationship of the emergency contact to the employee.

  • isPrimary boolean

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

  • createdAt createdAt, date-time

    Time at which the object was created.

  • updatedAt updatedAt, date-time

    Time at which the object was last updated.

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

List all emergency contacts

Returns a list of emergency contacts.

Parameters

  • isPrimary boolean

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

  • personId string | $in

    The person to filter queries by.

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/emergency-contacts
curl https://app.humaans.io/api/emergency-contacts \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "QmzB8xCTAG7IIHcsM1DKdpZe",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "name": "Sean Reese",
      "email": "sean@example.com",
      "phoneNumber": "+4479460000",
      "formattedPhoneNumber": "+44 7946 0000",
      "relationship": "Partner ❤️",
      "isPrimary": true,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve an emergency contact

Retrieves the emergency contact with the given ID.

Parameters
  • No parameters
Returns

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

GET /api/emergency-contacts/:id
curl https://app.humaans.io/api/emergency-contacts/QmzB8xCTAG7IIHcsM1DKdpZe \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "QmzB8xCTAG7IIHcsM1DKdpZe",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "name": "Sean Reese",
  "email": "sean@example.com",
  "phoneNumber": "+4479460000",
  "formattedPhoneNumber": "+44 7946 0000",
  "relationship": "Partner ❤️",
  "isPrimary": true,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create an emergency contact

Parameters

  • name string | null

    The name of the emergency contact.

  • email string | null

    The email of the emergency contact.

  • phoneNumber string | null

    The phone number of the emergency contact.

  • relationship string | null

    The relationship of the emergency contact to the employee.

  • personId string required

    ID of the person that this object is associated to.

  • isPrimary boolean required

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

Returns

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

POST /api/emergency-contacts
curl https://app.humaans.io/api/emergency-contacts \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","isPrimary":true}'
Response
{
  "id": "QmzB8xCTAG7IIHcsM1DKdpZe",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "name": "Sean Reese",
  "email": "sean@example.com",
  "phoneNumber": "+4479460000",
  "formattedPhoneNumber": "+44 7946 0000",
  "relationship": "Partner ❤️",
  "isPrimary": true,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update an emergency contact

Parameters

  • name string | null

    The name of the emergency contact.

  • email string | null

    The email of the emergency contact.

  • phoneNumber string | null

    The phone number of the emergency contact.

  • relationship string | null

    The relationship of the emergency contact to the employee.

Returns

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

PATCH /api/emergency-contacts/:id
curl https://app.humaans.io/api/emergency-contacts/QmzB8xCTAG7IIHcsM1DKdpZe \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"email":"sean.reese@example.com"}'
Response
{
  "id": "QmzB8xCTAG7IIHcsM1DKdpZe",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "name": "Sean Reese",
  "email": "sean.reese@example.com",
  "phoneNumber": "+4479460000",
  "formattedPhoneNumber": "+44 7946 0000",
  "relationship": "Partner ❤️",
  "isPrimary": true,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete an emergency contact

Permanently deletes an emergency contact. It cannot be undone.

Parameters
  • No parameters
Returns

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

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

Equipment

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

Endpoints
   GET /api/equipment
   GET /api/equipment/:id
  POST /api/equipment
 PATCH /api/equipment/:id
DELETE /api/equipment/:id
Required scopes
employment.read
private.read
employment.write
private.write

Equipment object

Attributes

  • id string

    Unique identifier for the object.

  • personId string

    ID of the person that this object is associated to.

  • type string

    The type of the equipment.

  • name string

    The name / model on the equipment.

  • serialNumber string

    The serial number.

  • cost string

    Cost, the fraction should be separated with a dot.

  • currency string

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

  • note string

    Any additional notes.

  • fileId string

    A file attachment.

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

  • issueDate string, date

    The date when the equipment was issued.

  • receiptDate string, date

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

  • collectionDate string, date

    The date when the equipment was collected from the employee.

  • collectedBy string

    The person that marked the equipment as collected.

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

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

List all equipment

Returns a list of equipment.

Parameters

  • personId string

    The person to filter queries by.

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/equipment
curl https://app.humaans.io/api/equipment \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "W1Uisa336KrC6Rt55pEBkTNZ",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "type": "Laptop",
      "name": "MacBook Pro (13-inch, 2017)",
      "serialNumber": "C012345678",
      "cost": "1299",
      "currency": "EUR",
      "note": "Refurbished.",
      "fileId": null,
      "file": null,
      "issueDate": "2020-01-28",
      "receiptDate": "2020-01-28",
      "collectionDate": null,
      "collectedBy": null,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve an equipment

Retrieves the equipment with the given ID.

Parameters
  • No parameters
Returns

Returns an equipment object if a valid identifier was provided.

GET /api/equipment/:id
curl https://app.humaans.io/api/equipment/W1Uisa336KrC6Rt55pEBkTNZ \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "W1Uisa336KrC6Rt55pEBkTNZ",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "Laptop",
  "name": "MacBook Pro (13-inch, 2017)",
  "serialNumber": "C012345678",
  "cost": "1299",
  "currency": "EUR",
  "note": "Refurbished.",
  "fileId": null,
  "file": null,
  "issueDate": "2020-01-28",
  "receiptDate": "2020-01-28",
  "collectionDate": null,
  "collectedBy": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create an equipment

Parameters

  • personId string required

    ID of the person that this object is associated to.

  • type string required

    The type of the equipment.

  • name string required

    The name / model on the equipment.

  • serialNumber string | null

    The serial number.

  • cost string | null

    Cost, the fraction should be separated with a dot.

  • currency string | null

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

  • note string | null

    Any additional notes.

  • fileId string | null

    A file attachment.

  • issueDate string, date required

    The date when the equipment was issued.

  • receiptDate string, date | null

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

  • collectionDate string, date | null

    The date when the equipment was collected from the employee.

Returns

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

POST /api/equipment
curl https://app.humaans.io/api/equipment \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","type":"Laptop","name":"MacBook Pro (13-inch, 2017)","issueDate":"2020-01-28"}'
Response
{
  "id": "W1Uisa336KrC6Rt55pEBkTNZ",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "Laptop",
  "name": "MacBook Pro (13-inch, 2017)",
  "serialNumber": "C012345678",
  "cost": "1299",
  "currency": "EUR",
  "note": "Refurbished.",
  "fileId": null,
  "file": null,
  "issueDate": "2020-01-28",
  "receiptDate": "2020-01-28",
  "collectionDate": null,
  "collectedBy": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update an equipment

Parameters

  • type string

    The type of the equipment.

  • name string

    The name / model on the equipment.

  • serialNumber string | null

    The serial number.

  • cost string | null

    Cost, the fraction should be separated with a dot.

  • currency string | null

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

  • note string | null

    Any additional notes.

  • fileId string | null

    A file attachment.

  • issueDate string, date

    The date when the equipment was issued.

  • receiptDate string, date | null

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

  • collectionDate string, date | null

    The date when the equipment was collected from the employee.

Returns

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

PATCH /api/equipment/:id
curl https://app.humaans.io/api/equipment/W1Uisa336KrC6Rt55pEBkTNZ \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"name":"MacBook Pro (13-inch, 2020)"}'
Response
{
  "id": "W1Uisa336KrC6Rt55pEBkTNZ",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "Laptop",
  "name": "MacBook Pro (13-inch, 2020)",
  "serialNumber": "C012345678",
  "cost": "1299",
  "currency": "EUR",
  "note": "Refurbished.",
  "fileId": null,
  "file": null,
  "issueDate": "2020-01-28",
  "receiptDate": "2020-01-28",
  "collectionDate": null,
  "collectedBy": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete an equipment

Permanently deletes an equipment. It cannot be undone.

Parameters
  • No parameters
Returns

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

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

Equipment names

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

Endpoints
GET /api/equipment-names
Required scopes
employment.read
private.read

Equipment name object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • value string

    The label of the equipment name.

  • isDefault boolean

    Whether this name is the default name provided by Humaans.

  • isUsed boolean

    Whether this name is used for some equipment.

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

List all equipment names

Returns a list of equipment names.

Parameters

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

  • type string

    Filter the equipment names by equipment type.

Returns

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

GET /api/equipment-names
curl https://app.humaans.io/api/equipment-names \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "j9541EU55Ru2fJ50WGWjPkod",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "value": "Laptop",
      "isDefault": true,
      "isUsed": true
    }
  ]
}

Equipment types

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

Endpoints
GET /api/equipment-types
Required scopes
employment.read
private.read

Equipment type object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • value string

    The label of the equipment type.

  • isDefault boolean

    Whether this type is the default type provided by Humaans.

  • isUsed boolean

    Whether this type is used for some equipment.

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

List all equipment types

Returns a list of equipment types.

Parameters

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/equipment-types
curl https://app.humaans.io/api/equipment-types \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "mK6SIWfNdZWb4x9dRmTYtn7g",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "value": "Laptop",
      "isDefault": true,
      "isUsed": true
    }
  ]
}

Esign bulk recipient data

Per-person recipient data for a bulk e-signature send. Overrides recipient details (e.g. email, identifier) for a specific person in the bulk.

Endpoints
Required scopes
esig.read
public.read
esig.write
private.write

Esign bulk recipient data object

Attributes

  • id string

    Unique identifier for the object.

  • esignBulkRecipientId string

  • esignBulkId string

  • identifier string

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

  • deletedAt string, date-time

esign bulk recipient data object
{
  "id": "zn0gWVzsqRrEAbBcbkPDS6NS",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Esign bulk recipients

A recipient definition within a bulk e-signature send. Defines the role and type of recipient that will be added to each instance in the bulk.

Endpoints
Required scopes
esig.read
public.read
esig.write
private.write

Esign bulk recipient object

Attributes

  • id string

    Unique identifier for the object.

  • esignBulkId string

  • orderIndex string

  • primary boolean

  • role string

  • type string

  • actionType string

  • identifier string

    Person ID for workEmail/personalEmail types, “manager” for dynamic type, or the name of the external recipient for external type.

  • email string

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

  • deletedAt string, date-time

  • valid boolean

  • errors object

esign bulk recipient object
{
  "id": "WZylU9Rs6klilSUjsrUqrG93",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "errors": {}
}

Esign bulk token data

Per-person token data for a bulk e-signature send. Provides specific values (e.g. salary, start date) for fillable fields for each person in the bulk.

Endpoints
Required scopes
esig.read
public.read
esig.write
private.write

Esign bulk token data object

Attributes

  • id string

    Unique identifier for the object.

  • esignBulkId string

  • esignBulkTokenId string

  • esignBulkRecipientDataId string

  • value string

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

  • deletedAt string, date-time

esign bulk token data object
{
  "id": "8KjiaC28Xa8gIlqhjp7xjZfn",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Esign bulk tokens

A token definition within a bulk e-signature send. Defines the fillable fields that will be created on each instance in the bulk.

Endpoints
Required scopes
esig.read
public.read
esig.write
private.write

Esign bulk token object

Attributes

  • id string

    Unique identifier for the object.

  • esignBulkId string

  • esignBulkRecipientId string

  • identifier string

  • type string

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

esign bulk token object
{
  "id": "Ub4NKAXPiDjwT1f4aet1CwPm",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Esign bulks

A bulk e-signature send operation. Groups multiple e-signature instances that were sent together (e.g. offer letters for a batch of new hires).

Endpoints
Required scopes
esig.read
public.read
esig.write
private.write

Esign bulk object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • documentType string

  • documentTypeId string

  • esignTemplateId string

  • status string

  • name string

  • body object

  • personId string

    ID of the person that this object is associated to.

  • emailSubject object

  • emailBody object

  • expiringAfter number

  • config object

  • config.margins object

  • config.margins.top number

  • config.margins.bottom number

  • config.margins.left number

  • config.margins.right number

  • config.dateFormat string

  • config.header object

  • config.footer object

  • config.beforeHeader number

  • config.afterHeader number

  • config.beforeFooter number

  • config.afterFooter number

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

  • deletedAt string, date-time

esign bulk object
{
  "id": "Cw7Ah6NQAolsYpB9lO3bJUq0",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "body": {},
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "emailSubject": {},
  "emailBody": {},
  "config": {
    "margins": {},
    "header": {},
    "footer": {}
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Esign instance recipients

A recipient on a specific e-signature instance. Tracks their signing status (queued, requested, completed) and contact details.

Endpoints
Required scopes
esig.read
public.read
esig.write
private.write

Esign instance recipient object

Attributes

  • id string

    Unique identifier for the object.

  • accessToken string

  • accessTokenExpiresAt string, date-time

  • esignInstanceId string

  • role string

  • type string

  • actionType string

  • identifier string

    Person ID for workEmail/personalEmail types, “manager” for dynamic type, or the name of the external recipient for external type.

  • email string

  • primary boolean

  • status string

  • orderIndex string

  • documentStatus string

  • viewedAt string, date-time

  • sentAt string, date-time

  • meta object

  • meta.ipAddress string

  • meta.resolvedFrom string

  • meta.resolvedAt string, date-time

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

  • valid boolean

  • errors object

esign instance recipient object
{
  "id": "mpkG7ztNtsDKzngGOs6UUttF",
  "meta": {},
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "errors": {}
}

Esign instance tokens

A fillable field on a specific e-signature instance. Sender tokens (recipientId is null) must be filled before sending. Recipient tokens are filled by the signer.

Endpoints
Required scopes
esig.read
public.read
esig.write
private.write

Esign instance token object

Attributes

  • id string

    Unique identifier for the object.

  • instanceId string

  • recipientId string

  • type string

  • identifier string

  • value string

  • meta object

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

esign instance token object
{
  "id": "ZWVrPay3j4D2xnTF5j7G5D5C",
  "meta": {},
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Esign instances

A specific e-signature document sent to a person. Created from a template or from scratch. Status lifecycle: draft → requested → completed/cancelled/expired/blocked.

Endpoints
Required scopes
esig.read
public.read
esig.write
private.write

Esign instance object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • name string

  • status string

  • body object

  • documentType string

  • documentTypeId string

  • fileId string

  • emailSubject object

  • emailBody object

  • esignTemplateId string

    Create from a template. When provided, do not send name, body, documentTypeId, emailBody, emailSubject, expiringAfter, or config — they are copied from the template.

  • esignBulkId string

  • primaryRecipient object

  • primaryRecipient.id string

    Unique identifier for the object.

  • primaryRecipient.accessToken string

  • primaryRecipient.accessTokenExpiresAt string, date-time

  • primaryRecipient.esignInstanceId string

  • primaryRecipient.role string

  • primaryRecipient.type string

  • primaryRecipient.actionType string

  • primaryRecipient.identifier string

    Person ID for workEmail/personalEmail types, “manager” for dynamic type, or the name of the external recipient for external type.

  • primaryRecipient.email string

  • primaryRecipient.primary boolean

  • primaryRecipient.status string

  • primaryRecipient.orderIndex string

  • primaryRecipient.documentStatus string

  • primaryRecipient.viewedAt string, date-time

  • primaryRecipient.sentAt string, date-time

  • primaryRecipient.meta object

  • primaryRecipient.meta.ipAddress string

  • primaryRecipient.meta.resolvedFrom string

  • primaryRecipient.meta.resolvedAt string, date-time

  • primaryRecipient.createdAt string, date-time

    Time at which the object was created.

  • primaryRecipient.updatedAt string, date-time

    Time at which the object was last updated.

  • primaryRecipient.valid boolean

  • primaryRecipient.errors object

  • expiringAfter number

  • config object

  • config.margins object

  • config.margins.top number

  • config.margins.bottom number

  • config.margins.left number

  • config.margins.right number

  • config.dateFormat string

  • config.header object

  • config.footer object

  • config.beforeHeader number

  • config.afterHeader number

  • config.beforeFooter number

  • config.afterFooter number

  • sentBy string

  • personId string

    ID of the person that this object is associated to.

  • requestedAt string, date-time

  • completedAt string, date-time

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

esign instance object
{
  "id": "bShNf9nVEYevKeYPyQLpoDHg",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "body": {},
  "emailSubject": {},
  "emailBody": {},
  "primaryRecipient": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "meta": {},
    "createdAt": "2020-01-28T08:44:42.000Z",
    "updatedAt": "2020-01-29T14:52:21.000Z",
    "errors": {}
  },
  "config": {
    "margins": {},
    "header": {},
    "footer": {}
  },
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Esign template recipients

A recipient slot on an e-signature template. Defines the role (e.g. Employee, Witness), type (internal person, external, dynamic), and action (sign, review, CC).

Endpoints
Required scopes
esig.read
public.read
esig.write
private.write

Esign template recipient object

Attributes

  • id string

    Unique identifier for the object.

  • esignTemplateId string

  • role string

  • type string

  • actionType string

  • identifier string

    Person ID for workEmail/personalEmail types, “manager” for dynamic type, or the name of the external recipient for external type.

  • email string

  • primary boolean

  • orderIndex string

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

esign template recipient object
{
  "id": "mFqCizFCVS7DfSDwO9BNJhnQ",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Esign template tokens

A fillable field in an e-signature template (e.g. signature, date, text input, auto-populated property). Tokens are embedded in the document body.

Endpoints
Required scopes
esig.read
public.read
esig.write
private.write

Esign template token object

Attributes

  • id string

    Unique identifier for the object.

  • templateId string

  • recipientId string

  • identifier string

  • type string

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

esign template token object
{
  "id": "0trZqDKlxXRpUvXKQbzdNfwD",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Esign templates

A reusable e-signature document template (e.g. employment contract, NDA). Contains the document body, email settings, recipients, and fillable tokens.

Endpoints
Required scopes
esig.read
public.read
esig.write
private.write

Esign template object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • name string

  • body object

  • documentType string

  • documentTypeId string

  • emailSubject object

  • emailBody object

  • esignTemplateId string

  • expiringAfter number

  • config object

  • config.margins object

  • config.margins.top number

  • config.margins.bottom number

  • config.margins.left number

  • config.margins.right number

  • config.dateFormat string

  • config.header object

  • config.footer object

  • config.beforeHeader number

  • config.afterHeader number

  • config.beforeFooter number

  • config.afterFooter number

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

esign template object
{
  "id": "QIVG3ElqysY9mmeFGYRVRfBd",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "body": {},
  "emailSubject": {},
  "emailBody": {},
  "config": {
    "margins": {},
    "header": {},
    "footer": {}
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Identity document types

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

Endpoints
GET /api/identity-document-types
Required scopes
documents.read

Identity document type object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • value string

    The label of the identity document type.

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

List all identity document types

Returns a list of identity document types.

Parameters

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/identity-document-types
curl https://app.humaans.io/api/identity-document-types \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "yI3rZlTcWBvn3F4ChC5d1X2b",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "value": "Passport"
    }
  ]
}

Identity documents

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

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

Identity document object

Attributes

  • id string

    Unique identifier for the object.

  • personId string

    ID of the person that this object is associated to.

  • type string

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

  • number string

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

  • countryCode string

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

  • expiryDate string, date

    Expiry date of the document.

  • note string

    An optional note about the identity document.

  • fileId string

    The ID of the file attached to this identity document.

  • file object

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

  • file.id string

    Unique identifier for the object.

  • file.url string

    The URL from which the attached file can be downloaded.

  • file.filename string

    The name of the file attached.

  • verifiedBy string

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

  • verifiedAt string, date-time

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

  • isVerified boolean

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

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

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

List all identity documents

Returns a list of identity documents.

Parameters

  • personId string

    The person to filter queries by.

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

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

Retrieve an identity document

Retrieves the identity document with the given ID.

Parameters
  • No parameters
Returns

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

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

Create an identity document

Parameters

  • personId string required

    ID of the person that this object is associated to.

  • type string required

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

  • number string | null

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

  • countryCode string | null

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

  • expiryDate string, date | null

    Expiry date of the document.

  • note string | null

    An optional note about the identity document.

  • fileId string required

    The ID of the file attached to this identity document.

  • verifiedBy string | null

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

Returns

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

POST /api/identity-documents
curl https://app.humaans.io/api/identity-documents \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","type":"Passport","fileId":"51YzMOYrc9rU0lNGn1QtgSv0"}'
Response
{
  "id": "a0M0OIrmNIQe7UP5AaPxv9jN",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "Passport",
  "number": "12345678",
  "countryCode": "GB",
  "expiryDate": "2050-06-24",
  "note": null,
  "fileId": "51YzMOYrc9rU0lNGn1QtgSv0",
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "verifiedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "verifiedAt": "ob4xPcVpGGZm043C7xGMfP1U",
  "isVerified": true,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update an identity document

Parameters

  • type string

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

  • number string | null

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

  • countryCode string | null

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

  • expiryDate string, date | null

    Expiry date of the document.

  • note string | null

    An optional note about the identity document.

  • fileId string

    The ID of the file attached to this identity document.

  • verifiedBy string | null

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

Returns

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

PATCH /api/identity-documents/:id
curl https://app.humaans.io/api/identity-documents/a0M0OIrmNIQe7UP5AaPxv9jN \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"expiryDate":"2050-05-01"}'
Response
{
  "id": "a0M0OIrmNIQe7UP5AaPxv9jN",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "Passport",
  "number": "12345678",
  "countryCode": "GB",
  "expiryDate": "2050-05-01",
  "note": null,
  "fileId": "51YzMOYrc9rU0lNGn1QtgSv0",
  "file": {
    "id": "51YzMOYrc9rU0lNGn1QtgSv0",
    "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0",
    "filename": "passport-scan.pdf"
  },
  "verifiedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "verifiedAt": "ob4xPcVpGGZm043C7xGMfP1U",
  "isVerified": true,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete an identity document

Permanently deletes an identity document. It cannot be undone.

Parameters
  • No parameters
Returns

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

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

Job roles

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

Endpoints
   GET /api/job-roles
   GET /api/job-roles/:id
  POST /api/job-roles
 PATCH /api/job-roles/:id
DELETE /api/job-roles/:id
Required scopes
employment.read
private.read
public.read
employment.write
private.write

Job role object

Attributes

  • id string

    Unique identifier for the object.

  • personId string

    ID of the person that this object is associated to.

  • jobTitle string

    Job title.

  • department string

    The name of the department.

  • effectiveDate string, date

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

  • endDate string, date

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

  • isFirst boolean

    Whether this is the first job role for this person.

  • reportingTo string

    The ID of the manager.

  • note string

    An optional note about this particular job role entry.

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

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

List all job roles

Returns a list of job roles.

Parameters

  • personId string | $in

    The person to filter queries by.

  • department string | empty

    Filter job roles by department name (exact match), or null to find roles with no department. Use with $asOf to get current roles in a department.

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

  • effectiveDate object

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

  • effectiveDate.$gt date | date-time

  • effectiveDate.$gte date | date-time

  • effectiveDate.$lt date | date-time

  • effectiveDate.$lte date | date-time

  • $sort object

  • $sort.effectiveDate number

Returns

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

GET /api/job-roles
curl https://app.humaans.io/api/job-roles \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "hmA5GnUq9ojK86LLKKWbiuKG",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "jobTitle": "Software Engineer",
      "department": "Engineering",
      "effectiveDate": "2020-02-15",
      "endDate": "2020-02-22",
      "reportingTo": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
      "note": "Switched departments",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a job role

Retrieves the job role with the given ID.

Parameters
  • No parameters
Returns

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

GET /api/job-roles/:id
curl https://app.humaans.io/api/job-roles/hmA5GnUq9ojK86LLKKWbiuKG \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "hmA5GnUq9ojK86LLKKWbiuKG",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "jobTitle": "Software Engineer",
  "department": "Engineering",
  "effectiveDate": "2020-02-15",
  "endDate": "2020-02-22",
  "reportingTo": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
  "note": "Switched departments",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a job role

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

Parameters

  • personId string required

    ID of the person that this object is associated to.

  • jobTitle string required

    Job title.

  • department string | null

    The name of the department.

  • effectiveDate string, date required

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

  • note string | null

    An optional note about this particular job role entry.

  • reportingTo string | null

    The ID of the manager.

  • customValues object[]

  • customValues.customFieldId string required

  • customValues.value string | array required

  • customValues.resourceId

Returns

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

POST /api/job-roles
curl https://app.humaans.io/api/job-roles \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"jobTitle":"Product Engineer"}'
Response
{
  "id": "hmA5GnUq9ojK86LLKKWbiuKG",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "jobTitle": "Product Engineer",
  "department": "Engineering",
  "effectiveDate": "2020-02-15",
  "endDate": "2020-02-22",
  "reportingTo": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
  "note": "Switched departments",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a job role

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

Parameters

  • jobTitle string

    Job title.

  • department string | null

    The name of the department.

  • effectiveDate string, date

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

  • note string | null

    An optional note about this particular job role entry.

  • reportingTo string | null

    The ID of the manager.

Returns

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

PATCH /api/job-roles/:id
curl https://app.humaans.io/api/job-roles/hmA5GnUq9ojK86LLKKWbiuKG \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"jobTitle":"Product Engineer"}'
Response
{
  "id": "hmA5GnUq9ojK86LLKKWbiuKG",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "jobTitle": "Product Engineer",
  "department": "Engineering",
  "effectiveDate": "2020-02-15",
  "endDate": "2020-02-22",
  "reportingTo": "6iJcJ6aKIj1H4ubC4Zp0LlT6",
  "note": "Switched departments",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a job role

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

Parameters
  • No parameters
Returns

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

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

Locations

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

Endpoints
   GET /api/locations
   GET /api/locations/:id
  POST /api/locations
 PATCH /api/locations/:id
DELETE /api/locations/:id
Required scopes
public.read
private.write
settings.write

Location object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • label string

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

  • displayName string

  • address string

    A street address of the location.

  • postcode string

    Postcode.

  • city string

    City.

  • state string

    State.

  • country string

    Country name, infered from the countryCode.

  • regionCode string

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

  • countryCode string

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

  • timezone string

    Timezone, infered from the city and country.

  • isAddressInvalid boolean

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

  • timeAwayPolicyId string

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

  • timeAwayPolicyEffectiveDate string, date

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

  • workingPatternId string

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

  • workingPatternEffectiveDate string, date

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

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

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

List all locations

Returns a list of locations.

Parameters

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/locations
curl https://app.humaans.io/api/locations \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "oIBBB436k2YCOY5gzVhC5idx",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "label": "Acme HQ",
      "displayName": "Acme HQ",
      "address": "Uncommon, 22 Curved Road",
      "postcode": "SE1 5AG",
      "city": "London",
      "state": null,
      "country": "United Kingdom",
      "regionCode": null,
      "countryCode": "GB",
      "timezone": "Europe/London",
      "isAddressInvalid": false,
      "timeAwayPolicyId": "lQhHxduYbvq0TRIJq2IPN3hH",
      "timeAwayPolicyEffectiveDate": "2024-01-30",
      "workingPatternId": "lQhHxduYbvq0TRIJq2IPN3hH",
      "workingPatternEffectiveDate": "2024-04-06",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a location

Retrieves the location with the given ID.

Parameters
  • No parameters
Returns

Returns a location object if a valid identifier was provided.

GET /api/locations/:id
curl https://app.humaans.io/api/locations/oIBBB436k2YCOY5gzVhC5idx \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "oIBBB436k2YCOY5gzVhC5idx",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "label": "Acme HQ",
  "displayName": "Acme HQ",
  "address": "Uncommon, 22 Curved Road",
  "postcode": "SE1 5AG",
  "city": "London",
  "state": null,
  "country": "United Kingdom",
  "regionCode": null,
  "countryCode": "GB",
  "timezone": "Europe/London",
  "isAddressInvalid": false,
  "timeAwayPolicyId": "lQhHxduYbvq0TRIJq2IPN3hH",
  "timeAwayPolicyEffectiveDate": "2024-01-30",
  "workingPatternId": "lQhHxduYbvq0TRIJq2IPN3hH",
  "workingPatternEffectiveDate": "2024-04-06",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a location

Parameters

  • address string | null

    A street address of the location.

  • city string required

    City.

  • state string | null

    State.

  • postcode string | null

    Postcode.

  • countryCode string required

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

  • label string | null

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

  • timeAwayPolicyId string required

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

  • timeAwayPolicyEffectiveDate string, date | null

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

  • workingPatternId string | null

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

  • workingPatternEffectiveDate string, date | null

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

Returns

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

POST /api/locations
curl https://app.humaans.io/api/locations \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"city":"London","countryCode":"GB","timeAwayPolicyId":"lQhHxduYbvq0TRIJq2IPN3hH"}'
Response
{
  "id": "oIBBB436k2YCOY5gzVhC5idx",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "label": "Acme HQ",
  "displayName": "Acme HQ",
  "address": "Uncommon, 22 Curved Road",
  "postcode": "SE1 5AG",
  "city": "London",
  "state": null,
  "country": "United Kingdom",
  "regionCode": null,
  "countryCode": "GB",
  "timezone": "Europe/London",
  "isAddressInvalid": false,
  "timeAwayPolicyId": "lQhHxduYbvq0TRIJq2IPN3hH",
  "timeAwayPolicyEffectiveDate": "2024-01-30",
  "workingPatternId": "lQhHxduYbvq0TRIJq2IPN3hH",
  "workingPatternEffectiveDate": "2024-04-06",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a location

Parameters

  • address string | null

    A street address of the location.

  • city string

    City.

  • state string | null

    State.

  • postcode string | null

    Postcode.

  • countryCode string

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

  • label string | null

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

  • timeAwayPolicyId string

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

  • timeAwayPolicyEffectiveDate string, date | null

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

  • workingPatternId string | null

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

  • workingPatternEffectiveDate string, date | null

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

  • updateExistingPeopleTimeAwayPolicy boolean

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

  • updateExistingPeopleWorkingPattern boolean

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

Returns

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

PATCH /api/locations/:id
curl https://app.humaans.io/api/locations/oIBBB436k2YCOY5gzVhC5idx \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"city":"Quebec"}'
Response
{
  "id": "oIBBB436k2YCOY5gzVhC5idx",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "label": "Acme HQ",
  "displayName": "Acme HQ",
  "address": "Uncommon, 22 Curved Road",
  "postcode": "SE1 5AG",
  "city": "Quebec",
  "state": null,
  "country": "United Kingdom",
  "regionCode": null,
  "countryCode": "GB",
  "timezone": "Europe/London",
  "isAddressInvalid": false,
  "timeAwayPolicyId": "lQhHxduYbvq0TRIJq2IPN3hH",
  "timeAwayPolicyEffectiveDate": "2024-01-30",
  "workingPatternId": "lQhHxduYbvq0TRIJq2IPN3hH",
  "workingPatternEffectiveDate": "2024-04-06",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a location

Permanently deletes a location. It cannot be undone.

Parameters
  • No parameters
Returns

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

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

Me

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

Endpoints
GET /api/me
Required scopes
private.read
public.read

Me object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • spaceId string

    ID of the Space this person belongs to.

  • firstName string

    First name.

  • middleName string

    Middle name.

  • lastName string

    Last name.

  • preferredName string

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

  • pronouns string

    Preferred pronouns that the person goes by

  • email string

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

  • locationId string

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

  • remoteCity string

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

  • remoteRegionCode string

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

  • remoteCountryCode string

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

  • remoteTimezone string

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

  • timeAwayApprovalFlowId string

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

  • personalEmail string

    Personal email of the person.

  • phoneNumber string

    Work phone number of the person.

  • formattedPhoneNumber string

    Work phone number of the person formatted for display.

  • personalPhoneNumber string

    Personal phone number of the person.

  • formattedPersonalPhoneNumber string

    Personal phone number of the person formatted for display.

  • gender string

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

  • birthday string

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

  • profilePhotoId string

    ID of the profile picture file.

  • profilePhoto object

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

  • profilePhoto.id string

    Unique identifier for the object.

  • profilePhoto.filename string

  • profilePhoto.variants object

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

  • profilePhoto.variants.64 string

    URL of one of the predefined 2x profile photo sizes.

  • profilePhoto.variants.96 string

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

  • profilePhoto.variants.104 string

    URL of one of the predefined 2x profile photo sizes.

  • profilePhoto.variants.136 string

    URL of one of the predefined 2x profile photo sizes.

  • profilePhoto.variants.156 string

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

  • profilePhoto.variants.204 string

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

  • profilePhoto.variants.320 string

    URL of one of the predefined 2x profile photo sizes.

  • profilePhoto.variants.480 string

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

  • nationality string

    Nationality.

  • nationalities string[]

    Nationalities.

  • spokenLanguages string[]

    Spoken languages.

  • dietaryPreference string

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

  • foodAllergies string[]

    A list of food allergies.

  • address string

    Street address component of the person’s home address.

  • city string

    City component of the persons home address.

  • state string

    Optional state component of the persons home address.

  • postcode string

    Postcode component of the persons home address.

  • countryCode string

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

  • country string

    Country name, infered from the countryCode.

  • bio string

    An optional description about the person.

  • linkedIn string

    LinkedIn handle

  • twitter string

    Twitter handle

  • github string

    GitHub handle

  • employmentStartDate string, date

    Employment start date.

  • firstWorkingDay string, date

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

  • employmentEndDate string, date

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

  • lastWorkingDay string, date

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

  • probationEndDate string, date

    Probation end date.

  • turnoverImpact string

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

  • isManager boolean

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

  • workingDays object[]

    A list of days worked by the employee.

  • workingDays.day string

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

  • publicHolidayCalendarId string

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

  • leavingReason string

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

  • leavingNote string

    Leaving note set for offboarded people.

  • leavingFileId string

    Leaving file id attached to offboarded people.

  • contractType string

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

  • employeeId string

    Employee ID as used by the company.

  • taxId string

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

  • taxCode string

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

  • teams object[]

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

  • teams.name string

    Name of the team

  • status string

    One of active, offboarded or newHire.

  • isVerified boolean

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

  • isWorkEmailHidden boolean

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

  • calendarFeedToken string

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

  • role string

  • seenDocumentsAt string, date-time

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

  • source string

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

  • sourceId string

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

  • timezone string

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

  • payrollProvider string

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

  • firstActiveAt string, date-time

    Timestamp the person became an active member

  • isBirthdayHidden boolean

    Whether this person has opted out from birthday announcements.

  • demo boolean

    Whether this user is a demo user

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

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

Retrieve me

Retrieves the currently logged in user.

Parameters
  • No parameters
Returns

Returns the currently logged in person object.

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

Okrs

An objective or key result (OKR). Objectives can have child key results, and both can be assigned to people, teams, or departments.

Endpoints
Required scopes
goals.read
goals.write

Okr object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • type string

  • objectiveId string

  • personId string

    ID of the person that this object is associated to.

  • status string

  • title string

  • periodStart string, date

  • periodEnd string, date

  • progress number

  • progressType string

  • assigneeId string

  • hasChildren boolean

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

  • deletedAt string, date-time

okr object
{
  "id": "hIcGBfZ2ki7NoWz6WWvIF0vk",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "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
employment.read
personal.read
private.read
public.read
employment.write
personal.write
private.write

Person object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • spaceId string

    ID of the Space this person belongs to.

  • firstName string

    First name.

  • middleName string

    Middle name.

  • lastName string

    Last name.

  • preferredName string

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

  • pronouns string

    Preferred pronouns that the person goes by

  • email string

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

  • jobRole object

    The job role details of this person.

  • locationId string

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

  • remoteCity string

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

  • remoteRegionCode string

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

  • remoteCountryCode string

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

  • remoteTimezone string

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

  • timeAwayApprovalFlowId string

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

  • personalEmail string

    Personal email of the person.

  • phoneNumber string

    Work phone number of the person.

  • formattedPhoneNumber string

    Work phone number of the person formatted for display.

  • personalPhoneNumber string

    Personal phone number of the person.

  • formattedPersonalPhoneNumber string

    Personal phone number of the person formatted for display.

  • gender string

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

  • birthday string

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

  • profilePhotoId string

    ID of the profile picture file.

  • profilePhoto object

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

  • profilePhoto.id string

    Unique identifier for the object.

  • profilePhoto.filename string

  • profilePhoto.variants object

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

  • profilePhoto.variants.64 string

    URL of one of the predefined 2x profile photo sizes.

  • profilePhoto.variants.96 string

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

  • profilePhoto.variants.104 string

    URL of one of the predefined 2x profile photo sizes.

  • profilePhoto.variants.136 string

    URL of one of the predefined 2x profile photo sizes.

  • profilePhoto.variants.156 string

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

  • profilePhoto.variants.204 string

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

  • profilePhoto.variants.320 string

    URL of one of the predefined 2x profile photo sizes.

  • profilePhoto.variants.480 string

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

  • nationality string

    Nationality.

  • nationalities string[]

    Nationalities.

  • spokenLanguages string[]

    Spoken languages.

  • dietaryPreference string

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

  • foodAllergies string[]

    A list of food allergies.

  • address string

    Street address component of the person’s home address.

  • city string

    City component of the persons home address.

  • state string

    Optional state component of the persons home address.

  • postcode string

    Postcode component of the persons home address.

  • countryCode string

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

  • country string

    Country name, infered from the countryCode.

  • bio string

    An optional description about the person.

  • linkedIn string

    LinkedIn handle

  • twitter string

    Twitter handle

  • github string

    GitHub handle

  • employmentStartDate string, date

    Employment start date.

  • firstWorkingDay string, date

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

  • employmentEndDate string, date

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

  • lastWorkingDay string, date

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

  • probationEndDate string, date

    Probation end date.

  • turnoverImpact string

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

  • isManager boolean

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

  • workingDays object[]

    A list of days worked by the employee.

  • workingDays.day string

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

  • publicHolidayCalendarId string

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

  • leavingReason string

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

  • leavingNote string

    Leaving note set for offboarded people.

  • leavingFileId string

    Leaving file id attached to offboarded people.

  • contractType string

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

  • employeeId string

    Employee ID as used by the company.

  • taxId string

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

  • taxCode string

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

  • teams object[]

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

  • teams.name string

    Name of the team

  • status string

    One of active, offboarded or newHire.

  • isVerified boolean

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

  • isWorkEmailHidden boolean

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

  • calendarFeedToken string

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

  • role string

  • seenDocumentsAt string, date-time

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

  • source string

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

  • sourceId string

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

  • timezone string

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

  • payrollProvider string

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

  • firstActiveAt string, date-time

    Timestamp the person became an active member

  • isBirthdayHidden boolean

    Whether this person has opted out from birthday announcements.

  • demo boolean

    Whether this user is a demo user

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

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

List all people

Returns a list of people.

By default, only people with status active are returned. These are people that are actively employed at the company. Note that people that have already started and people that have the employment start date in the future are considered to be active.

If the last working day is set and is in the past, the status changes to offboarded. Fetch only offboarded people with ?status=offboarded.

People that are imported from Applicant Tracking Systems (ATS) have the status of newHire. New hires is a way to add people into the system with limited data (e.g. without work email or place of work). Once the missing data is available and is populated, the new hires can be promoted to active status. Fetch only new hires with ?status=newHire.

To fetch all people at once, use ?status=all. Note: be cautious when fetching all people, as new statuses might get introduced in the future.

It is also possible to fetch multiple statuses at once, e.g. ?status[$in]=active&status[$in]=offboarded. Refer to Filtering documentation for further details on usage of $in.

Parameters

  • firstName string | $ilike

    Filter people by first name. Supports $ilike for case-insensitive matching.

  • lastName string | $ilike

    Filter people by last name. Supports $ilike for case-insensitive matching.

  • preferredName string | $ilike

    Filter people by preferred name. Supports $ilike for case-insensitive matching.

  • $or object[]

    Filter by multiple conditions using OR logic. Supports firstName, lastName, preferredName.

  • $or.firstName string | $ilike

  • $or.lastName string | $ilike

  • $or.preferredName string | $ilike

  • email string

    Filter people by work email address.

  • personalEmail string

    Filter people by personal email address.

  • spaceId string | $in | $nin

    Filter people by the ID of the Space they belong to.

  • teams string | $any | $not

    Filter people by team.

  • status string | $in

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

  • employmentStartDate object

    Filter people by employment start date.

  • employmentStartDate.$gt date | date-time

  • employmentStartDate.$gte date | date-time

  • employmentStartDate.$lt date | date-time

  • employmentStartDate.$lte date | date-time

  • employmentEndDate object

    Filter people by employment end date.

  • employmentEndDate.$gt date | date-time

  • employmentEndDate.$gte date | date-time

  • employmentEndDate.$lt date | date-time

  • employmentEndDate.$lte date | date-time

  • firstWorkingDay object

    Filter people by first working day.

  • firstWorkingDay.$gt date | date-time

  • firstWorkingDay.$gte date | date-time

  • firstWorkingDay.$lt date | date-time

  • firstWorkingDay.$lte date | date-time

  • lastWorkingDay object

    Filter people by last working day.

  • lastWorkingDay.$gt date | date-time

  • lastWorkingDay.$gte date | date-time

  • lastWorkingDay.$lt date | date-time

  • lastWorkingDay.$lte date | date-time

  • probationEndDate object

    Filter people by probation end date.

  • probationEndDate.$gt date | date-time

  • probationEndDate.$gte date | date-time

  • probationEndDate.$lt date | date-time

  • probationEndDate.$lte date | date-time

  • createdAt object

    Filter people by created at date.

  • createdAt.$gt date | date-time

  • createdAt.$gte date | date-time

  • createdAt.$lt date | date-time

  • createdAt.$lte date | date-time

  • updatedAt object

    Filter people by updated at date.

  • updatedAt.$gt date | date-time

  • updatedAt.$gte date | date-time

  • updatedAt.$lt date | date-time

  • updatedAt.$lte date | date-time

  • include string[]

    Additional fields to include, not provided as part of the default payload. Supported values are: isManager.

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

Retrieve a person

Retrieves the person with the given ID.

Parameters
  • No parameters
Returns

Returns a person object if a valid identifier was provided.

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

Create a person

People can be created in 2 ways - with status active or newHire.

By default, when not specified otherwise, employees get created with active status. In this case, all of the required fields as specified below must be provided.

It is possible to create people with status set to newHire. This is typically done in Applicant Tracking System (ATS) integrations. When creating a person as a new hire only one of email or personalEmail is required and all of the other fields are optional. When creating new hires, you can make use of the source and sourceId fields to specify extra metadata about where the new hire was imported from. New hires are only visible to Owner and Admin roles. Their full profiles can not be opened until their status is updated to active. To do so, use the patch method, set the status to active and provide any of the missing required fields that were not provided when creating the new hire.

Parameters

  • firstName string required

    First name.

  • middleName string | null

    Middle name.

  • lastName string required

    Last name.

  • preferredName string | null

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

  • pronouns string | null

    Preferred pronouns that the person goes by

  • email string required

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

  • personalEmail string | null

    Personal email of the person.

  • phoneNumber string | null

    Work phone number of the person.

  • personalPhoneNumber string | null

    Personal phone number of the person.

  • gender string | null

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

  • birthday string, date | null

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

  • isBirthdayHidden boolean

    Whether this person has opted out from birthday announcements.

  • profilePhotoId string | null

    ID of the profile picture file.

  • nationality string | null

    Nationality.

  • nationalities string[] | null

    Nationalities.

  • spokenLanguages string[] | null

    Spoken languages.

  • dietaryPreference string | null

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

  • foodAllergies string[]

    A list of food allergies.

  • address string | null

    Street address component of the person’s home address.

  • city string | null

    City component of the persons home address.

  • state string | null

    Optional state component of the persons home address.

  • postcode string | null

    Postcode component of the persons home address.

  • countryCode string | null

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

  • bio string | null

    An optional description about the person.

  • linkedIn string | null

    LinkedIn handle

  • twitter string | null

    Twitter handle

  • github string | null

    GitHub handle

  • employmentStartDate string, date required

    Employment start date.

  • firstWorkingDay string, date

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

  • employmentEndDate string, date | null

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

  • lastWorkingDay string, date | null

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

  • probationEndDate string, date | null

    Probation end date.

  • workingDays object[] | null

    A list of days worked by the employee.

  • workingDays.day string

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

  • turnoverImpact string | null

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

  • leavingReason string | null

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

  • leavingNote string | null

    Leaving note set for offboarded people.

  • leavingFileId string | null

    Leaving file id attached to offboarded people.

  • contractType string | null

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

  • payrollProvider string | null

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

  • employeeId string | null

    Employee ID as used by the company.

  • taxId string | null

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

  • taxCode string | null

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

  • locationId string required

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

  • remoteCity string | null

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

  • remoteCountryCode string | null

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

  • timeAwayApprovalFlowId string

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

  • spaceId string

    ID of the Space this person belongs to.

  • teams object[]

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

  • teams.name string required

    Name of the team

  • status string

    One of active, offboarded or newHire.

  • isWorkEmailHidden boolean

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

  • calendarFeedToken string

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

  • seenDocumentsAt string, date-time

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

  • publicHolidayCalendarId string | null

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

  • jobRole object required

    The job role details of this person.

  • jobRole.jobTitle string required

    Job title.

  • jobRole.department string | null

    Department name.

  • jobRole.reportingTo string | null

    The ID of the user this person reports to.

  • customValues object[]

  • customValues.customFieldId string required

  • customValues.value string required

  • timeAwayAllocation object

    The time away policy for this person.

  • timeAwayAllocation.timeAwayPolicyId string required

    The ID of the timeaway policy.

Returns

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

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

Update a person

To offboard a person, set the employmentEndDate (and if relevant lastWorkingDay) to some past or future date. Once that date is in the past (with respect to the UTC timezone), the employee is considered to be offboarded, and their status field will switch to offboarded.

Parameters

  • firstName string

    First name.

  • middleName string | null

    Middle name.

  • lastName string

    Last name.

  • preferredName string | null

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

  • pronouns string | null

    Preferred pronouns that the person goes by

  • email string | null

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

  • personalEmail string | null

    Personal email of the person.

  • phoneNumber string | null

    Work phone number of the person.

  • personalPhoneNumber string | null

    Personal phone number of the person.

  • gender string | null

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

  • birthday string, date | null

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

  • isBirthdayHidden boolean

    Whether this person has opted out from birthday announcements.

  • profilePhotoId string | null

    ID of the profile picture file.

  • nationality string | null

    Nationality.

  • nationalities string[] | null

    Nationalities.

  • spokenLanguages string[] | null

    Spoken languages.

  • dietaryPreference string | null

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

  • foodAllergies string[]

    A list of food allergies.

  • address string | null

    Street address component of the person’s home address.

  • city string | null

    City component of the persons home address.

  • state string | null

    Optional state component of the persons home address.

  • postcode string | null

    Postcode component of the persons home address.

  • countryCode string | null

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

  • bio string | null

    An optional description about the person.

  • linkedIn string | null

    LinkedIn handle

  • twitter string | null

    Twitter handle

  • github string | null

    GitHub handle

  • employmentStartDate string, date

    Employment start date.

  • firstWorkingDay string, date

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

  • employmentEndDate string, date | null

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

  • lastWorkingDay string, date | null

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

  • probationEndDate string, date | null

    Probation end date.

  • workingDays object[] | null

    A list of days worked by the employee.

  • workingDays.day string

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

  • turnoverImpact string | null

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

  • leavingReason string | null

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

  • leavingNote string | null

    Leaving note set for offboarded people.

  • leavingFileId string | null

    Leaving file id attached to offboarded people.

  • contractType string | null

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

  • payrollProvider string | null

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

  • employeeId string | null

    Employee ID as used by the company.

  • taxId string | null

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

  • taxCode string | null

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

  • locationId string

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

  • remoteCity string | null

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

  • remoteCountryCode string | null

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

  • timeAwayApprovalFlowId string

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

  • spaceId string

    ID of the Space this person belongs to.

  • teams object[]

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

  • teams.name string required

    Name of the team

  • status string

    One of active, offboarded or newHire.

  • isWorkEmailHidden boolean

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

  • calendarFeedToken string

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

  • seenDocumentsAt string, date-time

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

  • publicHolidayCalendarId string | null

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

Returns

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

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

Delete a person

Permanently deletes a person. It cannot be undone.

Parameters
  • No parameters
Returns

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

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

Performance instances Preview

An object representing a specific person’s review packet in a performance cycle. Each instance tracks the release status and other details for an individual employee within a performance cycle.

Endpoints
GET /api/performance-cycle-instances
GET /api/performance-cycle-instances/:id
Required scopes
performance.read
performance.write

Performance instance object

Attributes

  • id string

    Unique identifier for the object.

  • performanceCycleId string

    The ID of the performance cycle this instance belongs to.

  • personId string

    ID of the person that this object is associated to.

  • releasedAt string, date-time

    The time at which the performance cycle instance was released. Null if not yet released.

  • releasedBy string

    The ID of the person who released the performance cycle instance.

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

performance instance object
{
  "id": "0I5qP2OqcopXEPRv3qz3LVXP",
  "performanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "releasedAt": "2026-03-01T12:00:00.000Z",
  "releasedBy": "T7uqPFK7am4lFTZm39AmNuBQ",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all performance instances

Returns a list of performance instances.

Parameters

  • performanceCycleId string | $in | $nin

    The ID of the performance cycle this instance belongs to.

  • personId string | $in | $nin

    The person to filter queries by.

  • performanceCycleStatus string | $in | $nin

    Filter by the status of the parent performance cycle. One of draft, upcoming, active, completed, cancelled.

  • $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 performance instances. 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 performance instance object. If no performance instances are available, the resulting list will be empty. This request should never return an error.

GET /api/performance-cycle-instances
curl https://app.humaans.io/api/performance-cycle-instances \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "0I5qP2OqcopXEPRv3qz3LVXP",
      "performanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "releasedAt": "2026-03-01T12:00:00.000Z",
      "releasedBy": "T7uqPFK7am4lFTZm39AmNuBQ",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a performance instance

Retrieves the performance instance with the given ID.

Parameters
  • No parameters
Returns

Returns a performance instance object if a valid identifier was provided.

GET /api/performance-cycle-instances/:id
curl https://app.humaans.io/api/performance-cycle-instances/0I5qP2OqcopXEPRv3qz3LVXP \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "0I5qP2OqcopXEPRv3qz3LVXP",
  "performanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "releasedAt": "2026-03-01T12:00:00.000Z",
  "releasedBy": "T7uqPFK7am4lFTZm39AmNuBQ",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Performance cycle peer nominations

A peer nomination within a performance cycle. Captures who has been nominated to review whom during the peer nomination phase.

Endpoints
Required scopes
performance.read
performance.write

Performance cycle peer nomination object

Attributes

  • id string

    Unique identifier for the object.

  • performanceCycleInstanceId string

  • subjectId string

  • peerId string

  • nominatedBy string

  • approvedAt string

  • approvedBy string

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

performance cycle peer nomination object
{
  "id": "nZ33bKXnjToEJHObiaxrCqTo",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Performance templates Preview

An object representing a review template within a performance cycle. Each template defines the form fields and configuration for a specific type of review.

Endpoints
GET /api/performance-cycle-review-templates
GET /api/performance-cycle-review-templates/:id
Required scopes
performance.read
performance.write

Performance template object

Attributes

  • id string

    Unique identifier for the object.

  • performanceCycleId string

    The ID of the performance cycle this review template belongs to.

  • title string

    The title of the review template.

  • templateType string

    The type of review this template is for. One of peer, self, upward, manager.

  • fields object[]

    An array of form field objects that define the structure of the review. Each field has a type property determining its kind. One of text (short text input), longText (longer text input), textArea (rich text editor), select (single choice from a list), multiSelect (multiple choices from a list), rating (rating scale with predefined choices), scale (numeric scale with a range), heading (section heading), divider (visual separator). Each field has an id that uniquely identifies it within the template. These IDs are used as keys in the responses object of performance reviews. Input fields support label, hint, placeholder, required, and hideFromReviewee properties.

  • fields.id string

    Unique identifier for this field. Used as the key in the responses object of performance reviews.

  • fields.type string

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

performance template object
{
  "id": "PJIqTfdojEAWs8M4shG1x4eJ",
  "performanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
  "title": "Manager Review",
  "templateType": "manager",
  "fields": [
    {
      "id": "nB3xOmaAl0hx7FkGi2OBSqEp",
      "type": "heading",
      "content": "Performance Assessment"
    },
    {
      "id": "qR9yPzCdk2jv8WnHt5KDUfXm",
      "type": "longText",
      "label": "What are this person's key strengths?",
      "required": true,
      "hideFromReviewee": true
    },
    {
      "id": "xT4wLmNpR8kv2QjHs6YBUcAe",
      "type": "multiSelect",
      "label": "Which company values does this person demonstrate?",
      "choices": [
        "Ownership",
        "Collaboration",
        "Innovation",
        "Integrity"
      ],
      "required": false
    }
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all performance templates

Returns a list of performance templates.

Parameters

  • performanceCycleId string

    The ID of the performance cycle this review template belongs to.

  • $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 performance templates. 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 performance template object. If no performance templates are available, the resulting list will be empty. This request should never return an error.

GET /api/performance-cycle-review-templates
curl https://app.humaans.io/api/performance-cycle-review-templates \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "PJIqTfdojEAWs8M4shG1x4eJ",
      "performanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
      "title": "Manager Review",
      "templateType": "manager",
      "fields": [
        {
          "id": "nB3xOmaAl0hx7FkGi2OBSqEp",
          "type": "heading",
          "content": "Performance Assessment"
        },
        {
          "id": "qR9yPzCdk2jv8WnHt5KDUfXm",
          "type": "longText",
          "label": "What are this person's key strengths?",
          "required": true,
          "hideFromReviewee": true
        },
        {
          "id": "xT4wLmNpR8kv2QjHs6YBUcAe",
          "type": "multiSelect",
          "label": "Which company values does this person demonstrate?",
          "choices": [
            "Ownership",
            "Collaboration",
            "Innovation",
            "Integrity"
          ],
          "required": false
        }
      ],
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a performance template

Retrieves the performance template with the given ID.

Parameters
  • No parameters
Returns

Returns a performance template object if a valid identifier was provided.

GET /api/performance-cycle-review-templates/:id
curl https://app.humaans.io/api/performance-cycle-review-templates/PJIqTfdojEAWs8M4shG1x4eJ \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "PJIqTfdojEAWs8M4shG1x4eJ",
  "performanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
  "title": "Manager Review",
  "templateType": "manager",
  "fields": [
    {
      "id": "nB3xOmaAl0hx7FkGi2OBSqEp",
      "type": "heading",
      "content": "Performance Assessment"
    },
    {
      "id": "qR9yPzCdk2jv8WnHt5KDUfXm",
      "type": "longText",
      "label": "What are this person's key strengths?",
      "required": true,
      "hideFromReviewee": true
    },
    {
      "id": "xT4wLmNpR8kv2QjHs6YBUcAe",
      "type": "multiSelect",
      "label": "Which company values does this person demonstrate?",
      "choices": [
        "Ownership",
        "Collaboration",
        "Innovation",
        "Integrity"
      ],
      "required": false
    }
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Performance reviews Preview

An object representing a single review within a performance cycle. Each review captures a reviewer’s responses about a subject, the review type, and submission status.

Endpoints
GET /api/performance-cycle-reviews
GET /api/performance-cycle-reviews/:id
Required scopes
performance.read
performance.write

Performance review object

Attributes

  • id string

    Unique identifier for the object.

  • performanceCycleInstanceId string

    The ID of the performance cycle instance this review belongs to.

  • subjectId string

    The ID of the person being reviewed.

  • reviewerId string

    The ID of the person conducting the review.

  • reviewType string

    The type of review. One of peer, self, upward, manager.

  • responses object

    An object containing the responses to the review form fields, keyed by the field id from the corresponding performance template field.

  • submittedAt string, date-time

    The time at which this review was submitted. Null if not yet submitted or if changes have been requested.

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

performance review object
{
  "id": "aegY8UfWbpDonPFKhx6Z027o",
  "performanceCycleInstanceId": "IL19tIwMP2Hs7cpNHFOzNMeX",
  "subjectId": "wYW0B4dIbzyjm4FlJPv3cOS4",
  "reviewerId": "T7uqPFK7am4lFTZm39AmNuBQ",
  "reviewType": "manager",
  "responses": {
    "nB3xOmaAl0hx7FkGi2OBSqEp": "Great team player",
    "qR9yPzCdk2jv8WnHt5KDUfXm": {
      "value": 4,
      "furtherComments": "Consistently exceeds expectations"
    }
  },
  "submittedAt": "2026-03-15T10:30:00.000Z",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all performance reviews

Returns a list of performance reviews.

Parameters

  • performanceCycleStatus string | $in | $nin

    Filter by the status of the parent performance cycle. One of draft, upcoming, active, completed, cancelled.

  • performanceCycleInstanceId string | $in | $nin

    The ID of the performance cycle instance this review belongs to.

  • $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 performance reviews. 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 performance review object. If no performance reviews are available, the resulting list will be empty. This request should never return an error.

GET /api/performance-cycle-reviews
curl https://app.humaans.io/api/performance-cycle-reviews \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "aegY8UfWbpDonPFKhx6Z027o",
      "performanceCycleInstanceId": "IL19tIwMP2Hs7cpNHFOzNMeX",
      "subjectId": "wYW0B4dIbzyjm4FlJPv3cOS4",
      "reviewerId": "T7uqPFK7am4lFTZm39AmNuBQ",
      "reviewType": "manager",
      "responses": {
        "nB3xOmaAl0hx7FkGi2OBSqEp": "Great team player",
        "qR9yPzCdk2jv8WnHt5KDUfXm": {
          "value": 4,
          "furtherComments": "Consistently exceeds expectations"
        }
      },
      "submittedAt": "2026-03-15T10:30:00.000Z",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a performance review

Retrieves the performance review with the given ID.

Parameters
  • No parameters
Returns

Returns a performance review object if a valid identifier was provided.

GET /api/performance-cycle-reviews/:id
curl https://app.humaans.io/api/performance-cycle-reviews/aegY8UfWbpDonPFKhx6Z027o \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "aegY8UfWbpDonPFKhx6Z027o",
  "performanceCycleInstanceId": "IL19tIwMP2Hs7cpNHFOzNMeX",
  "subjectId": "wYW0B4dIbzyjm4FlJPv3cOS4",
  "reviewerId": "T7uqPFK7am4lFTZm39AmNuBQ",
  "reviewType": "manager",
  "responses": {
    "nB3xOmaAl0hx7FkGi2OBSqEp": "Great team player",
    "qR9yPzCdk2jv8WnHt5KDUfXm": {
      "value": 4,
      "furtherComments": "Consistently exceeds expectations"
    }
  },
  "submittedAt": "2026-03-15T10:30:00.000Z",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Performance cycles Preview

An object representing a performance review cycle. Performance cycles define the schedule, scope, and configuration for running performance reviews across the company.

Endpoints
GET /api/performance-cycles
GET /api/performance-cycles/:id
Required scopes
performance.read
performance.write

Performance cycle object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • title string

    The title of the performance cycle.

  • status string

    The current status of the performance cycle. One of draft, upcoming, active, completed, cancelled.

  • previousPerformanceCycleId string

    ID of the previous performance cycle (if the cycle is on a recurring schedule).

  • completedAt string, date-time

    Time at which the performance cycle was completed.

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

  • deletedAt string, date-time

performance cycle object
{
  "id": "vxRe1WOEJP2KxKCBBaad9NFM",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "title": "Q1 2026 Performance Review",
  "status": "active",
  "previousPerformanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
  "completedAt": "2026-04-01T12:00:00.000Z",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all performance cycles

Returns a list of performance cycles.

Parameters

  • status string | $in | $nin

    The current status of the performance cycle. One of draft, upcoming, active, completed, cancelled.

  • $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 performance cycles. 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 performance cycle object. If no performance cycles are available, the resulting list will be empty. This request should never return an error.

GET /api/performance-cycles
curl https://app.humaans.io/api/performance-cycles \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "vxRe1WOEJP2KxKCBBaad9NFM",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "title": "Q1 2026 Performance Review",
      "status": "active",
      "previousPerformanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
      "completedAt": "2026-04-01T12:00:00.000Z",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a performance cycle

Retrieves the performance cycle with the given ID.

Parameters
  • No parameters
Returns

Returns a performance cycle object if a valid identifier was provided.

GET /api/performance-cycles/:id
curl https://app.humaans.io/api/performance-cycles/vxRe1WOEJP2KxKCBBaad9NFM \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "vxRe1WOEJP2KxKCBBaad9NFM",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "title": "Q1 2026 Performance Review",
  "status": "active",
  "previousPerformanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM",
  "completedAt": "2026-04-01T12:00:00.000Z",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Performance ratings

A rating scale definition used in performance reviews (e.g. “Exceeds expectations”, “Meets expectations”). Companies configure their own rating scales.

Endpoints
Required scopes
performance.read
performance.write

Performance rating object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • ratings object[]

  • ratings.number integer

  • ratings.label string

  • ratings.color string

  • isTemplate boolean

  • createdAt string, date-time

    Time at which the object was created.

performance rating object
{
  "id": "QFE5gLHHkOMKR0M8OhVadSXr",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "ratings": [
    {}
  ],
  "createdAt": "2020-01-28T08:44:42.000Z"
}

Performance summaries

An aggregated performance summary for a person across all review cycles they have participated in.

Endpoints
Required scopes
performance.read

Performance summarie object

Attributes

  • id string

    Unique identifier for the object.

  • personId string

    ID of the person that this object is associated to.

  • reviewerIds string[]

  • performanceCycleInstanceId string

  • versionTag string

  • summary string

  • achievements object[]

  • achievements.achievement string

  • achievements.summary string

  • achievements.emoji string

  • strengths object[]

  • strengths.label string

  • strengths.summary string

  • strengths.emoji string

  • growthAreas object[]

  • growthAreas.label string

  • growthAreas.summary string

  • growthAreas.emoji string

  • includedReviews string[]

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

performance summarie object
{
  "id": "YQHgRkqgiBDfMAo2I6h0cxrX",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "achievements": [
    {}
  ],
  "strengths": [
    {}
  ],
  "growthAreas": [
    {}
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Public holiday calendar days

A resource representing a public holiday for a particular public holiday calendar day

Endpoints
  GET /api/public-holiday-calendar-days
  GET /api/public-holiday-calendar-days/:id
 POST /api/public-holiday-calendar-days
PATCH /api/public-holiday-calendar-days/:id
Required scopes
public.read
settings.write

Public holiday calendar day object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • publicHolidayCalendarId string

    The ID of the public holiday calendar this public holiday is part of.

  • name string

    The name of the public holiday.

  • date string, date

    The date of the public holiday.

  • enabled boolean

    The toggle state of the public holiday

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

  • deletedAt

Public holiday calendar day object
{
  "id": "MVvOIW2o1NLLtYga0REVbeeK",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Christmas Day",
  "date": "2022-12-25",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all Public holiday calendar days

List all public holiday calendar days

Parameters

  • publicHolidayCalendarId string | $in | $nin

    Filter by the public holiday calendar ID.

  • date

    The date of the public holiday.

  • enabled

    The toggle state of the public holiday

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

Returns an object with a data property that contains a list of Public holiday calendar days. 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 day object. If no Public holiday calendar days are available, the resulting list will be empty. This request should never return an error.

GET /api/public-holiday-calendar-days
curl https://app.humaans.io/api/public-holiday-calendar-days \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "MVvOIW2o1NLLtYga0REVbeeK",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "Christmas Day",
      "date": "2022-12-25",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a Public holiday calendar day

Get a specific public holiday calendar day

Parameters
  • No parameters
Returns

Returns a Public holiday calendar day object if a valid identifier was provided.

GET /api/public-holiday-calendar-days/:id
curl https://app.humaans.io/api/public-holiday-calendar-days/MVvOIW2o1NLLtYga0REVbeeK \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "MVvOIW2o1NLLtYga0REVbeeK",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Christmas Day",
  "date": "2022-12-25",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a Public holiday calendar day

Create a custom public holiday calendar day

Parameters

  • name string required

    The name of the public holiday.

  • date string, date required

    The date of the public holiday.

  • enabled boolean

    The toggle state of the public holiday

  • publicHolidayCalendarId string required

    The ID of the public holiday calendar this public holiday is part of.

Returns

Returns a Public holiday calendar day if the call succeeded. The call returns an error if parameters are invalid.

POST /api/public-holiday-calendar-days
curl https://app.humaans.io/api/public-holiday-calendar-days \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"Christmas Day","date":"2022-12-25"}'
Response
{
  "id": "MVvOIW2o1NLLtYga0REVbeeK",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Christmas Day",
  "date": "2022-12-25",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a Public holiday calendar day

Update a public holiday calendar day

Parameters

  • name string

    The name of the public holiday.

  • date string, date

    The date of the public holiday.

  • enabled boolean

    The toggle state of the public holiday

Returns

Returns the Public holiday calendar day if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/public-holiday-calendar-days/:id
curl https://app.humaans.io/api/public-holiday-calendar-days/MVvOIW2o1NLLtYga0REVbeeK \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'
Response
{
  "id": "MVvOIW2o1NLLtYga0REVbeeK",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Christmas Day",
  "date": "2022-12-25",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Public holiday calendars

A resource representing a public holiday calendar for a specific country or in some cases a region of a country.

Endpoints
GET /api/public-holiday-calendars
Required scopes
public.read

Public holiday calendar object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • name string

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

  • countryCode string

    The country code.

  • country string

    The country label.

  • regionCode string

    The region code.

  • region string

    The country label.

  • dayCount number

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

  • sourcePublicHolidayCalendarId string

    The ID of the calendar used to initially populate this calendar

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

public holiday calendar object
{
  "id": "J2zFVTiH0fduJ0p5639GNRBh",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "France",
  "countryCode": "FR",
  "country": "France",
  "regionCode": null,
  "region": null,
  "dayCount": 11,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all public holiday calendars

List all public holiday calendars

Parameters

  • id string | $in | $nin

    Filter by the public holiday calendar ID.

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/public-holiday-calendars
curl https://app.humaans.io/api/public-holiday-calendars \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "J2zFVTiH0fduJ0p5639GNRBh",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "France",
      "countryCode": "FR",
      "country": "France",
      "regionCode": null,
      "region": null,
      "dayCount": 11,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Public holidays

An object representing a public holiday.

Endpoints
GET /api/public-holidays
Required scopes
public.read

Public holiday object

Attributes

  • id string

    Unique identifier for the object.

  • date string

    The date of the public holiday.

  • name string

    The name of the public holiday.

  • publicHolidayCalendarId string

    The ID of the public holiday calendar this public holiday belongs to.

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

List all public holidays

Returns a list of public holidays.

Parameters

  • publicHolidayCalendarId string | $in | $nin required

    Filter by the public holiday calendar ID.

  • date date | $in | $nin | $gt | $lt | $gte | $lte required

    Filter holidays by date.

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/public-holidays
curl 'https://app.humaans.io/api/public-holidays?publicHolidayCalendarId=DE-BE&date[$gte]=2020-01-01' \
  -g \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "nk1kio8XMzUXY5eplJq7PrbI",
      "date": "2020-01-01",
      "name": "New year"
    }
  ]
}

Request activity logs

A read-only log entry tracking state changes on a request (e.g. submitted, approved, rejected, cancelled).

Endpoints
Required scopes
requests.read

Request activity log object

Attributes

  • id string

    Unique identifier for the object.

  • requestId string

  • personId string

    ID of the person that this object is associated to.

  • event string

  • metadata object

  • workflowName string

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

request activity log object
{
  "id": "16rsfv1eZIchphqIAnXv0EKG",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "metadata": {},
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Request comments

A comment on a request by a reviewer or the requestor. Used for discussion during the approval process.

Endpoints
Required scopes
requests.read
requests.write

Request comment object

Attributes

  • id string

    Unique identifier for the object.

  • requestId string

  • personId string

    ID of the person that this object is associated to.

  • content object

  • postedAt string

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

request comment object
{
  "id": "pZezAk7zuMBFB8AtlbJggLTj",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "content": {},
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Request reviews

An approval or rejection decision on a request. Each review belongs to an approval step and records the reviewer, their decision, and any comments.

Endpoints
Required scopes
requests.read
requests.write

Request review object

Attributes

  • id string

    Unique identifier for the object.

  • requestId string

  • subjectId string

  • reviewerId string

  • stepNumber number

  • decision string

  • satisfies object[]

  • satisfies.department string

  • satisfies.team string

  • satisfies.spaceId string

  • satisfies.dynamicId string

  • satisfies.approverId string

  • satisfies.customFieldId string

  • overwrittenById string

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

request review object
{
  "id": "QxqWzbwDM2O4rM6pVeMnv49r",
  "satisfies": [
    {}
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Request types

A template defining a type of employee request (e.g. equipment request, role change). Configures the approval flow, form fields, and eligible requestors.

Endpoints
Required scopes
public.read
requests.read
settings.write

Request type object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • name string

    Display name of the request type (e.g. “Equipment Request”).

  • description string

    Description shown to employees when submitting a request of this type.

  • isEnabled boolean

    Whether employees can submit new requests of this type.

  • formFields object[]

    The form fields shown to the requestor when submitting a request.

  • formFields.id string

  • formFields.label string

  • formFields.type string

  • formFields.anchor string

  • formFields.hint string

  • formFields.placeholder string

  • formFields.required boolean

  • formFields.choices string[]

  • formFields.creatable boolean

  • formFields.acknowledgement string

  • formFields.furtherComments boolean

  • formFields.files object[]

  • formFields.files.id string

  • formFields.files.url string

  • formFields.files.filename string

  • formFields.content string

  • approvalFlows object[]

    The multi-step approval chain. Each step defines who must approve and the required action.

  • approvalFlows.name string

  • approvalFlows.conditions object[]

  • approvalFlows.conditions.fieldName string

  • approvalFlows.conditions.operator string

  • approvalFlows.conditions.value string[]

  • approvalFlows.approvalSteps object[]

  • approvalFlows.approvalSteps.approvers object[]

  • approvalFlows.approvalSteps.approvers.department string

  • approvalFlows.approvalSteps.approvers.team string

  • approvalFlows.approvalSteps.approvers.spaceId string

  • approvalFlows.approvalSteps.approvers.dynamicId string

  • approvalFlows.approvalSteps.approvers.approverId string

  • approvalFlows.approvalSteps.approvers.customFieldId string

  • approvalFlows.approvalSteps.minCount number

  • afterApproval object

    Actions to take after the request is fully approved (e.g. assign to someone).

  • afterApproval.action

  • afterApproval.assignee object

  • afterApproval.assignee.assigneeType

  • afterApproval.assignee.spaceId string

  • afterApproval.assignee.team string

  • afterApproval.assignee.personId string

  • afterApproval.assignee.dynamicId string

  • afterApproval.assignee.customFieldId string

  • afterApproval.workflowId string

  • requestorFilters object[]

    Filters that restrict who can submit this request type (e.g. by department or location).

  • requestorFilters.fieldName string

  • requestorFilters.operator string

  • requestorFilters.value string[]

  • subjectScope string

    Who the request can be about: “self” (requestor only) or “anyone” (any employee).

  • isDeletable boolean

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

request type object
{
  "id": "kKnY01PbeZYTpqQjZxh2PuyV",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "formFields": [
    {
      "files": [
        {}
      ]
    }
  ],
  "approvalFlows": [
    {
      "conditions": [
        {}
      ],
      "approvalSteps": [
        {
          "approvers": [
            {}
          ]
        }
      ]
    }
  ],
  "requestorFilters": [
    {}
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Requests

An employee approval request (e.g. equipment request, role change). Requests follow a multi-step approval flow defined by their requestType. Status: requested → approved/rejected/cancelled.

Endpoints
Required scopes
requests.read
requests.write

Request object

Attributes

  • id string

    Unique identifier for the object.

  • requestTypeId string

    The ID of the request type (template) this request is based on.

  • responses object[]

    Form field responses as an array of { fieldId, value } objects matching the request type form fields.

  • responses.fieldId string

  • responses.value string | array | boolean | null | id | filename | url | fileId | type | number | expiryDate | countryCode | note | url | redacted

  • requestTypeVersionId string

  • requestedBy string

  • subjectId string

    The ID of the person this request is about (e.g. the employee requesting equipment).

  • status string

    Current status of the request: requested, inProgress, approved, declined, cancelled, or completed.

  • assignee object

  • assignee.assigneeType

  • assignee.spaceId string

  • assignee.team string

  • assignee.personId string

  • assignee.dynamicId string

  • assignee.customFieldId string

  • completedAt string

  • name string

  • syncStatus object

  • syncStatus.result string

  • syncStatus.completedAt string

  • syncStatus.attemptedAt string

  • syncStatus.error object

  • syncStatus.error.code number

  • syncStatus.error.name string

  • syncStatus.error.message string

  • syncStatus.error.issues object[]

  • syncStatus.error.issues.name string

  • syncStatus.error.issues.reason string

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

  • assigneeCustomValue string

  • approvalSteps object[]

  • approvalSteps.approvers object[]

  • approvalSteps.approvers.department string

  • approvalSteps.approvers.team string

  • approvalSteps.approvers.spaceId string

  • approvalSteps.approvers.dynamicId string

  • approvalSteps.approvers.approverId string

  • approvalSteps.approvers.customFieldId string

  • approvalSteps.minCount number

  • formFields object[]

  • formFields.id string

  • formFields.label string

  • formFields.type string

  • formFields.anchor string

  • formFields.hint string

  • formFields.placeholder string

  • formFields.required boolean

  • formFields.choices string[]

  • formFields.creatable boolean

  • formFields.acknowledgement string

  • formFields.furtherComments boolean

  • formFields.files object[]

  • formFields.files.id string

  • formFields.files.url string

  • formFields.files.filename string

  • formFields.content string

request object
{
  "id": "5FkPgq6LIWfwK1tD2KjGiPlW",
  "responses": [
    {}
  ],
  "assignee": {},
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "approvalSteps": [
    {
      "approvers": [
        {}
      ]
    }
  ],
  "formFields": [
    {
      "files": [
        {}
      ]
    }
  ]
}

Role members

A membership linking a person to a custom role. Adding a person as a role member grants them the permissions defined on that role.

Endpoints
Required scopes
security.read

Role member object

Attributes

  • id string

    Unique identifier for the object.

  • roleId string

    The ID of the role to add the person to.

  • companyId string

    ID of the company that this object is associated to.

  • personId string

    The ID of the person to add to the role.

  • createdAt string, date-time

    Time at which the object was created.

role member object
{
  "id": "yNpjpGbWz7mciYFwlt7Cn3V6",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "createdAt": "2020-01-28T08:44:42.000Z"
}

Role permissions

A permission entry on a custom role. Each entry specifies a permission group, access level, and optional conditions that scope the permission.

Endpoints
Required scopes
security.read

Role permission object

Attributes

  • id string

    Unique identifier for the object.

  • roleId string

    The ID of the role this permission belongs to.

  • permission string

    The permission key to grant (e.g. “people:read”, “compensations:manage”).

  • resourceId string

    Optional resource ID to scope the permission to a specific resource (e.g. a custom field ID).

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

role permission object
{
  "id": "YmOguWADrUOYgmCBt6IGkU0T",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Roles

A custom permission role that grants specific access levels to its members. Used to create fine-grained access controls beyond the built-in roles (owner, admin, finance, user).

Endpoints
Required scopes
security.read
documents.write
private.write
settings.write

Role object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • name string

    Display name of the role.

  • description string

    A short description of what this role is for.

  • scope string

    Whether the role applies company-wide (“company”) or to a specific space (“space”).

  • conditions object

    Optional conditions that dynamically scope role membership (e.g. by department, location, or team).

  • conditions.departments string[]

  • conditions.locations string[]

  • conditions.placeOfWorkCities string[]

  • conditions.placeOfWorkCountryCodes string[]

  • conditions.spaces string[]

  • conditions.includeSelf boolean

  • conditions.customFields object[]

  • conditions.customFields.fieldId string

  • conditions.customFields.values string[]

  • conditionMembership object

  • type string

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

role object
{
  "id": "en9saH18Q7mbgwiGQIPsttuE",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "conditions": {
    "customFields": [
      {}
    ]
  },
  "conditionMembership": {},
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Spaces

An object representing a space. Every user belongs to a single space.

Endpoints
   GET /api/spaces
   GET /api/spaces/:id
  POST /api/spaces
 PATCH /api/spaces/:id
DELETE /api/spaces/:id
Required scopes
public.read
settings.write

Space object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • name string

  • isDefault boolean

  • logo object

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

  • logo.id string

    Unique identifier for the object.

  • logo.filename string

  • logo.variants object

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

  • logo.variants.64 string

    URL of one of the predefined 2x logo sizes.

  • logo.variants.96 string

    URL of one of the predefined 3x logo sizes.

  • logo.variants.104 string

    URL of one of the predefined 2x logo sizes.

  • logo.variants.136 string

    URL of one of the predefined 2x logo sizes.

  • logo.variants.156 string

    URL of one of the predefined 3x logo sizes.

  • logo.variants.204 string

    URL of one of the predefined 3x logo sizes.

  • logo.variants.320 string

    URL of one of the predefined 2x logo sizes.

  • logo.variants.480 string

    URL of one of the predefined 3x logo sizes.

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

space object
{
  "id": "kxXqtnaI6J6203RFuzrfdB7C",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Contractors",
  "logo": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all spaces

Returns a list of spaces.

Parameters

  • companyId string | $in | $nin

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

  • $sort object

Returns

Returns an object with a data property that contains a list of spaces. 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 space object. If no spaces are available, the resulting list will be empty. This request should never return an error.

GET /api/spaces
curl https://app.humaans.io/api/spaces \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "kxXqtnaI6J6203RFuzrfdB7C",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "Contractors",
      "logo": {
        "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
        "filename": "image-file.jpg",
        "variants": {
          "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
          "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
          "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
          "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
          "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
          "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
          "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
          "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
        }
      },
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a space

Retrieves the space with the given ID.

Parameters
  • No parameters
Returns

Returns a space object if a valid identifier was provided.

GET /api/spaces/:id
curl https://app.humaans.io/api/spaces/kxXqtnaI6J6203RFuzrfdB7C \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "kxXqtnaI6J6203RFuzrfdB7C",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Contractors",
  "logo": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a space

Parameters

  • name string required

Returns

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

POST /api/spaces
curl https://app.humaans.io/api/spaces \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"Contractors"}'
Response
{
  "id": "kxXqtnaI6J6203RFuzrfdB7C",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Contractors",
  "logo": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a space

Parameters

  • name string

Returns

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

PATCH /api/spaces/:id
curl https://app.humaans.io/api/spaces/kxXqtnaI6J6203RFuzrfdB7C \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"name":"Contractors"}'
Response
{
  "id": "kxXqtnaI6J6203RFuzrfdB7C",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Contractors",
  "logo": {
    "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
    "filename": "image-file.jpg",
    "variants": {
      "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
      "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
      "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
      "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
      "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
      "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
      "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
      "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
    }
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a space

Permanently deletes a space. It cannot be undone.

Parameters
  • No parameters
Returns

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

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

Tasks

An aggregated task assigned to a person. Combines tasks from multiple sources including workflow tasks, onboarding checklists, and other task providers.

Endpoints
Required scopes
tasks.read

Task object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • resourceId string

  • resourceType string

  • group string

  • groupId string

  • section string

  • title string

  • hasDescription boolean

  • subjects object[]

  • subjects.subjectType string

  • subjects.person object

  • subjects.person.id string

    Unique identifier for the object.

  • subjects.person.companyId string

    ID of the company that this object is associated to.

  • subjects.person.firstName string

    First name.

  • subjects.person.preferredName string

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

  • subjects.person.lastName string

    Last name.

  • subjects.person.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 un-resized file via api/files.

  • subjects.person.profilePhoto.id string

    Unique identifier for the object.

  • subjects.person.profilePhoto.filename string

  • subjects.person.profilePhoto.variants object

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

  • subjects.person.profilePhoto.variants.64 string

    URL of one of the predefined 2x profile photo sizes.

  • subjects.person.profilePhoto.variants.96 string

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

  • subjects.person.profilePhoto.variants.104 string

    URL of one of the predefined 2x profile photo sizes.

  • subjects.person.profilePhoto.variants.136 string

    URL of one of the predefined 2x profile photo sizes.

  • subjects.person.profilePhoto.variants.156 string

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

  • subjects.person.profilePhoto.variants.204 string

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

  • subjects.person.profilePhoto.variants.320 string

    URL of one of the predefined 2x profile photo sizes.

  • subjects.person.profilePhoto.variants.480 string

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

  • subjects.person.timezone string

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

  • status string

  • activeDate string, date

  • dueDate string, date

  • completedAt string, date

  • personId string

    ID of the person that this object is associated to.

  • assignedTo object

  • assignedTo.team object

  • assignedTo.team.name string

  • assignedTo.team.spaceId string

  • assignedTo.personId string

    ID of the person that this object is associated to.

task object
{
  "id": "AmmZtg6ydnHVwkORn9qrP52o",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "subjects": [
    {
      "person": {
        "id": "smIkoZZ0t4KlXbEka2UC9m7I",
        "companyId": "T7uqPFK7am4lFTZm39AmNuay",
        "firstName": "Kelsey",
        "preferredName": null,
        "lastName": "Wicks",
        "profilePhoto": {
          "id": "Hgi5auXaKsjn2MjuYo1PDk3W",
          "filename": "image-file.jpg",
          "variants": {
            "64": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@64.jpg",
            "96": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@96.jpg",
            "104": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@104.jpg",
            "136": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@136.jpg",
            "156": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@156.jpg",
            "204": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@204.jpg",
            "320": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@320.jpg",
            "480": "https://storage.googleapis.com/humaans-public-prd/Hgi5auXaKsjn2MjuYo1PDk3W@480.jpg"
          }
        },
        "timezone": "Europe/London"
      }
    }
  ],
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "assignedTo": {
    "team": {},
    "personId": "IL3vneCYhIx0xrR6um2sy2nW"
  }
}

Time away

An object representing a time away entry of an employee. Time away can be a time off entry, e.g. paid time off, sick leave, paternity leave, etc. Or it can be a working away entry, e.g. working from home, travelling for work, etc.

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

Time away object

Attributes

  • id string

    Unique identifier for the object.

  • personId string

    ID of the person that this object is associated to.

  • startTime string

    If defined, specifies the start time for the time away booking in HH:MM:SS format. Applicable for same day bookings

  • endTime string

    If defined, specifies the end time for the time away booking in HH:MM:SS format. Applicable for same day bookings

  • startDate string, date

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

  • startPeriod string

    Indicates if the first date of the time away entry was taken in full or as half day. One of: full (when taking full day), am (when taking morning off) or pm (when taking afternoon off). Defaults to full.

  • endDate string, date

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

  • endPeriod string

    Indicates if the last date of the time away entry was taken in full or as half day. One of: full (when taking full day) or am (when taking morning off only). If startDate and endDate are the same, this should be the same as startPeriod. Defaults to full.

  • timeAwayTypeId string

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

  • name string

    A human readable label of the time away entry type.

  • isTimeOff boolean

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

  • workingFromLocationId string

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

  • note string

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

  • breakdown object[]

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

  • breakdown.date string, date

    The date.

  • breakdown.period string | number

    One of: full, am, pm.

  • breakdown.hours number

  • breakdown.weekend boolean

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

  • breakdown.holiday boolean

    True if the day is a public holiday.

  • breakdown.fteDay number

    Amount of day accounted for FTE.

  • days number

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

  • requestStatus string

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

  • requestedBy string

    The ID of the person that made this request.

  • reviewedBy string

    The ID of the person that reviewed this request.

  • reviewedAt string, date-time

    The date and time when this request was reviewed.

  • reviewNote string

    A note to accompany a time away review.

  • publicHolidayCalendarId string

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

  • workingDays object[]

    The person’s working days schedule at the time of booking time away

  • workingDays.day string

    A day of the week.

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

  • timezone string

    The timezone of the personId when the booking was made

time away object
{
  "id": "YLlqHE4DLvGtFJ7L2qro6bTF",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startTime": "09:00:00",
  "endTime": "18:00:00",
  "startDate": "2020-01-24",
  "startPeriod": "full",
  "endDate": "2020-01-29",
  "endPeriod": "am",
  "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
  "name": "Paid time off",
  "isTimeOff": true,
  "workingFromLocationId": null,
  "note": "🏝 Trip to New Zealand",
  "breakdown": [
    {
      "date": "2020-01-24",
      "period": "full"
    },
    {
      "date": "2020-01-25",
      "period": "full",
      "weekend": true
    },
    {
      "date": "2020-01-26",
      "period": "full",
      "weekend": true,
      "holiday": true
    },
    {
      "date": "2020-01-27",
      "period": "full",
      "holiday": true
    },
    {
      "date": "2020-01-28",
      "period": "full"
    },
    {
      "date": "2020-01-29",
      "period": "am"
    }
  ],
  "days": 2.5,
  "requestStatus": "declined",
  "requestedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedAt": "2020-01-20",
  "reviewNote": "Dates clash with product launch.",
  "publicHolidayCalendarId": "AU-NSW",
  "workingDays": [
    {
      "day": "monday"
    },
    {
      "day": "tuesday"
    }
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "timezone": "America/Los_Angeles"
}

List all time away

Returns a list of time away entries.

The time away entries can be filtered using more complex filter conditions. Refer to Filtering documentation for more details on usage.

When syncing time away entries to another system, it can be useful to get all entries that were created, updated or deleted since a certain date. You can use the includeDeleted=true parameter to include deleted entries.

Include deleted entries, the shape of deleted items is { id, personId, deletedAt }:

GET /api/time-away?includeDeleted=true

Fetch only deleted entries:

GET /api/time-away?includeDeleted=true&deletedAt[$ne]=null

Fetch all entries created updated or deleted since the specified date:

GET /api/time-away?includeDeleted=true&updatedAt[$gte]=2025-02-01

Parameters

  • personId string | $in

    The person to filter queries by.

  • personStatus string | $in

    The person status to filter queries by.

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

    Filter by start date.

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

    Filter by end date.

  • timeAwayTypeId string

    Filter by the time away type

  • requestStatus string | $in

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

  • includeDeleted boolean

    Include deleted time away entries. Only entries deleted within the last 90 days will show up. The content of deleted entries is { id, personId, deletedAt }.

  • updatedAt object

    Filter by updatedAt. Useful to get items that were created, updated or deleted since certain date.

  • updatedAt.$gt string

  • updatedAt.$gte string

  • updatedAt.$lt string

  • updatedAt.$lte string

  • deletedAt null | $ne

    Filter for deleted entries. Only relevant in combination with includeDeleted.

  • $sort object

  • $sort.startDate number

  • $sort.endDate number

  • $sort.createdAt number

  • $or object[]

    Filter results by multiple criteria.

  • $or.personId string | $in

    The person to filter queries by.

  • $or.personStatus string | $in

    The person status to filter queries by.

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

    Filter by start date.

  • $or.endDate date | $gt | $gte | $lt | $lte

    Filter by end date.

  • $or.type string

  • $or.timeAwayTypeId string

    Filter by the time away type

  • $or.requestStatus string | $in

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

  • $or.includeDeleted boolean

    Include deleted time away entries. Only entries deleted within the last 90 days will show up. The content of deleted entries is { id, personId, deletedAt }.

  • $or.updatedAt object

    Filter by updatedAt. Useful to get items that were created, updated or deleted since certain date.

  • $or.updatedAt.$gt string

  • $or.updatedAt.$gte string

  • $or.updatedAt.$lt string

  • $or.updatedAt.$lte string

  • $or.deletedAt null | $ne

    Filter for deleted entries. Only relevant in combination with includeDeleted.

  • $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",
      "startTime": "09:00:00",
      "endTime": "18:00:00",
      "startDate": "2020-01-24",
      "startPeriod": "full",
      "endDate": "2020-01-29",
      "endPeriod": "am",
      "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
      "name": "Paid time off",
      "isTimeOff": true,
      "workingFromLocationId": null,
      "note": "🏝 Trip to New Zealand",
      "breakdown": [
        {
          "date": "2020-01-24",
          "period": "full"
        },
        {
          "date": "2020-01-25",
          "period": "full",
          "weekend": true
        },
        {
          "date": "2020-01-26",
          "period": "full",
          "weekend": true,
          "holiday": true
        },
        {
          "date": "2020-01-27",
          "period": "full",
          "holiday": true
        },
        {
          "date": "2020-01-28",
          "period": "full"
        },
        {
          "date": "2020-01-29",
          "period": "am"
        }
      ],
      "days": 2.5,
      "requestStatus": "declined",
      "requestedBy": "ob4xPcVpGGZm043C7xGMfP1U",
      "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
      "reviewedAt": "2020-01-20",
      "reviewNote": "Dates clash with product launch.",
      "publicHolidayCalendarId": "AU-NSW",
      "workingDays": [
        {
          "day": "monday"
        },
        {
          "day": "tuesday"
        }
      ],
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z",
      "timezone": "America/Los_Angeles"
    }
  ]
}

Retrieve a time away

Retrieves the time away with the given ID.

Parameters
  • No parameters
Returns

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

GET /api/time-away/:id
curl https://app.humaans.io/api/time-away/YLlqHE4DLvGtFJ7L2qro6bTF \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "YLlqHE4DLvGtFJ7L2qro6bTF",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startTime": "09:00:00",
  "endTime": "18:00:00",
  "startDate": "2020-01-24",
  "startPeriod": "full",
  "endDate": "2020-01-29",
  "endPeriod": "am",
  "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
  "name": "Paid time off",
  "isTimeOff": true,
  "workingFromLocationId": null,
  "note": "🏝 Trip to New Zealand",
  "breakdown": [
    {
      "date": "2020-01-24",
      "period": "full"
    },
    {
      "date": "2020-01-25",
      "period": "full",
      "weekend": true
    },
    {
      "date": "2020-01-26",
      "period": "full",
      "weekend": true,
      "holiday": true
    },
    {
      "date": "2020-01-27",
      "period": "full",
      "holiday": true
    },
    {
      "date": "2020-01-28",
      "period": "full"
    },
    {
      "date": "2020-01-29",
      "period": "am"
    }
  ],
  "days": 2.5,
  "requestStatus": "declined",
  "requestedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedAt": "2020-01-20",
  "reviewNote": "Dates clash with product launch.",
  "publicHolidayCalendarId": "AU-NSW",
  "workingDays": [
    {
      "day": "monday"
    },
    {
      "day": "tuesday"
    }
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "timezone": "America/Los_Angeles"
}

Create a time away

Parameters

  • personId string required

    ID of the person that this object is associated to.

  • startTime string | null

    If defined, specifies the start time for the time away booking in HH:MM:SS format. Applicable for same day bookings

  • endTime string | null

    If defined, specifies the end time for the time away booking in HH:MM:SS format. Applicable for same day bookings

  • startDate string, date required

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

  • endDate string, date required

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

  • startPeriod string | null

    Indicates if the first date of the time away entry was taken in full or as half day. One of: full (when taking full day), am (when taking morning off) or pm (when taking afternoon off). Defaults to full.

  • endPeriod string | null

    Indicates if the last date of the time away entry was taken in full or as half day. One of: full (when taking full day) or am (when taking morning off only). If startDate and endDate are the same, this should be the same as startPeriod. Defaults to full.

  • note string | null

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

  • workingFromLocationId string | null

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

  • timeAwayTypeId string required

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

  • requestStatus string

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

  • reviewNote string

    A note to accompany a time away review.

Returns

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

POST /api/time-away
curl https://app.humaans.io/api/time-away \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"note":"✈️ Trip to New Zealand"}'
Response
{
  "id": "YLlqHE4DLvGtFJ7L2qro6bTF",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startTime": "09:00:00",
  "endTime": "18:00:00",
  "startDate": "2020-01-24",
  "startPeriod": "full",
  "endDate": "2020-01-29",
  "endPeriod": "am",
  "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
  "name": "Paid time off",
  "isTimeOff": true,
  "workingFromLocationId": null,
  "note": "✈️ Trip to New Zealand",
  "breakdown": [
    {
      "date": "2020-01-24",
      "period": "full"
    },
    {
      "date": "2020-01-25",
      "period": "full",
      "weekend": true
    },
    {
      "date": "2020-01-26",
      "period": "full",
      "weekend": true,
      "holiday": true
    },
    {
      "date": "2020-01-27",
      "period": "full",
      "holiday": true
    },
    {
      "date": "2020-01-28",
      "period": "full"
    },
    {
      "date": "2020-01-29",
      "period": "am"
    }
  ],
  "days": 2.5,
  "requestStatus": "declined",
  "requestedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedAt": "2020-01-20",
  "reviewNote": "Dates clash with product launch.",
  "publicHolidayCalendarId": "AU-NSW",
  "workingDays": [
    {
      "day": "monday"
    },
    {
      "day": "tuesday"
    }
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "timezone": "America/Los_Angeles"
}

Update a time away

Parameters

  • startTime string | null

    If defined, specifies the start time for the time away booking in HH:MM:SS format. Applicable for same day bookings

  • endTime string | null

    If defined, specifies the end time for the time away booking in HH:MM:SS format. Applicable for same day bookings

  • startDate string, date

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

  • endDate string, date

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

  • startPeriod string | null

    Indicates if the first date of the time away entry was taken in full or as half day. One of: full (when taking full day), am (when taking morning off) or pm (when taking afternoon off). Defaults to full.

  • endPeriod string | null

    Indicates if the last date of the time away entry was taken in full or as half day. One of: full (when taking full day) or am (when taking morning off only). If startDate and endDate are the same, this should be the same as startPeriod. Defaults to full.

  • note string | null

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

  • workingFromLocationId string | null

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

  • timeAwayTypeId string

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

  • requestStatus string

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

  • reviewNote string

    A note to accompany a time away review.

Returns

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

PATCH /api/time-away/:id
curl https://app.humaans.io/api/time-away/YLlqHE4DLvGtFJ7L2qro6bTF \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"note":"✈️ Trip to New Zealand"}'
Response
{
  "id": "YLlqHE4DLvGtFJ7L2qro6bTF",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startTime": "09:00:00",
  "endTime": "18:00:00",
  "startDate": "2020-01-24",
  "startPeriod": "full",
  "endDate": "2020-01-29",
  "endPeriod": "am",
  "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
  "name": "Paid time off",
  "isTimeOff": true,
  "workingFromLocationId": null,
  "note": "✈️ Trip to New Zealand",
  "breakdown": [
    {
      "date": "2020-01-24",
      "period": "full"
    },
    {
      "date": "2020-01-25",
      "period": "full",
      "weekend": true
    },
    {
      "date": "2020-01-26",
      "period": "full",
      "weekend": true,
      "holiday": true
    },
    {
      "date": "2020-01-27",
      "period": "full",
      "holiday": true
    },
    {
      "date": "2020-01-28",
      "period": "full"
    },
    {
      "date": "2020-01-29",
      "period": "am"
    }
  ],
  "days": 2.5,
  "requestStatus": "declined",
  "requestedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedAt": "2020-01-20",
  "reviewNote": "Dates clash with product launch.",
  "publicHolidayCalendarId": "AU-NSW",
  "workingDays": [
    {
      "day": "monday"
    },
    {
      "day": "tuesday"
    }
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z",
  "timezone": "America/Los_Angeles"
}

Delete a time away

Permanently deletes a time away. It cannot be undone.

Parameters
  • No parameters
Returns

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

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

Time away adjustments

An object representing a time away adjustment. Adjustments are used to add or remove days to the available time off balance. They are one off and are applied in the time away period they fall in based on the date.

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

Time away adjustment object

Attributes

  • id string

    Unique identifier for the object.

  • personId string

    ID of the person that this object is associated to.

  • date string, date

    The date when the adjustment was granted.

  • deltaAmount number

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

  • unit string

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

  • reason string

    A note describing the reason for this adjustment.

  • validUntil string, date

    The date when the adjustment expires.

  • timeAwayTypeId string

    ID of the Time away type this adjustment is attached to.

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

time away adjustment object
{
  "id": "BZJa63JpH4Bz25oM28zAbeoK",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "date": "2020-03-01",
  "deltaAmount": 2,
  "unit": "days",
  "reason": "For working over the weekend.",
  "validUntil": "2029-03-01",
  "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all time away adjustments

Returns a list of time away adjustments.

Parameters

  • $sort object

  • $sort.date number

  • $sort.createdAt number

  • personId string | $in

    The person to filter queries by.

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

    Filter by end date.

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/time-away-adjustments
curl https://app.humaans.io/api/time-away-adjustments \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "BZJa63JpH4Bz25oM28zAbeoK",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "date": "2020-03-01",
      "deltaAmount": 2,
      "unit": "days",
      "reason": "For working over the weekend.",
      "validUntil": "2029-03-01",
      "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a time away adjustment

Retrieves the time away adjustment with the given ID.

Parameters
  • No parameters
Returns

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

GET /api/time-away-adjustments/:id
curl https://app.humaans.io/api/time-away-adjustments/BZJa63JpH4Bz25oM28zAbeoK \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "BZJa63JpH4Bz25oM28zAbeoK",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "date": "2020-03-01",
  "deltaAmount": 2,
  "unit": "days",
  "reason": "For working over the weekend.",
  "validUntil": "2029-03-01",
  "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a time away adjustment

Parameters

  • personId string required

    ID of the person that this object is associated to.

  • date string, date required

    The date when the adjustment was granted.

  • deltaAmount number

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

  • unit string

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

  • reason string required

    A note describing the reason for this adjustment.

  • validUntil string, date | null

    The date when the adjustment expires.

  • timeAwayTypeId string required

    ID of the Time away type this adjustment is attached to.

Returns

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

POST /api/time-away-adjustments
curl https://app.humaans.io/api/time-away-adjustments \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","date":"2020-03-01","reason":"For working over the weekend.","timeAwayTypeId":"7xGMobpxPcVfP1UGGZm043C4"}'
Response
{
  "id": "BZJa63JpH4Bz25oM28zAbeoK",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "date": "2020-03-01",
  "deltaAmount": 2,
  "unit": "days",
  "reason": "For working over the weekend.",
  "validUntil": "2029-03-01",
  "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a time away adjustment

Parameters

  • date string, date

    The date when the adjustment was granted.

  • deltaAmount number

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

  • unit string

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

  • reason string

    A note describing the reason for this adjustment.

  • validUntil string, date | null

    The date when the adjustment expires.

  • timeAwayTypeId string

    ID of the Time away type this adjustment is attached to.

Returns

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

PATCH /api/time-away-adjustments/:id
curl https://app.humaans.io/api/time-away-adjustments/BZJa63JpH4Bz25oM28zAbeoK \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'
Response
{
  "id": "BZJa63JpH4Bz25oM28zAbeoK",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "date": "2020-03-01",
  "deltaAmount": 2,
  "unit": "days",
  "reason": "For working over the weekend.",
  "validUntil": "2029-03-01",
  "timeAwayTypeId": "7xGMobpxPcVfP1UGGZm043C4",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a time away adjustment

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

Parameters
  • No parameters
Returns

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

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

Time away allocations

An object representing the mapping between an employee and a time away policy.

To assign a specific time away policy to an employee an allocation with an effectiveDate is created and linked to a person (personId) and a time away policy (timeAwayPolicyId). Each person will often have only one allocation throughout their lifetime, but they can have multiple consecutive allocations in cases when the company is changing it’s time of policy or when the employee moves to a country, office or role with a different time off policy.

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

Time away allocation object

Attributes

  • id string

    Unique identifier for the object.

  • personId string

    ID of the person that this object is associated to.

  • type string

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

  • effectiveDate string, date

    The first day when the allocation is in effect.

  • timeAwayPolicyId string

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

  • timeAwayPolicy time away policy

    The time away policy used by this allocation. When the type of the allocation is custom, these attributes are writable and can be used to create custom inline per person policies. In case the type is placeOfWork or specific - only the timeAwayPolicyId is writable and must be used to assign an existing time away policy.

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

time away allocation object
{
  "id": "MfQQ2fWdXGD3hvZKrxm6zWE0",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "placeOfWork",
  "effectiveDate": "2020-04-01",
  "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I",
  "timeAwayPolicy": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "companyId": "T7uqPFK7am4lFTZm39AmNuay",
    "name": "UK Policy",
    "timeAwayPolicyVersion": {
      "id": "smIkoZZ0t4KlXbEka2UC9m7I",
      "bypassWorkingSchedule": false,
      "bypassPublicHolidays": false,
      "publicHolidayCalendarId": "GB",
      "visibleBalances": [
        "endOfYear"
      ],
      "rules": [
        {
          "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
          "limits": {
            "yearlyAllowance": 30,
            "maxCarryOver": 5,
            "yearStart": "01-01",
            "yearStartType": "employmentStartDate",
            "isUnlimited": false,
            "isProrated": false,
            "preventNegativeBalance": false,
            "usage": "upfront",
            "usagePeriod": 12,
            "roundingType": "halfUp"
          }
        }
      ]
    },
    "createdAt": "2020-01-28T08:44:42.000Z",
    "updatedAt": "2020-01-29T14:52:21.000Z"
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all time away allocations

Returns a list of time away allocations.

Parameters

  • personId string

    The person to filter queries by.

  • isCurrent boolean

    Return the current allocation only.

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/time-away-allocations
curl https://app.humaans.io/api/time-away-allocations \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "MfQQ2fWdXGD3hvZKrxm6zWE0",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "type": "placeOfWork",
      "effectiveDate": "2020-04-01",
      "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I",
      "timeAwayPolicy": {
        "id": "smIkoZZ0t4KlXbEka2UC9m7I",
        "companyId": "T7uqPFK7am4lFTZm39AmNuay",
        "name": "UK Policy",
        "timeAwayPolicyVersion": {
          "id": "smIkoZZ0t4KlXbEka2UC9m7I",
          "bypassWorkingSchedule": false,
          "bypassPublicHolidays": false,
          "publicHolidayCalendarId": "GB",
          "visibleBalances": [
            "endOfYear"
          ],
          "rules": [
            {
              "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
              "limits": {
                "yearlyAllowance": 30,
                "maxCarryOver": 5,
                "yearStart": "01-01",
                "yearStartType": "employmentStartDate",
                "isUnlimited": false,
                "isProrated": false,
                "preventNegativeBalance": false,
                "usage": "upfront",
                "usagePeriod": 12,
                "roundingType": "halfUp"
              }
            }
          ]
        },
        "createdAt": "2020-01-28T08:44:42.000Z",
        "updatedAt": "2020-01-29T14:52:21.000Z"
      },
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a time away allocation

Retrieves the time away allocation with the given ID.

Parameters
  • No parameters
Returns

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

GET /api/time-away-allocations/:id
curl https://app.humaans.io/api/time-away-allocations/MfQQ2fWdXGD3hvZKrxm6zWE0 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "MfQQ2fWdXGD3hvZKrxm6zWE0",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "placeOfWork",
  "effectiveDate": "2020-04-01",
  "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I",
  "timeAwayPolicy": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "companyId": "T7uqPFK7am4lFTZm39AmNuay",
    "name": "UK Policy",
    "timeAwayPolicyVersion": {
      "id": "smIkoZZ0t4KlXbEka2UC9m7I",
      "bypassWorkingSchedule": false,
      "bypassPublicHolidays": false,
      "publicHolidayCalendarId": "GB",
      "visibleBalances": [
        "endOfYear"
      ],
      "rules": [
        {
          "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
          "limits": {
            "yearlyAllowance": 30,
            "maxCarryOver": 5,
            "yearStart": "01-01",
            "yearStartType": "employmentStartDate",
            "isUnlimited": false,
            "isProrated": false,
            "preventNegativeBalance": false,
            "usage": "upfront",
            "usagePeriod": 12,
            "roundingType": "halfUp"
          }
        }
      ]
    },
    "createdAt": "2020-01-28T08:44:42.000Z",
    "updatedAt": "2020-01-29T14:52:21.000Z"
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a time away allocation

Parameters

  • personId string required

    ID of the person that this object is associated to.

  • type string required

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

  • effectiveDate string, date | null required

    The first day when the allocation is in effect.

  • timeAwayPolicyId string

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

  • timeAwayPolicy time away policy

    The time away policy used by this allocation. When the type of the allocation is custom, these attributes are writable and can be used to create custom inline per person policies. In case the type is placeOfWork or specific - only the timeAwayPolicyId is writable and must be used to assign an existing time away policy.

  • removeAllocations boolean

Returns

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

POST /api/time-away-allocations
curl https://app.humaans.io/api/time-away-allocations \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"effectiveDate":"2020-04-30"}'
Response
{
  "id": "MfQQ2fWdXGD3hvZKrxm6zWE0",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "placeOfWork",
  "effectiveDate": "2020-04-30",
  "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I",
  "timeAwayPolicy": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "companyId": "T7uqPFK7am4lFTZm39AmNuay",
    "name": "UK Policy",
    "timeAwayPolicyVersion": {
      "id": "smIkoZZ0t4KlXbEka2UC9m7I",
      "bypassWorkingSchedule": false,
      "bypassPublicHolidays": false,
      "publicHolidayCalendarId": "GB",
      "visibleBalances": [
        "endOfYear"
      ],
      "rules": [
        {
          "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
          "limits": {
            "yearlyAllowance": 30,
            "maxCarryOver": 5,
            "yearStart": "01-01",
            "yearStartType": "employmentStartDate",
            "isUnlimited": false,
            "isProrated": false,
            "preventNegativeBalance": false,
            "usage": "upfront",
            "usagePeriod": 12,
            "roundingType": "halfUp"
          }
        }
      ]
    },
    "createdAt": "2020-01-28T08:44:42.000Z",
    "updatedAt": "2020-01-29T14:52:21.000Z"
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a time away allocation

Parameters

  • type string

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

  • effectiveDate string, date | null

    The first day when the allocation is in effect.

  • timeAwayPolicyId string

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

  • timeAwayPolicy time away policy

    The time away policy used by this allocation. When the type of the allocation is custom, these attributes are writable and can be used to create custom inline per person policies. In case the type is placeOfWork or specific - only the timeAwayPolicyId is writable and must be used to assign an existing time away policy.

Returns

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

PATCH /api/time-away-allocations/:id
curl https://app.humaans.io/api/time-away-allocations/MfQQ2fWdXGD3hvZKrxm6zWE0 \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"effectiveDate":"2020-04-30"}'
Response
{
  "id": "MfQQ2fWdXGD3hvZKrxm6zWE0",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "type": "placeOfWork",
  "effectiveDate": "2020-04-30",
  "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I",
  "timeAwayPolicy": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "companyId": "T7uqPFK7am4lFTZm39AmNuay",
    "name": "UK Policy",
    "timeAwayPolicyVersion": {
      "id": "smIkoZZ0t4KlXbEka2UC9m7I",
      "bypassWorkingSchedule": false,
      "bypassPublicHolidays": false,
      "publicHolidayCalendarId": "GB",
      "visibleBalances": [
        "endOfYear"
      ],
      "rules": [
        {
          "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
          "limits": {
            "yearlyAllowance": 30,
            "maxCarryOver": 5,
            "yearStart": "01-01",
            "yearStartType": "employmentStartDate",
            "isUnlimited": false,
            "isProrated": false,
            "preventNegativeBalance": false,
            "usage": "upfront",
            "usagePeriod": 12,
            "roundingType": "halfUp"
          }
        }
      ]
    },
    "createdAt": "2020-01-28T08:44:42.000Z",
    "updatedAt": "2020-01-29T14:52:21.000Z"
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a time away allocation

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

Parameters
  • No parameters
Returns

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

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

Time away approval flows

Configures who must approve time off requests for a given time away type. Defines the approval chain (e.g. manager, then HR).

Endpoints
Required scopes
public.read
timeAway.read
settings.write

Time away approval flow object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • name string

  • isDefault boolean

time away approval flow object
{
  "id": "5wUWlVVACp7VmtqgCXrVdw1r",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay"
}

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
timeAway.read

Time away period object

Attributes

  • id string

    Unique identifier for the object.

  • personId string

    ID of the person that this object is associated to.

  • startDate string, date

    The start of the PTO accrual and usage periods. This can be either the start of a new year, the start of employment, or the date when a new policy was assigned. Note: the start of the year depends on the policy configuration.

  • endDate string, date

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

  • usageEndDate string, date

    The end of the PTO usage period. This can be either the end of the year, the end of employment, or the day before a new policy was assigned. Note: the end of the year will be ptoUsagePeriod months from the yearStart.

  • timeAwayAllocation time away allocation

    The time away allocation used in this period.

  • timeAwayTypeId string

    The id of the type this period data refers to

  • isCurrentPeriod boolean

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

  • isFinalPeriod boolean

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

  • hasAllocationChanged boolean

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

  • isCarriedOverInFull boolean

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

  • isProrated boolean

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

  • accrued number

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

  • allowance number

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

  • fromPrevAccrualPeriod integer

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

  • fromPrevAccrualPeriodValidUntilDate string, date

    The date at which fromPrevAccrualPeriod is valid until.

  • fromPrevAccrualPeriodExpired integer

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

  • carriedOver number

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

  • carriedOverDate string, date

    The date at which carriedOver is applied.

  • adjustments number

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

  • adjustmentsUpcoming number

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

  • used number

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

  • pending number

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

  • upcoming number

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

  • upcomingPending number

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

  • balance number

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

  • endingBalance number

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

time away period object
{
  "id": "X4XT4ZLOwT9GYbPyl90HztBu",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startDate": "2020-09-01",
  "endDate": "2021-08-31",
  "usageEndDate": "2021-12-31",
  "timeAwayAllocation": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "personId": "IL3vneCYhIx0xrR6um2sy2nW",
    "type": "placeOfWork",
    "effectiveDate": "2020-04-01",
    "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I",
    "timeAwayPolicy": {
      "id": "smIkoZZ0t4KlXbEka2UC9m7I",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "UK Policy",
      "timeAwayPolicyVersion": {
        "id": "smIkoZZ0t4KlXbEka2UC9m7I",
        "bypassWorkingSchedule": false,
        "bypassPublicHolidays": false,
        "publicHolidayCalendarId": "GB",
        "visibleBalances": [
          "endOfYear"
        ],
        "rules": [
          {
            "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
            "limits": {
              "yearlyAllowance": 30,
              "maxCarryOver": 5,
              "yearStart": "01-01",
              "yearStartType": "employmentStartDate",
              "isUnlimited": false,
              "isProrated": false,
              "preventNegativeBalance": false,
              "usage": "upfront",
              "usagePeriod": 12,
              "roundingType": "halfUp"
            }
          }
        ]
      },
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    },
    "createdAt": "2020-01-28T08:44:42.000Z",
    "updatedAt": "2020-01-29T14:52:21.000Z"
  },
  "timeAwayTypeId": "0defdigw4ayfQ0EP22HjZGiD",
  "isCurrentPeriod": true,
  "isFinalPeriod": false,
  "hasAllocationChanged": false,
  "isCarriedOverInFull": false,
  "isProrated": true,
  "accrued": 8.09,
  "allowance": 20,
  "fromPrevAccrualPeriod": 2,
  "fromPrevAccrualPeriodValidUntilDate": "2021-12-31",
  "fromPrevAccrualPeriodExpired": 2,
  "carriedOver": -0.17,
  "carriedOverDate": "2020-12-31",
  "adjustments": 0,
  "adjustmentsUpcoming": 0,
  "used": 2,
  "pending": 2,
  "upcoming": 0,
  "upcomingPending": 0,
  "balance": 5.92,
  "endingBalance": 17.83
}

List all time away periods

Returns a list of time away periods.

Parameters

  • personId string

    The person to filter queries by.

  • isCurrentPeriod boolean

    Return the current period only.

  • isFinalPeriod boolean

    Return the final period only.

  • date string, date

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

  • timeAwayTypeId string

    If a time away type is specified, returns the periods for that type. If set to ‘all’, the response includes periods for all time away types. Defaults to pto type if no type is provided.

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

GET /api/time-away-periods
curl https://app.humaans.io/api/time-away-periods \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "X4XT4ZLOwT9GYbPyl90HztBu",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "startDate": "2020-09-01",
      "endDate": "2021-08-31",
      "usageEndDate": "2021-12-31",
      "timeAwayAllocation": {
        "id": "smIkoZZ0t4KlXbEka2UC9m7I",
        "personId": "IL3vneCYhIx0xrR6um2sy2nW",
        "type": "placeOfWork",
        "effectiveDate": "2020-04-01",
        "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I",
        "timeAwayPolicy": {
          "id": "smIkoZZ0t4KlXbEka2UC9m7I",
          "companyId": "T7uqPFK7am4lFTZm39AmNuay",
          "name": "UK Policy",
          "timeAwayPolicyVersion": {
            "id": "smIkoZZ0t4KlXbEka2UC9m7I",
            "bypassWorkingSchedule": false,
            "bypassPublicHolidays": false,
            "publicHolidayCalendarId": "GB",
            "visibleBalances": [
              "endOfYear"
            ],
            "rules": [
              {
                "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
                "limits": {
                  "yearlyAllowance": 30,
                  "maxCarryOver": 5,
                  "yearStart": "01-01",
                  "yearStartType": "employmentStartDate",
                  "isUnlimited": false,
                  "isProrated": false,
                  "preventNegativeBalance": false,
                  "usage": "upfront",
                  "usagePeriod": 12,
                  "roundingType": "halfUp"
                }
              }
            ]
          },
          "createdAt": "2020-01-28T08:44:42.000Z",
          "updatedAt": "2020-01-29T14:52:21.000Z"
        },
        "createdAt": "2020-01-28T08:44:42.000Z",
        "updatedAt": "2020-01-29T14:52:21.000Z"
      },
      "timeAwayTypeId": "0defdigw4ayfQ0EP22HjZGiD",
      "isCurrentPeriod": true,
      "isFinalPeriod": false,
      "hasAllocationChanged": false,
      "isCarriedOverInFull": false,
      "isProrated": true,
      "accrued": 8.09,
      "allowance": 20,
      "fromPrevAccrualPeriod": 2,
      "fromPrevAccrualPeriodValidUntilDate": "2021-12-31",
      "fromPrevAccrualPeriodExpired": 2,
      "carriedOver": -0.17,
      "carriedOverDate": "2020-12-31",
      "adjustments": 0,
      "adjustmentsUpcoming": 0,
      "used": 2,
      "pending": 2,
      "upcoming": 0,
      "upcomingPending": 0,
      "balance": 5.92,
      "endingBalance": 17.83
    }
  ]
}

Time away policies

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

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

Time away policy object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • name string

    The name of the policy.

  • timeAwayPolicyVersion object

    Time away policy version information

  • timeAwayPolicyVersion.id string

    Unique identifier for the object.

  • timeAwayPolicyVersion.bypassWorkingSchedule boolean

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

  • timeAwayPolicyVersion.bypassPublicHolidays boolean

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

  • timeAwayPolicyVersion.publicHolidayCalendarId string

    A specific public holiday calendar id for all employees on this policy. If null, this will default to the employee’s office or remote location.

  • timeAwayPolicyVersion.visibleBalances string[]

    Which balances to show to employees. Available options are endOfYear or today.

  • timeAwayPolicyVersion.rules object[]

    List of time away types that are available on this policy.

  • timeAwayPolicyVersion.rules.timeAwayTypeId string

    ID of the time away type that this rule is associated to.

  • timeAwayPolicyVersion.rules.limits object

    If null, balances will not be caluclated for this type but usage numbers will still be available.

  • timeAwayPolicyVersion.rules.limits.yearlyAllowance number

    The number of paid time off days allowed per year.

  • timeAwayPolicyVersion.rules.limits.maxCarryOver number

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

  • timeAwayPolicyVersion.rules.limits.yearStart string

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

  • timeAwayPolicyVersion.rules.limits.yearStartType string

    Whether the policy starts on employment start date or a custom date.

  • timeAwayPolicyVersion.rules.limits.isUnlimited boolean

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

  • timeAwayPolicyVersion.rules.limits.isProrated boolean

    true means the allowance will be prorated based on FTE.

  • timeAwayPolicyVersion.rules.limits.preventNegativeBalance boolean

    true prevents booking more leave than currently available.

  • timeAwayPolicyVersion.rules.limits.usage string

    Whether the employee can use PTO days for the year upfront or after they’ve been accrued. One of upfront or accrued.

  • timeAwayPolicyVersion.rules.limits.usagePeriod integer

    The length of the period in months beginning on yearStart where the employees’ yearly PTO can be used. One of 12, 15, 16, or 18. Defaults to: 12.

  • timeAwayPolicyVersion.rules.limits.roundingType string

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

  • archivedAt string, date-time

    When the policy was archived.

  • isArchived boolean

    Whether the policy is archived.

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

time away policy object
{
  "id": "dFCSrX1I3nzOZQMpblBclisO",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "UK Policy",
  "timeAwayPolicyVersion": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "bypassWorkingSchedule": false,
    "bypassPublicHolidays": false,
    "publicHolidayCalendarId": "GB",
    "visibleBalances": [
      "endOfYear"
    ],
    "rules": [
      {
        "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
        "limits": {
          "yearlyAllowance": 30,
          "maxCarryOver": 5,
          "yearStart": "01-01",
          "yearStartType": "employmentStartDate",
          "isUnlimited": false,
          "isProrated": false,
          "preventNegativeBalance": false,
          "usage": "upfront",
          "usagePeriod": 12,
          "roundingType": "halfUp"
        }
      }
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all time away policies

Returns a list of time away policies.

Parameters

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/time-away-policies
curl https://app.humaans.io/api/time-away-policies \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "dFCSrX1I3nzOZQMpblBclisO",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "UK Policy",
      "timeAwayPolicyVersion": {
        "id": "smIkoZZ0t4KlXbEka2UC9m7I",
        "bypassWorkingSchedule": false,
        "bypassPublicHolidays": false,
        "publicHolidayCalendarId": "GB",
        "visibleBalances": [
          "endOfYear"
        ],
        "rules": [
          {
            "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
            "limits": {
              "yearlyAllowance": 30,
              "maxCarryOver": 5,
              "yearStart": "01-01",
              "yearStartType": "employmentStartDate",
              "isUnlimited": false,
              "isProrated": false,
              "preventNegativeBalance": false,
              "usage": "upfront",
              "usagePeriod": 12,
              "roundingType": "halfUp"
            }
          }
        ]
      },
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a time away policy

Retrieves the time away policy with the given ID.

Parameters
  • No parameters
Returns

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

GET /api/time-away-policies/:id
curl https://app.humaans.io/api/time-away-policies/dFCSrX1I3nzOZQMpblBclisO \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "dFCSrX1I3nzOZQMpblBclisO",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "UK Policy",
  "timeAwayPolicyVersion": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "bypassWorkingSchedule": false,
    "bypassPublicHolidays": false,
    "publicHolidayCalendarId": "GB",
    "visibleBalances": [
      "endOfYear"
    ],
    "rules": [
      {
        "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
        "limits": {
          "yearlyAllowance": 30,
          "maxCarryOver": 5,
          "yearStart": "01-01",
          "yearStartType": "employmentStartDate",
          "isUnlimited": false,
          "isProrated": false,
          "preventNegativeBalance": false,
          "usage": "upfront",
          "usagePeriod": 12,
          "roundingType": "halfUp"
        }
      }
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a time away policy

Parameters

  • name string required

    The name of the policy.

  • timeAwayPolicyVersion object required

    Time away policy version information

  • timeAwayPolicyVersion.bypassWorkingSchedule boolean

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

  • timeAwayPolicyVersion.bypassPublicHolidays boolean

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

  • timeAwayPolicyVersion.publicHolidayCalendarId string | null

    A specific public holiday calendar id for all employees on this policy. If null, this will default to the employee’s office or remote location.

  • timeAwayPolicyVersion.visibleBalances string[]

    Which balances to show to employees. Available options are endOfYear or today.

  • timeAwayPolicyVersion.rules object[] required

    List of time away types that are available on this policy.

  • timeAwayPolicyVersion.rules.timeAwayTypeId string required

    ID of the time away type that this rule is associated to.

  • timeAwayPolicyVersion.rules.limits object | null required

    If null, balances will not be caluclated for this type but usage numbers will still be available.

  • timeAwayPolicyVersion.rules.limits.yearlyAllowance number required

    The number of paid time off days allowed per year.

  • timeAwayPolicyVersion.rules.limits.maxCarryOver number required

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

  • timeAwayPolicyVersion.rules.limits.yearStart string

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

  • timeAwayPolicyVersion.rules.limits.yearStartType string

    Whether the policy starts on employment start date or a custom date.

  • timeAwayPolicyVersion.rules.limits.isUnlimited boolean required

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

  • timeAwayPolicyVersion.rules.limits.isProrated boolean required

    true means the allowance will be prorated based on FTE.

  • timeAwayPolicyVersion.rules.limits.preventNegativeBalance boolean

    true prevents booking more leave than currently available.

  • timeAwayPolicyVersion.rules.limits.usage string required

    Whether the employee can use PTO days for the year upfront or after they’ve been accrued. One of upfront or accrued.

  • timeAwayPolicyVersion.rules.limits.usagePeriod integer required

    The length of the period in months beginning on yearStart where the employees’ yearly PTO can be used. One of 12, 15, 16, or 18. Defaults to: 12.

  • timeAwayPolicyVersion.rules.limits.roundingType string

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

  • timeAwayPolicyTemplateId string required

Returns

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

POST /api/time-away-policies
curl https://app.humaans.io/api/time-away-policies \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"UK Policy","timeAwayPolicyVersion":{"id":"smIkoZZ0t4KlXbEka2UC9m7I","bypassWorkingSchedule":false,"bypassPublicHolidays":false,"publicHolidayCalendarId":"GB","visibleBalances":["endOfYear"],"rules":[{"timeAwayTypeId":"awM6sG5O2eSBAX2CeVap0MZa","limits":{"yearlyAllowance":30,"maxCarryOver":5,"yearStart":"01-01","yearStartType":"employmentStartDate","isUnlimited":false,"isProrated":false,"preventNegativeBalance":false,"usage":"upfront","usagePeriod":12,"roundingType":"halfUp"}}]}}'
Response
{
  "id": "dFCSrX1I3nzOZQMpblBclisO",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "UK Policy",
  "timeAwayPolicyVersion": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "bypassWorkingSchedule": false,
    "bypassPublicHolidays": false,
    "publicHolidayCalendarId": "GB",
    "visibleBalances": [
      "endOfYear"
    ],
    "rules": [
      {
        "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
        "limits": {
          "yearlyAllowance": 30,
          "maxCarryOver": 5,
          "yearStart": "01-01",
          "yearStartType": "employmentStartDate",
          "isUnlimited": false,
          "isProrated": false,
          "preventNegativeBalance": false,
          "usage": "upfront",
          "usagePeriod": 12,
          "roundingType": "halfUp"
        }
      }
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a time away policy

Parameters

  • name string

    The name of the policy.

  • isArchived boolean

    Whether the policy is archived.

  • timeAwayPolicyVersion object

    Time away policy version information

  • timeAwayPolicyVersion.bypassWorkingSchedule boolean

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

  • timeAwayPolicyVersion.bypassPublicHolidays boolean

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

  • timeAwayPolicyVersion.publicHolidayCalendarId string | null

    A specific public holiday calendar id for all employees on this policy. If null, this will default to the employee’s office or remote location.

  • timeAwayPolicyVersion.visibleBalances string[]

    Which balances to show to employees. Available options are endOfYear or today.

  • timeAwayPolicyVersion.rules object[]

    List of time away types that are available on this policy.

  • timeAwayPolicyVersion.rules.timeAwayTypeId string required

    ID of the time away type that this rule is associated to.

  • timeAwayPolicyVersion.rules.limits object | null required

    If null, balances will not be caluclated for this type but usage numbers will still be available.

  • timeAwayPolicyVersion.rules.limits.yearlyAllowance number required

    The number of paid time off days allowed per year.

  • timeAwayPolicyVersion.rules.limits.maxCarryOver number required

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

  • timeAwayPolicyVersion.rules.limits.yearStart string

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

  • timeAwayPolicyVersion.rules.limits.yearStartType string

    Whether the policy starts on employment start date or a custom date.

  • timeAwayPolicyVersion.rules.limits.isUnlimited boolean required

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

  • timeAwayPolicyVersion.rules.limits.isProrated boolean required

    true means the allowance will be prorated based on FTE.

  • timeAwayPolicyVersion.rules.limits.preventNegativeBalance boolean

    true prevents booking more leave than currently available.

  • timeAwayPolicyVersion.rules.limits.usage string required

    Whether the employee can use PTO days for the year upfront or after they’ve been accrued. One of upfront or accrued.

  • timeAwayPolicyVersion.rules.limits.usagePeriod integer required

    The length of the period in months beginning on yearStart where the employees’ yearly PTO can be used. One of 12, 15, 16, or 18. Defaults to: 12.

  • timeAwayPolicyVersion.rules.limits.roundingType string

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

Returns

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

PATCH /api/time-away-policies/:id
curl https://app.humaans.io/api/time-away-policies/dFCSrX1I3nzOZQMpblBclisO \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'
Response
{
  "id": "dFCSrX1I3nzOZQMpblBclisO",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "UK Policy",
  "timeAwayPolicyVersion": {
    "id": "smIkoZZ0t4KlXbEka2UC9m7I",
    "bypassWorkingSchedule": false,
    "bypassPublicHolidays": false,
    "publicHolidayCalendarId": "GB",
    "visibleBalances": [
      "endOfYear"
    ],
    "rules": [
      {
        "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa",
        "limits": {
          "yearlyAllowance": 30,
          "maxCarryOver": 5,
          "yearStart": "01-01",
          "yearStartType": "employmentStartDate",
          "isUnlimited": false,
          "isProrated": false,
          "preventNegativeBalance": false,
          "usage": "upfront",
          "usagePeriod": 12,
          "roundingType": "halfUp"
        }
      }
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a time away policy

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

Parameters
  • No parameters
Returns

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

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

Time away types

An object representing a time away type. Types are the set of reasons people can book time away for. Examples of types are “Paid time off”, “Sick leave”, “Maternity leave” and so on. Custom types can be created in addition to the standard types provided by Humaans.

Endpoints
   GET /api/time-away-types
   GET /api/time-away-types/:id
  POST /api/time-away-types
 PATCH /api/time-away-types/:id
DELETE /api/time-away-types/:id
Required scopes
public.read
timeAway.read
private.write
settings.write

Time away type object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • name string

    The name of the time away type.

  • emoji string

    An emoji for visualising the time away type.

  • emojiLabel string

    An emoji label for accessibility.

  • category string

    One of workingAway or timeOff.

  • baseType string

    The base type of the time away type. One of pto, sick, workingFromHome, or workingFromAnotherLocation

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

time away type object
{
  "id": "4NJq5i7WwkUgHYzRqkLritrb",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Paid time off",
  "emoji": "🏝",
  "emojiLabel": "Beach",
  "category": "timeOff",
  "baseType": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all time away types

Returns a list of time away types.

Parameters

  • id string | $in

    The ID of the time away type.

  • $or object[]

    Filter results by multiple criteria.

  • $or.id string | $in

    The ID of the time away type.

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/time-away-types
curl https://app.humaans.io/api/time-away-types \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "4NJq5i7WwkUgHYzRqkLritrb",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "name": "Paid time off",
      "emoji": "🏝",
      "emojiLabel": "Beach",
      "category": "timeOff",
      "baseType": null,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a time away type

Retrieves the time away type with the given ID.

Parameters
  • No parameters
Returns

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

GET /api/time-away-types/:id
curl https://app.humaans.io/api/time-away-types/4NJq5i7WwkUgHYzRqkLritrb \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "4NJq5i7WwkUgHYzRqkLritrb",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Paid time off",
  "emoji": "🏝",
  "emojiLabel": "Beach",
  "category": "timeOff",
  "baseType": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a time away type

Parameters

  • name string required

    The name of the time away type.

  • emoji string required

    An emoji for visualising the time away type.

  • category string required

    One of workingAway or timeOff.

Returns

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

POST /api/time-away-types
curl https://app.humaans.io/api/time-away-types \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"Paid time off","emoji":"🏝","category":"timeOff"}'
Response
{
  "id": "4NJq5i7WwkUgHYzRqkLritrb",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Paid time off",
  "emoji": "🏝",
  "emojiLabel": "Beach",
  "category": "timeOff",
  "baseType": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a time away type

Parameters

  • name string

    The name of the time away type.

  • emoji string

    An emoji for visualising the time away type.

Returns

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

PATCH /api/time-away-types/:id
curl https://app.humaans.io/api/time-away-types/4NJq5i7WwkUgHYzRqkLritrb \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'
Response
{
  "id": "4NJq5i7WwkUgHYzRqkLritrb",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "name": "Paid time off",
  "emoji": "🏝",
  "emojiLabel": "Beach",
  "category": "timeOff",
  "baseType": null,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a time away type

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

Parameters
  • No parameters
Returns

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

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

Timesheet entries

An object representing a timesheet entry of an employee

Endpoints
   GET /api/timesheet-entries
   GET /api/timesheet-entries/:id
  POST /api/timesheet-entries
 PATCH /api/timesheet-entries/:id
DELETE /api/timesheet-entries/:id
Required scopes
private.read
timesheets.read
private.write
timesheets.write

Timesheet entry object

Attributes

  • id string

    Unique identifier for the object.

  • personId string

    ID of the person that this object is associated to.

  • date string, date

    The date of this timesheet entry.

  • startTime string

    The start time of this timesheet entry.

  • endTime string

    The end time of this timesheet entry.

  • duration object

    The duration of this timesheet entry.

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

timesheet entry object
{
  "id": "0vUGk85FkSDHXfeOTnXqkk4d",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "date": "2020-04-01",
  "startTime": "09:00:00",
  "endTime": "12:30:00",
  "duration": {
    "hours": 3,
    "minutes": 30
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all timesheet entries

Returns a list of timesheet entries.

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

Parameters

  • personId string

    The person to filter queries by.

  • date string | object

    The date of this timesheet entry.

  • date.$gt string, date

  • date.$gte string, date

  • date.$lt string, date

  • date.$lte string, date

  • endTime string | empty

    The end time of this timesheet entry.

  • id object

    The ID of an existing timesheet entry.

  • id.$in string[]

    An array of IDs of existing timesheet entries.

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/timesheet-entries
curl https://app.humaans.io/api/timesheet-entries \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "0vUGk85FkSDHXfeOTnXqkk4d",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "date": "2020-04-01",
      "startTime": "09:00:00",
      "endTime": "12:30:00",
      "duration": {
        "hours": 3,
        "minutes": 30
      },
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a timesheet entry

Retrieves the timesheet entry with the given ID.

Parameters
  • No parameters
Returns

Returns a timesheet entry object if a valid identifier was provided.

GET /api/timesheet-entries/:id
curl https://app.humaans.io/api/timesheet-entries/0vUGk85FkSDHXfeOTnXqkk4d \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "0vUGk85FkSDHXfeOTnXqkk4d",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "date": "2020-04-01",
  "startTime": "09:00:00",
  "endTime": "12:30:00",
  "duration": {
    "hours": 3,
    "minutes": 30
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a timesheet entry

Parameters

  • personId string required

    ID of the person that this object is associated to.

  • date string, date required

    The date of this timesheet entry.

  • startTime string required

    The start time of this timesheet entry.

  • endTime string

    The end time of this timesheet entry.

Returns

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

POST /api/timesheet-entries
curl https://app.humaans.io/api/timesheet-entries \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","date":"2020-04-01","startTime":"09:00:00"}'
Response
{
  "id": "0vUGk85FkSDHXfeOTnXqkk4d",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "date": "2020-04-01",
  "startTime": "09:00:00",
  "endTime": "12:30:00",
  "duration": {
    "hours": 3,
    "minutes": 30
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a timesheet entry

Parameters

  • date string, date

    The date of this timesheet entry.

  • startTime string

    The start time of this timesheet entry.

  • endTime string

    The end time of this timesheet entry.

Returns

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

PATCH /api/timesheet-entries/:id
curl https://app.humaans.io/api/timesheet-entries/0vUGk85FkSDHXfeOTnXqkk4d \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'
Response
{
  "id": "0vUGk85FkSDHXfeOTnXqkk4d",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "date": "2020-04-01",
  "startTime": "09:00:00",
  "endTime": "12:30:00",
  "duration": {
    "hours": 3,
    "minutes": 30
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a timesheet entry

Permanently deletes a timesheet entry. It cannot be undone.

Parameters
  • No parameters
Returns

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

DELETE /api/timesheet-entries/:id
curl https://app.humaans.io/api/timesheet-entries/0vUGk85FkSDHXfeOTnXqkk4d \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -X DELETE
Response
{
  "id": "0vUGk85FkSDHXfeOTnXqkk4d",
  "deleted": true
}

Timesheet submissions

An object representing a timesheet submission of an employee

Endpoints
   GET /api/timesheet-submissions
   GET /api/timesheet-submissions/:id
  POST /api/timesheet-submissions
 PATCH /api/timesheet-submissions/:id
DELETE /api/timesheet-submissions/:id
Required scopes
private.read
timesheets.read
private.write
timesheets.write

Timesheet submission object

Attributes

  • id string

    Unique identifier for the object.

  • personId string

    ID of the person that this object is associated to.

  • startDate string, date

    The start date of the month which this submission covers.

  • endDate string, date

    The end date of the month which this submission covers.

  • status string

    One of pending, approved, rejected.

  • submittedAt string, date-time

    The date and time when this submission was last submitted.

  • reviewedBy string

    The ID of the person that reviewed this submission.

  • reviewedAt string, date-time

    The date and time when this submission was reviewed.

  • changesRequested string

    Changes requested to accompany a rejected submission.

  • durationAsTime object

    The total time attached to this submission.

  • durationAsDays number

    The total days attached to this submission.

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

timesheet submission object
{
  "id": "Qh1bcl6baOIFPBgJjM0I9wNB",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startDate": "2020-04-01",
  "endDate": "2020-04-30",
  "status": "pending",
  "submittedAt": "2020-04-30T17:08:29.290Z",
  "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedAt": "2020-04-30T17:08:29.290Z",
  "changesRequested": "Missing hours from weekend shift.",
  "durationAsTime": {
    "hours": 127,
    "minutes": 30
  },
  "durationAsDays": 23,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all timesheet submissions

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

Parameters

  • personId string

    The person to filter queries by.

  • startDate string

    The start date of the month which this submission covers.

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

Returns a list of timesheet submissions.

GET /api/timesheet-submissions
curl https://app.humaans.io/api/timesheet-submissions \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "Qh1bcl6baOIFPBgJjM0I9wNB",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "startDate": "2020-04-01",
      "endDate": "2020-04-30",
      "status": "pending",
      "submittedAt": "2020-04-30T17:08:29.290Z",
      "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
      "reviewedAt": "2020-04-30T17:08:29.290Z",
      "changesRequested": "Missing hours from weekend shift.",
      "durationAsTime": {
        "hours": 127,
        "minutes": 30
      },
      "durationAsDays": 23,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a timesheet submission

Retrieves the timesheet submission with the given ID.

Parameters
  • No parameters
Returns

Returns a timesheet submission object if a valid identifier was provided.

GET /api/timesheet-submissions/:id
curl https://app.humaans.io/api/timesheet-submissions/Qh1bcl6baOIFPBgJjM0I9wNB \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "Qh1bcl6baOIFPBgJjM0I9wNB",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startDate": "2020-04-01",
  "endDate": "2020-04-30",
  "status": "pending",
  "submittedAt": "2020-04-30T17:08:29.290Z",
  "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedAt": "2020-04-30T17:08:29.290Z",
  "changesRequested": "Missing hours from weekend shift.",
  "durationAsTime": {
    "hours": 127,
    "minutes": 30
  },
  "durationAsDays": 23,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a timesheet submission

Parameters

  • personId string required

    ID of the person that this object is associated to.

  • startDate string, date required

    The start date of the month which this submission covers.

Returns

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

POST /api/timesheet-submissions
curl https://app.humaans.io/api/timesheet-submissions \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","startDate":"2020-04-01"}'
Response
{
  "id": "Qh1bcl6baOIFPBgJjM0I9wNB",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startDate": "2020-04-01",
  "endDate": "2020-04-30",
  "status": "pending",
  "submittedAt": "2020-04-30T17:08:29.290Z",
  "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedAt": "2020-04-30T17:08:29.290Z",
  "changesRequested": "Missing hours from weekend shift.",
  "durationAsTime": {
    "hours": 127,
    "minutes": 30
  },
  "durationAsDays": 23,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a timesheet submission

Parameters

  • status string required

    One of pending, approved, rejected.

  • changesRequested string

    Changes requested to accompany a rejected submission.

Returns

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

PATCH /api/timesheet-submissions/:id
curl https://app.humaans.io/api/timesheet-submissions/Qh1bcl6baOIFPBgJjM0I9wNB \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"status":"pending"}'
Response
{
  "id": "Qh1bcl6baOIFPBgJjM0I9wNB",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "startDate": "2020-04-01",
  "endDate": "2020-04-30",
  "status": "pending",
  "submittedAt": "2020-04-30T17:08:29.290Z",
  "reviewedBy": "ob4xPcVpGGZm043C7xGMfP1U",
  "reviewedAt": "2020-04-30T17:08:29.290Z",
  "changesRequested": "Missing hours from weekend shift.",
  "durationAsTime": {
    "hours": 127,
    "minutes": 30
  },
  "durationAsDays": 23,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a timesheet submission

Permanently deletes a timesheet submission. It cannot be undone.

Parameters
  • No parameters
Returns

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

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

Token info

An object containing the scoped permissions of the current access token.

Endpoints
GET /api/token-info
Required scopes

Token info object

Attributes

  • scopes string[]

token-info object
{
  "scopes": "['public:read', 'documents:read']"
}

Retrieve my token info

Retrieves the currently used token scopes.

Parameters
  • No parameters
Returns

Returns the current tokens` scopes.

GET /api/token-info
curl https://app.humaans.io/api/token-info/undefined \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "scopes": "['public:read', 'documents:read']"
}

Webhook events

An object representing an action triggered by a person, integration, the system or support.

Webhook event object

Attributes

  • id

    The unique ID of the event

  • seq

    A sortable sequence string

  • ts

    The date time the event was created

  • action

    The action type of the event sent. One of timeAway.created, timeAway.updated, timeAway.deleted, timeAway.approved, timeAway.rejected, timeAwayAdjustment.created, timeAwayAdjustment.updated, timeAwayAdjustment.deleted, person.created, person.updated, person.offboarded, person.reonboarded, person.deleted, bankAccount.created, bankAccount.updated, bankAccount.deleted, jobRole.created, jobRole.updated, jobRole.deleted, compensation.created, compensation.updated, compensation.deleted, emergencyContact.created, emergencyContact.updated, emergencyContact.deleted, equipment.created, equipment.updated, equipment.deleted.

  • subject

    The affected participant of the event

  • actor

    The affecting participant of the event, may be an integration

  • entity

    The information that has been changed in the event

  • entity.id

    The ID if the affected entity

  • entity.fieldsChanged

    A list of all the fields changed, including the ids of any custom fields

  • entity.next

    Any newly set information, will be null if unset in action

  • entity.prev

    Any previously set information, will be null if set in action

  • entity.customFields

    Any changed custom fields are listed here

  • entity.metadata

    This is used to store additional information on the entity that may be useful, for example in the case of a compensation update it will contain the type of compensation that’s being updated

webhook event object
{
    "id": "qCNHkhApepOJf0eFHuPzQbDg",
    "seq": "01J4GSN4XYQ7401FXCYQPWH3V7",
    "ts": "2024-08-05T08:14:24.190Z",
    "action": "emergencyContact.created",
    "subject": {
      "id": "8Rc7dFxm7OFoiwxVBIFrLRAi",
      "type": "person"
    },
    "actor": {
      "personId": "8Rc7dFxm7OFoiwxVBIFrLRAi",
      "type": "person"
    },
    "entity": {
      "id": "OCPMqZtTcgFOuoc56TiKo9OT",
      "fieldsChanged": [
        "8Yzi4vi9SI43R5ubSAQOae5q",
        "name",
        "email",
        "isPrimary",
        "phoneNumber",
        "relationship"
      ],
      "next": {
        "email": "jd@humaans.io",
        "isPrimary": false,
        "name": "jane",
        "phoneNumber": "0123412345",
        "relationship": "doe"
      },
      "prev": {
        "email": null,
        "isPrimary": null,
        "name": null,
        "phoneNumber": null,
        "relationship": null
      },
      "customFields": [
        {
          "customFieldId": "8Yzi4vi9SI43R5ubSAQOae5q",
          "next": "[\"+447979512293\"]",
          "prev": null
        }
      ],
      "metadata": {}
    }
  }

Webhooks

An object representing a webhook and it’s configuration. If a webhook is created or patched with status equal to active then prodEndpointUrl and subscribedEvents become mandatory properties.

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

Webhook object

Attributes

  • id string

    Unique identifier for the object.

  • name string

    A short name for the webhook.

  • description string

    A longer description for the webhook.

  • prodEndpointUrl string

    The endpoint that will receive webhook events.

  • prodEndpointSignature string

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

  • subscribedEvents string[]

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

  • status string

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

  • createdBy string

    The person who first created the webhook.

  • publishedBy string

    The person who last published the webhook.

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

webhook object
{
  "id": "2ehafnPohpOY49mlQx0i3SHL",
  "name": "Payroll integration",
  "description": "Integrates Humaans with the PayrollX system",
  "prodEndpointUrl": "https://myco.io/api/webhook/humaans",
  "prodEndpointSignature": "whsec_FZXyzQwEgwnENgbRDtLjBdoHcd",
  "subscribedEvents": [
    "person.created",
    "person.updated",
    "person.removed"
  ],
  "status": "active",
  "createdBy": "C6WWf6y0z7VEWlNWaSxUMntV",
  "publishedBy": "C6WWf6y0z7VEWlNWaSxUMntV",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all webhooks

Returns a list of webhooks.

Parameters

  • $limit number

    Limit number of results.

  • $skip number

    Skip the specified number of results.

Returns

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

GET /api/webhooks
curl https://app.humaans.io/api/webhooks \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "2ehafnPohpOY49mlQx0i3SHL",
      "name": "Payroll integration",
      "description": "Integrates Humaans with the PayrollX system",
      "prodEndpointUrl": "https://myco.io/api/webhook/humaans",
      "prodEndpointSignature": "whsec_FZXyzQwEgwnENgbRDtLjBdoHcd",
      "subscribedEvents": [
        "person.created",
        "person.updated",
        "person.removed"
      ],
      "status": "active",
      "createdBy": "C6WWf6y0z7VEWlNWaSxUMntV",
      "publishedBy": "C6WWf6y0z7VEWlNWaSxUMntV",
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a webhook

Retrieves the webhook with the given ID.

Parameters
  • No parameters
Returns

Returns a webhook object if a valid identifier was provided.

GET /api/webhooks/:id
curl https://app.humaans.io/api/webhooks/2ehafnPohpOY49mlQx0i3SHL \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "2ehafnPohpOY49mlQx0i3SHL",
  "name": "Payroll integration",
  "description": "Integrates Humaans with the PayrollX system",
  "prodEndpointUrl": "https://myco.io/api/webhook/humaans",
  "prodEndpointSignature": "whsec_FZXyzQwEgwnENgbRDtLjBdoHcd",
  "subscribedEvents": [
    "person.created",
    "person.updated",
    "person.removed"
  ],
  "status": "active",
  "createdBy": "C6WWf6y0z7VEWlNWaSxUMntV",
  "publishedBy": "C6WWf6y0z7VEWlNWaSxUMntV",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a webhook

Parameters

  • name string required

    A short name for the webhook.

  • description string | null

    A longer description for the webhook.

  • prodEndpointUrl string | null

    The endpoint that will receive webhook events.

  • subscribedEvents string[]

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

  • status string

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

Returns

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

POST /api/webhooks
curl https://app.humaans.io/api/webhooks \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"name":"Payroll integration"}'
Response
{
  "id": "2ehafnPohpOY49mlQx0i3SHL",
  "name": "Payroll integration",
  "description": "Integrates Humaans with the PayrollX system",
  "prodEndpointUrl": "https://myco.io/api/webhook/humaans",
  "prodEndpointSignature": "whsec_FZXyzQwEgwnENgbRDtLjBdoHcd",
  "subscribedEvents": [
    "person.created",
    "person.updated",
    "person.removed"
  ],
  "status": "active",
  "createdBy": "C6WWf6y0z7VEWlNWaSxUMntV",
  "publishedBy": "C6WWf6y0z7VEWlNWaSxUMntV",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a webhook

Parameters

  • name string

    A short name for the webhook.

  • description string | null

    A longer description for the webhook.

  • status string

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

  • subscribedEvents string[]

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

  • prodEndpointUrl string | null

    The endpoint that will receive webhook events.

Returns

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

PATCH /api/webhooks/:id
curl https://app.humaans.io/api/webhooks/2ehafnPohpOY49mlQx0i3SHL \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{}'
Response
{
  "id": "2ehafnPohpOY49mlQx0i3SHL",
  "name": "Payroll integration",
  "description": "Integrates Humaans with the PayrollX system",
  "prodEndpointUrl": "https://myco.io/api/webhook/humaans",
  "prodEndpointSignature": "whsec_FZXyzQwEgwnENgbRDtLjBdoHcd",
  "subscribedEvents": [
    "person.created",
    "person.updated",
    "person.removed"
  ],
  "status": "active",
  "createdBy": "C6WWf6y0z7VEWlNWaSxUMntV",
  "publishedBy": "C6WWf6y0z7VEWlNWaSxUMntV",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a webhook

Permanently deletes a webhook. It cannot be undone.

Parameters
  • No parameters
Returns

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

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

Workflow dependencies

A dependency between two workflow tasks. When task A depends on task B, task A is blocked until task B is completed.

Endpoints
Required scopes
workflows.read
workflows.write

Workflow dependencie object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • workflowId string

  • workflowInstanceId string

  • workflowPublicationId string

  • dependentTaskId string

  • dependentActionId string

  • dependsOnTaskId string

  • dependsOnActionId string

  • externalServiceType string

  • externalResourceId string

  • externalExpectedStatus string

  • isSatisfied boolean

  • satisfiedAt string, date-time

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

workflow dependencie object
{
  "id": "NQqtC1vuRzoaSfCcrINmypfR",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Workflow form responses

A submitted response to a workflow form. Contains the field values filled in by the assignee or an external respondent.

Endpoints
Required scopes
workflows.read

Workflow form response object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • workflowId string

  • values object[]

  • values.fieldId string

  • values.value string | array | boolean | null | id | filename | url | fileId | type | number | expiryDate | countryCode | note | url | redacted

  • syncStatus object

  • syncStatus.result string

  • syncStatus.completedAt string

  • syncStatus.attemptedAt string

  • syncStatus.error object

  • syncStatus.error.code number

  • syncStatus.error.name string

  • syncStatus.error.message string

  • syncStatus.error.issues object[]

  • syncStatus.error.issues.name string

  • syncStatus.error.issues.reason string

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

workflow form response object
{
  "id": "ykvvjHFY5IjSwxPnonyvmmX9",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "values": [
    {}
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Workflow publications

A published snapshot of a workflow. When a workflow is published, its current tasks and configuration are frozen into a publication that new instances are created from.

Endpoints
Required scopes
workflows.read
workflows.write

Workflow publication object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • workflowId string

  • trigger object

  • trigger.mode

  • trigger.mode string

  • trigger.filters undefined[]

    Applicable when mode is onboarding, offboarding, date, or timeAway.

  • trigger.schedule object

    Applicable when mode is date.

  • trigger.schedule.scheduleMode string

  • trigger.schedule.value string, date

  • trigger.schedule.time object

  • trigger.schedule.time.hour number

  • trigger.schedule.time.minute number

  • trigger.schedule.month number

  • trigger.schedule.day number

  • trigger.schedule.anchor string

  • trigger.schedule.offset string

  • trigger.schedule.yearsThreshold number

  • trigger.timeAwayTypeIds string[]

    Applicable when mode is timeAway.

  • trigger.timing string

    Applicable when mode is timeAway.

  • trigger.offset string

    Applicable when mode is timeAway.

  • trigger.threshold object

    Applicable when mode is timeAway.

  • trigger.threshold.value number

  • trigger.threshold.unit string

  • contentHash string

  • publishedAt string, date-time

  • isLive boolean

  • createdAt string, date-time

    Time at which the object was created.

workflow publication object
{
  "id": "mWvppt9QBncBonVW3xI69HM1",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "trigger": {},
  "createdAt": "2020-01-28T08:44:42.000Z"
}

Workflow slack actions

A Slack notification action within a workflow. Configures which Slack channel or user receives a message when the workflow reaches this step.

Endpoints
Required scopes
workflows.read
workflows.write

Workflow slack action object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • workflowSlackActionPrototypeId string

  • workflowId string

  • workflowInstanceId string

  • workflowPublicationId string

  • workflowActionId string

  • body object

  • slackWebhookUrl string

  • slackChannelName string

  • slackChannelId string

  • recipientType string

  • personRecipient object

  • personRecipient.type string

  • personRecipient.personId string

  • personRecipient.customFieldId string

  • recipient object

  • recipient.type string

  • recipient.slackChannelId string

  • recipient.slackChannelName string

  • recipient.slackWebhookUrl string

  • recipient.personId string

  • recipient.customFieldId string

  • sentAt string

  • trigger object

  • trigger.mode string

  • trigger.value string

  • trigger.anchor string

  • trigger.time string

  • triggerDate string, date

  • sendAt string

  • resolvedTriggerTime string

  • status string

  • contentEditedAt string

  • cancelledAt string, date-time

  • cancelledBy string

  • resolvedMessageBody string

  • missingValues string[]

  • blockedBy object[]

  • blockedBy.type string

  • blockedBy.id string

  • blockedBy.title string

  • isCancelled boolean

  • triggerSlackMessageNow boolean

  • hasError boolean

  • isCompleted boolean

  • createdAt string, date-time

    Time at which the object was created.

  • updatedAt string, date-time

    Time at which the object was last updated.

  • deletedAt string

workflow slack action object
{
  "id": "6ykQBJtGHNB9GaebjqVAZLe6",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "body": {},
  "personRecipient": {},
  "recipient": {},
  "trigger": {},
  "blockedBy": [
    {}
  ],
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Workflow stats

Read-only aggregate statistics for a workflow, including total instances, completion rates, and average time to complete.

Endpoints
Required scopes
workflows.read

Workflow stat object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • workflowId string

  • mode string

  • currentIncompleteTasks number

    The number of incomplete tasks for the workflowId as per the current date

workflow stat object
{
  "id": "yZyRz4TxoZ4tC06uFVZL2Fk3",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "workflowId": ""
}

Working pattern allocations

An object representing the assignment of a working pattern to an employee.

To assign a working pattern to an employee, create an allocation linking a person (personId) to either:

  • An existing company-wide working pattern via workingPatternId
  • A custom inline working pattern via the workingPattern object

Each employee typically has one allocation, but can have multiple with different effectiveDate values to track changes over time (e.g. when moving to part-time or changing offices with different schedules). The allocation with the most recent effectiveDate that is not in the future is considered currently active.

Endpoints
   GET /api/working-pattern-allocations
   GET /api/working-pattern-allocations/:id
  POST /api/working-pattern-allocations
 PATCH /api/working-pattern-allocations/:id
DELETE /api/working-pattern-allocations/:id
Required scopes
employment.read
private.read
public.read
employment.write
private.write

Working pattern allocation object

Attributes

  • id string

    Unique identifier for the object.

  • personId string

    The ID of the person this working pattern allocation is for.

  • workingPatternId string

    The ID of the working pattern being assigned. Must reference a company-wide working pattern (where personId is null). Either workingPatternId or workingPattern must be provided when creating an allocation.

  • effectiveDate string, date

    The date from which this working pattern allocation takes effect. If null, the allocation is effective from the employee’s start date. When multiple allocations exist, the most recent effective date determines the current working pattern.

  • effectiveEndDate string, date

    The date to which this working pattern allocation takes effect.

  • workingPattern object

    The full working pattern object associated with this allocation. When creating an allocation, you can provide an inline workingPattern object instead of a workingPatternId to create a custom pattern specific to this person.

  • workingPattern.id string

    Unique identifier for the object.

  • workingPattern.companyId string

    ID of the company that this object is associated to.

  • workingPattern.personId string

    The ID of the person this working pattern is created for. Only set for individual custom working patterns. When null, the working pattern is a company-wide template that can be assigned to any employee.

  • workingPattern.name string

    The name of the working pattern.

  • workingPattern.summary string

    A summary describing the working pattern schedule.

  • workingPattern.fullTimeHours number

    The number of hours that constitute full-time work over the specified periodType. Used as the reference for calculating the FTE (Full Time Equivalent).

  • workingPattern.standardDayHours number

    The standard number of working hours per day. Used for calculating time away allowances and working days.

  • workingPattern.periodType string

    The time period over which fullTimeHours and workingHours are measured. One of week, day, or month.

  • workingPattern.workingHours number

    The total hours the employee is expected to work over the period. For fixed-hours patterns, this is calculated from the workingPattern array. For flexible patterns (where workingPattern contains booleans), this specifies the total hours to be distributed across working days.

  • workingPattern.workingPattern undefined[]

    The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either:

    • An array of numbers representing hours worked per day (e.g. [8,8,8,8,8,0,0] for Mon-Fri 8h)
    • An array of booleans for flexible patterns where true indicates a working day (e.g. [true,true,true,true,true,false,false] for Mon-Fri flexible)

  • workingPattern.fte number

    The Full Time Equivalent, calculated as workingHours / fullTimeHours. Rounded to 4 decimal places. A value of 1.0 represents full-time work.

  • workingPattern.unroundedFte number

    The exact Full Time Equivalent before rounding. Useful for precise calculations.

  • workingPattern.createdAt string, date-time

    Timestamp when the working pattern was created.

  • workingPattern.updatedAt string, date-time

    Timestamp when the working pattern was last updated.

  • createdAt string, date-time

    Timestamp when the allocation was created.

  • updatedAt string, date-time

    Timestamp when the allocation was last updated.

working pattern allocation object
{
  "id": "wiyjmFuX79AGNiROhmIJFxHC",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "workingPatternId": "xzZJYmdPHDFSxfpWaamgVR7U",
  "effectiveDate": "2020-04-01",
  "effectiveEndDate": "2020-04-01",
  "workingPattern": {
    "fullTimeHours": 40,
    "standardDayHours": 8,
    "workingPattern": [
      8,
      8,
      8,
      8,
      8,
      0,
      0
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all working pattern allocations

Returns a list of working pattern allocations.

Parameters

  • personId string | $in | $nin

    Filter by people ids

  • $asOf string, date

    Filter the list of working pattern allocations to the current one per employee in effect at 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 working pattern 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 working pattern allocation object. If no working pattern allocations are available, the resulting list will be empty. This request should never return an error.

GET /api/working-pattern-allocations
curl https://app.humaans.io/api/working-pattern-allocations \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "wiyjmFuX79AGNiROhmIJFxHC",
      "personId": "IL3vneCYhIx0xrR6um2sy2nW",
      "workingPatternId": "xzZJYmdPHDFSxfpWaamgVR7U",
      "effectiveDate": "2020-04-01",
      "effectiveEndDate": "2020-04-01",
      "workingPattern": {
        "fullTimeHours": 40,
        "standardDayHours": 8,
        "workingPattern": [
          8,
          8,
          8,
          8,
          8,
          0,
          0
        ]
      },
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a working pattern allocation

Retrieves the working pattern allocation with the given ID.

Parameters
  • No parameters
Returns

Returns a working pattern allocation object if a valid identifier was provided.

GET /api/working-pattern-allocations/:id
curl https://app.humaans.io/api/working-pattern-allocations/wiyjmFuX79AGNiROhmIJFxHC \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "wiyjmFuX79AGNiROhmIJFxHC",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "workingPatternId": "xzZJYmdPHDFSxfpWaamgVR7U",
  "effectiveDate": "2020-04-01",
  "effectiveEndDate": "2020-04-01",
  "workingPattern": {
    "fullTimeHours": 40,
    "standardDayHours": 8,
    "workingPattern": [
      8,
      8,
      8,
      8,
      8,
      0,
      0
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a working pattern allocation

Parameters

  • personId string

    The ID of the person this working pattern allocation is for.

  • effectiveDate string, date | null

    The date from which this working pattern allocation takes effect. If null, the allocation is effective from the employee’s start date. When multiple allocations exist, the most recent effective date determines the current working pattern.

  • workingPatternId string

    The ID of the working pattern being assigned. Must reference a company-wide working pattern (where personId is null). Either workingPatternId or workingPattern must be provided when creating an allocation.

  • workingPattern object

    The full working pattern object associated with this allocation. When creating an allocation, you can provide an inline workingPattern object instead of a workingPatternId to create a custom pattern specific to this person.

  • workingPattern.name string

    The name of the working pattern.

  • workingPattern.fullTimeHours number required

    The number of hours that constitute full-time work over the specified periodType. Used as the reference for calculating the FTE (Full Time Equivalent).

  • workingPattern.standardDayHours number required

    The standard number of working hours per day. Used for calculating time away allowances and working days.

  • workingPattern.periodType string

    The time period over which fullTimeHours and workingHours are measured. One of week, day, or month.

  • workingPattern.workingHours number

    The total hours the employee is expected to work over the period. For fixed-hours patterns, this is calculated from the workingPattern array. For flexible patterns (where workingPattern contains booleans), this specifies the total hours to be distributed across working days.

  • workingPattern.workingPattern undefined[] required

    The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either:

    • An array of numbers representing hours worked per day (e.g. [8,8,8,8,8,0,0] for Mon-Fri 8h)
    • An array of booleans for flexible patterns where true indicates a working day (e.g. [true,true,true,true,true,false,false] for Mon-Fri flexible)

  • workingPattern.personId string | null

    The ID of the person this working pattern is created for. Only set for individual custom working patterns. When null, the working pattern is a company-wide template that can be assigned to any employee.

Returns

Returns a working pattern allocation if the call succeeded. The call returns an error if parameters are invalid.

POST /api/working-pattern-allocations
curl https://app.humaans.io/api/working-pattern-allocations \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW","workingPatternId":"xzZJYmdPHDFSxfpWaamgVR7U","effectiveDate":"2024-01-01"}'
Response
{
  "id": "wiyjmFuX79AGNiROhmIJFxHC",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "workingPatternId": "xzZJYmdPHDFSxfpWaamgVR7U",
  "effectiveDate": "2024-01-01",
  "effectiveEndDate": "2020-04-01",
  "workingPattern": {
    "fullTimeHours": 40,
    "standardDayHours": 8,
    "workingPattern": [
      8,
      8,
      8,
      8,
      8,
      0,
      0
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a working pattern allocation

Parameters

  • id string

    Unique identifier for the object.

  • workingPatternId string

    The ID of the working pattern being assigned. Must reference a company-wide working pattern (where personId is null). Either workingPatternId or workingPattern must be provided when creating an allocation.

  • effectiveDate string, date | null

    The date from which this working pattern allocation takes effect. If null, the allocation is effective from the employee’s start date. When multiple allocations exist, the most recent effective date determines the current working pattern.

  • workingPattern object

    The full working pattern object associated with this allocation. When creating an allocation, you can provide an inline workingPattern object instead of a workingPatternId to create a custom pattern specific to this person.

  • workingPattern.name string

    The name of the working pattern.

  • workingPattern.fullTimeHours number required

    The number of hours that constitute full-time work over the specified periodType. Used as the reference for calculating the FTE (Full Time Equivalent).

  • workingPattern.standardDayHours number required

    The standard number of working hours per day. Used for calculating time away allowances and working days.

  • workingPattern.periodType string

    The time period over which fullTimeHours and workingHours are measured. One of week, day, or month.

  • workingPattern.workingHours number

    The total hours the employee is expected to work over the period. For fixed-hours patterns, this is calculated from the workingPattern array. For flexible patterns (where workingPattern contains booleans), this specifies the total hours to be distributed across working days.

  • workingPattern.workingPattern undefined[] required

    The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either:

    • An array of numbers representing hours worked per day (e.g. [8,8,8,8,8,0,0] for Mon-Fri 8h)
    • An array of booleans for flexible patterns where true indicates a working day (e.g. [true,true,true,true,true,false,false] for Mon-Fri flexible)

  • workingPattern.personId string | null

    The ID of the person this working pattern is created for. Only set for individual custom working patterns. When null, the working pattern is a company-wide template that can be assigned to any employee.

Returns

Returns the working pattern allocation if the update succeeded. The call returns an error if parameters are invalid.

PATCH /api/working-pattern-allocations/:id
curl https://app.humaans.io/api/working-pattern-allocations/wiyjmFuX79AGNiROhmIJFxHC \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"effectiveDate":"2024-06-01"}'
Response
{
  "id": "wiyjmFuX79AGNiROhmIJFxHC",
  "personId": "IL3vneCYhIx0xrR6um2sy2nW",
  "workingPatternId": "xzZJYmdPHDFSxfpWaamgVR7U",
  "effectiveDate": "2024-06-01",
  "effectiveEndDate": "2020-04-01",
  "workingPattern": {
    "fullTimeHours": 40,
    "standardDayHours": 8,
    "workingPattern": [
      8,
      8,
      8,
      8,
      8,
      0,
      0
    ]
  },
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a working pattern allocation

Permanently deletes a working pattern allocation. It cannot be undone.

Parameters
  • No parameters
Returns

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

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

Working patterns

A working pattern defines the schedule and hours an employee works. Working patterns can be company-wide templates (where personId is null) or custom patterns created for specific individuals.

Each pattern specifies the fullTimeHours (reference for FTE calculation), standardDayHours, and the actual workingPattern array which can be either:

  • Fixed hours: an array of numbers representing hours per day (e.g. [8,8,8,8,8,0,0] for Mon-Fri)
  • Flexible: an array of booleans indicating working days, with workingHours specifying total hours

To assign a working pattern to an employee, use the Working Pattern Allocations API.

Endpoints
   GET /api/working-patterns
   GET /api/working-patterns/:id
  POST /api/working-patterns
 PATCH /api/working-patterns/:id
DELETE /api/working-patterns/:id
Required scopes
employment.read
private.read
public.read
private.write
settings.write

Working pattern object

Attributes

  • id string

    Unique identifier for the object.

  • companyId string

    ID of the company that this object is associated to.

  • personId string

    The ID of the person this working pattern is created for. Only set for individual custom working patterns. When null, the working pattern is a company-wide template that can be assigned to any employee.

  • name string

    The name of the working pattern.

  • summary string

    A summary describing the working pattern schedule.

  • fullTimeHours number

    The number of hours that constitute full-time work over the specified periodType. Used as the reference for calculating the FTE (Full Time Equivalent).

  • standardDayHours number

    The standard number of working hours per day. Used for calculating time away allowances and working days.

  • periodType string

    The time period over which fullTimeHours and workingHours are measured. One of week, day, or month.

  • workingHours number

    The total hours the employee is expected to work over the period. For fixed-hours patterns, this is calculated from the workingPattern array. For flexible patterns (where workingPattern contains booleans), this specifies the total hours to be distributed across working days.

  • workingPattern undefined[]

    The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either:

    • An array of numbers representing hours worked per day (e.g. [8,8,8,8,8,0,0] for Mon-Fri 8h)
    • An array of booleans for flexible patterns where true indicates a working day (e.g. [true,true,true,true,true,false,false] for Mon-Fri flexible)

  • fte number

    The Full Time Equivalent, calculated as workingHours / fullTimeHours. Rounded to 4 decimal places. A value of 1.0 represents full-time work.

  • unroundedFte number

    The exact Full Time Equivalent before rounding. Useful for precise calculations.

  • createdAt string, date-time

    Timestamp when the working pattern was created.

  • updatedAt string, date-time

    Timestamp when the working pattern was last updated.

working pattern object
{
  "id": "MLYRjj1YdpuQp5Qe6HQsvUys",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "personId": null,
  "name": "Mon-Fri 8h/day",
  "summary": "Mon-Fri (8h)",
  "fullTimeHours": 40,
  "standardDayHours": 8,
  "periodType": "week",
  "workingHours": 40,
  "workingPattern": [
    8,
    8,
    8,
    8,
    8,
    0,
    0
  ],
  "fte": 1,
  "unroundedFte": 1,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

List all working patterns

Returns a list of working patterns.

Parameters

  • companyId string | empty

  • personId | $ne

    The ID of the person this working pattern is created for. Only set for individual custom working patterns. When null, the working pattern is a company-wide template that can be assigned to any employee.

  • $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 working patterns. 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 working pattern object. If no working patterns are available, the resulting list will be empty. This request should never return an error.

GET /api/working-patterns
curl https://app.humaans.io/api/working-patterns \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "total": 1,
  "limit": 100,
  "skip": 0,
  "data": [
    {
      "id": "MLYRjj1YdpuQp5Qe6HQsvUys",
      "companyId": "T7uqPFK7am4lFTZm39AmNuay",
      "personId": null,
      "name": "Mon-Fri 8h/day",
      "summary": "Mon-Fri (8h)",
      "fullTimeHours": 40,
      "standardDayHours": 8,
      "periodType": "week",
      "workingHours": 40,
      "workingPattern": [
        8,
        8,
        8,
        8,
        8,
        0,
        0
      ],
      "fte": 1,
      "unroundedFte": 1,
      "createdAt": "2020-01-28T08:44:42.000Z",
      "updatedAt": "2020-01-29T14:52:21.000Z"
    }
  ]
}

Retrieve a working pattern

Retrieves the working pattern with the given ID.

Parameters
  • No parameters
Returns

Returns a working pattern object if a valid identifier was provided.

GET /api/working-patterns/:id
curl https://app.humaans.io/api/working-patterns/MLYRjj1YdpuQp5Qe6HQsvUys \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6'
Response
{
  "id": "MLYRjj1YdpuQp5Qe6HQsvUys",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "personId": null,
  "name": "Mon-Fri 8h/day",
  "summary": "Mon-Fri (8h)",
  "fullTimeHours": 40,
  "standardDayHours": 8,
  "periodType": "week",
  "workingHours": 40,
  "workingPattern": [
    8,
    8,
    8,
    8,
    8,
    0,
    0
  ],
  "fte": 1,
  "unroundedFte": 1,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Create a working pattern

Parameters

  • name string

    The name of the working pattern.

  • fullTimeHours number required

    The number of hours that constitute full-time work over the specified periodType. Used as the reference for calculating the FTE (Full Time Equivalent).

  • standardDayHours number required

    The standard number of working hours per day. Used for calculating time away allowances and working days.

  • periodType string

    The time period over which fullTimeHours and workingHours are measured. One of week, day, or month.

  • workingHours number

    The total hours the employee is expected to work over the period. For fixed-hours patterns, this is calculated from the workingPattern array. For flexible patterns (where workingPattern contains booleans), this specifies the total hours to be distributed across working days.

  • workingPattern undefined[] required

    The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either:

    • An array of numbers representing hours worked per day (e.g. [8,8,8,8,8,0,0] for Mon-Fri 8h)
    • An array of booleans for flexible patterns where true indicates a working day (e.g. [true,true,true,true,true,false,false] for Mon-Fri flexible)

  • personId string | null

    The ID of the person this working pattern is created for. Only set for individual custom working patterns. When null, the working pattern is a company-wide template that can be assigned to any employee.

Returns

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

POST /api/working-patterns
curl https://app.humaans.io/api/working-patterns \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{"fullTimeHours":40,"standardDayHours":8,"workingPattern":[8,8,8,8,8,0,0]}'
Response
{
  "id": "MLYRjj1YdpuQp5Qe6HQsvUys",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "personId": null,
  "name": "Mon-Fri 8h/day",
  "summary": "Mon-Fri (8h)",
  "fullTimeHours": 40,
  "standardDayHours": 8,
  "periodType": "week",
  "workingHours": 40,
  "workingPattern": [
    8,
    8,
    8,
    8,
    8,
    0,
    0
  ],
  "fte": 1,
  "unroundedFte": 1,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Update a working pattern

Parameters

  • name string

    The name of the working pattern.

  • fullTimeHours number

    The number of hours that constitute full-time work over the specified periodType. Used as the reference for calculating the FTE (Full Time Equivalent).

  • standardDayHours number

    The standard number of working hours per day. Used for calculating time away allowances and working days.

  • periodType string

    The time period over which fullTimeHours and workingHours are measured. One of week, day, or month.

  • workingHours number

    The total hours the employee is expected to work over the period. For fixed-hours patterns, this is calculated from the workingPattern array. For flexible patterns (where workingPattern contains booleans), this specifies the total hours to be distributed across working days.

  • workingPattern undefined[]

    The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either:

    • An array of numbers representing hours worked per day (e.g. [8,8,8,8,8,0,0] for Mon-Fri 8h)
    • An array of booleans for flexible patterns where true indicates a working day (e.g. [true,true,true,true,true,false,false] for Mon-Fri flexible)

Returns

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

PATCH /api/working-patterns/:id
curl https://app.humaans.io/api/working-patterns/MLYRjj1YdpuQp5Qe6HQsvUys \
  -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \
  -H 'Content-Type: application/json' \
  -X PATCH \
  -d '{"name":"Mon-Fri 8h/day"}'
Response
{
  "id": "MLYRjj1YdpuQp5Qe6HQsvUys",
  "companyId": "T7uqPFK7am4lFTZm39AmNuay",
  "personId": null,
  "name": "Mon-Fri 8h/day",
  "summary": "Mon-Fri (8h)",
  "fullTimeHours": 40,
  "standardDayHours": 8,
  "periodType": "week",
  "workingHours": 40,
  "workingPattern": [
    8,
    8,
    8,
    8,
    8,
    0,
    0
  ],
  "fte": 1,
  "unroundedFte": 1,
  "createdAt": "2020-01-28T08:44:42.000Z",
  "updatedAt": "2020-01-29T14:52:21.000Z"
}

Delete a working pattern

Permanently deletes a working pattern. It cannot be undone.

Parameters
  • No parameters
Returns

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

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