# 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.  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.: ```sh curl https://app.humaans.io/api/me \ -H 'Authorization: Bearer ' ``` ### Expiry and rotation When you create an API access token you can choose how long it stays valid, from 1 to 365 days, or leave it without an expiry. Requests made with an expired token fail with a `401` error. The token's owner is emailed before it expires: 30 days before for tokens valid for more than 30 days, 7 days before for tokens valid for 8 to 30 days, and 1 day before for shorter ones. Rotate a token from the API tokens page to generate a new secret. The token keeps its label, scopes and settings, and a new expiry period starts. You can keep the previous secret working for up to 7 days after rotating, so integrations and service accounts can switch to the new secret without downtime. Call `GET /api/token-info` to check when the token used for the request expires. ### Scopes The API access token can be restricted to certain scopes, which limits what actions the API access token can perform. - `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 {#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. - `Owner` Has full access to read and modify all employees and data. - `Admin` Can access and edit all profiles. - `Finance` Can access all profiles and manage the subscription. - `Tech` View limited data for all profiles. Manage equipment. No access to documents or sensitive data by default. - `Manager` Can access some profile data for their reports. Unlike the other roles, Manager is inferred from reporting lines and cannot be assigned directly. - `User` Can access their own profile data. Note that access to compensation is only available to **owner** and **finance** roles (and the employee) by default. Access to personal documents is only available to **owner** (and the employee) by default. You can set custom permissions to allow **admin** and **finance** roles and managers to access compensation and documents. ### Structure You will find the structure of the API to be highly uniform and consistent. Typically every resource can be accessed via a top level endpoint, such as `/api/people`. For every such resource, you can perform some of the following operations: - `GET /api/:resource` List all objects of this type - `GET /api/:resource/:id` Retrieve a resource by id - `POST /api/:resource` Create a resource of this type - `PATCH /api/:resource/:id` Update the resource by id - `DELETE /api/:resource/:id` Delete the resource by id In terms of the information hierarchy, at the center we have a `company`. The company has a set of resources such as `people`, `locations` and `time away policies`. Each person has further resources, such as `job roles`, `bank accounts` and `documents`. ### Pagination Almost all resources have support for listing all the records by paging over them. These list API methods share a common structure and can optionally take two parameters: `$limit` and `$skip`. - `$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: ```shell curl 'https://app.humaans.io/api/people' -g \ -H 'Authorization: Bearer ' # -> { "total": 152, "limit": 100, "skip": 0, "data": [.. 100 items ..] } curl 'https://app.humaans.io/api/people?$skip=100' -g \ -H 'Authorization: Bearer ' # -> { "total": 152, "limit": 100, "skip": 100, "data": [.. 52 items ..] } ``` Note: the `-g, --globoff` argument and single quotes `''` are used in some of the curl examples, to allow usage of `$` and `[]` commonly used in Humaans API. ### Filtering Some list endpoints allow you to filter results by certain conditions. Refer to specific resources to find out what criteria are allowed. Below is a list of the different `types` of conditions. In resource type labels, value types appear before `·` and supported filter operators appear after it. When operator groups accept different value types, `/` separates each group from its accepted types. #### `string`, `number`, `boolean` Find all results matching the attribute value specified. ```shell GET /api/example?personId=IL3vne ``` #### `$in`, `$nin` Find all results matching (`$in`) or not matching (`$nin`) any of the attribute values specified. ```shell GET /api/example?personId[$in]=IL3vne&personId[$in]=5dPtfT ``` #### `$gt`, `$gte` Find results where the value is greater than (`$gt`) or greater than or equal to (`$gte`) a given value. ```shell GET /api/example?startDate[$gte]=2020-01-01 ``` #### `$lt`, `$lte` Find results where the value is less than (`$lt`) or less than or equal to (`$lte`) a given value. ```shell GET /api/example?startDate[$lte]=2020-12-31 ``` #### `$or` Find results using multiple conditions. ```shell GET /api/example?$or[0][personId]=IL3vne&$or[1][startDate][$gte]=2020-01-01 ``` ### Syncing data To sync Humaans data to another system, start with a full import of each resource. Request the maximum page size of 250 records, then increase `$skip` until the response contains no more records. Each page is fetched from live data, not a fixed snapshot. Before starting the initial import, record its start time. Changes made during the import may cause records to be skipped or returned twice. After the initial import, run the incremental query below with `updatedAt[$gte]` set to the recorded start time to reconcile those changes. ```shell curl 'https://app.humaans.io/api/people?$limit=250&$skip=0' -g \ -H 'Authorization: Bearer ' ``` For later imports, use `updatedAt` to fetch anything that changed. Add `$includeDeleted=true` to include deletions. For a deleted record, `updatedAt` is the time it was deleted. For example, if your sync runs daily, fetch the previous two days: ```shell curl --get 'https://app.humaans.io/api/people' \ -H 'Authorization: Bearer ' \ --data-urlencode '$includeDeleted=true' \ --data-urlencode 'updatedAt[$gte]=2026-08-28' \ --data-urlencode '$sort[updatedAt]=1' \ --data-urlencode '$limit=250' \ --data-urlencode '$skip=0' ``` Store each active record using `id` as its unique key, replacing any existing record with the same `id`. Deleted records are minimal tombstones containing `id` and `deletedAt`. When you receive one, remove the matching record from your system. To fetch only deleted records, add `deletedAt[$ne]=null`: ```shell curl --get 'https://app.humaans.io/api/people' \ -H 'Authorization: Bearer ' \ --data-urlencode '$includeDeleted=true' \ --data-urlencode 'deletedAt[$ne]=null' ``` Deleted records remain available through the public API for 30 days. Check each list endpoint to confirm that it supports `updatedAt` and `$includeDeleted`. ### Rate limiting {#rate-limiting} Each API access token has its own rate limit, so no single integration can overwhelm the platform. Requests made from within the Humaans app are not affected. The limit supports roughly **400 requests per minute** under a steady request pattern. The limit uses a token bucket: each token gets a bucket of **40 requests** that refills at **7 per second**. Every request spends one token and once the bucket is empty requests are rejected until it refills. So you can burst up to 40 requests at once, then settle to the steady refill rate. When rate limiting is active for a token, responses include headers describing the current allowance so you can adapt before hitting the limit: - `X-RateLimit-Limit` The maximum number of requests the token bucket can hold, i.e. the largest burst you can make when the bucket is full. - `X-RateLimit-Remaining` The number of requests you can still make right now before being rate limited. - `X-RateLimit-Policy` The active policy, formatted as `;refill=`. For example `40;refill=7` means a bucket of 40 that refills at 7 requests per second. - `Retry-After` Only present on `429` responses. The number of seconds to wait before retrying the request. When you exceed the limit, the API responds with a `429 Too Many Requests` error and a `Retry-After` header telling you how many seconds to wait before retrying: ```shell curl -i 'https://app.humaans.io/api/people' -g \ -H 'Authorization: Bearer ' # -> HTTP/1.1 429 Too Many Requests # -> X-RateLimit-Limit: 40 # -> X-RateLimit-Remaining: 0 # -> X-RateLimit-Policy: 40;refill=7 # -> Retry-After: 1 ``` #### Avoiding rate limits The most reliable way to stay within the limit is to make fewer, larger requests rather than polling the API with many small ones: - **Combine requests.** Fetch records in bulk from the list endpoints instead of requesting them one at a time. - **Use larger pages.** Raise `$limit` (up to a maximum of 250) so you retrieve more records per request when [paginating](#pagination). - **Filter server side.** Use [filtering](#filtering) to request only the records you need, instead of fetching everything and filtering in your own code. - **Prefer webhooks over polling.** Subscribe to [webhooks](#webhook-howto) to be notified of changes as they happen, rather than repeatedly polling for updates. - **Respect `Retry-After`.** When you receive a `429`, wait for the number of seconds given in the `Retry-After` header and back off, rather than retrying immediately. ### Errors Humaans uses conventional HTTP status codes to indicate whether an API request succeeded. Codes in the `2xx` range indicate success. Codes in the `4xx` range mean the request could not be completed as sent, for example because a required parameter was omitted or the token lacks permission. Codes in the `5xx` range mean Humaans could not complete a valid request. - `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[]` Details for validation, permission, or request errors. This field is omitted when no details are available. - `issues[].name` · `string` The name of the field that failed validation. - `issues[].reason` · `string` The reason why this field was invalid. - `issues[].index` · `number` The index of the item that this issue applies to in cases where the input is a list of objects. - `issues[].entityId` · `string` The identifier of the entity associated with a nested group of issues. - `issues[].entityPath` · `string[]` The path to the entity associated with a nested group of issues. - `issues[].issues` · `object[]` A nested list of issues for the associated entity. - `%!s(float64=400)` · `BadRequest` The request is invalid - `%!s(float64=401)` · `NotAuthenticated` Missing, invalid or expired access token - `%!s(float64=403)` · `Forbidden` The provided access token does not have sufficient privileges - `%!s(float64=404)` · `NotFound` The requested resource could not be found - `%!s(float64=405)` · `MethodNotAllowed` The operation is not allowed for this resource - `%!s(float64=409)` · `Conflict` The request conflicts with the current state of the resource - `%!s(float64=413)` · `PayloadTooLarge` The request payload is too large - `%!s(float64=422)` · `ValidationError` The request parameters are invalid - `%!s(float64=422)` · `Unprocessable` The request is well-formed but cannot be processed - `%!s(float64=422)` · `EmailTaken` Returned when a user is being re-onboarded, but their email is already taken - `%!s(float64=429)` · `TooManyRequests` The access token has exceeded its rate limit. See [rate limiting](#rate-limiting) for details - `%!s(float64=500)` · `GeneralError` An unexpected server error occurred - `%!s(float64=502)` · `GeneralError` A temporary upstream availability issue occurred - `%!s(float64=503)` · `GeneralError` A temporary availability issue occurred ### Versioning Humaans API currently does not use versioning. We are committed to not introducing any backward incompatible changes outside possible feature removal. If we do remove certain features, we will make sure that the API for such features continues returning the correct response structure. We might remove some APIs in cases where they are not being actively used. And if we have to introduce versioning, it will be done without breaking the existing API. ### Webhooks {#webhook-howto} Webhooks allow you listen to events happening in Humaans, as they happen. A webhook may be created by an Owner on the [webhooks page](https://app.humaans.io/settings/webhooks). 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](#webhooks). Webhook events have a generic wrapper, with event specific data contained within, this is documented [below](#webhook-events). 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: ```js 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](https://docs.svix.com/receiving/verifying-payloads). 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 ### 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 ```http GET /api/bank-accounts GET /api/bank-accounts/:id POST /api/bank-accounts PATCH /api/bank-accounts/:id DELETE /api/bank-accounts/:id ``` #### Required scopes - `private:read` - `private:write` #### Bank account object ##### Attributes - `id` · `string` Unique identifier for the object. - `personId` · `string` ID of the person that this object is associated to. - `bankName` · `string` The name of the bank. - `nameOnAccount` · `string` The name on the bank account. - `accountNumber` · `string` Bank account number. - `swiftCode` · `string` The swift code of the bank account if relevant. - `sortCode` · `string` The sort code of the bank account if relevant. - `routingNumber` · `string` The routing number of the bank account if relevant. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. ##### Example ```json { "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. `GET /api/bank-accounts` ##### Parameters - `personId` · `string · $in` The person to filter queries by. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` bank accounts. The response skips the first `$skip` results. Each entry is a separate bank account object. If no bank accounts are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/bank-accounts \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/bank-accounts/:id` ##### Parameters _None._ ##### Returns Returns a bank account object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/bank-accounts/Ivl8mvdLO8ux7T1h1DjGtClc \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 `POST /api/bank-accounts` ##### 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. ##### Request ```shell curl https://app.humaans.io/api/bank-accounts \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X POST \ -d '{"personId":"IL3vneCYhIx0xrR6um2sy2nW"}' ``` ##### Response ```json { "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 `PATCH /api/bank-accounts/:id` ##### 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. ##### Request ```shell 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 ```json { "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. `DELETE /api/bank-accounts/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/bank-accounts/Ivl8mvdLO8ux7T1h1DjGtClc \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "Ivl8mvdLO8ux7T1h1DjGtClc", "deleted": true } ``` ### Companies An object representing the company. Every user belongs to a single company and all of the resources accessible via the API are linked to this company (unless stated otherwise, such as public holidays). #### Endpoints ```http GET /api/companies GET /api/companies/:id PATCH /api/companies/:id ``` #### Required scopes - `private:read` - `public:read` - `private:write` #### Company object ##### Attributes - `id` · `string` Unique identifier for the object. - `name` · `string` Company name. - `status` · `string` One of `terms`, `trialing`, `expired`, `active`, `suspended`. - `paymentStatus` · `string` One of `requires_action`, `past_due`, `ok`. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `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` URLs for the predefined logo sizes, keyed by width in pixels. Available widths: 64, 96, 104, 136, 156, 204, 320, and 480. ##### Example ```json { "id": "uoWtfpDIMI2IZ8doGK7kkCwS", "name": "Acme", "status": "active", "paymentStatus": "ok", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "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" } } } ``` #### List all companies Returns a list of companies. `GET /api/companies` ##### Parameters - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter companies by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter companies by updated at date. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` companies. The response skips the first `$skip` results. Each entry is a separate company object. If no companies are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/companies \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "uoWtfpDIMI2IZ8doGK7kkCwS", "name": "Acme", "status": "active", "paymentStatus": "ok", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "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" } } } ] } ``` #### Retrieve a company Retrieves the company with the given ID. `GET /api/companies/:id` ##### Parameters _None._ ##### Returns Returns a company object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/companies/uoWtfpDIMI2IZ8doGK7kkCwS \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "uoWtfpDIMI2IZ8doGK7kkCwS", "name": "Acme", "status": "active", "paymentStatus": "ok", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "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" } } } ``` #### Update a company `PATCH /api/companies/:id` ##### Parameters - `name` · `string` Company name. ##### Returns Returns the company if the update succeeded. The call returns an error if parameters are invalid. ##### Request ```shell curl https://app.humaans.io/api/companies/uoWtfpDIMI2IZ8doGK7kkCwS \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X PATCH \ -d '{"name":"Meac"}' ``` ##### Response ```json { "id": "uoWtfpDIMI2IZ8doGK7kkCwS", "name": "Meac", "status": "active", "paymentStatus": "ok", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "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" } } } ``` ### 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 ```http GET /api/compensation-types GET /api/compensation-types/:id ``` #### Required scopes - `public:read` - `private:write` #### Compensation type object ##### Attributes - `id` · `string` Unique identifier for the object. - `companyId` · `string` ID of the company that this object is associated to. - `name` · `string` The name of the compensation type. - `baseType` · `string` The base type of the compensation type. One of `salary`, `bonus`, `commission`, `equity`, `custom` - `formula` · `object` Used to calculate compensation values for this type. Available for custom types only. It can only be edited if set, but not added or removed. - `formula.formula` · `string` The formula expression as plain text. Fields are written as `{{compensationType..amount}}` or `{{companyVariable..value}}`. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` - `filters` · `object[]` Filters restricting who this compensation type can be created for. An empty array means unrestricted. Only custom compensation types can have filters. - `filters.field` · `string` The field to filter on. Available fields for type `enum`: `spaceId`, `payrollProvider`, `department`, `contractType`, `locationId`, `placeOfWorkCountry`, `placeOfWorkCity`, `orgLevel`, `reportingTo`. Available fields for type `array`: `teams`, `reportsUpTo`. - `filters.operator` · `string` The operator to use when filtering. Available operators for field type `string`: `eq`, `ne`, `contains`, `ncontains`, `exists`, `nexists`. Available operators for field type `enum`: `in`, `nin`, `exists`, `nexists`. Available operators for field type `array`: `all`, `any`, `nany`, `nall`, `exists`, `nexists`. Available operators for field type `number`: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `exists`, `nexists`. Available operators for field type `date`: `eq`, `lt`, `gt`, `lte`, `gte`, `exists`, `nexists`. Available operators for field type `boolean`: `eq`, `exists`, `nexists`. - `filters.value` The value(s) of the field to check ##### Example ```json { "id": "ldOQU3pLI5i8Y9k2rJbrXbFc", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "name": "Salary", "baseType": "salary", "formula": { "formula": "{{compensationType.aejf1oD4bZWNtEEnbFwrYGVg.amount}} * 0.05" }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "filters": [ { "field": "department", "operator": "in", "value": [ "Engineering" ] } ] } ``` #### List all compensation types Returns a list of compensation types. `GET /api/compensation-types` ##### Parameters - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter compensation types by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` compensation types. The response skips the first `$skip` results. Each entry is a separate compensation type object. If no compensation types are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/compensation-types \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "ldOQU3pLI5i8Y9k2rJbrXbFc", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "name": "Salary", "baseType": "salary", "formula": { "formula": "{{compensationType.aejf1oD4bZWNtEEnbFwrYGVg.amount}} * 0.05" }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "filters": [ { "field": "department", "operator": "in", "value": [ "Engineering" ] } ] } ] } ``` #### Retrieve a compensation type Retrieves the compensation type with the given ID. `GET /api/compensation-types/:id` ##### Parameters _None._ ##### Returns Returns a compensation type object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/compensation-types/ldOQU3pLI5i8Y9k2rJbrXbFc \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "ldOQU3pLI5i8Y9k2rJbrXbFc", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "name": "Salary", "baseType": "salary", "formula": { "formula": "{{compensationType.aejf1oD4bZWNtEEnbFwrYGVg.amount}} * 0.05" }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "filters": [ { "field": "department", "operator": "in", "value": [ "Engineering" ] } ] } ``` ### Compensations An object representing compensation of an employee. Compensations come in several types: salary, bonus, commission, equity, and custom. Employees can have multiple compensations of each type. Only one compensation of each type with the latest `effectiveDate` value that is not in the future is considered to be currently in effect. #### Endpoints ```http 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. Only compensations of a custom compensation type can be negative (e.g. -500). Exceptionally, this is `#N/A` — which does not match the format above — on a compensation of a computed compensation type whose formula could not be evaluated. In that case `computationError` says why, and no amount could be determined. - `computationError` · `string` Why this compensation's value could not be computed. Only ever set on a compensation of a computed compensation type. Whenever it is set, `amount` is `#N/A`, and whenever it is `null`, `amount` is a real value. - `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. Always `null` for compensations of a computed type. - `note` · `string` An optional note about this particular compensation entry. - `effectiveDate` · `date` The date when this compensation took effect. Can be a past or future date. - `endDate` · `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` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` The date and time the compensation was deleted. Only present on deleted compensations, which are only returned when querying with `$includeDeleted`. ##### Example ```json { "id": "m54mmpqDwthFwiiMcY0ptJdz", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "compensationTypeId": "aejf1oD4bZWNtEEnbFwrYGVg", "amount": "70000", "computationError": null, "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. `GET /api/compensations` ##### Parameters - `compensationTypeId` · `string · $eq $ne $in $nin` ID of the Compensation type this compensation is related to. - `personId` · `string · $in` The person to filter queries by. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter compensations by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$asOf` · `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. Cannot be combined with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.effectiveDate` · `number` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` compensations. The response skips the first `$skip` results. Each entry is a separate compensation object. If no compensations are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/compensations \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "m54mmpqDwthFwiiMcY0ptJdz", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "compensationTypeId": "aejf1oD4bZWNtEEnbFwrYGVg", "amount": "70000", "computationError": null, "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. `GET /api/compensations/:id` ##### Parameters _None._ ##### Returns Returns a compensation object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/compensations/m54mmpqDwthFwiiMcY0ptJdz \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "m54mmpqDwthFwiiMcY0ptJdz", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "compensationTypeId": "aejf1oD4bZWNtEEnbFwrYGVg", "amount": "70000", "computationError": null, "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. `POST /api/compensations` ##### Parameters - `personId` · `string` · required ID of the person that this object is associated to. - `compensationTypeId` · `string` · one of type or compensationTypeId 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. Only compensations of a custom compensation type can be negative (e.g. -500). Exceptionally, this is `#N/A` — which does not match the format above — on a compensation of a computed compensation type whose formula could not be evaluated. In that case `computationError` says why, and no amount could be determined. - `currency` · `string | null` Currency in 3 letter format (ISO 4217), e.g. EUR, USD, GBP, BTC. - `note` · `string | null` An optional note about this particular compensation entry. - `effectiveDate` · `date` · required The date when this compensation took effect. Can be a past or future date. - `endDate` · `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. - `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. Always `null` for compensations of a computed type. ##### Returns Returns a compensation if the call succeeded. The call returns an error if parameters are invalid. ##### Request ```shell 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 ```json { "id": "m54mmpqDwthFwiiMcY0ptJdz", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "compensationTypeId": "aejf1oD4bZWNtEEnbFwrYGVg", "amount": "70000", "computationError": null, "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. `PATCH /api/compensations/:id` ##### Parameters - `compensationTypeId` · `string` · at most one of type or compensationTypeId 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. Only compensations of a custom compensation type can be negative (e.g. -500). Exceptionally, this is `#N/A` — which does not match the format above — on a compensation of a computed compensation type whose formula could not be evaluated. In that case `computationError` says why, and no amount could be determined. - `currency` · `string | null` Currency in 3 letter format (ISO 4217), e.g. EUR, USD, GBP, BTC. - `note` · `string | null` An optional note about this particular compensation entry. - `effectiveDate` · `date` The date when this compensation took effect. Can be a past or future date. - `endDate` · `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. - `period` · `string` The period over which this compensation amount is paid. One of annual, biannual, quarterly, monthly, semimonthly, biweekly, weekly, daily, hourly, fixed, sale. Always `null` for compensations of a computed type. ##### Returns Returns the compensation if the update succeeded. The call returns an error if parameters are invalid. ##### Request ```shell curl https://app.humaans.io/api/compensations/m54mmpqDwthFwiiMcY0ptJdz \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X PATCH \ -d '{"amount":"70000"}' ``` ##### Response ```json { "id": "m54mmpqDwthFwiiMcY0ptJdz", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "compensationTypeId": "aejf1oD4bZWNtEEnbFwrYGVg", "amount": "70000", "computationError": null, "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. `DELETE /api/compensations/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/compensations/m54mmpqDwthFwiiMcY0ptJdz \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "m54mmpqDwthFwiiMcY0ptJdz", "deleted": true } ``` ### Custom fields An object representing a custom field and its configuration. #### Endpoints ```http GET /api/custom-fields GET /api/custom-fields/:id POST /api/custom-fields PATCH /api/custom-fields/:id DELETE /api/custom-fields/:id ``` #### Required scopes - `private:read` - `private:write` #### Custom field object ##### Attributes - `id` · `string` Unique identifier for the object. - `companyId` · `string` ID of the company that this object is associated to. - `name` · `string` The name of the custom field. - `section` · `string` The profile section where the custom field will appear in. One of `basics`, `health`, `diversity`, `banking`, `equipment`, `social`, `employment`, `jobRole`, `employmentTerms`, `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` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` ##### Example ```json { "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. `GET /api/custom-fields` ##### Parameters - `id` · `string · $eq $ne $in $nin` - `section` · `string · $eq $ne $in $nin` The profile section where the custom field will appear in. One of `basics`, `health`, `diversity`, `banking`, `equipment`, `social`, `employment`, `jobRole`, `employmentTerms`, `compensation`, `offboarding` - `type` · `string · $eq $ne $in $nin` Custom field type. One of `text`, `longText`, `select`, `multiSelect`, `link`, `date`, `person`. If section is `diversity`, this is limited to `text`, `select`, `multiSelect` - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` custom fields. The response skips the first `$skip` results. Each entry is a separate custom field object. If no custom fields are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/custom-fields \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/custom-fields/:id` ##### Parameters _None._ ##### Returns Returns a custom field object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/custom-fields/ZpbLXlJRpBJQOre5kbFQqYf4 \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 `POST /api/custom-fields` ##### 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`, `employmentTerms`, `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. ##### Request ```shell 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 ```json { "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 `PATCH /api/custom-fields/:id` ##### 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. ##### Request ```shell 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 ```json { "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. `DELETE /api/custom-fields/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/custom-fields/ZpbLXlJRpBJQOre5kbFQqYf4 \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "ZpbLXlJRpBJQOre5kbFQqYf4", "deleted": true } ``` ### Custom values An object representing a custom field value. #### Endpoints ```http GET /api/custom-values GET /api/custom-values/:id POST /api/custom-values PATCH /api/custom-values/:id DELETE /api/custom-values/:id ``` #### Required scopes - `private:read` - `public:read` - `private:write` #### Custom value object ##### Attributes - `id` · `string` Unique identifier for the object. - `personId` · `string` ID of the person that this object is associated to. - `customFieldId` · `string` The ID of the custom field this value is for. - `resourceId` · `string` The ID of the resource this field belongs to in case it is a subresource of a person. This is an ID of a Bank account in case `section` is `banking`. It's an ID of an Equipment in case `section` is `equipment`, a Job role in case `section` is `jobRole`, and an Employment terms entry in case `section` is `employmentTerms`. - `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` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` ##### Example ```json { "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. `GET /api/custom-values` ##### Parameters - `customFieldId` · `string · $eq $ne $in $nin` The custom field to filter queries by. - `personId` · `string · $eq $ne $in $nin` The person to filter queries by. - `resourceId` · `string · $eq $ne $in $nin` The ID of the resource this field belongs to in case it is a subresource of a person. This is an ID of a Bank account in case `section` is `banking`. It's an ID of an Equipment in case `section` is `equipment`, a Job role in case `section` is `jobRole`, and an Employment terms entry in case `section` is `employmentTerms`. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter custom values by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$or` · `object[]` - `$or.resourceId` · `string · $eq $ne $in $nin` - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` custom values. The response skips the first `$skip` results. Each entry is a separate custom value object. If no custom values are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/custom-values \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/custom-values/:id` ##### Parameters _None._ ##### Returns Returns a custom value object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/custom-values/gk1P9Iidto7eh2ygaYD865P2 \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 `POST /api/custom-values` ##### 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 `section` is `equipment`, a Job role in case `section` is `jobRole`, and an Employment terms entry in case `section` is `employmentTerms`. ##### Returns Returns a custom value if the call succeeded. The call returns an error if parameters are invalid. ##### Request ```shell 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 ```json { "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 `PATCH /api/custom-values/:id` ##### 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. ##### Request ```shell 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 ```json { "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. `DELETE /api/custom-values/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/custom-values/gk1P9Iidto7eh2ygaYD865P2 \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "gk1P9Iidto7eh2ygaYD865P2", "deleted": true } ``` ### Data exports Data export API can be used to quickly export a large set of data about all of the employees. #### Endpoints ```http GET /api/data-exports/:id POST /api/data-exports DELETE /api/data-exports/:id ``` #### Required scopes Multiple scopes are allowed. Depending on which fields you'd like to export, use one of `public:read`, `private:read`, or `compensations:read`. #### Data export object ##### Attributes - `id` · `string` Unique identifier for the object. - `companyId` · `string` ID of the company that this object is associated to. - `url` · `string` The URL from which exported data file can be downloaded. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. ##### Example ```json { "id": "yQYtUaI6LeTc1Ss5S0FgInPo", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "url": "/data-exports/dPnhSGDoq9UUR9Bf1BwPPkjC", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Retrieve a data export Retrieves the data export with the given ID. Note that this only retrieves the metadata about the data export. To download the actual data, you need to resolve the `url` and download the data from that URL. `GET /api/data-exports/:id` ##### Parameters _None._ ##### Returns Returns a data export object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/data-exports/yQYtUaI6LeTc1Ss5S0FgInPo \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "yQYtUaI6LeTc1Ss5S0FgInPo", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "url": "/data-exports/dPnhSGDoq9UUR9Bf1BwPPkjC", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Create a data export Note that once the data export is created the exported data needs to be downloaded separately. This can be done by resolving the `url` field and downloading data from that URL. `POST /api/data-exports` ##### Parameters - `compensationTypes` · `string[]` The list of compensation type IDs that should be included in the data export. - `customFields` · `string[]` The list of custom field IDs that should be included in the data export. - `customIdentifierFields` · `string[]` The list of custom field IDs that should be treated as identifier fields in changes report - `download` · `boolean` By default, the resulting payload of creating an export includes a URL from which exported data file can be downloaded, set this to true to immediately get the generated result in the same request. - `endDate` · `string | null` The end date of the data export. - `fields` · `string[] | null` The list of fields that should be included in the data export. Available fields for export type `people`: `companyName`, `firstName`, `preferredName`, `preferredNameOrFirstName`, `middleName`, `lastName`, `fullName`, `pronouns`, `birthday`, `shortBirthday`, `nationality`, `spokenLanguages`, `gender`, `email`, `phoneNumber`, `personalEmail`, `personalPhoneNumber`, `fullAddress`, `country`, `countryCode`, `dietaryPreference`, `foodAllergies`, `idExpiryDates`, `emergencyContacts`, `timezone`, `jobTitle`, `department`, `manager`, `managerPreferredName`, `managerEmail`, `roleEffectiveDate`, `lastPerformanceRating`, `teams`, `placeOfWork`, `fullPlaceOfWork`, `placeOfWorkCity`, `placeOfWorkCountry`, `isRemote`, `space`, `payrollProvider`, `employmentType`, `contractType`, `employmentTermsEffectiveDate`, `employeeId`, `taxId`, `taxCode`, `employeeStatus`, `employmentStartDate`, `firstWorkingDay`, `firstActiveAt`, `workingDays`, `workingPattern`, `fte`, `unroundedFte`, `probationEndDate`, `employmentEndDate`, `lastWorkingDay`, `leavingReason`, `turnoverImpact`, `leavingNote`, `jobProfileCode`, `jobProfileExternalTitle`, `jobProfileFunction`, `jobProfileFamily`, `jobProfileRole`, `jobProfileRoleCode`, `jobProfileLevel`, `jobProfileLevelCode`, `jobProfileTrack`, `jobProfileGrade`, `bankName`, `nameOnAccount`, `accountNumber`, `swiftCode`, `sortCode`, `routingNumber`, `remoteCountryCode`, `salary`, `bonus`, `equity`, `commission`, `paidTimeOff`, `unpaidLeave`, `sickLeave`, `parentalLeave`, `workingFromHome`, `otherTimeAway`, `approvalFlow`, `allowance`, `fromPrevAccrualPeriod`, `fromPrevAccrualPeriodExpired`, `carriedOver`, `carriedOverExpired`, `adjustments`, `accrued`, `upcoming`, `balance`, `endOfYearBalance`, `ptoPolicy`, `social`, `diversity`. Available fields for export type `equipment`: `firstName`, `preferredName`, `middleName`, `lastName`, `gender`, `email`, `phoneNumber`, `personalEmail`, `personalPhoneNumber`, `fullAddress`, `country`, `jobTitle`, `department`, `manager`, `managerPreferredName`, `managerEmail`, `roleEffectiveDate`, `lastPerformanceRating`, `teams`, `placeOfWork`, `fullPlaceOfWork`, `isRemote`, `space`, `payrollProvider`, `contractType`, `employeeId`, `employeeStatus`, `employmentStartDate`, `firstWorkingDay`, `firstActiveAt`, `workingDays`, `workingPattern`, `fte`, `unroundedFte`, `probationEndDate`, `employmentEndDate`, `lastWorkingDay`, `leavingReason`, `turnoverImpact`, `leavingNote`, `type`, `name`, `serialNumber`, `cost`, `currency`, `note`, `attachment`, `issueDate`, `receiptDate`, `collectionDate`. Available fields for export type `timeAway`: `firstName`, `preferredName`, `middleName`, `lastName`, `gender`, `email`, `phoneNumber`, `personalEmail`, `personalPhoneNumber`, `fullAddress`, `country`, `isTimeOff`, `jobTitle`, `department`, `manager`, `managerPreferredName`, `managerEmail`, `roleEffectiveDate`, `lastPerformanceRating`, `teams`, `placeOfWork`, `fullPlaceOfWork`, `isRemote`, `space`, `payrollProvider`, `contractType`, `employeeId`, `employeeStatus`, `employmentStartDate`, `firstWorkingDay`, `firstActiveAt`, `workingDays`, `workingPattern`, `fte`, `unroundedFte`, `probationEndDate`, `employmentEndDate`, `lastWorkingDay`, `leavingReason`, `turnoverImpact`, `leavingNote`, `timeAwayType`, `startDate`, `endDate`, `startPeriod`, `endPeriod`, `days`, `note`, `registeredOn`, `requestStatus`, `reviewer`, `reviewerEmail`, `reviewedAt`, `publicHolidayCalendar`, `approvalFlow`, `ptoPolicy`. Available fields for export type `timesheet`: `firstName`, `preferredName`, `middleName`, `lastName`, `gender`, `email`, `phoneNumber`, `personalEmail`, `personalPhoneNumber`, `fullAddress`, `country`, `jobTitle`, `department`, `manager`, `managerPreferredName`, `managerEmail`, `roleEffectiveDate`, `lastPerformanceRating`, `teams`, `placeOfWork`, `fullPlaceOfWork`, `isRemote`, `space`, `payrollProvider`, `contractType`, `employeeId`, `employeeStatus`, `employmentStartDate`, `firstWorkingDay`, `firstActiveAt`, `workingDays`, `workingPattern`, `fte`, `unroundedFte`, `probationEndDate`, `employmentEndDate`, `lastWorkingDay`, `leavingReason`, `turnoverImpact`, `leavingNote`, `startDate`, `endDate`, `submittedAt`, `totalTime`, `totalDays`, `status`, `reviewer`, `reviewerEmail`, `reviewedAt`. Available fields for export type `document`: `firstName`, `preferredName`, `middleName`, `lastName`, `gender`, `email`, `phoneNumber`, `personalEmail`, `personalPhoneNumber`, `fullAddress`, `country`, `jobTitle`, `department`, `manager`, `managerPreferredName`, `managerEmail`, `roleEffectiveDate`, `lastPerformanceRating`, `teams`, `placeOfWork`, `fullPlaceOfWork`, `isRemote`, `space`, `payrollProvider`, `contractType`, `employeeId`, `employeeStatus`, `employmentStartDate`, `firstWorkingDay`, `firstActiveAt`, `workingDays`, `workingPattern`, `fte`, `unroundedFte`, `probationEndDate`, `employmentEndDate`, `lastWorkingDay`, `leavingReason`, `turnoverImpact`, `leavingNote`, `type`, `name`, `issueDate`, `link`, `documentLink`, `uploader`, `uploaderEmail`. Available fields for export type `identityDocument`: `firstName`, `preferredName`, `middleName`, `lastName`, `nationality`, `gender`, `email`, `phoneNumber`, `personalEmail`, `personalPhoneNumber`, `fullAddress`, `country`, `jobTitle`, `department`, `manager`, `managerPreferredName`, `managerEmail`, `roleEffectiveDate`, `lastPerformanceRating`, `teams`, `placeOfWork`, `fullPlaceOfWork`, `isRemote`, `space`, `payrollProvider`, `contractType`, `employeeId`, `employeeStatus`, `employmentStartDate`, `firstWorkingDay`, `firstActiveAt`, `workingDays`, `workingPattern`, `fte`, `unroundedFte`, `probationEndDate`, `employmentEndDate`, `lastWorkingDay`, `leavingReason`, `turnoverImpact`, `leavingNote`, `type`, `number`, `expiryDate`, `note`, `issueCountry`, `link`, `verifier`, `verifierEmail`. Available fields for export type `workflowActivity`: `firstName`, `preferredName`, `middleName`, `lastName`, `gender`, `email`, `phoneNumber`, `personalEmail`, `personalPhoneNumber`, `fullAddress`, `country`, `jobTitle`, `department`, `manager`, `managerPreferredName`, `managerEmail`, `roleEffectiveDate`, `lastPerformanceRating`, `teams`, `placeOfWork`, `fullPlaceOfWork`, `isRemote`, `space`, `payrollProvider`, `contractType`, `employeeId`, `employeeStatus`, `employmentStartDate`, `firstWorkingDay`, `firstActiveAt`, `workingDays`, `workingPattern`, `fte`, `unroundedFte`, `probationEndDate`, `employmentEndDate`, `lastWorkingDay`, `leavingReason`, `turnoverImpact`, `leavingNote`, `workflowName`, `instanceCreatedAt`, `workflowArchivedAt`, `actionTitle`, `actionType`, `taskTitle`, `taskAssignee`, `taskAssigneeEmail`, `taskCompletedBy`, `taskCompletedByEmail`, `emailSubject`, `emailSenderName`, `emailSender`, `triggerDate`, `triggerTime`, `createdAt`, `completedAt`. Available fields for export type `changes`: `firstName`, `preferredName`, `middleName`, `lastName`, `pronouns`, `birthday`, `shortBirthday`, `nationality`, `spokenLanguages`, `gender`, `email`, `phoneNumber`, `personalEmail`, `personalPhoneNumber`, `fullAddress`, `country`, `dietaryPreference`, `foodAllergies`, `idExpiryDates`, `emergencyContacts`, `jobTitle`, `department`, `managerPreferredName`, `managerEmail`, `roleEffectiveDate`, `lastPerformanceRating`, `teams`, `isRemote`, `space`, `placeOfWork`, `payrollProvider`, `contractType`, `employeeId`, `taxId`, `taxCode`, `employeeStatus`, `employmentStartDate`, `firstWorkingDay`, `firstActiveAt`, `workingDays`, `workingPattern`, `fte`, `unroundedFte`, `probationEndDate`, `employmentEndDate`, `lastWorkingDay`, `leavingReason`, `turnoverImpact`, `leavingNote`, `bankName`, `nameOnAccount`, `accountNumber`, `swiftCode`, `sortCode`, `routingNumber`, `social`, `diversity`. Available fields for export type `payroll`: `firstName`, `preferredName`, `middleName`, `lastName`, `pronouns`, `birthday`, `shortBirthday`, `nationality`, `spokenLanguages`, `gender`, `email`, `phoneNumber`, `personalEmail`, `personalPhoneNumber`, `fullAddress`, `country`, `dietaryPreference`, `foodAllergies`, `idExpiryDates`, `emergencyContacts`, `jobTitle`, `department`, `managerPreferredName`, `managerEmail`, `roleEffectiveDate`, `lastPerformanceRating`, `teams`, `isRemote`, `space`, `placeOfWork`, `payrollProvider`, `contractType`, `employeeId`, `taxId`, `taxCode`, `employeeStatus`, `employmentStartDate`, `firstWorkingDay`, `firstActiveAt`, `workingDays`, `workingPattern`, `fte`, `unroundedFte`, `probationEndDate`, `employmentEndDate`, `lastWorkingDay`, `leavingReason`, `turnoverImpact`, `leavingNote`, `bankName`, `nameOnAccount`, `accountNumber`, `swiftCode`, `sortCode`, `routingNumber`, `social`, `diversity`. Available fields for export type `requests`: `firstName`, `preferredName`, `middleName`, `lastName`, `gender`, `email`, `phoneNumber`, `personalEmail`, `personalPhoneNumber`, `country`, `jobTitle`, `department`, `managerPreferredName`, `managerEmail`, `roleEffectiveDate`, `teams`, `space`, `contractType`, `employeeId`, `employeeStatus`, `employmentStartDate`, `firstWorkingDay`, `probationEndDate`, `lastWorkingDay`, `leavingReason`, `requestTypeName`, `requestStatus`, `requestedByName`, `requestedByEmail`, `currentApprovalStep`, `totalApprovalSteps`, `approvalRequirement`, `currentApprovers`, `daysOpen`, `timeToComplete`, `requestCreatedAt`, `requestCompletedAt`, `stepsApprovals`. Available fields for export type `goals`: `firstName`, `preferredName`, `middleName`, `lastName`, `email`, `personalEmail`, `jobTitle`, `department`, `managerPreferredName`, `managerEmail`, `teams`, `space`, `employeeId`, `employeeStatus`, `employmentStartDate`, `lastWorkingDay`, `goalType`, `goalTitle`, `goalStatus`, `goalProgress`, `goalProgressType`, `goalPeriodStart`, `goalPeriodEnd`, `goalAssigneePreferredName`, `goalAssigneeEmail`, `goalParentObjectiveTitle`. Available fields for export type `events`: `firstName`, `preferredName`, `middleName`, `lastName`, `pronouns`, `birthday`, `shortBirthday`, `nationality`, `spokenLanguages`, `gender`, `email`, `phoneNumber`, `personalEmail`, `personalPhoneNumber`, `fullAddress`, `country`, `dietaryPreference`, `foodAllergies`, `idExpiryDates`, `emergencyContacts`, `jobTitle`, `department`, `managerPreferredName`, `managerEmail`, `roleEffectiveDate`, `lastPerformanceRating`, `teams`, `fullPlaceOfWork`, `space`, `payrollProvider`, `contractType`, `employeeId`, `taxId`, `taxCode`, `employeeStatus`, `employmentStartDate`, `firstWorkingDay`, `firstActiveAt`, `workingDays`, `workingPattern`, `fte`, `unroundedFte`, `probationEndDate`, `employmentEndDate`, `lastWorkingDay`, `leavingReason`, `turnoverImpact`, `leavingNote`, `event`, `date`, `anniversaryLength`. For `performance`, columns are generated automatically from the performance cycle and selected view. - `identifierFields` · `string[]` The list of fields that should be treated as identifier fields in changes report. Available fields: `firstName`, `preferredName`, `middleName`, `lastName`, `pronouns`, `birthday`, `nationality`, `gender`, `email`, `phoneNumber`, `personalEmail`, `personalPhoneNumber`, `country`, `fullAddress`, `jobTitle`, `department`, `teams`, `payrollProvider`, `contractType`, `employeeId`, `employeeStatus`, `employmentStartDate`, `firstWorkingDay`, `firstActiveAt`, `probationEndDate`, `employmentEndDate`, `lastWorkingDay`. - `includeAdjustments` · `boolean` Set to `true` to include time away adjustments. Only applies to exports of type `timeAway` - `includeUnsubmittedHours` · `boolean` Set to `true` to include recorded hours that have not been submitted yet. Only applies to exports of type `timesheet` - `includeAllDocumentVersions` · `boolean` Set to `true` to include all document versions. Only applies to exports of type `identityDocument` - `includeAnniversaries` · `boolean` Set to `true` to include work anniversary events. Only applies to exports of type `events`. Defaults to `false`. - `includeArchivedWorkflows` · `boolean` Set to `true` to include archived workflow instances. Only applies to exports of type `workflowActivity` - `includeBirthdays` · `boolean` Set to `true` to include birthday events. Only applies to exports of type `events`. Defaults to `false`. - `includeCompensationHistory` · `boolean` Set to `true` to include every compensation that was in effect within the filtered date range. This will output multiple rows of data per each employee. - `includeJoiners` · `boolean` Set to `true` to include joiner events. Only applies to exports of type `events`. Defaults to `false`. - `includeLeavers` · `boolean` Set to `true` to include leaver events. Only applies to exports of type `events`. Defaults to `false`. - `includeProbationEnd` · `boolean` Set to `true` to include probation end events. Only applies to exports of type `events`. Defaults to `false`. - `includeOffboarded` · `boolean` Set to `true` to include offboarded people in the data export. - `includeNewHires` · `boolean` Set to `false` to exclude people marked as new hires from the data export. Defaults to `true`. - `includeRoleHistory` · `boolean` Set to `true` to include every job role that was in effect within the filtered date range. This will output multiple rows of data per each employee. - `includeWithoutDocuments` · `boolean` Set to `true` to include employees without any documents. Only applies to exports of type `document` or `identityDocument` - `includeWithoutEquipment` · `boolean` Set to `true` to include employees without any equipment. Only applies to exports of type `equipment` - `includeWithoutGoals` · `boolean` Set to `true` to include employees without any goals. Only applies to exports of type `goals` - `json` · `boolean` Generate the output in JSON format instead of CSV - `orgUnitFields` · `string[]` The org unit assignment columns that should be included in the data export, as `:`. Available fields: `unit`, `path`, `code`, `effectiveDate`, `manager`, `managerAssignment`. - `startDate` · `string | null` The start date of the data export. This is used to include only the people that were active after this date. It is also used when rolling up time away taken totals. - `timeAwayTypes` · `string[]` The list of time away type IDs that should be included in the data export. - `type` · `string` The type of export, one of `people`, `equipment`, `timesheet`, `timeAway`, `document`, `identityDocument`, `workflowActivity`, `changes`, `payroll`, `requests`, `goals`, `events`, `performance`. Default: `people`. - `filters` · `object[]` Filters to control the data included in the export - `filters.field` · `string` · required The field to filter on. Available fields for type `enum`: `spaceId`, `payrollProvider`, `department`, `contractType`, `locationId`, `placeOfWorkCountry`, `placeOfWorkCity`, `orgLevel`, `reportingTo`, `jobProfileId`, `jobProfileRoleId`, `jobProfileLevelId`, `jobProfileFunction`, `jobProfileFamily`, `jobProfileTrack`, `jobProfileGrade`. Available fields for type `array`: `teams`, `reportsUpTo`. - `filters.operator` · `string` · required The operator to use when filtering. Available operators for field type `string`: `eq`, `ne`, `contains`, `ncontains`, `exists`, `nexists`. Available operators for field type `enum`: `in`, `nin`, `exists`, `nexists`. Available operators for field type `array`: `all`, `any`, `nany`, `nall`, `exists`, `nexists`. Available operators for field type `number`: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `exists`, `nexists`. Available operators for field type `date`: `eq`, `lt`, `gt`, `lte`, `gte`, `exists`, `nexists`. Available operators for field type `boolean`: `eq`, `exists`, `nexists`. - `filters.value` The value(s) of the field to check ##### Returns Returns a data export if the call succeeded. The call returns an error if parameters are invalid. ##### Request ```shell curl https://app.humaans.io/api/data-exports \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X POST \ -d '{"fields":["firstName","lastName","email","jobTitle"]}' ``` ##### Response ```json { "id": "yQYtUaI6LeTc1Ss5S0FgInPo", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "url": "/data-exports/dPnhSGDoq9UUR9Bf1BwPPkjC", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Delete a data export Permanently deletes a data export. It cannot be undone. Note that data exports expire automatically after a short period of time. `DELETE /api/data-exports/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/data-exports/yQYtUaI6LeTc1Ss5S0FgInPo \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "yQYtUaI6LeTc1Ss5S0FgInPo", "deleted": true } ``` ### Document types An object representing a type of a document. This resource is used to find out the list of all document types that are in use in the account. #### Endpoints ```http GET /api/document-types POST /api/document-types PATCH /api/document-types/:id DELETE /api/document-types/:id ``` #### Required scopes - `documents:read` - `documents:write` #### Document type object ##### Attributes - `id` · `string` Unique identifier for the object. - `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` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` ##### Example ```json { "id": "Ozcv1Wea2yfUhSm8fsj0ziIf", "name": "Employment agreement", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### List all document types Returns a list of document types. `GET /api/document-types` ##### Parameters - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter document types by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` document types. The response skips the first `$skip` results. Each entry is a separate document type object. If no document types are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/document-types \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "Ozcv1Wea2yfUhSm8fsj0ziIf", "name": "Employment agreement", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ] } ``` #### Create a document type `POST /api/document-types` ##### 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. ##### Request ```shell 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 ```json { "id": "Ozcv1Wea2yfUhSm8fsj0ziIf", "name": "Employment agreement", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Update a document type `PATCH /api/document-types/:id` ##### 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. ##### Request ```shell 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 ```json { "id": "Ozcv1Wea2yfUhSm8fsj0ziIf", "name": "Employment agreement", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Delete a document type Permanently deletes a document type. It cannot be undone. `DELETE /api/document-types/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/document-types/Ozcv1Wea2yfUhSm8fsj0ziIf \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "Ozcv1Wea2yfUhSm8fsj0ziIf", "deleted": true } ``` ### Documents An object representing a document that can be attached to an employee or the company. #### Endpoints ```http 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. - `personId` · `string` ID of the person that this object is associated to. - `name` · `string` The name of the document - `documentTypeId` · `string` The ID of the document type. - `link` · `string` Documents **must** have either a link or a file attached. - `fileId` · `string` Documents **must** have either a link or a file attached. - `file` · `object` A subset of the file object attached to this document. The full file object can be retrieved using the [Files](#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` · `date` The date when the document was issued. - `createdBy` · `string` ID of the user who created the document - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. ##### Example ```json { "id": "j5nMguwlwQeNYkk9Jie8u1Q2", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "name": "Employment agreement 2020 (Initial)", "link": "https://drive.google.com/docs/KMjibfqIQC3hiZK2tFItQetm", "fileId": null, "file": { "id": "51YzMOYrc9rU0lNGn1QtgSv0", "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0", "filename": "passport-scan.pdf" }, "source": null, "sourceId": null, "issueDate": "2020-01-28", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### List all documents Returns a list of documents. `GET /api/documents` ##### Parameters - `personId` · `string · $eq $ne $in $nin` ID of the person that this object is associated to. Pass null or no value for company documents only (personId is null). Use personId[$ne]=null for personal docs only, personId[$in][]=id for multiple. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter documents by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$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]=` - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` documents. The response skips the first `$skip` results. Each entry is a separate document object. If no documents are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/documents \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "j5nMguwlwQeNYkk9Jie8u1Q2", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "name": "Employment agreement 2020 (Initial)", "link": "https://drive.google.com/docs/KMjibfqIQC3hiZK2tFItQetm", "fileId": null, "file": { "id": "51YzMOYrc9rU0lNGn1QtgSv0", "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0", "filename": "passport-scan.pdf" }, "source": null, "sourceId": null, "issueDate": "2020-01-28", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ] } ``` #### Retrieve a document Retrieves the document with the given ID. `GET /api/documents/:id` ##### Parameters _None._ ##### Returns Returns a document object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/documents/j5nMguwlwQeNYkk9Jie8u1Q2 \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "j5nMguwlwQeNYkk9Jie8u1Q2", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "name": "Employment agreement 2020 (Initial)", "link": "https://drive.google.com/docs/KMjibfqIQC3hiZK2tFItQetm", "fileId": null, "file": { "id": "51YzMOYrc9rU0lNGn1QtgSv0", "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0", "filename": "passport-scan.pdf" }, "source": null, "sourceId": null, "issueDate": "2020-01-28", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Create a document `POST /api/documents` ##### 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. - `link` · `string | null` · one of link or fileId required Documents **must** have either a link or a file attached. - `fileId` · `string | null` · one of link or fileId required Documents **must** have either a link or a file attached. - `issueDate` · `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. ##### Request ```shell 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 ```json { "id": "j5nMguwlwQeNYkk9Jie8u1Q2", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "name": "Employment agreement 2020 (Initial)", "link": "https://drive.google.com/docs/KMjibfqIQC3hiZK2tFItQetm", "fileId": null, "file": { "id": "51YzMOYrc9rU0lNGn1QtgSv0", "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0", "filename": "passport-scan.pdf" }, "source": null, "sourceId": null, "issueDate": "2020-01-28", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Update a document `PATCH /api/documents/:id` ##### Parameters - `name` · `string` The name of the document - `documentTypeId` · `string | null` The ID of the document type. - `issueDate` · `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. ##### Request ```shell 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 ```json { "id": "j5nMguwlwQeNYkk9Jie8u1Q2", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "name": "Employment agreement 2020 (Initial)", "link": "https://intranet/doc/2", "fileId": null, "file": { "id": "51YzMOYrc9rU0lNGn1QtgSv0", "url": "https://app.humaans.io/files/51YzMOYrc9rU0lNGn1QtgSv0", "filename": "passport-scan.pdf" }, "source": null, "sourceId": null, "issueDate": "2020-01-28", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Delete a document Permanently deletes a document. It cannot be undone. `DELETE /api/documents/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/documents/j5nMguwlwQeNYkk9Jie8u1Q2 \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "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 ```http GET /api/emergency-contacts GET /api/emergency-contacts/:id POST /api/emergency-contacts PATCH /api/emergency-contacts/:id DELETE /api/emergency-contacts/:id ``` #### Required scopes - `private:read` - `private:write` #### Emergency contact object ##### Attributes - `id` · `string` Unique identifier for the object. - `personId` · `string` ID of the person that this object is associated to. - `name` · `string` The name of the emergency contact. - `email` · `string` The email of the emergency contact. - `phoneNumber` · `string` The phone number of the emergency contact. - `formattedPhoneNumber` · `string` This holds the value of the phoneNumber field but formatted for display. - `relationship` · `string` The relationship of the emergency contact to the employee. - `isPrimary` · `boolean` Indicates the primary emergency contact. Only one emergency can be primary. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. ##### Example ```json { "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. `GET /api/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. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` emergency contacts. The response skips the first `$skip` results. Each entry is a separate emergency contact object. If no emergency contacts are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/emergency-contacts \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/emergency-contacts/:id` ##### Parameters _None._ ##### Returns Returns an emergency contact object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/emergency-contacts/QmzB8xCTAG7IIHcsM1DKdpZe \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 `POST /api/emergency-contacts` ##### 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. ##### Request ```shell 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 ```json { "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 `PATCH /api/emergency-contacts/:id` ##### 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. ##### Request ```shell 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 ```json { "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. `DELETE /api/emergency-contacts/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/emergency-contacts/QmzB8xCTAG7IIHcsM1DKdpZe \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "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 ```http GET /api/equipment GET /api/equipment/:id POST /api/equipment PATCH /api/equipment/:id DELETE /api/equipment/:id ``` #### Required scopes - `private:read` - `private:write` #### Equipment object ##### Attributes - `id` · `string` Unique identifier for the object. - `personId` · `string` ID of the person that this object is associated to. - `type` · `string` The type of the equipment. - `name` · `string` The name / model on the equipment. - `serialNumber` · `string` The serial number. - `cost` · `string` Cost, the fraction should be separated with a dot. - `currency` · `string` Currency in 3 letter format (ISO 4217), e.g. EUR, USD, GBP, BTC. - `note` · `string` Any additional notes. - `fileId` · `string` A file attachment. - `file` · `object` A subset of the file object attached to this document. The full file object can be retrieved using the [Files](#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` · `date` The date when the equipment was issued. - `receiptDate` · `date` The date when the equipment was received by the employee, if different from issue date. - `collectionDate` · `date` The date when the equipment was collected from the employee. - `collectedBy` · `string` The person that marked the equipment as collected. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` ##### Example ```json { "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. `GET /api/equipment` ##### Parameters - `personId` · `string` The person to filter queries by. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` equipment. The response skips the first `$skip` results. Each entry is a separate equipment object. If no equipment are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/equipment \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/equipment/:id` ##### Parameters _None._ ##### Returns Returns an equipment object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/equipment/W1Uisa336KrC6Rt55pEBkTNZ \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 `POST /api/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` · `date` · required The date when the equipment was issued. - `receiptDate` · `date | null` The date when the equipment was received by the employee, if different from issue date. - `collectionDate` · `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. ##### Request ```shell 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 ```json { "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 `PATCH /api/equipment/:id` ##### 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` · `date` The date when the equipment was issued. - `receiptDate` · `date | null` The date when the equipment was received by the employee, if different from issue date. - `collectionDate` · `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. ##### Request ```shell 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 ```json { "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. `DELETE /api/equipment/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/equipment/W1Uisa336KrC6Rt55pEBkTNZ \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "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 ```http GET /api/equipment-names ``` #### Required scopes - `private:read` #### Equipment name object ##### Attributes - `id` · `string` Unique identifier for the object. - `companyId` · `string` ID of the company that this object is associated to. - `value` · `string` The label of the equipment name. - `isDefault` · `boolean` Whether this name is the default name provided by Humaans. - `isUsed` · `boolean` Whether this name is used for some equipment. ##### Example ```json { "id": "j9541EU55Ru2fJ50WGWjPkod", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "value": "Laptop", "isDefault": true, "isUsed": true } ``` #### List all equipment names Returns a list of equipment names. `GET /api/equipment-names` ##### Parameters - `type` · `string` Filter the equipment names by equipment type. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` equipment names. The response skips the first `$skip` results. Each entry is a separate equipment name object. If no equipment names are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/equipment-names \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 ```http GET /api/equipment-types ``` #### Required scopes - `private:read` #### Equipment type object ##### Attributes - `id` · `string` Unique identifier for the object. - `companyId` · `string` ID of the company that this object is associated to. - `value` · `string` The label of the equipment type. - `isDefault` · `boolean` Whether this type is the default type provided by Humaans. - `isUsed` · `boolean` Whether this type is used for some equipment. ##### Example ```json { "id": "mK6SIWfNdZWb4x9dRmTYtn7g", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "value": "Laptop", "isDefault": true, "isUsed": true } ``` #### List all equipment types Returns a list of equipment types. `GET /api/equipment-types` ##### Parameters - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` equipment types. The response skips the first `$skip` results. Each entry is a separate equipment type object. If no equipment types are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/equipment-types \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "mK6SIWfNdZWb4x9dRmTYtn7g", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "value": "Laptop", "isDefault": true, "isUsed": true } ] } ``` ### Files An object representing a file uploaded to Humaans. The files API is used for uploading profile photos as well as files that are attached to identity documents, documents and offboarded people. #### Endpoints ```http GET /api/files/:id POST /api/files ``` #### Required scopes Multiple scopes allowed. The scope required for creating or accessing a particular file depends on the `type` attribute of the file. #### File object ##### Attributes - `id` · `string` Unique identifier for the object. - `companyId` · `string` ID of the company that this object is associated to. - `personId` · `string` ID of the person that this object is associated to. Set to the ID of the person that this file will be attached to. Set to `null` if it's a company wide `document`. - `type` · `string` The type of resource that uses the file. For uploads through the public API, use one of `profilePhoto`, `document`, `identityDocument`, `equipmentFile`, `leavingFile`. - `uploadedBy` · `string` The ID of the person who uploaded this file. - `filename` · `string` The original filename of the uploaded file. - `url` · `string` The URL from which the file can be downloaded. Note, the `api/files` is only used for creating the files and retrieving their metadata. Use this URL to retrieve the actual uploaded file. - `isPublic` · `boolean` Can the original file be accessed without authentication. - `variants` · `object` URLs for the predefined photo sizes, keyed by width in pixels. Available widths: 64, 96, 104, 136, 156, 204, 320, and 480. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. ##### Example ```json { "id": "UJx97ZPPgz2EncFbxXIQkxEq", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "type": "document", "uploadedBy": "AfcpS6HbVjoXdMLZ6aF4Sfad", "filename": "employment-agreement-kw-2020.pdf", "url": "https://app.humaans.io/file/UJx97ZPPgz2EncFbxXIQkxEq", "isPublic": false, "variants": null, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Retrieve a file Retrieves the file with the given ID. `GET /api/files/:id` ##### Parameters _None._ ##### Returns Returns a file object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/files/UJx97ZPPgz2EncFbxXIQkxEq \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "UJx97ZPPgz2EncFbxXIQkxEq", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "type": "document", "uploadedBy": "AfcpS6HbVjoXdMLZ6aF4Sfad", "filename": "employment-agreement-kw-2020.pdf", "url": "https://app.humaans.io/file/UJx97ZPPgz2EncFbxXIQkxEq", "isPublic": false, "variants": null, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Create a file The file create API must be used as a multipart form data instead of content type JSON in order to upload the files. Once the file is uploaded, it is typically then attached to the target object, such as person's `profilePhotoId` field, document's `fileId` field and so on. Files that are not attached to any resource get periodically deleted. `POST /api/files` ##### Parameters - `personId` · `string | null` ID of the person that this object is associated to. Set to the ID of the person that this file will be attached to. Set to `null` if it's a company wide `document`. - `type` · `string` · required The type of resource that uses the file. For uploads through the public API, use one of `profilePhoto`, `document`, `identityDocument`, `equipmentFile`, `leavingFile`. - `isPublic` · `boolean` Can the original file be accessed without authentication. ##### Returns Returns a file if the call succeeded. The call returns an error if parameters are invalid. ##### Request ```shell curl https://app.humaans.io/api/files \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X POST \ -F personId=NF28Pg0RN4xdDjZcocDiL9lz \ -F type=document \ -F @employment-agreement.pdf ``` ##### Response ```json { "id": "UJx97ZPPgz2EncFbxXIQkxEq", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "type": "document", "uploadedBy": "AfcpS6HbVjoXdMLZ6aF4Sfad", "filename": "employment-agreement-kw-2020.pdf", "url": "https://app.humaans.io/file/UJx97ZPPgz2EncFbxXIQkxEq", "isPublic": false, "variants": null, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` ### Identity document types An object representing a type of an identity document. This resource is used to find out the list of all identity types that are in use in the account. #### Endpoints ```http GET /api/identity-document-types ``` #### Required scopes - `documents:read` #### Identity document type object ##### Attributes - `id` · `string` Unique identifier for the object. - `value` · `string` The label of the identity document type. ##### Example ```json { "id": "yI3rZlTcWBvn3F4ChC5d1X2b", "value": "Passport" } ``` #### List all identity document types Returns a list of identity document types. `GET /api/identity-document-types` ##### Parameters - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` identity document types. The response skips the first `$skip` results. Each entry is a separate identity document type object. If no identity document types are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/identity-document-types \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "yI3rZlTcWBvn3F4ChC5d1X2b", "value": "Passport" } ] } ``` ### Identity documents An object representing an identity (or identification) document of an employee. #### Endpoints ```http 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` · `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](#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` · `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` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. ##### Example ```json { "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. `GET /api/identity-documents` ##### Parameters - `personId` · `string · $eq $ne $in $nin` The person to filter queries by. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter identity documents by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` identity documents. The response skips the first `$skip` results. Each entry is a separate identity document object. If no identity documents are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/identity-documents \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/identity-documents/:id` ##### Parameters _None._ ##### Returns Returns an identity document object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/identity-documents/a0M0OIrmNIQe7UP5AaPxv9jN \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 `POST /api/identity-documents` ##### 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` · `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. ##### Request ```shell 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 ```json { "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 `PATCH /api/identity-documents/:id` ##### 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` · `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. ##### Request ```shell 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 ```json { "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. `DELETE /api/identity-documents/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/identity-documents/a0M0OIrmNIQe7UP5AaPxv9jN \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "a0M0OIrmNIQe7UP5AaPxv9jN", "deleted": true } ``` ### Job library levels A job library level is a seniority or rank within a career track, for example "Senior". Levels in different tracks that share the same `grade` are considered equivalent. Levels are combined with roles to form job library profiles. #### Endpoints ```http GET /api/job-library-levels GET /api/job-library-levels/:id POST /api/job-library-levels PATCH /api/job-library-levels/:id DELETE /api/job-library-levels/:id ``` #### Required scopes - `jobLibrary:read` - `jobLibrary:write` #### Job library level object ##### Attributes - `id` · `string` Unique identifier for the object. - `track` · `string` The career track this level belongs to, e.g. "Professional". - `name` · `string` The name of the level, e.g. "Senior". - `code` · `string` A short code for the level, e.g. "L5" or "M3". - `grade` · `integer` A company-wide grade shared across tracks. Levels in different tracks with the same `grade` are considered equivalent (e.g. "M1" and "L3"). - `status` · `string` Whether the level is `active` or `archived`. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` The date and time the level was deleted. Only present on deleted levels, which are only returned when querying with `$includeDeleted`. ##### Example ```json { "id": "y03tuSYgIN4v9R3eNQCrw31i", "track": "Professional", "name": "Senior", "code": "L5", "grade": 5, "status": "active", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` #### List all job library levels Returns a list of job library levels. `GET /api/job-library-levels` ##### Parameters - `id` · `string · $in` The ID of the level. - `status` · `string` Filter levels by status. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter levels by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$select` · `string[]` - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` job library levels. The response skips the first `$skip` results. Each entry is a separate job library level object. If no job library levels are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/job-library-levels \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "y03tuSYgIN4v9R3eNQCrw31i", "track": "Professional", "name": "Senior", "code": "L5", "grade": 5, "status": "active", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ] } ``` #### Retrieve a job library level Retrieves the job library level with the given ID. `GET /api/job-library-levels/:id` ##### Parameters _None._ ##### Returns Returns a job library level object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/job-library-levels/y03tuSYgIN4v9R3eNQCrw31i \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "y03tuSYgIN4v9R3eNQCrw31i", "track": "Professional", "name": "Senior", "code": "L5", "grade": 5, "status": "active", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` #### Create a job library level `POST /api/job-library-levels` ##### Parameters - `track` · `string` · required The career track this level belongs to, e.g. "Professional". - `name` · `string` · required The name of the level, e.g. "Senior". - `code` · `string | null` A short code for the level, e.g. "L5" or "M3". - `grade` · `integer` · required A company-wide grade shared across tracks. Levels in different tracks with the same `grade` are considered equivalent (e.g. "M1" and "L3"). - `status` · `string` Whether the level is `active` or `archived`. ##### Returns Returns a job library level if the call succeeded. The call returns an error if parameters are invalid. ##### Request ```shell curl https://app.humaans.io/api/job-library-levels \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X POST \ -d '{"track":"Professional","name":"Senior","grade":5}' ``` ##### Response ```json { "id": "y03tuSYgIN4v9R3eNQCrw31i", "track": "Professional", "name": "Senior", "code": "L5", "grade": 5, "status": "active", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` #### Update a job library level `PATCH /api/job-library-levels/:id` ##### Parameters - `track` · `string` The career track this level belongs to, e.g. "Professional". - `name` · `string` The name of the level, e.g. "Senior". - `code` · `string | null` A short code for the level, e.g. "L5" or "M3". - `grade` · `integer` A company-wide grade shared across tracks. Levels in different tracks with the same `grade` are considered equivalent (e.g. "M1" and "L3"). - `status` · `string` Whether the level is `active` or `archived`. ##### Returns Returns the job library level if the update succeeded. The call returns an error if parameters are invalid. ##### Request ```shell curl https://app.humaans.io/api/job-library-levels/y03tuSYgIN4v9R3eNQCrw31i \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X PATCH \ -d '{}' ``` ##### Response ```json { "id": "y03tuSYgIN4v9R3eNQCrw31i", "track": "Professional", "name": "Senior", "code": "L5", "grade": 5, "status": "active", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` #### Delete a job library level Permanently deletes a job library level. It cannot be undone. `DELETE /api/job-library-levels/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/job-library-levels/y03tuSYgIN4v9R3eNQCrw31i \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "y03tuSYgIN4v9R3eNQCrw31i", "deleted": true } ``` ### Job library profiles A job library profile joins one job library role and one job library level into an assignable job profile, for example "Senior Software Engineer". A profile can be linked to a person via the `jobLibraryProfileId` field on their job role. #### Endpoints ```http GET /api/job-library-profiles GET /api/job-library-profiles/:id POST /api/job-library-profiles PATCH /api/job-library-profiles/:id DELETE /api/job-library-profiles/:id ``` #### Required scopes - `jobLibrary:read` - `jobLibrary:write` #### Job library profile object ##### Attributes - `id` · `string` Unique identifier for the object. - `jobLibraryRoleId` · `string` The job library role this profile is based on. - `jobLibraryLevelId` · `string` The job library level this profile is based on. - `code` · `string` Stable profile code. - `jobTitle` · `string` Main display title shown in the directory. - `externalTitle` · `string` Public/recruiting title. - `description` · `string` Optional profile description. - `status` · `string` Current status of the job profile. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` The date and time the profile was deleted. Only present on deleted profiles, which are only returned when querying with `$includeDeleted`. ##### Example ```json { "id": "QQX6J5Mu8wgmBjlDH6FLqnX0", "jobLibraryRoleId": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "jobLibraryLevelId": "Kx2mR8nQvT5wY7bH3cF6dJ9p", "code": "SSE", "jobTitle": "Senior Software Engineer", "externalTitle": "Senior Software Engineer", "description": "Designs and builds core product features end to end.", "status": "active", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` #### List all job library profiles Returns a list of job library profiles. `GET /api/job-library-profiles` ##### Parameters - `id` · `string · $in` The ID of the profile. - `jobLibraryLevelId` · `string` The job library level this profile is based on. - `jobLibraryRoleId` · `string` The job library role this profile is based on. - `status` · `string` Current status of the job profile. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter profiles by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$select` · `string[]` - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` job library profiles. The response skips the first `$skip` results. Each entry is a separate job library profile object. If no job library profiles are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/job-library-profiles \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "QQX6J5Mu8wgmBjlDH6FLqnX0", "jobLibraryRoleId": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "jobLibraryLevelId": "Kx2mR8nQvT5wY7bH3cF6dJ9p", "code": "SSE", "jobTitle": "Senior Software Engineer", "externalTitle": "Senior Software Engineer", "description": "Designs and builds core product features end to end.", "status": "active", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ] } ``` #### Retrieve a job library profile Retrieves the job library profile with the given ID. `GET /api/job-library-profiles/:id` ##### Parameters _None._ ##### Returns Returns a job library profile object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/job-library-profiles/QQX6J5Mu8wgmBjlDH6FLqnX0 \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "QQX6J5Mu8wgmBjlDH6FLqnX0", "jobLibraryRoleId": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "jobLibraryLevelId": "Kx2mR8nQvT5wY7bH3cF6dJ9p", "code": "SSE", "jobTitle": "Senior Software Engineer", "externalTitle": "Senior Software Engineer", "description": "Designs and builds core product features end to end.", "status": "active", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` #### Create a job library profile `POST /api/job-library-profiles` ##### Parameters - `jobLibraryRoleId` · `string` · required The job library role this profile is based on. - `jobLibraryLevelId` · `string` · required The job library level this profile is based on. - `code` · `string` · required Stable profile code. - `jobTitle` · `string` · required Main display title shown in the directory. - `externalTitle` · `string | null` Public/recruiting title. - `description` · `string | null` Optional profile description. - `status` · `string` Current status of the job profile. ##### Returns Returns a job library profile if the call succeeded. The call returns an error if parameters are invalid. ##### Request ```shell curl https://app.humaans.io/api/job-library-profiles \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X POST \ -d '{"jobLibraryRoleId":"6iJcJ6aKIj1H4ubC4Zp0LlT6","jobLibraryLevelId":"Kx2mR8nQvT5wY7bH3cF6dJ9p","code":"SSE","jobTitle":"Senior Software Engineer"}' ``` ##### Response ```json { "id": "QQX6J5Mu8wgmBjlDH6FLqnX0", "jobLibraryRoleId": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "jobLibraryLevelId": "Kx2mR8nQvT5wY7bH3cF6dJ9p", "code": "SSE", "jobTitle": "Senior Software Engineer", "externalTitle": "Senior Software Engineer", "description": "Designs and builds core product features end to end.", "status": "active", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` #### Update a job library profile `PATCH /api/job-library-profiles/:id` ##### Parameters - `jobLibraryRoleId` · `string` The job library role this profile is based on. - `jobLibraryLevelId` · `string` The job library level this profile is based on. - `code` · `string` Stable profile code. - `jobTitle` · `string` Main display title shown in the directory. - `externalTitle` · `string | null` Public/recruiting title. - `description` · `string | null` Optional profile description. - `status` · `string` Current status of the job profile. ##### Returns Returns the job library profile if the update succeeded. The call returns an error if parameters are invalid. ##### Request ```shell curl https://app.humaans.io/api/job-library-profiles/QQX6J5Mu8wgmBjlDH6FLqnX0 \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X PATCH \ -d '{}' ``` ##### Response ```json { "id": "QQX6J5Mu8wgmBjlDH6FLqnX0", "jobLibraryRoleId": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "jobLibraryLevelId": "Kx2mR8nQvT5wY7bH3cF6dJ9p", "code": "SSE", "jobTitle": "Senior Software Engineer", "externalTitle": "Senior Software Engineer", "description": "Designs and builds core product features end to end.", "status": "active", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` #### Delete a job library profile Permanently deletes a job library profile. It cannot be undone. `DELETE /api/job-library-profiles/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/job-library-profiles/QQX6J5Mu8wgmBjlDH6FLqnX0 \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "QQX6J5Mu8wgmBjlDH6FLqnX0", "deleted": true } ``` ### Job library roles A job library role is a job function or family, for example "Software Engineer" within the "Engineering" function. Roles are combined with levels to form job library profiles. #### Endpoints ```http GET /api/job-library-roles GET /api/job-library-roles/:id POST /api/job-library-roles PATCH /api/job-library-roles/:id DELETE /api/job-library-roles/:id ``` #### Required scopes - `jobLibrary:read` - `jobLibrary:write` #### Job library role object ##### Attributes - `id` · `string` Unique identifier for the object. - `code` · `string` A stable code identifier for the role, e.g. "SWE". - `name` · `string` The name of the role, e.g. "Software Engineer". - `jobFunction` · `string` The job function this role belongs to, e.g. "Engineering". - `jobFamily` · `string` The job family this role belongs to, e.g. "Software Engineering". - `status` · `string` Whether the role is `active` or `archived`. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` The date and time the role was deleted. Only present on deleted roles, which are only returned when querying with `$includeDeleted`. ##### Example ```json { "id": "nEi45tsrWdbcJqxzaH8lA36H", "code": "SWE", "name": "Software Engineer", "jobFunction": "Engineering", "jobFamily": "Software Engineering", "status": "active", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` #### List all job library roles Returns a list of job library roles. `GET /api/job-library-roles` ##### Parameters - `id` · `string · $in` The ID of the role. - `status` · `string` Filter roles by status. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter roles by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$select` · `string[]` - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` job library roles. The response skips the first `$skip` results. Each entry is a separate job library role object. If no job library roles are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/job-library-roles \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "nEi45tsrWdbcJqxzaH8lA36H", "code": "SWE", "name": "Software Engineer", "jobFunction": "Engineering", "jobFamily": "Software Engineering", "status": "active", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ] } ``` #### Retrieve a job library role Retrieves the job library role with the given ID. `GET /api/job-library-roles/:id` ##### Parameters _None._ ##### Returns Returns a job library role object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/job-library-roles/nEi45tsrWdbcJqxzaH8lA36H \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "nEi45tsrWdbcJqxzaH8lA36H", "code": "SWE", "name": "Software Engineer", "jobFunction": "Engineering", "jobFamily": "Software Engineering", "status": "active", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` #### Create a job library role `POST /api/job-library-roles` ##### Parameters - `code` · `string` · required A stable code identifier for the role, e.g. "SWE". - `name` · `string` · required The name of the role, e.g. "Software Engineer". - `jobFunction` · `string` · required The job function this role belongs to, e.g. "Engineering". - `jobFamily` · `string` · required The job family this role belongs to, e.g. "Software Engineering". - `status` · `string` Whether the role is `active` or `archived`. ##### Returns Returns a job library role if the call succeeded. The call returns an error if parameters are invalid. ##### Request ```shell curl https://app.humaans.io/api/job-library-roles \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X POST \ -d '{"code":"SWE","name":"Software Engineer","jobFunction":"Engineering","jobFamily":"Software Engineering"}' ``` ##### Response ```json { "id": "nEi45tsrWdbcJqxzaH8lA36H", "code": "SWE", "name": "Software Engineer", "jobFunction": "Engineering", "jobFamily": "Software Engineering", "status": "active", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` #### Update a job library role `PATCH /api/job-library-roles/:id` ##### Parameters - `code` · `string` A stable code identifier for the role, e.g. "SWE". - `name` · `string` The name of the role, e.g. "Software Engineer". - `jobFunction` · `string` The job function this role belongs to, e.g. "Engineering". - `jobFamily` · `string` The job family this role belongs to, e.g. "Software Engineering". - `status` · `string` Whether the role is `active` or `archived`. ##### Returns Returns the job library role if the update succeeded. The call returns an error if parameters are invalid. ##### Request ```shell curl https://app.humaans.io/api/job-library-roles/nEi45tsrWdbcJqxzaH8lA36H \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X PATCH \ -d '{}' ``` ##### Response ```json { "id": "nEi45tsrWdbcJqxzaH8lA36H", "code": "SWE", "name": "Software Engineer", "jobFunction": "Engineering", "jobFamily": "Software Engineering", "status": "active", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` #### Delete a job library role Permanently deletes a job library role. It cannot be undone. `DELETE /api/job-library-roles/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/job-library-roles/nEi45tsrWdbcJqxzaH8lA36H \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "nEi45tsrWdbcJqxzaH8lA36H", "deleted": true } ``` ### Job roles An object representing the role of an employee at a company. Employees always have a role that is currently in effect and optionally some past roles. #### Endpoints ```http 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 - `jobLibrary:read` - `private:read` - `public:read` - `private:write` #### Job role object ##### Attributes - `id` · `string` Unique identifier for the object. - `personId` · `string` ID of the person that this object is associated to. - `jobTitle` · `string` Job title. - `department` · `string` The name of the department. - `effectiveDate` · `date` The date when this role took effect. Can be a past or future date. - `endDate` · `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. - `jobLibraryProfileId` · `string` The job library profile this role is linked to. - `jobLibraryLevelId` · `string` The ID of the job library level this role is linked to through its profile. - `jobLibraryLevelCode` · `string` The code of the job library level this role is linked to through its profile. - `jobLibraryLevelName` · `string` The name of the job library level this role is linked to through its profile. - `jobLibraryLevelTrack` · `string` The career track of the job library level this role is linked to through its profile. - `jobLibraryLevelGrade` · `integer` The grade of the job library level this role is linked to through its profile. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` The date and time this job role was deleted. Only present on deleted job roles, which are only returned when querying with `$includeDeleted`. ##### Example ```json { "id": "hmA5GnUq9ojK86LLKKWbiuKG", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "jobTitle": "Software Engineer", "department": "Engineering", "effectiveDate": "2020-02-15", "endDate": "2020-02-22", "reportingTo": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "note": "Switched departments", "jobLibraryProfileId": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "jobLibraryLevelId": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "jobLibraryLevelCode": "L5", "jobLibraryLevelName": "Senior", "jobLibraryLevelTrack": "Professional", "jobLibraryLevelGrade": 5, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` #### List all job roles Returns a list of job roles. `GET /api/job-roles` ##### Parameters - `department` · `string | empty` Filter job roles by department name, or null to find roles with no department. Each role is matched against the department in effect on $asOf, or on the role's own effectiveDate when $asOf is omitted. Where departments form a hierarchy, a role in a sub-department also matches its parent. Use with $asOf to get current roles in a department. - `effectiveDate` · `date | date-time · $gt $gte $lt $lte` Filter job roles by the date the role takes or took effect. Dates may be past or future. - `personId` · `string · $in` The person to filter queries by. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter job roles by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$asOf` · `date` Filter the list to at most one role per employee, finding the job role that was in effect on the provided date. Cannot be combined with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.effectiveDate` · `number` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` job roles. The response skips the first `$skip` results. Each entry is a separate job role object. If no job roles are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/job-roles \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "hmA5GnUq9ojK86LLKKWbiuKG", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "jobTitle": "Software Engineer", "department": "Engineering", "effectiveDate": "2020-02-15", "endDate": "2020-02-22", "reportingTo": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "note": "Switched departments", "jobLibraryProfileId": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "jobLibraryLevelId": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "jobLibraryLevelCode": "L5", "jobLibraryLevelName": "Senior", "jobLibraryLevelTrack": "Professional", "jobLibraryLevelGrade": 5, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ] } ``` #### Retrieve a job role Retrieves the job role with the given ID. `GET /api/job-roles/:id` ##### Parameters _None._ ##### Returns Returns a job role object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/job-roles/hmA5GnUq9ojK86LLKKWbiuKG \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "hmA5GnUq9ojK86LLKKWbiuKG", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "jobTitle": "Software Engineer", "department": "Engineering", "effectiveDate": "2020-02-15", "endDate": "2020-02-22", "reportingTo": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "note": "Switched departments", "jobLibraryProfileId": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "jobLibraryLevelId": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "jobLibraryLevelCode": "L5", "jobLibraryLevelName": "Senior", "jobLibraryLevelTrack": "Professional", "jobLibraryLevelGrade": 5, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` #### Create a job role An employee can have any number of job roles. The role in effect is the one with the latest `effectiveDate` that is not in the future. To keep an accurate history, create a new role when a job title, manager or other part of the role changes, rather than editing the existing one. Custom values are not copied from the previous role, so include them in `customValues`. `POST /api/job-roles` ##### 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` · `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. - `jobLibraryProfileId` · `string | null` The job library profile this role is linked to. - `customValues` · `object[]` - `customValues.customFieldId` · `string` · required - `customValues.value` · `string | string[]` · required - `customValues.resourceId` ##### Returns Returns a job role if the call succeeded. The call returns an error if parameters are invalid. ##### Request ```shell 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 ```json { "id": "hmA5GnUq9ojK86LLKKWbiuKG", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "jobTitle": "Product Engineer", "department": "Engineering", "effectiveDate": "2020-02-15", "endDate": "2020-02-22", "reportingTo": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "note": "Switched departments", "jobLibraryProfileId": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "jobLibraryLevelId": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "jobLibraryLevelCode": "L5", "jobLibraryLevelName": "Senior", "jobLibraryLevelTrack": "Professional", "jobLibraryLevelGrade": 5, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` #### Update a job role Updates the job role object. Note, that to preserve accurate records and history typically you want to create new roles instead of editing existing ones when job titles, managers or other aspects of the role change. `PATCH /api/job-roles/:id` ##### Parameters - `jobTitle` · `string` Job title. - `department` · `string | null` The name of the department. - `effectiveDate` · `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. - `jobLibraryProfileId` · `string | null` The job library profile this role is linked to. ##### Returns Returns the job role if the update succeeded. The call returns an error if parameters are invalid. ##### Request ```shell 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 ```json { "id": "hmA5GnUq9ojK86LLKKWbiuKG", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "jobTitle": "Product Engineer", "department": "Engineering", "effectiveDate": "2020-02-15", "endDate": "2020-02-22", "reportingTo": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "note": "Switched departments", "jobLibraryProfileId": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "jobLibraryLevelId": "6iJcJ6aKIj1H4ubC4Zp0LlT6", "jobLibraryLevelCode": "L5", "jobLibraryLevelName": "Senior", "jobLibraryLevelTrack": "Professional", "jobLibraryLevelGrade": 5, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` #### Delete a job role Permanently deletes a job role. It cannot be undone. Note that every employee must have at least one job role, deleting the last job role is going to return an error. `DELETE /api/job-roles/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/job-roles/hmA5GnUq9ojK86LLKKWbiuKG \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "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 ```http GET /api/locations GET /api/locations/:id POST /api/locations PATCH /api/locations/:id DELETE /api/locations/:id ``` #### Required scopes - `public:read` - `private:write` #### Location object ##### Attributes - `id` · `string` Unique identifier for the object. - `companyId` · `string` ID of the company that this object is associated to. - `label` · `string` A label for this location that is used to refer to the location. - `displayName` · `string` - `code` · `string` A short unique code for this location, e.g. an identifier used in payroll or other external systems. - `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. - `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` · `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` · `date` When provided, working pattern changes will be effective from this date. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` ##### Example ```json { "id": "oIBBB436k2YCOY5gzVhC5idx", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "label": "Acme HQ", "displayName": "Acme HQ", "code": "LON", "address": "Uncommon, 22 Curved Road", "postcode": "SE1 5AG", "city": "London", "state": null, "country": "United Kingdom", "regionCode": null, "countryCode": "GB", "timezone": "Europe/London", "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. `GET /api/locations` ##### Parameters - `code` · `string · $in` Filter locations by code. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter locations by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` locations. The response skips the first `$skip` results. Each entry is a separate location object. If no locations are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/locations \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "oIBBB436k2YCOY5gzVhC5idx", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "label": "Acme HQ", "displayName": "Acme HQ", "code": "LON", "address": "Uncommon, 22 Curved Road", "postcode": "SE1 5AG", "city": "London", "state": null, "country": "United Kingdom", "regionCode": null, "countryCode": "GB", "timezone": "Europe/London", "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. `GET /api/locations/:id` ##### Parameters _None._ ##### Returns Returns a location object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/locations/oIBBB436k2YCOY5gzVhC5idx \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "oIBBB436k2YCOY5gzVhC5idx", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "label": "Acme HQ", "displayName": "Acme HQ", "code": "LON", "address": "Uncommon, 22 Curved Road", "postcode": "SE1 5AG", "city": "London", "state": null, "country": "United Kingdom", "regionCode": null, "countryCode": "GB", "timezone": "Europe/London", "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 `POST /api/locations` ##### 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. - `code` · `string | null` A short unique code for this location, e.g. an identifier used in payroll or other external systems. - `timeAwayPolicyId` · `string | null` 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` · `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` · `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. ##### Request ```shell curl https://app.humaans.io/api/locations \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X POST \ -d '{"city":"London","countryCode":"GB"}' ``` ##### Response ```json { "id": "oIBBB436k2YCOY5gzVhC5idx", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "label": "Acme HQ", "displayName": "Acme HQ", "code": "LON", "address": "Uncommon, 22 Curved Road", "postcode": "SE1 5AG", "city": "London", "state": null, "country": "United Kingdom", "regionCode": null, "countryCode": "GB", "timezone": "Europe/London", "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 `PATCH /api/locations/:id` ##### 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. - `code` · `string | null` A short unique code for this location, e.g. an identifier used in payroll or other external systems. - `timeAwayPolicyId` · `string | null` 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` · `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` · `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. ##### Request ```shell curl https://app.humaans.io/api/locations/oIBBB436k2YCOY5gzVhC5idx \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X PATCH \ -d '{"city":"Quebec"}' ``` ##### Response ```json { "id": "oIBBB436k2YCOY5gzVhC5idx", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "label": "Acme HQ", "displayName": "Acme HQ", "code": "LON", "address": "Uncommon, 22 Curved Road", "postcode": "SE1 5AG", "city": "Quebec", "state": null, "country": "United Kingdom", "regionCode": null, "countryCode": "GB", "timezone": "Europe/London", "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. `DELETE /api/locations/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/locations/oIBBB436k2YCOY5gzVhC5idx \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "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](#people) to retrieve this object. #### Endpoints ```http 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 in 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. It can be either the ID of a location or the string literal `remote`, in which case it indicates this person works remotely and the working location can be found in the `remoteCity`, `remoteRegionCode` and `remoteCountryCode` fields. - `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. - `shortBirthday` · `string` Birthday month and day in MM-DD format, omitted when birthday announcements are hidden or the caller cannot read birthdays. - `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` URLs for the predefined profile photo sizes, keyed by width in pixels. Available widths: 64, 96, 104, 136, 156, 204, 320, and 480. - `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` · `date` Employment start date. - `firstWorkingDay` · `date` The first day at work. Defaults to `employmentStartDate` if not specified. - `employmentEndDate` · `date` Employment end date. If this date is in the past, this employee is considered to be offboarded and inactive. - `lastWorkingDay` · `date` The last day at work. Defaults to `employmentEndDate` if not specified. - `probationEndDate` · `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. - `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. - `isBirthdayHidden` · `boolean` Whether this person has opted out from birthday announcements. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. ##### Example ```json { "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", "shortBirthday": "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", "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. `GET /api/me` ##### Parameters _None._ ##### Returns Returns the currently logged in person object. ##### Request ```shell curl https://app.humaans.io/api/me \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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", "shortBirthday": "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", "source": null, "sourceId": null, "timezone": "Europe/London", "payrollProvider": null, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` ### Org hierarchies An org hierarchy is a way of grouping people in your organisation, for example by department or by team. Each hierarchy is made up of one or more org unit types (its layers). #### Endpoints ```http GET /api/org-hierarchies GET /api/org-hierarchies/:id ``` #### Required scopes - `orgModel:read` #### Org hierarchy object ##### Attributes - `id` · `string` Unique identifier for the object. - `name` · `string` The name of the hierarchy. - `code` · `string` A user specified code for the hierarchy, `null` if not set. - `isPrimary` · `boolean` Whether this is the primary hierarchy for the company. Exactly one hierarchy is primary. - `orgUnitTypes` · `object[]` The types of org units which can appear in this hierarchy, returned in hierarchical order. - `orgUnitTypes.id` · `string` Unique identifier for the org unit type. - `orgUnitTypes.code` · `string` A user specified code for the org unit type. - `orgUnitTypes.name` · `string` The name of the org unit type. - `reportingRole` · `string` The name of the role people report up to in this hierarchy. `null` when the hierarchy has no lead field. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` The date and time the hierarchy was deleted. Only present on deleted hierarchies, which are only returned when querying with `$includeDeleted`. ##### Example ```json { "id": "Nyilss56MOoMjRDgXz2SNQWW", "name": "Departments", "code": "department", "isPrimary": true, "orgUnitTypes": [ { "id": "T7uqPFK7am4lFTZm39AmNuay", "code": "department", "name": "Department" } ], "reportingRole": "Manager", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### List all org hierarchies Returns a list of org hierarchies. `GET /api/org-hierarchies` ##### Parameters - `isPrimary` · `boolean` Whether this is the primary hierarchy for the company. Exactly one hierarchy is primary. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter by createdAt. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` org hierarchies. The response skips the first `$skip` results. Each entry is a separate org hierarchy object. If no org hierarchies are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/org-hierarchies \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "Nyilss56MOoMjRDgXz2SNQWW", "name": "Departments", "code": "department", "isPrimary": true, "orgUnitTypes": [ { "id": "T7uqPFK7am4lFTZm39AmNuay", "code": "department", "name": "Department" } ], "reportingRole": "Manager", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ] } ``` #### Retrieve an org hierarchy Retrieves the org hierarchy with the given ID. `GET /api/org-hierarchies/:id` ##### Parameters _None._ ##### Returns Returns an org hierarchy object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/org-hierarchies/Nyilss56MOoMjRDgXz2SNQWW \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "Nyilss56MOoMjRDgXz2SNQWW", "name": "Departments", "code": "department", "isPrimary": true, "orgUnitTypes": [ { "id": "T7uqPFK7am4lFTZm39AmNuay", "code": "department", "name": "Department" } ], "reportingRole": "Manager", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` ### Org unit assignments An org unit assignment records that a person belongs to an org unit over a period of time. Listing them returns the full timeline by default, including past and future assignments — pass `$asOf` to narrow to a given date. #### Endpoints ```http GET /api/org-unit-assignments GET /api/org-unit-assignments/:id ``` #### Required scopes - `orgModel:read` #### Org unit assignment object ##### Attributes - `id` · `string` Unique identifier for the object. - `personId` · `string` The id of the person this assignment belongs to. - `orgUnitId` · `string` The id of the org unit the person is assigned to. - `effectiveDate` · `date` The date when this assignment took effect. Can be a past or future date. - `endDate` · `date` The date when this assignment ends, `null` if this is the last assignment. - `orgHierarchyId` · `string` The id of the hierarchy this assignment belongs to. - `isPrimaryHierarchy` · `boolean` Whether this assignment belongs to the company’s primary hierarchy. - `isPrimaryAssignment` · `boolean` Whether this is the person’s primary assignment within this hierarchy. At most one assignment is primary per person per hierarchy at any point in time. - `reportingTo` · `string` The id of the person this assignment reports into. See `reportingRelationship` below for more details. - `reportingRelationship` · `object` Details on the reporting role this assignment reports into, and how that role was resolved. `null` when the hierarchy has no reporting role. - `reportingRelationship.name` · `string` The name of the reporting role. - `reportingRelationship.source` · `object` Where `reportingTo` resolved from. `null` when there is no reporting leader. - `reportingRelationship.source.type` · `string` `direct` when `reportingTo` is specified by the org unit, `inherited` when it comes from an ancestor org unit, and `individualOverride` when this person has their own value for the reporting role. - `reportingRelationship.source.orgUnitId` · `string` The org unit the value applies to. The assigned unit itself for `direct` and `individualOverride`, otherwise the ancestor the value was inherited from. - `createdAt` · `date-time` The date and time this assignment was created. - `updatedAt` · `date-time` The date and time this assignment was last updated. - `deletedAt` · `date-time` The date and time this assignment was deleted. Only present on deleted assignments, which are only returned when querying with `$includeDeleted`. ##### Example ```json { "id": "x3F5Q3cPpSHg1p53bAwZPVFv", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "orgUnitId": "Nyilss56MOoMjRDgXz2SNQWW", "effectiveDate": "2020-02-15", "endDate": null, "orgHierarchyId": "Nyilss56MOoMjRDgXz2SNQWW", "isPrimaryHierarchy": true, "isPrimaryAssignment": true, "reportingTo": "IL3vneCYhIx0xrR6um2sy2nW", "reportingRelationship": { "source": {} }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### List all org unit assignments Returns a list of org unit assignments. `GET /api/org-unit-assignments` ##### Parameters - `effectiveDate` · `date | date-time · $gt $gte $lt $lte` The date when this assignment took effect. Can be a past or future date. - `isPrimaryAssignment` · `boolean` Restrict the assignments to only the primary ones, or only the non-primary ones. - `isPrimaryHierarchy` · `boolean` · at most one of orgHierarchyId or isPrimaryHierarchy Restrict the assignments to the company’s primary hierarchy, or to every hierarchy except it. Cannot be combined with `orgHierarchyId`. - `orgHierarchyId` · `string · $eq $ne $in $nin` · at most one of orgHierarchyId or isPrimaryHierarchy The id of the hierarchy this assignment belongs to. - `orgUnitId` · `string · $eq $ne $in $nin` The id of the org unit the person is assigned to. - `personId` · `string · $in` The id of the person this assignment belongs to. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter by createdAt. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$asOf` · `date | empty` Restrict the assignments to those in effect on the given date. Cannot be combined with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.effectiveDate` · `number` - `$sort.orgUnitId` · `number` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` org unit assignments. The response skips the first `$skip` results. Each entry is a separate org unit assignment object. If no org unit assignments are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/org-unit-assignments \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "x3F5Q3cPpSHg1p53bAwZPVFv", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "orgUnitId": "Nyilss56MOoMjRDgXz2SNQWW", "effectiveDate": "2020-02-15", "endDate": null, "orgHierarchyId": "Nyilss56MOoMjRDgXz2SNQWW", "isPrimaryHierarchy": true, "isPrimaryAssignment": true, "reportingTo": "IL3vneCYhIx0xrR6um2sy2nW", "reportingRelationship": { "source": {} }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ] } ``` #### Retrieve an org unit assignment Retrieves the org unit assignment with the given ID. `GET /api/org-unit-assignments/:id` ##### Parameters _None._ ##### Returns Returns an org unit assignment object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/org-unit-assignments/x3F5Q3cPpSHg1p53bAwZPVFv \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "x3F5Q3cPpSHg1p53bAwZPVFv", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "orgUnitId": "Nyilss56MOoMjRDgXz2SNQWW", "effectiveDate": "2020-02-15", "endDate": null, "orgHierarchyId": "Nyilss56MOoMjRDgXz2SNQWW", "isPrimaryHierarchy": true, "isPrimaryAssignment": true, "reportingTo": "IL3vneCYhIx0xrR6um2sy2nW", "reportingRelationship": { "source": {} }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` ### Org units An org unit is a node in an org hierarchy, for example a specific department or team. The list is flat: `parentId` carries the tree shape within a hierarchy. #### Endpoints ```http GET /api/org-units GET /api/org-units/:id ``` #### Required scopes - `orgModel:read` #### Org unit object ##### Attributes - `id` · `string` Unique identifier for the object. - `orgUnitTypeId` · `string` The id of org unit type this unit belongs to - `name` · `string` The name of the org unit. Must not contain colons. - `code` · `string` A user specified code for the org unit. `null` when not set. - `description` · `string` Free text description of the org unit. - `parentId` · `string` The id of the parent org unit. `null` if this is a top level org unit. - `orgHierarchyId` · `string` The id of the org hierarchy this unit belongs to. - `reportingLeaderId` · `string` The id of the reporting lead for this org unit. - `reportingRelationship` · `object` The reporting role this unit reports into, and where the reporting leader resolved from. `null` when the hierarchy has no reporting role, in which case it produces no reporting at all. - `reportingRelationship.name` · `string` The name of the reporting role. - `reportingRelationship.source` · `object` Where `reportingLeaderId` resolved from. `null` when there is no reporting leader. - `reportingRelationship.source.type` · `string` `direct` when `reportingTo` is specified by the org unit and `inherited` when it comes from an ancestor org unit. - `reportingRelationship.source.orgUnitId` · `string` The org unit the value applies to. The org unit itself for `direct`, or otherwise the ancestor the value was inherited from. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` The date and time the org unit was deleted. Only present on deleted units, which are only returned when querying with `$includeDeleted`. ##### Example ```json { "id": "buMfTrl9M65AHakPANgNqfzP", "name": "Engineering", "code": "engineering", "parentId": null, "orgHierarchyId": "Nyilss56MOoMjRDgXz2SNQWW", "reportingLeaderId": "IL3vneCYhIx0xrR6um2sy2nW", "reportingRelationship": { "name": "Manager", "source": { "type": "direct", "orgUnitId": "Nyilss56MOoMjRDgXz2SNQWW" } }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` #### List all org units Returns a list of org units. `GET /api/org-units` ##### Parameters - `id` · `string · $eq $ne $in $nin` - `isPrimaryHierarchy` · `boolean` · at most one of orgHierarchyId or isPrimaryHierarchy Restrict the units to the company’s primary hierarchy, or to every hierarchy except it. Cannot be combined with `orgHierarchyId`. - `orgHierarchyId` · `string` · at most one of orgHierarchyId or isPrimaryHierarchy Restrict the units to a single org hierarchy. Units in every hierarchy are returned when omitted. Cannot be combined with `isPrimaryHierarchy`. - `orgUnitTypeId` · `string · $eq $ne $in $nin` The id of org unit type this unit belongs to - `parentId` · `string | empty` Restrict the units to the direct children of the given org unit. Pass an empty value to return only the top level units. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter by createdAt. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` org units. The response skips the first `$skip` results. Each entry is a separate org unit object. If no org units are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/org-units \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "buMfTrl9M65AHakPANgNqfzP", "name": "Engineering", "code": "engineering", "parentId": null, "orgHierarchyId": "Nyilss56MOoMjRDgXz2SNQWW", "reportingLeaderId": "IL3vneCYhIx0xrR6um2sy2nW", "reportingRelationship": { "name": "Manager", "source": { "type": "direct", "orgUnitId": "Nyilss56MOoMjRDgXz2SNQWW" } }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ] } ``` #### Retrieve an org unit Retrieves the org unit with the given ID. `GET /api/org-units/:id` ##### Parameters _None._ ##### Returns Returns an org unit object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/org-units/buMfTrl9M65AHakPANgNqfzP \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "buMfTrl9M65AHakPANgNqfzP", "name": "Engineering", "code": "engineering", "parentId": null, "orgHierarchyId": "Nyilss56MOoMjRDgXz2SNQWW", "reportingLeaderId": "IL3vneCYhIx0xrR6um2sy2nW", "reportingRelationship": { "name": "Manager", "source": { "type": "direct", "orgUnitId": "Nyilss56MOoMjRDgXz2SNQWW" } }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z", "deletedAt": null } ``` ### People An object representing an an employee at a company. The most important object in Humaans. #### Endpoints ```http GET /api/people GET /api/people/:id POST /api/people PATCH /api/people/:id DELETE /api/people/:id ``` #### Required scopes - `private:read` - `public:read` - `private:write` #### Person object ##### Attributes - `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 in 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. It can be either the ID of a location or the string literal `remote`, in which case it indicates this person works remotely and the working location can be found in the `remoteCity`, `remoteRegionCode` and `remoteCountryCode` fields. - `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. - `shortBirthday` · `string` Birthday month and day in MM-DD format, omitted when birthday announcements are hidden or the caller cannot read birthdays. - `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` URLs for the predefined profile photo sizes, keyed by width in pixels. Available widths: 64, 96, 104, 136, 156, 204, 320, and 480. - `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` · `date` Employment start date. - `firstWorkingDay` · `date` The first day at work. Defaults to `employmentStartDate` if not specified. - `employmentEndDate` · `date` Employment end date. If this date is in the past, this employee is considered to be offboarded and inactive. - `lastWorkingDay` · `date` The last day at work. Defaults to `employmentEndDate` if not specified. - `probationEndDate` · `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. - `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. - `isBirthdayHidden` · `boolean` Whether this person has opted out from birthday announcements. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. ##### Example ```json { "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", "shortBirthday": "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", "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](#filtering) documentation for further details on usage of `$in`. `GET /api/people` ##### Parameters - `email` · `string` Filter people by work email address. - `employmentEndDate` · `date | date-time · $gt $gte $lt $lte` Filter people by employment end date. - `employmentStartDate` · `date | date-time · $gt $gte $lt $lte` Filter people by employment start date. - `firstName` · `string · $ilike` Filter people by first name. Supports $ilike for case-insensitive matching. - `firstWorkingDay` · `date | date-time · $gt $gte $lt $lte` Filter people by first working day. - `gender` · `string · $eq $ne $in $nin $ilike` Filter people by gender (free-form value). Pass a string for an exact match, { "$in": [...] } for several values, or { "$ilike": "..." } for case-insensitive matching. - `include` · `string[]` Additional fields to include, not provided as part of the default payload. Supported values are: `isManager`. - `lastName` · `string · $ilike` Filter people by last name. Supports $ilike for case-insensitive matching. - `lastWorkingDay` · `date | date-time · $gt $gte $lt $lte` Filter people by last working day. - `payrollProvider` · `string · $eq $ne $in $nin` Filter people by payroll provider. - `personalEmail` · `string` Filter people by personal email address. - `preferredName` · `string · $ilike` Filter people by preferred name. Supports $ilike for case-insensitive matching. - `probationEndDate` · `date | date-time · $gt $gte $lt $lte` Filter people by probation end date. - `spaceId` · `string · $eq $ne $in $nin` Filter people by the ID of the Space they belong to. - `status` · `string · $in $nin` Filter people by status, one of `all`, `newHire`, `active`, `offboarded`. Default: `active`. - `teams` · `string · $any $not` Filter people by team. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter people by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$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` - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` people. The response skips the first `$skip` results. Each entry is a separate person object. If no people are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/people \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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", "shortBirthday": "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", "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. `GET /api/people/:id` ##### Parameters _None._ ##### Returns Returns a person object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/people/VMB1yzL5uL8VvNNCJc9rykJz \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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", "shortBirthday": "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", "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. `POST /api/people` ##### 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 in 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` · `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` · `date` · required Employment start date. - `firstWorkingDay` · `date` The first day at work. Defaults to `employmentStartDate` if not specified. - `employmentEndDate` · `date | null` Employment end date. If this date is in the past, this employee is considered to be offboarded and inactive. - `lastWorkingDay` · `date | null` The last day at work. Defaults to `employmentEndDate` if not specified. - `probationEndDate` · `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 | null` The ID of the location this person works at. It can be either the ID of a location or the string literal `remote`, in which case it indicates this person works remotely and the working location can be found in the `remoteCity`, `remoteRegionCode` and `remoteCountryCode` fields. - `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 | null` 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. - `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.jobLibraryProfileId` · `string | null` - `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. ##### Request ```shell 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","jobRole":{"jobTitle":"Software Engineer","department":"Engineering","reportingTo":"OfcRvv174ir3Y6mNA5bPXqeY"},"employmentStartDate":"2018-03-10"}' ``` ##### Response ```json { "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", "shortBirthday": "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", "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`. `PATCH /api/people/:id` ##### 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 in 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` · `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` · `date` Employment start date. - `firstWorkingDay` · `date` The first day at work. Defaults to `employmentStartDate` if not specified. - `employmentEndDate` · `date | null` Employment end date. If this date is in the past, this employee is considered to be offboarded and inactive. - `lastWorkingDay` · `date | null` The last day at work. Defaults to `employmentEndDate` if not specified. - `probationEndDate` · `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 | null` The ID of the location this person works at. It can be either the ID of a location or the string literal `remote`, in which case it indicates this person works remotely and the working location can be found in the `remoteCity`, `remoteRegionCode` and `remoteCountryCode` fields. - `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 | null` 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. - `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. ##### Request ```shell curl https://app.humaans.io/api/people/VMB1yzL5uL8VvNNCJc9rykJz \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X PATCH \ -d '{}' ``` ##### Response ```json { "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", "shortBirthday": "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", "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. `DELETE /api/people/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/people/VMB1yzL5uL8VvNNCJc9rykJz \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "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 ```http GET /api/performance-cycle-instances GET /api/performance-cycle-instances/:id ``` #### Required scopes - `performance:read` #### 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` · `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` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. ##### Example ```json { "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. `GET /api/performance-cycle-instances` ##### Parameters - `performanceCycleId` · `string · $eq $ne $in $nin` The ID of the performance cycle this instance belongs to. - `performanceCycleStatus` · `string · $eq $ne $in $nin` · at most one of status or performanceCycleStatus Filter by the status of the parent performance cycle. One of `draft`, `upcoming`, `active`, `completed`, `cancelled`. - `personId` · `string · $eq $ne $in $nin` The person to filter queries by. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` performance instances. The response skips the first `$skip` results. Each entry is a separate performance instance object. If no performance instances are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/performance-cycle-instances \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/performance-cycle-instances/:id` ##### Parameters _None._ ##### Returns Returns a performance instance object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/performance-cycle-instances/0I5qP2OqcopXEPRv3qz3LVXP \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "0I5qP2OqcopXEPRv3qz3LVXP", "performanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "releasedAt": "2026-03-01T12:00:00.000Z", "releasedBy": "T7uqPFK7am4lFTZm39AmNuBQ", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` ### Performance templates · Preview An object representing a review template within a performance cycle. Each template defines the form fields and configuration for a specific type of review. #### Endpoints ```http GET /api/performance-cycle-review-templates GET /api/performance-cycle-review-templates/:id ``` #### 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. A template may contain at most one `rating` field. - `fields.id` · `string` Unique identifier for this field. Used as the key in the responses object of performance reviews. - `fields.type` · `string` - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. ##### Example ```json { "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. `GET /api/performance-cycle-review-templates` ##### Parameters - `performanceCycleId` · `string · $eq $ne $in $nin` The ID of the performance cycle this review template belongs to. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter performance cycle review templates by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter performance cycle review templates by updated at date. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` performance templates. The response skips the first `$skip` results. Each entry is a separate performance template object. If no performance templates are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/performance-cycle-review-templates \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/performance-cycle-review-templates/:id` ##### Parameters _None._ ##### Returns Returns a performance template object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/performance-cycle-review-templates/PJIqTfdojEAWs8M4shG1x4eJ \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 ```http GET /api/performance-cycle-reviews GET /api/performance-cycle-reviews/:id ``` #### Required scopes - `performance:read` #### 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` · `date-time` The time at which this review was submitted. Null if not yet submitted or if changes have been requested. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. ##### Example ```json { "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. `GET /api/performance-cycle-reviews` ##### Parameters - `performanceCycleInstanceId` · `string · $eq $ne $in $nin` The ID of the performance cycle instance this review belongs to. - `performanceCycleStatus` · `string · $eq $ne $in $nin` Filter by the status of the parent performance cycle. One of `draft`, `upcoming`, `active`, `completed`, `cancelled`. - `subjectId` · `string · $eq $ne $in $nin` The ID of the person being reviewed. - `submittedAt` · `date-time · $ne` The time at which this review was submitted. Null if not yet submitted or if changes have been requested. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter performance cycle reviews by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter performance cycle reviews by updated at date. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` performance reviews. The response skips the first `$skip` results. Each entry is a separate performance review object. If no performance reviews are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/performance-cycle-reviews \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/performance-cycle-reviews/:id` ##### Parameters _None._ ##### Returns Returns a performance review object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/performance-cycle-reviews/aegY8UfWbpDonPFKhx6Z027o \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 ```http GET /api/performance-cycles GET /api/performance-cycles/:id ``` #### Required scopes - `performance:read` #### 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` · `date-time` Time at which the performance cycle was completed. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` ##### Example ```json { "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. `GET /api/performance-cycles` ##### Parameters - `status` · `string · $eq $ne $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 whose `data` property contains up to `$limit` performance cycles. The response skips the first `$skip` results. Each entry is a separate performance cycle object. If no performance cycles are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/performance-cycles \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/performance-cycles/:id` ##### Parameters _None._ ##### Returns Returns a performance cycle object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/performance-cycles/vxRe1WOEJP2KxKCBBaad9NFM \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "vxRe1WOEJP2KxKCBBaad9NFM", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "title": "Q1 2026 Performance Review", "status": "active", "previousPerformanceCycleId": "vxRe1WOEJP2KxKCBBaad9NFM", "completedAt": "2026-04-01T12:00:00.000Z", "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` ### Public holiday calendar days A resource representing a public holiday for a particular public holiday calendar day #### Endpoints ```http 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 DELETE /api/public-holiday-calendar-days/:id ``` #### Required scopes - `public:read` #### 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` · `date` The date of the public holiday. - `enabled` · `boolean` The toggle state of the public holiday - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` ##### Example ```json { "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 `GET /api/public-holiday-calendar-days` ##### Parameters - `date` The date of the public holiday. - `enabled` The toggle state of the public holiday - `publicHolidayCalendarId` · `string · $eq $ne $in $nin` Filter by the public holiday calendar ID. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter public holiday calendar days by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` Public holiday calendar days. The response skips the first `$skip` results. Each entry is a separate Public holiday calendar day object. If no Public holiday calendar days are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/public-holiday-calendar-days \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 `GET /api/public-holiday-calendar-days/:id` ##### Parameters _None._ ##### Returns Returns a Public holiday calendar day object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/public-holiday-calendar-days/MVvOIW2o1NLLtYga0REVbeeK \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 `POST /api/public-holiday-calendar-days` ##### Parameters - `name` · `string` · required The name of the public holiday. - `date` · `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. ##### Request ```shell 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 ```json { "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 `PATCH /api/public-holiday-calendar-days/:id` ##### Parameters - `name` · `string` The name of the public holiday. - `date` · `date` The date of the public holiday. - `enabled` · `boolean` The toggle state of the public holiday - `publicHolidayCalendarId` · `string` The ID of the public holiday calendar this public holiday is part of. ##### Returns Returns the Public holiday calendar day if the update succeeded. The call returns an error if parameters are invalid. ##### Request ```shell 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 ```json { "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" } ``` #### Delete a Public holiday calendar day Delete a public holiday calendar day `DELETE /api/public-holiday-calendar-days/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/public-holiday-calendar-days/MVvOIW2o1NLLtYga0REVbeeK \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "MVvOIW2o1NLLtYga0REVbeeK", "deleted": true } ``` ### Public holiday calendars A resource representing a public holiday calendar for a specific country or in some cases a region of a country. #### Endpoints ```http 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. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` ##### Example ```json { "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 `GET /api/public-holiday-calendars` ##### Parameters - `id` · `string · $eq $ne $in $nin` Filter by the public holiday calendar ID. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter public holiday calendars by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` public holiday calendars. The response skips the first `$skip` results. Each entry is a separate public holiday calendar object. If no public holiday calendars are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/public-holiday-calendars \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 ```http 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. ##### Example ```json { "id": "nk1kio8XMzUXY5eplJq7PrbI", "date": "2020-01-01", "name": "New year" } ``` #### List all public holidays Returns a list of public holidays. `GET /api/public-holidays` ##### Parameters - `date` · `date · $eq $ne $in $nin $gt $lt $gte $lte` · required Filter holidays by date. - `publicHolidayCalendarId` · `string · $eq $ne $in $nin` · required 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 whose `data` property contains up to `$limit` public holidays. The response skips the first `$skip` results. Each entry is a separate public holiday object. If no public holidays are available, `data` is empty. ##### Request ```shell curl 'https://app.humaans.io/api/public-holidays?publicHolidayCalendarId=DE-BE&date[$gte]=2020-01-01' \ -g \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "nk1kio8XMzUXY5eplJq7PrbI", "date": "2020-01-01", "name": "New year" } ] } ``` ### Spaces An object representing a space. Every user belongs to a single space. #### Endpoints ```http GET /api/spaces GET /api/spaces/:id POST /api/spaces PATCH /api/spaces/:id DELETE /api/spaces/:id ``` #### Required scopes - `public:read` #### Space object ##### Attributes - `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` URLs for the predefined logo sizes, keyed by width in pixels. Available widths: 64, 96, 104, 136, 156, 204, 320, and 480. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` ##### Example ```json { "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. `GET /api/spaces` ##### Parameters - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter spaces by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` spaces. The response skips the first `$skip` results. Each entry is a separate space object. If no spaces are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/spaces \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/spaces/:id` ##### Parameters _None._ ##### Returns Returns a space object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/spaces/kxXqtnaI6J6203RFuzrfdB7C \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 `POST /api/spaces` ##### Parameters - `name` · `string` · required ##### Returns Returns a space if the call succeeded. The call returns an error if parameters are invalid. ##### Request ```shell curl https://app.humaans.io/api/spaces \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X POST \ -d '{"name":"Contractors"}' ``` ##### Response ```json { "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 `PATCH /api/spaces/:id` ##### Parameters - `name` · `string` ##### Returns Returns the space if the update succeeded. The call returns an error if parameters are invalid. ##### Request ```shell curl https://app.humaans.io/api/spaces/kxXqtnaI6J6203RFuzrfdB7C \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X PATCH \ -d '{"name":"Contractors"}' ``` ##### Response ```json { "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. `DELETE /api/spaces/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/spaces/kxXqtnaI6J6203RFuzrfdB7C \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "kxXqtnaI6J6203RFuzrfdB7C", "deleted": true } ``` ### Time away An object representing a time away entry of an employee. Time away can be a time off entry, e.g. paid time off, sick leave, paternity leave, etc. Or it can be a working away entry, e.g. working from home, travelling for work, etc. #### Endpoints ```http GET /api/time-away GET /api/time-away/:id POST /api/time-away PATCH /api/time-away/:id DELETE /api/time-away/:id ``` #### Required scopes - `private:read` - `public:read` - `private:write` #### Time away object ##### Attributes - `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` · `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` · `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` · `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` · `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` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `timezone` · `string` The timezone of the personId when the booking was made ##### Example ```json { "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](#filtering) documentation for more details on usage. `GET /api/time-away` ##### Parameters - `endDate` · `date · $gt $gte $lt $lte` Filter by end date. - `personId` · `string · $in` The person to filter queries by. - `personStatus` · `string · $in` The person status to filter queries by. - `requestStatus` · `string · $in` Filter by request status. Useful when time away approvals are enabled. - `startDate` · `date · $gt $gte $lt $lte` Filter by start date. - `timeAwayTypeId` · `string` Filter by the time away type - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter by createdAt. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$or` · `object[]` Filter results by multiple criteria. - `$or.createdAt` · `date | date-time · $gt $gte $lt $lte` Filter by createdAt. - `$or.endDate` · `date · $gt $gte $lt $lte` Filter by end date. - `$or.personId` · `string · $in` The person to filter queries by. - `$or.personStatus` · `string · $in` The person status to filter queries by. - `$or.requestStatus` · `string · $in` Filter by request status. Useful when time away approvals are enabled. - `$or.startDate` · `date · $gt $gte $lt $lte` Filter by start date. - `$or.timeAwayTypeId` · `string` Filter by the time away type - `$or.type` · `string` Filter by time away type — one of the default type ids (`workingFromAnotherLocation`, `workingFromHome`, `training`, `travellingForWork`, `pto`, `compassionate`, `emergency`, `juryDuty`, `mentalHealth`, `parental`, `sabbatical`, `sick`, `toil`, `unpaid`, `volunteering`) or a company-specific time away type id. Unknown values match nothing. - `$sort` · `object` - `$sort.createdAt` · `number` - `$sort.endDate` · `number` - `$sort.startDate` · `number` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` time away. The response skips the first `$skip` results. Each entry is a separate time away object. If no time away are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/time-away \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/time-away/:id` ##### Parameters _None._ ##### Returns Returns a time away object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/time-away/YLlqHE4DLvGtFJ7L2qro6bTF \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 `POST /api/time-away` ##### Parameters - `personId` · `string` · required ID of the person that this object is associated to. - `startTime` · `string | null` · at most one of startTime or startPeriod If defined, specifies the start time for the time away booking in HH:MM:SS format. Applicable for same day bookings - `endTime` · `string | null` · at most one of endTime or startPeriod If defined, specifies the end time for the time away booking in HH:MM:SS format. Applicable for same day bookings - `startDate` · `date` · required The first date of the time away entry (inclusive). - `endDate` · `date` · required The last date of the time away entry (inclusive). - `startPeriod` · `string | null` · at most one of startPeriod or breakdown Indicates if the first date of the time away entry was taken in full or as half day. One of: `full` (when taking full day), `am` (when taking morning off) or `pm` (when taking afternoon off). Defaults to `full`. - `endPeriod` · `string | null` · at most one of startTime or endPeriod Indicates if the last date of the time away entry was taken in full or as half day. One of: `full` (when taking full day) or `am` (when taking morning off only). If `startDate` and `endDate` are the same, this should be the same as `startPeriod`. Defaults to `full`. - `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` · at most one of type or timeAwayTypeId 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. ##### Request ```shell 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 ```json { "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 `PATCH /api/time-away/:id` ##### Parameters - `startTime` · `string | null` · at most one of startTime or startPeriod If defined, specifies the start time for the time away booking in HH:MM:SS format. Applicable for same day bookings - `endTime` · `string | null` · at most one of endTime or startPeriod If defined, specifies the end time for the time away booking in HH:MM:SS format. Applicable for same day bookings - `startDate` · `date` The first date of the time away entry (inclusive). - `endDate` · `date` The last date of the time away entry (inclusive). - `startPeriod` · `string | null` · at most one of startPeriod or breakdown Indicates if the first date of the time away entry was taken in full or as half day. One of: `full` (when taking full day), `am` (when taking morning off) or `pm` (when taking afternoon off). Defaults to `full`. - `endPeriod` · `string | null` · at most one of startTime or endPeriod Indicates if the last date of the time away entry was taken in full or as half day. One of: `full` (when taking full day) or `am` (when taking morning off only). If `startDate` and `endDate` are the same, this should be the same as `startPeriod`. Defaults to `full`. - `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` · at most one of type or timeAwayTypeId 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. ##### Request ```shell 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 ```json { "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. `DELETE /api/time-away/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/time-away/YLlqHE4DLvGtFJ7L2qro6bTF \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "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 ```http GET /api/time-away-adjustments GET /api/time-away-adjustments/:id POST /api/time-away-adjustments PATCH /api/time-away-adjustments/:id DELETE /api/time-away-adjustments/:id ``` #### Required scopes - `private:read` - `private:write` #### Time away adjustment object ##### Attributes - `id` · `string` Unique identifier for the object. - `personId` · `string` ID of the person that this object is associated to. - `date` · `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` · `date` The date when the adjustment expires. - `timeAwayTypeId` · `string` ID of the Time away type this adjustment is attached to. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` ##### Example ```json { "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. `GET /api/time-away-adjustments` ##### Parameters - `date` · `date · $eq $ne $in $nin $gt $lt $gte $lte` Filter by end date. - `personId` · `string · $in` The person to filter queries by. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.createdAt` · `number` - `$sort.date` · `number` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` time away adjustments. The response skips the first `$skip` results. Each entry is a separate time away adjustment object. If no time away adjustments are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/time-away-adjustments \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/time-away-adjustments/:id` ##### Parameters _None._ ##### Returns Returns a time away adjustment object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/time-away-adjustments/BZJa63JpH4Bz25oM28zAbeoK \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 `POST /api/time-away-adjustments` ##### Parameters - `personId` · `string` · required ID of the person that this object is associated to. - `date` · `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` · `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. ##### Request ```shell 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 ```json { "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 `PATCH /api/time-away-adjustments/:id` ##### Parameters - `date` · `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` · `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. ##### Request ```shell curl https://app.humaans.io/api/time-away-adjustments/BZJa63JpH4Bz25oM28zAbeoK \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X PATCH \ -d '{}' ``` ##### Response ```json { "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. `DELETE /api/time-away-adjustments/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/time-away-adjustments/BZJa63JpH4Bz25oM28zAbeoK \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "BZJa63JpH4Bz25oM28zAbeoK", "deleted": true } ``` ### Time away allocations An object representing the mapping between an employee and a time away policy. To assign a specific time away policy to an employee an allocation with an `effectiveDate` is created and linked to a person (`personId`) and a time away policy (`timeAwayPolicyId`). Each person will often have only one allocation throughout their lifetime, but they can have multiple consecutive allocations when the company changes its time off policy or when the employee moves to a country, office or role with a different time off policy. #### Endpoints ```http GET /api/time-away-allocations GET /api/time-away-allocations/:id POST /api/time-away-allocations PATCH /api/time-away-allocations/:id DELETE /api/time-away-allocations/:id ``` #### Required scopes - `private:read` - `private:write` #### Time away allocation object ##### Attributes - `id` · `string` Unique identifier for the object. - `personId` · `string` ID of the person that this object is associated to. - `type` · `string` The type of allocation. One of: `placeOfWork`, `specific`, `custom`. Setting allocation `type` to `placeOfWork` will apply the time away policy based on the place of work of the employee. Setting it to `specific` requires providing the `timeAwayPolicyId` that should be applied. Setting to `custom` requires passing policy object in the `timeAwayPolicy` field. - `effectiveDate` · `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` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. ##### Example ```json { "id": "MfQQ2fWdXGD3hvZKrxm6zWE0", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "type": "placeOfWork", "effectiveDate": "2020-04-01", "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I", "timeAwayPolicy": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "name": "UK Policy", "timeAwayPolicyVersion": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "bypassWorkingSchedule": false, "bypassPublicHolidays": false, "publicHolidayCalendarId": "GB", "visibleBalances": [ "endOfYear" ], "rules": [ { "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa", "limits": { "yearlyAllowance": 30, "maxCarryOver": 5, "yearStart": "01-01", "yearStartType": "employmentStartDate", "isUnlimited": false, "isProrated": false, "maxBalance": 30, "preventNegativeBalance": false, "maxNegativeBalance": 5, "usage": "upfront", "usagePeriod": 12, "carryOverUsagePeriod": 3, "roundingType": "halfUp" } } ] }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### List all time away allocations Returns a list of time away allocations. `GET /api/time-away-allocations` ##### Parameters - `isCurrent` · `boolean` Return the current allocation only. - `personId` · `string` The person to filter queries by. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` time away allocations. The response skips the first `$skip` results. Each entry is a separate time away allocation object. If no time away allocations are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/time-away-allocations \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "MfQQ2fWdXGD3hvZKrxm6zWE0", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "type": "placeOfWork", "effectiveDate": "2020-04-01", "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I", "timeAwayPolicy": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "name": "UK Policy", "timeAwayPolicyVersion": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "bypassWorkingSchedule": false, "bypassPublicHolidays": false, "publicHolidayCalendarId": "GB", "visibleBalances": [ "endOfYear" ], "rules": [ { "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa", "limits": { "yearlyAllowance": 30, "maxCarryOver": 5, "yearStart": "01-01", "yearStartType": "employmentStartDate", "isUnlimited": false, "isProrated": false, "maxBalance": 30, "preventNegativeBalance": false, "maxNegativeBalance": 5, "usage": "upfront", "usagePeriod": 12, "carryOverUsagePeriod": 3, "roundingType": "halfUp" } } ] }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ] } ``` #### Retrieve a time away allocation Retrieves the time away allocation with the given ID. `GET /api/time-away-allocations/:id` ##### Parameters _None._ ##### Returns Returns a time away allocation object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/time-away-allocations/MfQQ2fWdXGD3hvZKrxm6zWE0 \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "MfQQ2fWdXGD3hvZKrxm6zWE0", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "type": "placeOfWork", "effectiveDate": "2020-04-01", "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I", "timeAwayPolicy": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "name": "UK Policy", "timeAwayPolicyVersion": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "bypassWorkingSchedule": false, "bypassPublicHolidays": false, "publicHolidayCalendarId": "GB", "visibleBalances": [ "endOfYear" ], "rules": [ { "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa", "limits": { "yearlyAllowance": 30, "maxCarryOver": 5, "yearStart": "01-01", "yearStartType": "employmentStartDate", "isUnlimited": false, "isProrated": false, "maxBalance": 30, "preventNegativeBalance": false, "maxNegativeBalance": 5, "usage": "upfront", "usagePeriod": 12, "carryOverUsagePeriod": 3, "roundingType": "halfUp" } } ] }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Create a time away allocation `POST /api/time-away-allocations` ##### 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` · `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. - `replaceInitialAllocation` · `boolean` Must be `true` to change the initial ("from employment start") allocation's policy. That allocation has no effective date and applies across the person's whole employment history, so replacing its policy rewrites all past leave. - `removeAllocations` · `boolean` ##### Returns Returns a time away allocation if the call succeeded. The call returns an error if parameters are invalid. ##### Request ```shell 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 ```json { "id": "MfQQ2fWdXGD3hvZKrxm6zWE0", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "type": "placeOfWork", "effectiveDate": "2020-04-30", "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I", "timeAwayPolicy": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "name": "UK Policy", "timeAwayPolicyVersion": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "bypassWorkingSchedule": false, "bypassPublicHolidays": false, "publicHolidayCalendarId": "GB", "visibleBalances": [ "endOfYear" ], "rules": [ { "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa", "limits": { "yearlyAllowance": 30, "maxCarryOver": 5, "yearStart": "01-01", "yearStartType": "employmentStartDate", "isUnlimited": false, "isProrated": false, "maxBalance": 30, "preventNegativeBalance": false, "maxNegativeBalance": 5, "usage": "upfront", "usagePeriod": 12, "carryOverUsagePeriod": 3, "roundingType": "halfUp" } } ] }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Update a time away allocation `PATCH /api/time-away-allocations/:id` ##### 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` · `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. - `replaceInitialAllocation` · `boolean` Must be `true` to change the initial ("from employment start") allocation's policy. That allocation has no effective date and applies across the person's whole employment history, so replacing its policy rewrites all past leave. ##### Returns Returns the time away allocation if the update succeeded. The call returns an error if parameters are invalid. ##### Request ```shell 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 ```json { "id": "MfQQ2fWdXGD3hvZKrxm6zWE0", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "type": "placeOfWork", "effectiveDate": "2020-04-30", "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I", "timeAwayPolicy": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "name": "UK Policy", "timeAwayPolicyVersion": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "bypassWorkingSchedule": false, "bypassPublicHolidays": false, "publicHolidayCalendarId": "GB", "visibleBalances": [ "endOfYear" ], "rules": [ { "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa", "limits": { "yearlyAllowance": 30, "maxCarryOver": 5, "yearStart": "01-01", "yearStartType": "employmentStartDate", "isUnlimited": false, "isProrated": false, "maxBalance": 30, "preventNegativeBalance": false, "maxNegativeBalance": 5, "usage": "upfront", "usagePeriod": 12, "carryOverUsagePeriod": 3, "roundingType": "halfUp" } } ] }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Delete a time away allocation Permanently deletes a time away allocation. It cannot be undone. `DELETE /api/time-away-allocations/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/time-away-allocations/MfQQ2fWdXGD3hvZKrxm6zWE0 \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "MfQQ2fWdXGD3hvZKrxm6zWE0", "deleted": true } ``` ### Time away periods Time away periods is used to find employee's time off allowance, remaining balance and many other useful attributes. Time away is sliced into periods and each period contains a summary. Typically a period year long starting on 1st of January and ending on 31st of December. But it can also start and end mid year in case it is the first period and the employee started working mid year, if the time away allocation was changed mid year, or if the employee is offboarded. For example, consider an employee that started employment on 2018-08-01 and left on 2020-03-15. Such an employee would have 3 periods: * `2018-08-01 - 2018-12-31` * `2019-01-01 - 2019-12-31` * `2020-01-01 - 2020-03-15` Each of these periods will contain allowance, accrued days, balance, adjustments, days taken and so on. The last period for active employees has the `isCurrentPeriod` attribute set to `true` and can be used to find the current status of the employee's time away. Note, that a policy can be configured to have a different year start than January 1st, in which case each period under that policy would start on the day configured in the policy. #### Endpoints ```http GET /api/time-away-periods ``` #### Required scopes - `private:read` #### Time away period object ##### Attributes - `id` · `string` Unique identifier for the object. - `personId` · `string` ID of the person that this object is associated to. - `startDate` · `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` · `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` · `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**. What has accrued by the `date` query parameter, or by `endDate` for past periods. - `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` · `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` · `date` The date at which `carriedOver` is applied. - `carriedOverExpired` · `number` The amount of carried-over balance that expired unused because it was not used within the carry-over usage period. 0 when the carry-over usage window has not closed yet or no window applies. - `carryOverUsageEndDate` · `date` The date the carried-over balance stops being usable, derived from the policy's carry-over usage period. Null when no carry-over usage window applies. - `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 in this period on or before the `date` query parameter. Approved days after it are in `upcoming`. - `pending` · `number` The number of pending days in this period on or before the `date` query parameter. Pending days after it are in `upcomingPending`, so the total awaiting approval is `pending` plus `upcomingPending`. - `upcoming` · `number` The number of approved days in this period after the `date` query parameter. Always 0 if this is not the current period. - `upcomingPending` · `number` The number of pending days in this period after the `date` query parameter. Always 0 if this is not the current period. - `balance` · `number` **Current balance**. What has accrued by the `date` query parameter, or by `endDate` for past periods, minus days used. Use it for a balance on a particular day, such as a leaving date. `endingBalance` is what is still available to book. - `endingBalance` · `number` **End of year balance**. What is still available to book until the end of the period: `totalAllowance` less time off used, upcoming and pending, and less carried-over days that expire before the period ends. - `totalAllowance` · `number` **Total allowance**. `allowance` plus `carriedOver`: everything available for the period before used, pending and upcoming time off are deducted. ##### Example ```json { "id": "X4XT4ZLOwT9GYbPyl90HztBu", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "startDate": "2020-09-01", "endDate": "2021-08-31", "usageEndDate": "2021-12-31", "timeAwayAllocation": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "type": "placeOfWork", "effectiveDate": "2020-04-01", "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I", "timeAwayPolicy": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "name": "UK Policy", "timeAwayPolicyVersion": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "bypassWorkingSchedule": false, "bypassPublicHolidays": false, "publicHolidayCalendarId": "GB", "visibleBalances": [ "endOfYear" ], "rules": [ { "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa", "limits": { "yearlyAllowance": 30, "maxCarryOver": 5, "yearStart": "01-01", "yearStartType": "employmentStartDate", "isUnlimited": false, "isProrated": false, "maxBalance": 30, "preventNegativeBalance": false, "maxNegativeBalance": 5, "usage": "upfront", "usagePeriod": 12, "carryOverUsagePeriod": 3, "roundingType": "halfUp" } } ] }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" }, "timeAwayTypeId": "0defdigw4ayfQ0EP22HjZGiD", "isCurrentPeriod": true, "isFinalPeriod": false, "hasAllocationChanged": false, "isCarriedOverInFull": false, "isProrated": true, "accrued": 8.09, "allowance": 20, "fromPrevAccrualPeriod": 2, "fromPrevAccrualPeriodValidUntilDate": "2021-12-31", "fromPrevAccrualPeriodExpired": 2, "carriedOver": -0.17, "carriedOverDate": "2020-12-31", "carriedOverExpired": 0, "carryOverUsageEndDate": "2021-03-31", "adjustments": 0, "adjustmentsUpcoming": 0, "used": 2, "pending": 2, "upcoming": 0, "upcomingPending": 0, "balance": 5.92, "endingBalance": 17.83, "totalAllowance": 25 } ``` #### List all time away periods Returns a list of time away periods. `GET /api/time-away-periods` ##### Parameters - `date` · `date` Work out the period's figures as of this date. Defaults to today. It also decides which period is current. `allowance`, `totalAllowance` and `endingBalance` cover the whole period, so `date` normally doesn't change them. - `isCurrentPeriod` · `boolean` Return the current period only. - `isFinalPeriod` · `boolean` Return the final period only. - `personId` · `string` The person to filter queries by. - `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. ##### Request ```shell curl https://app.humaans.io/api/time-away-periods \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "X4XT4ZLOwT9GYbPyl90HztBu", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "startDate": "2020-09-01", "endDate": "2021-08-31", "usageEndDate": "2021-12-31", "timeAwayAllocation": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "personId": "IL3vneCYhIx0xrR6um2sy2nW", "type": "placeOfWork", "effectiveDate": "2020-04-01", "timeAwayPolicyId": "smIkoZZ0t4KlXbEka2UC9m7I", "timeAwayPolicy": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "name": "UK Policy", "timeAwayPolicyVersion": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "bypassWorkingSchedule": false, "bypassPublicHolidays": false, "publicHolidayCalendarId": "GB", "visibleBalances": [ "endOfYear" ], "rules": [ { "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa", "limits": { "yearlyAllowance": 30, "maxCarryOver": 5, "yearStart": "01-01", "yearStartType": "employmentStartDate", "isUnlimited": false, "isProrated": false, "maxBalance": 30, "preventNegativeBalance": false, "maxNegativeBalance": 5, "usage": "upfront", "usagePeriod": 12, "carryOverUsagePeriod": 3, "roundingType": "halfUp" } } ] }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" }, "timeAwayTypeId": "0defdigw4ayfQ0EP22HjZGiD", "isCurrentPeriod": true, "isFinalPeriod": false, "hasAllocationChanged": false, "isCarriedOverInFull": false, "isProrated": true, "accrued": 8.09, "allowance": 20, "fromPrevAccrualPeriod": 2, "fromPrevAccrualPeriodValidUntilDate": "2021-12-31", "fromPrevAccrualPeriodExpired": 2, "carriedOver": -0.17, "carriedOverDate": "2020-12-31", "carriedOverExpired": 0, "carryOverUsageEndDate": "2021-03-31", "adjustments": 0, "adjustmentsUpcoming": 0, "used": 2, "pending": 2, "upcoming": 0, "upcomingPending": 0, "balance": 5.92, "endingBalance": 17.83, "totalAllowance": 25 } ] } ``` ### 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 ```http GET /api/time-away-policies GET /api/time-away-policies/:id POST /api/time-away-policies PATCH /api/time-away-policies/:id DELETE /api/time-away-policies/:id ``` #### Required scopes - `private:read` - `public:read` - `private:write` #### Time away policy object ##### Attributes - `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. `null` carries over the entire balance (no cap), which is the default when a `maxBalance` is set. - `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.maxBalance` · `number` The maximum balance an employee can accrue. Once reached, accrual pauses until the balance drops below the cap, then resumes. Not valid for unlimited policies. Prorated by FTE when `isProrated` is true. - `timeAwayPolicyVersion.rules.limits.preventNegativeBalance` · `boolean` `true` prevents booking more leave than currently available. - `timeAwayPolicyVersion.rules.limits.maxNegativeBalance` · `number` The maximum number of days the balance is allowed to go negative. Only applies when `preventNegativeBalance` is false. `null` means the balance can go negative without limit. - `timeAwayPolicyVersion.rules.limits.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`. `null` means carried over balance never expires, and goes hand in hand with a `null` `maxCarryOver`. Defaults to: 12. - `timeAwayPolicyVersion.rules.limits.carryOverUsagePeriod` · `integer` The number of months, from the start of the year the balance is carried into, that carried-over balance stays usable before it expires. When booking time off, balance expiring soonest is used first. `null` means carried-over balance follows the same usage period as the yearly allowance (`usagePeriod`). - `timeAwayPolicyVersion.rules.limits.roundingType` · `string` The rounding method applied to the time away balance. Valid options are `halfUp`, `wholeUp` and `noRounding`. - `archivedAt` · `date-time` When the policy was archived. - `isArchived` · `boolean` Whether the policy is archived. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. ##### Example ```json { "id": "dFCSrX1I3nzOZQMpblBclisO", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "name": "UK Policy", "timeAwayPolicyVersion": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "bypassWorkingSchedule": false, "bypassPublicHolidays": false, "publicHolidayCalendarId": "GB", "visibleBalances": [ "endOfYear" ], "rules": [ { "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa", "limits": { "yearlyAllowance": 30, "maxCarryOver": 5, "yearStart": "01-01", "yearStartType": "employmentStartDate", "isUnlimited": false, "isProrated": false, "maxBalance": 30, "preventNegativeBalance": false, "maxNegativeBalance": 5, "usage": "upfront", "usagePeriod": 12, "carryOverUsagePeriod": 3, "roundingType": "halfUp" } } ] }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### List all time away policies Returns a list of time away policies. `GET /api/time-away-policies` ##### Parameters - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` time away policies. The response skips the first `$skip` results. Each entry is a separate time away policy object. If no time away policies are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/time-away-policies \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "dFCSrX1I3nzOZQMpblBclisO", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "name": "UK Policy", "timeAwayPolicyVersion": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "bypassWorkingSchedule": false, "bypassPublicHolidays": false, "publicHolidayCalendarId": "GB", "visibleBalances": [ "endOfYear" ], "rules": [ { "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa", "limits": { "yearlyAllowance": 30, "maxCarryOver": 5, "yearStart": "01-01", "yearStartType": "employmentStartDate", "isUnlimited": false, "isProrated": false, "maxBalance": 30, "preventNegativeBalance": false, "maxNegativeBalance": 5, "usage": "upfront", "usagePeriod": 12, "carryOverUsagePeriod": 3, "roundingType": "halfUp" } } ] }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ] } ``` #### Retrieve a time away policy Retrieves the time away policy with the given ID. `GET /api/time-away-policies/:id` ##### Parameters _None._ ##### Returns Returns a time away policy object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/time-away-policies/dFCSrX1I3nzOZQMpblBclisO \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "dFCSrX1I3nzOZQMpblBclisO", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "name": "UK Policy", "timeAwayPolicyVersion": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "bypassWorkingSchedule": false, "bypassPublicHolidays": false, "publicHolidayCalendarId": "GB", "visibleBalances": [ "endOfYear" ], "rules": [ { "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa", "limits": { "yearlyAllowance": 30, "maxCarryOver": 5, "yearStart": "01-01", "yearStartType": "employmentStartDate", "isUnlimited": false, "isProrated": false, "maxBalance": 30, "preventNegativeBalance": false, "maxNegativeBalance": 5, "usage": "upfront", "usagePeriod": 12, "carryOverUsagePeriod": 3, "roundingType": "halfUp" } } ] }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Create a time away policy `POST /api/time-away-policies` ##### Parameters - `name` · `string` · required The name of the policy. - `timeAwayPolicyVersion` · `object` · one of yearlyPtoAllowance or timeAwayPolicyVersion or timeAwayPolicyTemplateId 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` · one of timeAwayTypeId or timeAwayType 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 | null` The number of days to carry over into the next year. `null` carries over the entire balance (no cap), which is the default when a `maxBalance` is set. - `timeAwayPolicyVersion.rules.limits.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.maxBalance` · `number | null` The maximum balance an employee can accrue. Once reached, accrual pauses until the balance drops below the cap, then resumes. Not valid for unlimited policies. Prorated by FTE when `isProrated` is true. - `timeAwayPolicyVersion.rules.limits.preventNegativeBalance` · `boolean` `true` prevents booking more leave than currently available. - `timeAwayPolicyVersion.rules.limits.maxNegativeBalance` · `number | null` The maximum number of days the balance is allowed to go negative. Only applies when `preventNegativeBalance` is false. `null` means the balance can go negative without limit. - `timeAwayPolicyVersion.rules.limits.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 | null` The length of the period in months beginning on `yearStart` where the employees' yearly PTO can be used. One of `12`, `15`, `16`, or `18`. `null` means carried over balance never expires, and goes hand in hand with a `null` `maxCarryOver`. Defaults to: 12. - `timeAwayPolicyVersion.rules.limits.carryOverUsagePeriod` · `integer | null` The number of months, from the start of the year the balance is carried into, that carried-over balance stays usable before it expires. When booking time off, balance expiring soonest is used first. `null` means carried-over balance follows the same usage period as the yearly allowance (`usagePeriod`). - `timeAwayPolicyVersion.rules.limits.roundingType` · `string` The rounding method applied to the time away balance. Valid options are `halfUp`, `wholeUp` and `noRounding`. - `timeAwayPolicyTemplateId` · `string` · one of yearlyPtoAllowance or timeAwayPolicyVersion or timeAwayPolicyTemplateId required ##### Returns Returns a time away policy if the call succeeded. The call returns an error if parameters are invalid. ##### Request ```shell curl https://app.humaans.io/api/time-away-policies \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X POST \ -d '{"name":"UK Policy","timeAwayPolicyVersion":{"id":"smIkoZZ0t4KlXbEka2UC9m7I","bypassWorkingSchedule":false,"bypassPublicHolidays":false,"publicHolidayCalendarId":"GB","visibleBalances":["endOfYear"],"rules":[{"timeAwayTypeId":"awM6sG5O2eSBAX2CeVap0MZa","limits":{"yearlyAllowance":30,"maxCarryOver":5,"yearStart":"01-01","yearStartType":"employmentStartDate","isUnlimited":false,"isProrated":false,"maxBalance":30,"preventNegativeBalance":false,"maxNegativeBalance":5,"usage":"upfront","usagePeriod":12,"carryOverUsagePeriod":3,"roundingType":"halfUp"}}]}}' ``` ##### Response ```json { "id": "dFCSrX1I3nzOZQMpblBclisO", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "name": "UK Policy", "timeAwayPolicyVersion": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "bypassWorkingSchedule": false, "bypassPublicHolidays": false, "publicHolidayCalendarId": "GB", "visibleBalances": [ "endOfYear" ], "rules": [ { "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa", "limits": { "yearlyAllowance": 30, "maxCarryOver": 5, "yearStart": "01-01", "yearStartType": "employmentStartDate", "isUnlimited": false, "isProrated": false, "maxBalance": 30, "preventNegativeBalance": false, "maxNegativeBalance": 5, "usage": "upfront", "usagePeriod": 12, "carryOverUsagePeriod": 3, "roundingType": "halfUp" } } ] }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Update a time away policy `PATCH /api/time-away-policies/:id` ##### 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` · one of timeAwayTypeId or timeAwayType 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 | null` The number of days to carry over into the next year. `null` carries over the entire balance (no cap), which is the default when a `maxBalance` is set. - `timeAwayPolicyVersion.rules.limits.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.maxBalance` · `number | null` The maximum balance an employee can accrue. Once reached, accrual pauses until the balance drops below the cap, then resumes. Not valid for unlimited policies. Prorated by FTE when `isProrated` is true. - `timeAwayPolicyVersion.rules.limits.preventNegativeBalance` · `boolean` `true` prevents booking more leave than currently available. - `timeAwayPolicyVersion.rules.limits.maxNegativeBalance` · `number | null` The maximum number of days the balance is allowed to go negative. Only applies when `preventNegativeBalance` is false. `null` means the balance can go negative without limit. - `timeAwayPolicyVersion.rules.limits.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 | null` The length of the period in months beginning on `yearStart` where the employees' yearly PTO can be used. One of `12`, `15`, `16`, or `18`. `null` means carried over balance never expires, and goes hand in hand with a `null` `maxCarryOver`. Defaults to: 12. - `timeAwayPolicyVersion.rules.limits.carryOverUsagePeriod` · `integer | null` The number of months, from the start of the year the balance is carried into, that carried-over balance stays usable before it expires. When booking time off, balance expiring soonest is used first. `null` means carried-over balance follows the same usage period as the yearly allowance (`usagePeriod`). - `timeAwayPolicyVersion.rules.limits.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. ##### Request ```shell curl https://app.humaans.io/api/time-away-policies/dFCSrX1I3nzOZQMpblBclisO \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X PATCH \ -d '{}' ``` ##### Response ```json { "id": "dFCSrX1I3nzOZQMpblBclisO", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "name": "UK Policy", "timeAwayPolicyVersion": { "id": "smIkoZZ0t4KlXbEka2UC9m7I", "bypassWorkingSchedule": false, "bypassPublicHolidays": false, "publicHolidayCalendarId": "GB", "visibleBalances": [ "endOfYear" ], "rules": [ { "timeAwayTypeId": "awM6sG5O2eSBAX2CeVap0MZa", "limits": { "yearlyAllowance": 30, "maxCarryOver": 5, "yearStart": "01-01", "yearStartType": "employmentStartDate", "isUnlimited": false, "isProrated": false, "maxBalance": 30, "preventNegativeBalance": false, "maxNegativeBalance": 5, "usage": "upfront", "usagePeriod": 12, "carryOverUsagePeriod": 3, "roundingType": "halfUp" } } ] }, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Delete a time away policy Permanently deletes a time away policy. It cannot be undone. `DELETE /api/time-away-policies/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/time-away-policies/dFCSrX1I3nzOZQMpblBclisO \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "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 ```http GET /api/time-away-types GET /api/time-away-types/:id POST /api/time-away-types PATCH /api/time-away-types/:id DELETE /api/time-away-types/:id ``` #### Required scopes - `public:read` - `private:write` #### Time away type object ##### Attributes - `id` · `string` Unique identifier for the object. - `companyId` · `string` ID of the company that this object is associated to. - `name` · `string` The name of the time away type. - `emoji` · `string` An emoji for visualising the time away type. - `emojiLabel` · `string` An emoji label for accessibility. - `category` · `string` Whether the type represents time off or working away. `timeOff` is a genuine absence such as holiday, sick, or parental leave; `workingAway` is time worked off-site, such as from home or another location. - `baseType` · `string` The base type of the time away type. One of `pto`, `sick`, `workingFromHome`, or `workingFromAnotherLocation` - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` ##### Example ```json { "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. `GET /api/time-away-types` ##### Parameters - `id` · `string · $in` The ID of the time away type. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter time away types by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$or` · `object[]` Filter results by multiple criteria. - `$or.id` · `string · $in` The ID of the time away type. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` time away types. The response skips the first `$skip` results. Each entry is a separate time away type object. If no time away types are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/time-away-types \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/time-away-types/:id` ##### Parameters _None._ ##### Returns Returns a time away type object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/time-away-types/4NJq5i7WwkUgHYzRqkLritrb \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 `POST /api/time-away-types` ##### Parameters - `name` · `string` · required The name of the time away type. - `emoji` · `string` · required An emoji for visualising the time away type. - `category` · `string` · one of type or category required Whether the type represents time off or working away. `timeOff` is a genuine absence such as holiday, sick, or parental leave; `workingAway` is time worked off-site, such as from home or another location. ##### Returns Returns a time away type if the call succeeded. The call returns an error if parameters are invalid. ##### Request ```shell 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 ```json { "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 `PATCH /api/time-away-types/:id` ##### 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. ##### Request ```shell curl https://app.humaans.io/api/time-away-types/4NJq5i7WwkUgHYzRqkLritrb \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X PATCH \ -d '{}' ``` ##### Response ```json { "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. `DELETE /api/time-away-types/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/time-away-types/4NJq5i7WwkUgHYzRqkLritrb \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "4NJq5i7WwkUgHYzRqkLritrb", "deleted": true } ``` ### Timesheet entries An object representing a timesheet entry of an employee #### Endpoints ```http GET /api/timesheet-entries GET /api/timesheet-entries/:id POST /api/timesheet-entries PATCH /api/timesheet-entries/:id DELETE /api/timesheet-entries/:id ``` #### Required scopes - `private:read` - `private:write` #### Timesheet entry object ##### Attributes - `id` · `string` Unique identifier for the object. - `personId` · `string` ID of the person that this object is associated to. - `date` · `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, as `{hours, minutes}`. To total it, combine both parts — e.g. `duration.hours + duration.minutes / 60` for hours — since one part alone is only half the answer. - `createdAt` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` ##### Example ```json { "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](#filtering) documentation for more details on usage. `GET /api/timesheet-entries` ##### Parameters - `id` · `object` The ID of an existing timesheet entry. - `date` · `date · $eq $ne $in $nin $gt $lt $gte $lte` The date of this timesheet entry. - `endTime` · `string | empty` The end time of this timesheet entry. - `id.$in` · `string[]` · required An array of IDs of existing timesheet entries. - `personId` · `string` The person to filter queries by. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter timesheet entries by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` timesheet entries. The response skips the first `$skip` results. Each entry is a separate timesheet entry object. If no timesheet entries are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/timesheet-entries \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/timesheet-entries/:id` ##### Parameters _None._ ##### Returns Returns a timesheet entry object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/timesheet-entries/0vUGk85FkSDHXfeOTnXqkk4d \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 `POST /api/timesheet-entries` ##### Parameters - `personId` · `string` · required ID of the person that this object is associated to. - `date` · `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. ##### Request ```shell 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 ```json { "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 `PATCH /api/timesheet-entries/:id` ##### Parameters - `date` · `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. ##### Request ```shell curl https://app.humaans.io/api/timesheet-entries/0vUGk85FkSDHXfeOTnXqkk4d \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X PATCH \ -d '{}' ``` ##### Response ```json { "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. `DELETE /api/timesheet-entries/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/timesheet-entries/0vUGk85FkSDHXfeOTnXqkk4d \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "0vUGk85FkSDHXfeOTnXqkk4d", "deleted": true } ``` ### Timesheet submissions An object representing a timesheet submission of an employee #### Endpoints ```http GET /api/timesheet-submissions GET /api/timesheet-submissions/:id POST /api/timesheet-submissions PATCH /api/timesheet-submissions/:id DELETE /api/timesheet-submissions/:id ``` #### Required scopes - `private:read` - `private:write` #### Timesheet submission object ##### Attributes - `id` · `string` Unique identifier for the object. - `personId` · `string` ID of the person that this object is associated to. - `startDate` · `date` The start date of the month which this submission covers. - `endDate` · `date` The end date of the month which this submission covers. - `status` · `string` One of `pending`, `approved`, `rejected`. - `submittedAt` · `date-time` The date and time when this submission was last submitted. - `reviewedBy` · `string` The ID of the person that reviewed this submission. - `reviewedAt` · `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` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. - `deletedAt` · `date-time` ##### Example ```json { "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](#filtering) documentation for more details on usage. `GET /api/timesheet-submissions` ##### Parameters - `personId` · `string` The person to filter queries by. - `startDate` · `string` The start date of the month which this submission covers. - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter timesheet submissions by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns a list of timesheet submissions. ##### Request ```shell curl https://app.humaans.io/api/timesheet-submissions \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/timesheet-submissions/:id` ##### Parameters _None._ ##### Returns Returns a timesheet submission object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/timesheet-submissions/Qh1bcl6baOIFPBgJjM0I9wNB \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 `POST /api/timesheet-submissions` ##### Parameters - `personId` · `string` · required ID of the person that this object is associated to. - `startDate` · `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. ##### Request ```shell 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 ```json { "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 `PATCH /api/timesheet-submissions/:id` ##### 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. ##### Request ```shell 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 ```json { "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. `DELETE /api/timesheet-submissions/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/timesheet-submissions/Qh1bcl6baOIFPBgJjM0I9wNB \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "Qh1bcl6baOIFPBgJjM0I9wNB", "deleted": true } ``` ### Token info An object containing the scoped permissions of the current access token. #### Endpoints ```http GET /api/token-info ``` #### Required scopes `*` #### Token info object ##### Attributes - `scopes` · `string[]` - `expiresAt` · `date-time` When the token used for this request stops working. Null when it never expires. ##### Example ```json { "scopes": [ "public:read", "documents:read" ], "expiresAt": "2027-03-24T09:30:00.000Z" } ``` #### Retrieve my token info Retrieves the scopes assigned to the current token and when it expires. `GET /api/token-info` ##### Parameters _None._ ##### Returns Returns the current token's scopes and expiry. ##### Request ```shell curl https://app.humaans.io/api/token-info \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "scopes": [ "public:read", "documents:read" ], "expiresAt": "2027-03-24T09:30:00.000Z" } ``` ### 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 ##### Example ```json { "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 ```http GET /api/webhooks GET /api/webhooks/:id POST /api/webhooks PATCH /api/webhooks/:id DELETE /api/webhooks/:id ``` #### Required scopes - `webhooks:manage` #### Webhook object ##### Attributes - `id` · `string` Unique identifier for the object. - `name` · `string` A short name for the webhook. - `description` · `string` A longer description for the webhook. - `prodEndpointUrl` · `string` The endpoint that will receive [webhook events](#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](#webhook-howto) section. - `subscribedEvents` · `string[]` The list of [webhook events](#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` · `date-time` Time at which the object was created. - `updatedAt` · `date-time` Time at which the object was last updated. ##### Example ```json { "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. `GET /api/webhooks` ##### Parameters - `createdAt` · `date | date-time · $gt $gte $lt $lte` Filter webhooks by created at date. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter webhooks by updated at date. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` webhooks. The response skips the first `$skip` results. Each entry is a separate webhook object. If no webhooks are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/webhooks \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/webhooks/:id` ##### Parameters _None._ ##### Returns Returns a webhook object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/webhooks/2ehafnPohpOY49mlQx0i3SHL \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 `POST /api/webhooks` ##### 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](#webhook-events). - `subscribedEvents` · `string[]` The list of [webhook events](#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. ##### Request ```shell curl https://app.humaans.io/api/webhooks \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X POST \ -d '{"name":"Payroll integration"}' ``` ##### Response ```json { "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 `PATCH /api/webhooks/:id` ##### 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](#webhook-events) that will be sent to the configured endpoint. - `prodEndpointUrl` · `string | null` The endpoint that will receive [webhook events](#webhook-events). ##### Returns Returns the webhook if the update succeeded. The call returns an error if parameters are invalid. ##### Request ```shell curl https://app.humaans.io/api/webhooks/2ehafnPohpOY49mlQx0i3SHL \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -H 'Content-Type: application/json' \ -X PATCH \ -d '{}' ``` ##### Response ```json { "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. `DELETE /api/webhooks/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/webhooks/2ehafnPohpOY49mlQx0i3SHL \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "2ehafnPohpOY49mlQx0i3SHL", "deleted": true } ``` ### Working pattern allocations An object representing the assignment of a working pattern to an employee. To assign a working pattern to an employee, create an allocation linking a person (`personId`) to either: - An existing company-wide working pattern via `workingPatternId` - A custom inline working pattern via the `workingPattern` object Each employee typically has one allocation, but can have multiple with different `effectiveDate` values to track changes over time (e.g. when moving to part-time or changing offices with different schedules). The allocation with the most recent `effectiveDate` that is not in the future is considered currently active. #### Endpoints ```http GET /api/working-pattern-allocations GET /api/working-pattern-allocations/:id POST /api/working-pattern-allocations PATCH /api/working-pattern-allocations/:id DELETE /api/working-pattern-allocations/:id ``` #### Required scopes - `private:read` - `public:read` - `private:write` #### Working pattern allocation object ##### Attributes - `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` · `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` · `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` · `boolean[] | number[]` The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either: - An array of numbers representing hours worked per day (e.g. `[8,8,8,8,8,0,0]` for Mon-Fri 8h) - An array of booleans for flexible patterns where `true` indicates a working day (e.g. `[true,true,true,true,true,false,false]` for Mon-Fri flexible) - `workingPattern.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.archivedAt` · `date-time` When the working pattern was archived. - `workingPattern.isArchived` · `boolean` Whether the working pattern is archived. - `workingPattern.createdAt` · `date-time` Timestamp when the working pattern was created. - `workingPattern.updatedAt` · `date-time` Timestamp when the working pattern was last updated. - `createdAt` · `date-time` Timestamp when the allocation was created. - `updatedAt` · `date-time` Timestamp when the allocation was last updated. - `deletedAt` · `date-time` The date and time the allocation was deleted. Only present on deleted allocations, which are only returned when querying with `$includeDeleted`. ##### Example ```json { "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. `GET /api/working-pattern-allocations` ##### Parameters - `personId` · `string · $eq $ne $in $nin` Filter by people ids - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `deletedAt` · `null | string · $ne` Filter records by deletion status. Use with `$includeDeleted`. - `$asOf` · `date` Filter the list of working pattern allocations to the current one per employee in effect at the provided date. Cannot be combined with `$includeDeleted`. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` working pattern allocations. The response skips the first `$skip` results. Each entry is a separate working pattern allocation object. If no working pattern allocations are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/working-pattern-allocations \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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. `GET /api/working-pattern-allocations/:id` ##### Parameters _None._ ##### Returns Returns a working pattern allocation object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/working-pattern-allocations/wiyjmFuX79AGNiROhmIJFxHC \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "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 `POST /api/working-pattern-allocations` ##### Parameters - `personId` · `string` The ID of the person this working pattern allocation is for. - `effectiveDate` · `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` · `(boolean | number)[]` · required The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either: - An array of numbers representing hours worked per day (e.g. `[8,8,8,8,8,0,0]` for Mon-Fri 8h) - An array of booleans for flexible patterns where `true` indicates a working day (e.g. `[true,true,true,true,true,false,false]` for Mon-Fri flexible) - `workingPattern.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. ##### Request ```shell 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 ```json { "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 `PATCH /api/working-pattern-allocations/:id` ##### 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` · `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` · `(boolean | number)[]` · required The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either: - An array of numbers representing hours worked per day (e.g. `[8,8,8,8,8,0,0]` for Mon-Fri 8h) - An array of booleans for flexible patterns where `true` indicates a working day (e.g. `[true,true,true,true,true,false,false]` for Mon-Fri flexible) - `workingPattern.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. ##### Request ```shell 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 ```json { "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. `DELETE /api/working-pattern-allocations/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/working-pattern-allocations/wiyjmFuX79AGNiROhmIJFxHC \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "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 ```http GET /api/working-patterns GET /api/working-patterns/:id POST /api/working-patterns PATCH /api/working-patterns/:id DELETE /api/working-patterns/:id ``` #### Required scopes - `private:read` - `private:write` #### Working pattern object ##### Attributes - `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` · `boolean[] | number[]` The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either: - An array of numbers representing hours worked per day (e.g. `[8,8,8,8,8,0,0]` for Mon-Fri 8h) - An array of booleans for flexible patterns where `true` indicates a working day (e.g. `[true,true,true,true,true,false,false]` for Mon-Fri flexible) - `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. - `archivedAt` · `date-time` When the working pattern was archived. - `isArchived` · `boolean` Whether the working pattern is archived. - `createdAt` · `date-time` Timestamp when the working pattern was created. - `updatedAt` · `date-time` Timestamp when the working pattern was last updated. ##### Example ```json { "id": "MLYRjj1YdpuQp5Qe6HQsvUys", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "personId": null, "name": "Mon-Fri 8h/day", "summary": "Mon-Fri (8h)", "fullTimeHours": 40, "standardDayHours": 8, "periodType": "week", "workingHours": 40, "workingPattern": [ 8, 8, 8, 8, 8, 0, 0 ], "fte": 1, "unroundedFte": 1, "archivedAt": "2020-01-28T08:44:42.000Z", "isArchived": false, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### List all working patterns Returns a list of working patterns. `GET /api/working-patterns` ##### Parameters - `personId` · `null · $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. - `updatedAt` · `date | date-time · $gt $gte $lt $lte` Filter by update time. With $includeDeleted=true, deleted records are matched at their deletion time. - `$includeDeleted` · `boolean` Include records deleted in the last 30 days as minimal tombstones. - `$sort` · `object` - `$sort.updatedAt` · `number` Sort by update time. With $includeDeleted=true, deleted records are sorted by deletion time. - `$limit` · `number` Limit number of results. - `$skip` · `number` Skip the specified number of results. ##### Returns Returns an object whose `data` property contains up to `$limit` working patterns. The response skips the first `$skip` results. Each entry is a separate working pattern object. If no working patterns are available, `data` is empty. ##### Request ```shell curl https://app.humaans.io/api/working-patterns \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "total": 1, "limit": 100, "skip": 0, "data": [ { "id": "MLYRjj1YdpuQp5Qe6HQsvUys", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "personId": null, "name": "Mon-Fri 8h/day", "summary": "Mon-Fri (8h)", "fullTimeHours": 40, "standardDayHours": 8, "periodType": "week", "workingHours": 40, "workingPattern": [ 8, 8, 8, 8, 8, 0, 0 ], "fte": 1, "unroundedFte": 1, "archivedAt": "2020-01-28T08:44:42.000Z", "isArchived": false, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ] } ``` #### Retrieve a working pattern Retrieves the working pattern with the given ID. `GET /api/working-patterns/:id` ##### Parameters _None._ ##### Returns Returns a working pattern object if a valid identifier was provided. ##### Request ```shell curl https://app.humaans.io/api/working-patterns/MLYRjj1YdpuQp5Qe6HQsvUys \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' ``` ##### Response ```json { "id": "MLYRjj1YdpuQp5Qe6HQsvUys", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "personId": null, "name": "Mon-Fri 8h/day", "summary": "Mon-Fri (8h)", "fullTimeHours": 40, "standardDayHours": 8, "periodType": "week", "workingHours": 40, "workingPattern": [ 8, 8, 8, 8, 8, 0, 0 ], "fte": 1, "unroundedFte": 1, "archivedAt": "2020-01-28T08:44:42.000Z", "isArchived": false, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Create a working pattern `POST /api/working-patterns` ##### 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` · `boolean[] | number[]` · required The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either: - An array of numbers representing hours worked per day (e.g. `[8,8,8,8,8,0,0]` for Mon-Fri 8h) - An array of booleans for flexible patterns where `true` indicates a working day (e.g. `[true,true,true,true,true,false,false]` for Mon-Fri flexible) - `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. ##### Request ```shell 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 ```json { "id": "MLYRjj1YdpuQp5Qe6HQsvUys", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "personId": null, "name": "Mon-Fri 8h/day", "summary": "Mon-Fri (8h)", "fullTimeHours": 40, "standardDayHours": 8, "periodType": "week", "workingHours": 40, "workingPattern": [ 8, 8, 8, 8, 8, 0, 0 ], "fte": 1, "unroundedFte": 1, "archivedAt": "2020-01-28T08:44:42.000Z", "isArchived": false, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Update a working pattern `PATCH /api/working-patterns/:id` ##### 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` · `boolean[] | number[]` The pattern of work as a JSON array where each position represents a day (starting from Monday). The array length must be a multiple of 7. Can be either: - An array of numbers representing hours worked per day (e.g. `[8,8,8,8,8,0,0]` for Mon-Fri 8h) - An array of booleans for flexible patterns where `true` indicates a working day (e.g. `[true,true,true,true,true,false,false]` for Mon-Fri flexible) - `isArchived` · `boolean` Whether the working pattern is archived. ##### Returns Returns the working pattern if the update succeeded. The call returns an error if parameters are invalid. ##### Request ```shell 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 ```json { "id": "MLYRjj1YdpuQp5Qe6HQsvUys", "companyId": "T7uqPFK7am4lFTZm39AmNuay", "personId": null, "name": "Mon-Fri 8h/day", "summary": "Mon-Fri (8h)", "fullTimeHours": 40, "standardDayHours": 8, "periodType": "week", "workingHours": 40, "workingPattern": [ 8, 8, 8, 8, 8, 0, 0 ], "fte": 1, "unroundedFte": 1, "archivedAt": "2020-01-28T08:44:42.000Z", "isArchived": false, "createdAt": "2020-01-28T08:44:42.000Z", "updatedAt": "2020-01-29T14:52:21.000Z" } ``` #### Delete a working pattern Permanently deletes a working pattern. It cannot be undone. `DELETE /api/working-patterns/:id` ##### Parameters _None._ ##### Returns Returns an object confirming the deletion on success. Otherwise returns an error. ##### Request ```shell curl https://app.humaans.io/api/working-patterns/MLYRjj1YdpuQp5Qe6HQsvUys \ -H 'Authorization: Bearer example_PqspbWe4p2cDapt4itzAZM6' \ -X DELETE ``` ##### Response ```json { "id": "MLYRjj1YdpuQp5Qe6HQsvUys", "deleted": true } ```