Guides
Signup For Free

Humaans API Integration

Suggest Edits

These are the list of integration use cases supported by Knit for Humaans API as part of the HRIS category

Delete a Compensation

  • ID: delete_a_compensation
  • Operation: delete
  • Entities: compensation
  • Summary: The 'Delete a Compensation' API permanently deletes a compensation record identified by its ID. This action cannot be undone. The API requires an authorization header with a bearer token for authentication. The compensation ID must be provided as a path parameter. On successful deletion, the API returns an object containing the ID of the deleted compensation and a confirmation boolean 'deleted' set to true. If the deletion fails, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete a Data Export

  • ID: delete_a_data_export
  • Operation: delete
  • Entities: data export
  • Summary: This API permanently deletes a data export identified by its ID. The deletion cannot be undone. The request requires an Authorization header with a Bearer token. The endpoint does not take any query parameters or request body. On successful deletion, it returns an object containing the ID of the deleted data export and a confirmation boolean. If the deletion fails, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete a Document

  • ID: delete_a_document
  • Operation: write
  • Entities: document
  • Summary: The 'Delete a Document' API permanently deletes a document identified by its document ID. This action cannot be undone. The API requires an Authorization header with a Bearer token for authentication. The document ID must be provided as a path parameter. On successful deletion, the API returns an object containing the document ID and a boolean indicating the deletion status. If the deletion fails, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete a Job Role

  • ID: delete_a_job_role
  • Operation: write
  • Entities: job role, employee
  • Summary: This API permanently deletes a job role identified by its unique ID. It requires an authorization bearer token in the headers. The job role ID must be provided as a path parameter. On successful deletion, it returns an object with the job role ID and a boolean indicating the deletion status. If the job role is the last one for an employee, an error will be returned as every employee must have at least one job role.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete a Location

  • ID: delete_a_location
  • Operation: write
  • Entities: location
  • Summary: This API permanently deletes a location identified by its ID. The DELETE method is used, and the endpoint requires an Authorization header with a Bearer token. The location ID is specified as a path parameter. On successful deletion, the API returns an object containing the ID of the deleted location and a boolean indicating the deletion status. If the deletion fails, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete a Person

  • ID: delete_a_person
  • Operation: write
  • Entities: deletion, person
  • Summary: The 'Delete a Person' API permanently deletes a person from the system using their unique identifier. This action cannot be undone. The API requires an Authorization header with a Bearer token for authentication and a path parameter 'id' which specifies the unique identifier of the person to be deleted. On successful deletion, the API returns a response body containing the 'id' of the deleted person and a 'deleted' boolean set to true. If the deletion fails, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete a time away

  • ID: delete_a_time_away
  • Operation: write
  • Entities: time away
  • Summary: The 'Delete a time away' API permanently deletes a specified time away entry. This action cannot be undone. The API does not require any parameters in the request. Upon successful deletion, it returns a JSON object with a 'success' boolean set to true and a confirmation message. If the deletion fails, it returns an error message.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete an Equipment

  • ID: delete_an_equipment
  • Operation: write
  • Entities: equipment
  • Summary: This API permanently deletes an equipment identified by its unique ID. The DELETE request requires an Authorization header with a Bearer token for authentication. The equipment ID is specified in the path parameters. On successful deletion, the API returns a response body containing the equipment ID and a boolean indicating the deletion status. If the deletion fails, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete a Bank Account

  • ID: delete_bank_account
  • Operation: write
  • Entities: bank account
  • Summary: This API permanently deletes a bank account identified by its unique ID. The DELETE method is used at the endpoint https://app.humaans.io/api/bank-accounts/{id}. The request requires an Authorization header with a Bearer token for authentication. The path parameter 'id' specifies the bank account to be deleted. On success, the response returns an object with the 'id' of the deleted bank account and a 'deleted' boolean set to true. If the deletion fails, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete a Custom Field

  • ID: delete_custom_field
  • Operation: write
  • Entities: custom field
  • Summary: This API permanently deletes a custom field identified by its ID. The DELETE method is used, and the endpoint requires an Authorization header with a Bearer token. The path parameter 'id' specifies the custom field to be deleted. On success, the response body confirms the deletion with the field's ID and a 'deleted' status set to true. If the deletion fails, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete a Custom Value

  • ID: delete_custom_value
  • Operation: delete
  • Entities: custom value
  • Summary: This API permanently deletes a custom value identified by its ID. The DELETE method is used, and the endpoint requires an Authorization header with a Bearer token. The ID of the custom value to be deleted is specified in the path parameters. On success, the API returns an object confirming the deletion with the ID of the deleted custom value and a boolean indicating the deletion status. If the deletion is unsuccessful, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete an Emergency Contact

  • ID: delete_emergency_contact
  • Operation: write
  • Entities: error, emergency contact, object
  • Summary: This API permanently deletes an emergency contact identified by the given ID. The request requires an Authorization header with a Bearer token for authentication. The ID of the emergency contact to be deleted must be provided as a path parameter. On successful deletion, the API returns an object containing the ID of the deleted contact and a confirmation boolean 'deleted' set to true. If the deletion fails, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete an Identity Document

  • ID: delete_identity_document
  • Operation: delete
  • Entities: identity document
  • Summary: This API permanently deletes an identity document specified by its ID. The DELETE method is used, and the endpoint requires an Authorization header with a Bearer token. The path parameter 'id' is required to specify which identity document to delete. On success, the response body confirms the deletion with the document ID and a 'deleted' status set to true. If the deletion fails, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete a Time Away Adjustment

  • ID: delete_time_away_adjustment
  • Operation: delete
  • Entities: time away adjustment
  • Summary: This API permanently deletes a time away adjustment identified by its ID. The DELETE method is used, and the endpoint requires an Authorization header with a Bearer token. The ID of the time away adjustment must be provided as a path parameter. On successful deletion, the API returns an object containing the ID of the deleted adjustment and a boolean indicating the deletion status. If the deletion fails, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete a Time Away Allocation

  • ID: delete_time_away_allocation
  • Operation: delete
  • Entities: time away allocation
  • Summary: This API permanently deletes a time away allocation identified by the given ID. The DELETE request requires an Authorization header with a Bearer token for authentication. The path parameter 'id' specifies the time away allocation to be deleted. On success, the API returns a JSON object confirming the deletion with the 'id' of the deleted allocation and a 'deleted' status set to true. If the deletion fails, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete a Time Away Policy

  • ID: delete_time_away_policy
  • Operation: write
  • Entities: time away policy
  • Summary: This API permanently deletes a time away policy identified by its ID. The DELETE method is used, and the endpoint requires an Authorization header with a Bearer token. The path parameter 'id' specifies the policy to be deleted. On success, the response returns an object with the 'id' of the deleted policy and a 'deleted' status set to true. If the deletion fails, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete a Time Away Type

  • ID: delete_time_away_type
  • Operation: write
  • Entities: time away type
  • Summary: This API permanently deletes a time away type identified by its ID. The request requires an Authorization header with a Bearer token for authentication. The ID of the time away type to be deleted must be provided as a path parameter. On successful deletion, the API returns an object containing the ID of the deleted time away type and a boolean indicating the deletion status. If the deletion fails, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete a Timesheet Entry

  • ID: delete_timesheet_entry
  • Operation: write
  • Entities: timesheet entry
  • Summary: This API permanently deletes a timesheet entry identified by its ID. The DELETE method is used, and the endpoint requires an Authorization header with a Bearer token for authentication. The path parameter 'id' specifies the timesheet entry to be deleted. On successful deletion, the API returns a JSON object containing the 'id' of the deleted entry and a 'deleted' boolean set to true. If the deletion fails, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Delete a Timesheet Submission

  • ID: delete_timesheet_submission
  • Operation: delete
  • Entities: timesheet submission
  • Summary: This API permanently deletes a timesheet submission identified by its ID. The request requires an Authorization header with a Bearer token for authentication. The ID of the timesheet submission to be deleted must be provided as a path parameter. On successful deletion, the API returns an object containing the ID of the deleted timesheet submission and a boolean indicating the success of the deletion. If the deletion is unsuccessful, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List all public holiday calendars

  • ID: get_all_public_holiday_calendars
  • Operation: read
  • Entities: company, country, public holiday calendar
  • Summary: This API endpoint retrieves a list of public holiday calendars. It accepts optional query parameters such as 'id' to filter by calendar ID, '$limit' to limit the number of results, and '$skip' to skip a specified number of results. The request requires an 'Authorization' header with a Bearer token. The response includes a 'total' count of calendars, the 'limit' and 'skip' values used, and a 'data' array containing public holiday calendar objects. Each calendar object includes details such as 'id', 'companyId', 'name', 'countryCode', 'country', 'regionCode', 'region', 'dayCount', 'createdAt', and 'updatedAt'.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Data Export

  • ID: get_create_a_data_export
  • Operation: read
  • Entities: people, document, data export
  • Summary: The Create a Data Export API allows users to generate a data export based on specified parameters. The API accepts various parameters such as fields, customFields, timeAwayTypes, startDate, endDate, and more to customize the data export. The type of export is required and can be one of people, equipment, timeAway, timesheet, document, or identityDocument. The API returns a data export object containing an ID, company ID, URL for downloading the data, and timestamps for creation and last update. The exported data needs to be downloaded separately using the provided URL.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a Custom Value

  • ID: get_custom_value
  • Operation: read
  • Entities: custom value, person, custom field
  • Summary: This API retrieves a custom value object using the specified ID. The request requires an Authorization header with a Bearer token. The path parameter 'id' is required to specify which custom value to retrieve. The response includes details such as the custom value's ID, associated person ID, custom field ID, resource ID, the value itself, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve an Emergency Contact

  • ID: get_emergency_contact
  • Operation: read
  • Entities: person, emergency contact
  • Summary: This API retrieves an emergency contact using the provided unique identifier. The request requires an Authorization header with a Bearer token for authentication. The path parameter 'id' is mandatory and specifies the unique identifier of the emergency contact to be retrieved. The response includes details such as the contact's name, email, phone number, relationship to the person, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve Equipment Details

  • ID: get_equipment_details
  • Operation: read
  • Entities: person, file, equipment
  • Summary: The Retrieve Equipment Details API allows users to fetch details of a specific equipment by providing its unique identifier in the path parameters. The request requires an Authorization header with a Bearer token for authentication. The response includes detailed information about the equipment such as its type, name, serial number, cost, currency, and associated dates. It also provides metadata like creation and update timestamps.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve an Identity Document

  • ID: get_identity_document
  • Operation: read
  • Entities: person, identity document, file
  • Summary: This API retrieves an identity document using the provided document ID. The request requires an Authorization header with a Bearer token. The response includes details of the identity document such as its type, number, country code, expiry date, and associated file information. It also provides metadata like verification status, creation, and update timestamps.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Bank Accounts

  • ID: get_list_all_bank_accounts
  • Operation: read
  • Entities: person, bank account, account
  • Summary: The 'List All Bank Accounts' API endpoint allows users to retrieve a list of bank accounts. It supports filtering by personId and pagination through $limit and $skip query parameters. The response includes a list of bank account objects, each containing details such as bank name, account number, and timestamps for creation and last update. The request requires an Authorization header with a Bearer token. The API guarantees a response without errors, even if no bank accounts are available.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Companies

  • ID: get_list_all_companies
  • Operation: read
  • Entities: company
  • Summary: The 'List All Companies' API endpoint retrieves a list of companies from the Humaans platform. It uses the GET method and requires an Authorization header with a Bearer token. The API accepts optional query parameters '$limit' to limit the number of results and '$skip' to skip a specified number of results. The response includes a 'total' count of companies, the 'limit' and 'skip' values used, and a 'data' array containing company objects. Each company object includes details such as 'id', 'name', 'domains', 'trialEndDate', 'status', 'paymentStatus', 'package', 'createdAt', 'updatedAt', and 'isTimesheetEnabled'.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Compensations

  • ID: get_list_all_compensations
  • Operation: read
  • Entities: compensation type, employee, compensation
  • Summary: The 'List All Compensations' API endpoint retrieves a list of compensations from the system. It uses the GET method and requires an Authorization header with a Bearer token. The API requires filtering by personId and allows optional filtering by type and date ($asOf). It supports pagination through $limit and $skip query parameters. The response includes a total count, limit, skip, and a data array containing compensation objects with details such as id, personId, type, amount, currency, period, note, effectiveDate, endDate, endReason, createdAt, and updatedAt. If no compensations are available, the data array will be empty.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Custom Fields

  • ID: get_list_all_custom_fields
  • Operation: read
  • Entities: company, profile section, custom field
  • Summary: The 'List All Custom Fields' API endpoint allows users to retrieve a list of custom fields from the Humaans application. The API uses the GET method and requires an Authorization header with a Bearer token. Users can filter the results using query parameters such as 'section' and 'type', and control pagination with '$limit' and '$skip'. The response includes a 'data' array containing custom field objects, each with details like 'id', 'name', 'section', 'type', and timestamps for creation and last update. The API ensures that the list is up to the specified limit and skips the given number of results.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Custom Values

  • ID: get_list_all_custom_values
  • Operation: read
  • Entities: custom value, person, custom field
  • Summary: The 'List All Custom Values' API endpoint allows users to retrieve a list of custom values. The API supports filtering by personId, customFieldId, resourceId, createdAt, and updatedAt. Users can also limit the number of results with $limit and skip a specified number of results with $skip. The response includes a total count of custom values, the limit, the number of skipped results, and an array of custom value objects. Each custom value object contains details such as id, personId, customFieldId, resourceId, value, createdAt, and updatedAt. This API requires an Authorization header with a Bearer token.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Document Types

  • ID: get_list_all_document_types
  • Operation: read
  • Entities: company, employment agreement, document type
  • Summary: The 'List All Document Types' API retrieves a list of document types from the Humaans platform. It requires an authorization header with a Bearer token. The API supports optional query parameters '$limit' and '$skip' to control the number of results returned and the number of results to skip, respectively. The response includes a 'total' count of document types, the 'limit' and 'skip' values used, and a 'data' array containing document type objects. Each document type object includes an 'id', 'companyId', 'name', 'createdAt', and 'updatedAt' fields. If no document types are available, the 'data' array will be empty.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Documents

  • ID: get_list_all_documents
  • Operation: read
  • Entities: company, document, person
  • Summary: The 'List All Documents' API retrieves a list of documents from the Humaans platform. It requires a 'personId' in the query parameters to specify the person associated with the documents. It supports filtering by multiple conditions using the '$or' parameter. The results can be limited and paginated using the '$limit' and '$skip' parameters. The API requires an authorization header with a bearer token. The response includes a 'data' property containing document objects, each with details such as document ID, company ID, person ID, name, link, file information, and timestamps for creation and updates. The API is designed to never return an error, and if no documents are available, the 'data' list will be empty.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Emergency Contacts

  • ID: get_list_all_emergency_contacts
  • Operation: read
  • Entities: relationship, person, emergency contact
  • Summary: The 'List All Emergency Contacts' API endpoint allows users to retrieve a list of emergency contacts. The API supports filtering by primary contact status and person ID, and allows pagination through the use of limit and skip query parameters. The request requires an Authorization header with a Bearer token. The response includes a total count of contacts, the limit and skip values used, and an array of emergency contact objects, each containing details such as name, email, phone number, relationship, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Equipment

  • ID: get_list_all_equipment
  • Operation: read
  • Entities: person, file, equipment
  • Summary: The 'List All Equipment' API endpoint retrieves a list of equipment items. It supports filtering by person ID and allows pagination through the use of '$limit' and '$skip' query parameters. The request requires an authorization header with a bearer token. The response includes a 'total' count of equipment, the 'limit' and 'skip' values used, and a 'data' array containing equipment objects. Each equipment object includes details such as ID, type, name, serial number, cost, currency, and timestamps for creation and updates.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Equipment Names

  • ID: get_list_all_equipment_names
  • Operation: read
  • Entities: company, equipment name
  • Summary: This API endpoint retrieves a list of equipment names from the system. It supports filtering by equipment type and allows pagination through the use of $limit and $skip query parameters. The request requires an Authorization header with a Bearer token. The response includes a total count of equipment names, the limit and skip values used, and an array of equipment name objects, each containing details such as id, companyId, value, isDefault, and isUsed. The API is designed to always return a response without errors, even if the list is empty.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Equipment Types

  • ID: get_list_all_equipment_types
  • Operation: read
  • Entities: company, equipment type
  • Summary: The 'List All Equipment Types' API retrieves a list of equipment types available in the system. It accepts optional query parameters '$limit' and '$skip' to control the number of results returned and the number of results to skip, respectively. The request requires an 'Authorization' header with a Bearer token for authentication. The response includes a 'total' count of equipment types, the 'limit' and 'skip' values used, and a 'data' array containing equipment type objects. Each equipment type object includes an 'id', 'companyId', 'value', 'isDefault', and 'isUsed' properties. The API is designed to never return an error, and if no equipment types are available, the 'data' array will be empty.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Identity Document Types

  • ID: get_list_all_identity_document_types
  • Operation: read
  • Entities: company, identity document type
  • Summary: This API endpoint retrieves a list of identity document types. It accepts optional query parameters $limit and $skip to control the number of results returned and the number of results to skip, respectively. The request requires an Authorization header with a Bearer token. The response includes a total count of identity document types, the limit and skip values used, and an array of identity document type objects, each containing an id, companyId, and value. If no identity document types are available, the data array will be empty. This request should never return an error.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Identity Documents

  • ID: get_list_all_identity_documents
  • Operation: read
  • Entities: person, identity document, file
  • Summary: The 'List All Identity Documents' API endpoint retrieves a list of identity documents associated with a person. It uses the GET method and requires an Authorization header with a Bearer token. The 'personId' query parameter is required to filter documents by person. Optional query parameters include '$limit' to limit the number of results, and '$skip' to skip a specified number of results. The response includes a 'total' count of documents, the 'limit' and 'skip' values used, and a 'data' array containing identity document objects. Each document object includes details such as 'id', 'personId', 'type', 'number', 'countryCode', 'expiryDate', 'file' information, and verification status.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List all job roles

  • ID: get_list_all_job_roles
  • Operation: read
  • Entities: person, job role, department
  • Summary: This API endpoint retrieves a list of job roles from the Humaans platform. It supports filtering by person ID and date, and allows limiting and skipping results. The request requires an Authorization header with a Bearer token and a required 'personId' query parameter. The response includes a total count of job roles, the limit and skip values used, and an array of job role objects, each containing details such as job title, department, effective and end dates, and reporting information.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Locations

  • ID: get_list_all_locations
  • Operation: read
  • Entities: company, time away policy, location
  • Summary: The 'List All Locations' API endpoint allows users to retrieve a list of locations from the Humaans platform. The API uses the GET method and requires an Authorization header with a Bearer token for access. Users can specify optional query parameters '$limit' to limit the number of results and '$skip' to skip a specified number of results. The response includes a 'total' count of locations, the 'limit' and 'skip' values used, and a 'data' array containing location objects. Each location object includes details such as 'id', 'companyId', 'label', 'displayName', 'address', 'postcode', 'city', 'country', 'timezone', and timestamps for creation and last update. The API guarantees a response without errors, even if no locations are available.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All People

  • ID: get_list_all_people
  • Operation: read
  • Entities: company, status, person
  • Summary: The 'List All People' API allows you to retrieve a list of people from the system. By default, it returns only active employees, but you can filter by status to include offboarded or new hires. You can also filter by email, creation date, and update date, and control the number of results with $limit and $skip parameters. The response includes detailed information about each person, such as their name, email, location, employment details, and more. This API requires an Authorization header with a Bearer token.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List all public holidays

  • ID: get_list_all_public_holidays
  • Operation: read
  • Entities: public holiday, date, public holiday calendar
  • Summary: This API endpoint retrieves a list of public holidays based on the specified public holiday calendar ID and date filters. The request requires an authorization header with a bearer token. The query parameters include 'publicHolidayCalendarId' and 'date' which are required, and optional parameters '$limit' and '$skip' to control the number of results and pagination. The response includes the total number of holidays, the limit, the number skipped, and a data array containing public holiday objects with 'id', 'date', and 'name'.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Time Away Adjustments

  • ID: get_list_all_time_away_adjustments
  • Operation: read
  • Entities: time away adjustment, person
  • Summary: This API endpoint retrieves a list of time away adjustments. It supports filtering by person ID and date, and allows sorting by date or creation date. The results can be limited and paginated using the $limit and $skip parameters. The response includes a total count of adjustments, the limit applied, the number of skipped results, and an array of time away adjustment objects, each containing details such as the ID, person ID, date, delta days, reason, validity, type ID, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Time Away Allocations

  • ID: get_list_all_time_away_allocations
  • Operation: read
  • Entities: time away policy, person, time away allocation
  • Summary: This API endpoint retrieves a list of time away allocations. It supports filtering by person ID and can return only current allocations if specified. The results can be limited and paginated using the $limit and $skip query parameters. The response includes a total count of allocations, the limit applied, the number of results skipped, and an array of time away allocation objects. Each allocation object contains details such as the allocation ID, person ID, type, effective date, and associated time away policy information. The request requires an Authorization header with a Bearer token.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Time Away Entries

  • ID: get_list_all_time_away_entries
  • Operation: read
  • Entities: time away, entry, filter condition
  • Summary: The 'List All Time Away Entries' API endpoint allows users to retrieve a list of time away entries from the system. The entries can be filtered using various query parameters such as personId, personStatus, startDate, endDate, timeAwayTypeId, and requestStatus. The 'personId' parameter is required to specify the person for whom the time away entries are being queried. Sorting and pagination are supported through $sort, $limit, and $skip parameters. The response includes a total count of entries, the limit and skip values, and an array of time away objects, each containing detailed information about the time away, such as start and end dates, type, status, and associated notes. This API requires an Authorization header with a Bearer token for access.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Time Away Periods

  • ID: get_list_all_time_away_periods
  • Operation: read
  • Entities: person, time away allocation, time away period
  • Summary: The 'List All Time Away Periods' API endpoint retrieves a list of time away periods for employees. It supports filtering by person ID, current period, final period, and a specific date for calculating balances and accruals. The request requires an authorization header with a bearer token. The response includes details such as the total number of periods, limit, skip, and an array of time away periods with comprehensive details about each period, including allocation, policy, and balance information.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Time Away Policies

  • ID: get_list_all_time_away_policies
  • Operation: read
  • Entities: skip, limit, time away policy
  • Summary: This API endpoint retrieves a list of time away policies from the Humaans platform. It supports optional query parameters $limit and $skip to control the number of results returned and the number of results to skip, respectively. The request requires an Authorization header with a Bearer token. The response includes a total count of policies, the limit and skip values used, and an array of time away policy objects, each containing details such as policy ID, company ID, name, version details, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Time Away Types

  • ID: get_list_all_time_away_types
  • Operation: read
  • Entities: company, category, time away type
  • Summary: The 'List All Time Away Types' API endpoint retrieves a list of time away types available in the system. It supports filtering by ID and multiple criteria using the '$or' parameter. The results can be limited using the '$limit' parameter and can skip a specified number of results using the '$skip' parameter. The response includes a 'data' property containing an array of time away type objects, each with details such as 'id', 'companyId', 'name', 'emoji', 'emojiLabel', 'category', 'baseType', 'createdAt', and 'updatedAt'. The request requires an 'Authorization' header with a Bearer token.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Timesheet Entries

  • ID: get_list_all_timesheet_entries
  • Operation: read
  • Entities: timesheet entry, person, duration
  • Summary: The 'List All Timesheet Entries' API allows users to retrieve a list of timesheet entries from the system. The API supports filtering by various parameters such as personId, date, endTime, and id. It also allows pagination through $limit and $skip parameters. The response includes a total count of entries, the limit applied, the number of entries skipped, and an array of timesheet entry objects. Each entry contains details such as id, personId, date, startTime, endTime, duration, createdAt, and updatedAt. The request requires an Authorization header with a Bearer token.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

List All Timesheet Submissions

  • ID: get_list_all_timesheet_submissions
  • Operation: read
  • Entities: person, timesheet submission, duration
  • Summary: This API endpoint retrieves a list of timesheet submissions. It supports filtering by personId and startDate, and allows pagination through $limit and $skip query parameters. The response includes a list of timesheet submissions with details such as submission ID, person ID, start and end dates, status, submission and review timestamps, and any requested changes. The API requires an Authorization header with a Bearer token for access.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a Bank Account

  • ID: get_retrieve_a_bank_account
  • Operation: read
  • Entities: bank account
  • Summary: This API retrieves a bank account using the provided unique identifier. The request requires an Authorization header with a Bearer token for authentication. The path parameter 'id' is required to specify the bank account to retrieve. The response includes details of the bank account such as the bank name, name on account, account number, sort code, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a Company

  • ID: get_retrieve_a_company
  • Operation: read
  • Entities: company, timesheet, package
  • Summary: This API retrieves the details of a company using its unique identifier. The request requires an Authorization header with a Bearer token. The company ID is provided as a path parameter. The response includes details such as the company's name, domains, trial end date, status, payment status, creation and update timestamps, and whether timesheet is enabled.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a Compensation

  • ID: get_retrieve_a_compensation
  • Operation: read
  • Entities: person, compensation
  • Summary: This API retrieves a compensation record using the specified compensation ID. The request requires an Authorization header with a Bearer token. The response includes details such as the compensation ID, person ID, type, amount, currency, period, notes, effective date, end date, end reason, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a Custom Field

  • ID: get_retrieve_a_custom_field
  • Operation: read
  • Entities: company, employment, custom field
  • Summary: This API retrieves a custom field using its unique identifier. The request requires an Authorization header with a Bearer token for authentication. The endpoint URL includes a path parameter 'id' which specifies the custom field to be retrieved. The response returns a custom field object containing details such as the field's ID, company ID, name, section, subsection, type, configuration, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a Data Export

  • ID: get_retrieve_a_data_export
  • Operation: read
  • Entities: company, data export
  • Summary: This API retrieves the metadata of a data export identified by the given ID. It requires an Authorization header with a Bearer token for authentication. The endpoint does not take any query parameters or request body. The response includes the ID of the data export, the associated company ID, a URL to download the actual data, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a Document

  • ID: get_retrieve_a_document
  • Operation: read
  • Entities: company, document, person
  • Summary: The 'Retrieve a Document' API allows users to retrieve a document by its unique identifier. The API requires an authorization header with a Bearer token for authentication. The document ID is specified as a path parameter in the URL. Upon a successful request, the API returns a document object containing details such as the document's ID, company ID, person ID, name, link, file details, source, issue date, creation date, and last update date.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a File

  • ID: get_retrieve_a_file
  • Operation: read
  • Entities: company, person, file
  • Summary: The 'Retrieve a File' API allows users to retrieve a file using its unique identifier. The API requires an Authorization header with a Bearer token for authentication. The file ID is specified as a path parameter in the URL. Upon a successful request, the API returns a file object containing details such as the file's ID, company ID, person ID, type, uploader ID, filename, URL, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a Job Role

  • ID: get_retrieve_a_job_role
  • Operation: read
  • Entities: note, job role, department
  • Summary: This API retrieves a job role using the specified job role ID. The request requires an Authorization header with a Bearer token. The response includes details about the job role such as the job title, department, effective and end dates, reporting structure, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a Location

  • ID: get_retrieve_a_location
  • Operation: read
  • Entities: company, time away policy, location
  • Summary: The 'Retrieve a Location' API is used to fetch details of a specific location using its unique identifier. The API requires an authorization header with a bearer token for access. The endpoint includes a path parameter 'id' which is the unique identifier of the location to be retrieved. Upon a successful request, the API returns a location object containing details such as the location's label, display name, address, city, country, timezone, and other relevant information.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a Person

  • ID: get_retrieve_a_person
  • Operation: read
  • Entities: profile photo, person, team
  • Summary: The 'Retrieve a Person' API allows you to retrieve detailed information about a person using their unique ID. The API endpoint is 'https://app.humaans.io/api/people/{id}' and requires a GET request. The request must include an 'Authorization' header with a Bearer token for authentication. The path parameter 'id' is required to specify the person to retrieve. The response includes a comprehensive person object with details such as name, email, phone number, address, employment details, and more. The response also includes profile photo variants and team information.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a Time Away

  • ID: get_retrieve_a_time_away
  • Operation: read
  • Entities: time away, breakdown, person
  • Summary: The 'Retrieve a Time Away' API allows users to retrieve details of a specific time away entry using its unique ID. The API requires an authorization header with a bearer token for access. The endpoint is accessed via a GET request to 'https://app.humaans.io/api/time-away/{id}', where '{id}' is the path parameter representing the time away ID. The response includes detailed information about the time away, such as the person ID, start and end dates, type of time away, notes, breakdown of days, request status, and more. This API is useful for retrieving comprehensive details about a specific time away entry in the system.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve Company Details Using Person's Company ID

  • ID: get_retrieve_company_details_using_persons_company_id
  • Operation: ['read', 'read']
  • Entities:
  • Summary: This configuration retrieves the details of a company using the company ID obtained from a person's details. The process involves two steps: first, retrieving a person's details using their ID to obtain the company ID, and second, using this company ID to fetch the company's details. The request requires an Authorization header with a Bearer token. The person ID is provided as a path parameter. The final response includes details such as the company's name, domains, trial end date, status, payment status, creation and update timestamps, and whether timesheet is enabled.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve Currently Logged In User

  • ID: get_retrieve_currently_logged_in_user
  • Operation: read
  • Entities: user, profile photo, team
  • Summary: This API retrieves the currently logged in user from the Humaans platform. It requires an Authorization header with a Bearer token for authentication. The endpoint uses a path parameter 'id' to specify the user ID. The response includes detailed information about the user, such as personal details, contact information, employment details, and profile photo variants. The API does not require any query parameters or request body.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a Time Away Adjustment

  • ID: get_time_away_adjustment
  • Operation: read
  • Entities: time away adjustment, person, time away type
  • Summary: This API retrieves a time away adjustment using the specified ID. The request requires an Authorization header with a Bearer token. The ID of the time away adjustment must be provided as a path parameter. The response includes details such as the person ID, date, delta days, reason, validity, time away type ID, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a Time Away Allocation

  • ID: get_time_away_allocation
  • Operation: read
  • Entities: time away policy, person, time away allocation
  • Summary: This API retrieves a time away allocation using the specified ID. The request requires an Authorization header with a Bearer token. The response includes details of the time away allocation, such as the ID, person ID, type, effective date, and associated time away policy details. The time away policy includes information like the policy ID, company ID, name, version details, and rules with limits on yearly allowance, carry over, and usage.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a Time Away Policy

  • ID: get_time_away_policy
  • Operation: read
  • Entities: company, rule, time away policy
  • Summary: This API retrieves a time away policy using the specified ID. The request requires an Authorization header with a Bearer token. The response includes details of the time away policy such as the policy ID, company ID, name, version details, and rules. The version details include information about bypassing working schedules and public holidays, visible balances, and specific rules with limits on yearly allowance, carry over, and usage.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a Time Away Type

  • ID: get_time_away_type
  • Operation: read
  • Entities: company, category, time away type
  • Summary: This API retrieves a time away type using the specified ID. The request requires an Authorization header with a Bearer token. The response includes details such as the ID, company ID, name, emoji, emoji label, category, base type, and timestamps for creation and last update of the time away type.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a Timesheet Entry

  • ID: get_timesheet_entry
  • Operation: read
  • Entities: timesheet entry, person, duration
  • Summary: This API retrieves a timesheet entry with the specified ID. The request requires an Authorization header with a Bearer token. The path parameter 'id' is required to specify which timesheet entry to retrieve. The response includes details of the timesheet entry such as the ID, person ID, date, start and end times, duration, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve a Timesheet Submission

  • ID: get_timesheet_submission
  • Operation: read
  • Entities: person, timesheet submission, duration
  • Summary: This API retrieves a timesheet submission using a GET request to the specified endpoint. It requires an Authorization header with a Bearer token for authentication. The API does not require any path or query parameters. Upon a successful request, it returns a timesheet submission object containing details such as the submission ID, person ID, start and end dates, status, submission and review timestamps, any requested changes, duration in hours and days, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Retrieve Token Information

  • ID: get_token_information
  • Operation: read
  • Entities: token
  • Summary: The 'Retrieve Token Information' API is used to retrieve the scopes associated with the currently used token. It requires an Authorization header with a Bearer token. The API does not require any path parameters, query parameters, or request body. Upon a successful request, it returns the scopes of the current token in the response body.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update a Bank Account

  • ID: patch_update_a_bank_account
  • Operation: write
  • Entities: person, bank account
  • Summary: This API allows updating the details of a bank account identified by its unique ID. The PATCH request can update fields such as bankName, nameOnAccount, accountNumber, swiftCode, sortCode, and routingNumber. The request requires an Authorization header with a Bearer token and a Content-Type header set to application/json. The response returns the updated bank account details, including the id, personId, bankName, nameOnAccount, accountNumber, swiftCode, sortCode, routingNumber, createdAt, and updatedAt timestamps. If the parameters are invalid, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update a Company

  • ID: patch_update_a_company
  • Operation: write
  • Entities: company, timesheet, employee
  • Summary: The 'Update a Company' API allows users to update the details of a company identified by its unique ID. The API uses the PATCH method and requires an authorization bearer token. The request can include parameters such as 'name', 'isTimesheetEnabled', 'autogenerateEmployeeId', 'autogenerateEmployeeIdForNewHires', and 'nextEmployeeId'. The response returns the updated company details, including fields like 'id', 'name', 'domains', 'trialEndDate', 'status', 'paymentStatus', 'package', 'createdAt', 'updatedAt', and 'isTimesheetEnabled'.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update a Compensation

  • ID: patch_update_a_compensation
  • Operation: write
  • Entities: note, job role, compensation
  • Summary: The Update a Compensation API allows you to update the details of a compensation entry for a specific job role. The API uses the PATCH method and requires the compensation ID as a path parameter. The request headers must include an Authorization token and specify the Content-Type as application/json. The request body can include optional parameters such as compensationTypeId, amount, currency, period, note, effectiveDate, endDate, and endReason to update the compensation details. The response returns the updated compensation details, including the ID, personId, compensationTypeId, amount, currency, period, note, effectiveDate, endDate, endReason, createdAt, and updatedAt timestamps. If the parameters are invalid, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update a Document

  • ID: patch_update_a_document
  • Operation: write
  • Entities: company, document, person
  • Summary: This API allows you to update a document in the Humaans system. You can update the document's name, document type ID, issue date, and type by providing the document ID in the path parameters. The request must include an authorization bearer token and specify the content type as JSON. The response returns the updated document details, including the document ID, company ID, person ID, name, link, file details, source, source ID, issue date, creation date, and last update date. If the update is successful, the updated document is returned; otherwise, an error is returned if the parameters are invalid.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update a Job Role

  • ID: patch_update_a_job_role
  • Operation: write
  • Entities: manager, job role, department
  • Summary: This API updates a job role object at the specified endpoint. It allows updating fields such as job title, department, effective date, note, and reporting manager. The request requires an authorization header with a bearer token and a content-type header set to application/json. The job role ID is specified in the path parameters. The response returns the updated job role details if successful, or an error if the parameters are invalid.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update a Location

  • ID: patch_update_a_location
  • Operation: write
  • Entities: working pattern, time away policy, location
  • Summary: The 'Update a Location' API allows users to update the details of a specific location identified by its unique ID. The API endpoint is accessed via a PATCH request to 'https://app.humaans.io/api/locations/{id}'. The request must include an authorization header with a bearer token and a content-type header set to 'application/json'. The body of the request can include various parameters such as 'address', 'city', 'state', 'postcode', 'countryCode', 'label', 'timeAwayPolicyId', 'timeAwayPolicyEffectiveDate', 'workingPatternId', and 'workingPatternEffectiveDate'. The response returns the updated location details if the update is successful, or an error if the parameters are invalid. The response includes fields such as 'id', 'companyId', 'label', 'displayName', 'address', 'postcode', 'city', 'state', 'country', 'regionCode', 'countryCode', 'timezone', 'isAddressInvalid', 'timeAwayPolicyId', 'timeAwayPolicyEffectiveDate', 'workingPatternId', 'workingPatternEffectiveDate', 'createdAt', and 'updatedAt'.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update a Custom Field

  • ID: patch_update_custom_field
  • Operation: write
  • Entities: company, custom field
  • Summary: This API allows updating a custom field in the Humaans application. The endpoint requires the custom field ID as a path parameter. The request must include an Authorization header with a Bearer token and a Content-Type header set to application/json. The request body can include the 'name' of the custom field and an optional 'config' object for additional configuration. The response returns the updated custom field details, including its ID, company ID, name, section, subsection, type, configuration, creation date, and last update date.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update a Custom Value

  • ID: patch_update_custom_value
  • Operation: write
  • Entities: custom value, person, custom field
  • Summary: This API updates a custom value in the Humaans system. It requires the ID of the custom value to be updated, provided in the path parameters. The request must include an Authorization header with a Bearer token and a Content-Type header set to application/json. The body of the request should contain the new value for the custom field, which can be a string, an array of strings, or null, depending on the type of the custom field. The API returns the updated custom value if the update is successful, or an error if the parameters are invalid.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update Emergency Contact

  • ID: patch_update_emergency_contact
  • Operation: write
  • Entities: emergency contact, employee
  • Summary: This API allows updating an emergency contact's details using the PATCH method. The endpoint requires the ID of the emergency contact to be updated in the path parameters. The request headers must include an Authorization bearer token and specify the Content-Type as application/json. The request body can include optional fields such as name, email, phoneNumber, and relationship to update the respective details of the emergency contact. The response returns the updated emergency contact details, including fields like id, personId, name, email, phoneNumber, formattedPhoneNumber, relationship, isPrimary, createdAt, and updatedAt. If the update is successful, the updated emergency contact is returned; otherwise, an error is returned if the parameters are invalid.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update Equipment Details

  • ID: patch_update_equipment_details
  • Operation: write
  • Entities: response, parameter, equipment
  • Summary: This API allows updating the details of a specific equipment identified by its unique ID. The PATCH request can modify various attributes of the equipment such as type, name, serial number, cost, currency, notes, file attachment, issue date, receipt date, and collection date. The request requires an Authorization header with a Bearer token and a Content-Type header set to application/json. The response returns the updated equipment details if successful, or an error if the parameters are invalid.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update an Identity Document

  • ID: patch_update_identity_document
  • Operation: write
  • Entities: person, identity document, file
  • Summary: This API allows updating an identity document in the system. The PATCH request is sent to the endpoint with the document ID in the path. The request body can include fields such as type, number, countryCode, expiryDate, note, fileId, and verifiedBy to update the respective details of the identity document. The request must include an Authorization header with a Bearer token. If the update is successful, the API returns the updated identity document details, including fields like id, personId, type, number, countryCode, expiryDate, note, fileId, file details, verifiedBy, verifiedAt, isVerified, createdAt, and updatedAt.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update a Person's Details

  • ID: patch_update_person_details
  • Operation: write
  • Entities: employment, person, address
  • Summary: This API endpoint allows updating the details of a person in the Humaans system. The PATCH request can update various fields such as name, email, phone numbers, address, employment details, and more. The request requires an Authorization header with a Bearer token and a Content-Type header set to application/json. The person to be updated is identified by the 'id' path parameter. The response returns the updated details of the person if the update is successful. If any parameters are invalid, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update a Time Away Adjustment

  • ID: patch_update_time_away_adjustment
  • Operation: write
  • Entities: time away adjustment, person, time away type
  • Summary: The 'Update a Time Away Adjustment' API allows users to modify an existing time away adjustment by specifying the adjustment ID in the path parameters. The API accepts optional fields in the request body such as 'date', 'deltaDays', 'reason', 'validUntil', and 'timeAwayTypeId' to update the respective details of the adjustment. The request must include an 'Authorization' header with a bearer token and a 'Content-Type' header set to 'application/json'. Upon successful update, the API returns the updated time away adjustment details including 'id', 'personId', 'date', 'deltaDays', 'reason', 'validUntil', 'timeAwayTypeId', 'createdAt', and 'updatedAt'.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update a Time Away Allocation

  • ID: patch_update_time_away_allocation
  • Operation: write
  • Entities: time away policy, place of work, time away allocation
  • Summary: This API endpoint allows updating a time away allocation for an employee. The PATCH request is made to the endpoint with the specific allocation ID. The request can include parameters such as 'type', 'effectiveDate', 'timeAwayPolicyId', and 'timeAwayPolicy'. The 'type' parameter determines the kind of allocation and can be 'placeOfWork', 'specific', or 'custom'. The 'effectiveDate' specifies when the allocation starts. If the type is 'specific', a 'timeAwayPolicyId' must be provided. If the type is 'custom', a 'timeAwayPolicy' object can be included to define custom policies. The response returns the updated time away allocation details, including the allocation ID, person ID, type, effective date, and policy details.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update a Time Away Entry

  • ID: patch_update_time_away_entry
  • Operation: write
  • Entities: time away, time away type, location
  • Summary: This API allows updating a time away entry in the Humaans system. The PATCH request is sent to the endpoint with the specific time away entry ID. The request can include parameters such as startDate, endDate, startPeriod, endPeriod, note, workingFromLocationId, timeAwayTypeId, requestStatus, and reviewNote. The response returns the updated time away entry details, including breakdown of days, request status, and any review notes. Authorization is required via a Bearer token.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update a Time Away Policy

  • ID: patch_update_time_away_policy
  • Operation: write
  • Entities: rule, limit, time away policy
  • Summary: This API allows updating a time away policy by sending a PATCH request to the specified endpoint. The request requires an authorization header with a bearer token and a content-type header set to 'application/json'. The path parameter 'id' is required to specify the policy to be updated. The request body can include the policy name and time away policy version details, such as bypassing working schedules, public holidays, public holiday calendar ID, visible balances, and rules for time away types. Each rule must include a time away type ID and limits, which define yearly allowance, max carryover, year start, unlimited status, prorated status, usage, and usage period. The response returns the updated time away policy details, including the policy ID, company ID, name, version details, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update a Time Away Type

  • ID: patch_update_time_away_type
  • Operation: write
  • Entities: company, category, time away type
  • Summary: This API allows updating a time away type by sending a PATCH request to the specified endpoint. The request requires an Authorization header with a Bearer token and a Content-Type header set to application/json. The path parameter 'id' is required to specify the time away type to update. The request body can include optional parameters 'name' and 'emoji' to update the respective fields. The response returns the updated time away type details, including its id, companyId, name, emoji, emojiLabel, category, baseType, createdAt, and updatedAt timestamps.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update a Timesheet Entry

  • ID: patch_update_timesheet_entry
  • Operation: write
  • Entities: timesheet entry, time, duration
  • Summary: This API allows updating a timesheet entry by specifying the entry ID in the path parameters. The request can include optional fields such as date, startTime, and endTime in the body to update the respective timesheet entry details. The request must include an Authorization header with a Bearer token and a Content-Type header set to application/json. Upon successful update, the API returns the updated timesheet entry details including the ID, personId, date, startTime, endTime, duration, createdAt, and updatedAt timestamps.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update a Timesheet Submission

  • ID: patch_update_timesheet_submission
  • Operation: write
  • Entities: status, change requested, timesheet submission
  • Summary: This API allows updating a timesheet submission by changing its status to one of 'pending', 'approved', or 'rejected'. If the status is set to 'rejected', an optional 'changesRequested' field can be provided to specify the changes needed. The API requires an authorization token and the content type to be specified in the headers. The timesheet submission ID is required as a path parameter. Upon successful update, the API returns the updated timesheet submission details, including the ID, person ID, start and end dates, status, submission and review timestamps, requested changes, duration in hours and days, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Compensation

  • ID: post_create_a_compensation
  • Operation: write
  • Entities: role, employee, compensation
  • Summary: This API endpoint allows the creation of a compensation entry for a specific person. The request requires the person's ID, type of compensation, amount, period, and effective date. Optional fields include currency, note, end date, and end reason. The response returns the created compensation details including timestamps for creation and last update. The API ensures that only the role with the highest effective date that is not in the future is considered active.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Document

  • ID: post_create_a_document
  • Operation: write
  • Entities: person, document, file
  • Summary: This API endpoint allows you to create a document in the system. You need to provide the document's name and the person ID in the request body. Optionally, you can provide the document type ID, link, file ID, issue date, and type. The request must include an authorization bearer token and specify the content type as JSON. The response returns the created document details, including its ID, company ID, person ID, name, link, file details, source, issue date, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a File

  • ID: post_create_a_file
  • Operation: write
  • Entities: person, document, file
  • Summary: The Create a File API allows users to upload files to the Humaans platform using a multipart form data request. The API requires an authorization token in the headers and accepts parameters such as personId, type, and the file itself in the body. The personId is optional and should be set to the ID of the person the file will be attached to, or null for company-wide documents. The type parameter is required and specifies the kind of resource the file is attached to, such as profilePhoto, identityDocument, document, equipment, or leavingFile. Upon successful upload, the API returns details of the file, including its ID, associated company and person IDs, type, uploader ID, filename, access URL, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Location

  • ID: post_create_a_location
  • Operation: write
  • Entities: working pattern, time away policy, location
  • Summary: The 'Create a Location' API allows users to create a new location within the system. It requires a POST request to the endpoint 'https://app.humaans.io/api/locations'. The request must include headers for authorization and content type, and a body with details such as city, country code, and time away policy ID. Optional fields include address, state, postcode, label, and working pattern details. Upon successful creation, the API returns a detailed response with the location's ID, company ID, address, and other relevant information.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Person

  • ID: post_create_a_person
  • Operation: write
  • Entities: job role, person, location
  • Summary: The 'Create a Person' API allows for the creation of a new person in the system with either an 'active' or 'newHire' status. By default, the status is 'active', requiring all mandatory fields such as firstName, lastName, email, locationId, jobRole, employmentStartDate, teams.name, and timeAwayAllocation.timeAwayPolicyId. For 'newHire' status, only one of email or personalEmail is required, and other fields are optional. This API is typically used in Applicant Tracking System (ATS) integrations. The API requires authorization via a Bearer token and accepts JSON formatted data. Upon successful creation, it returns the details of the person, including their ID, name, email, location, job role, and other personal and employment details.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Bank Account

  • ID: post_create_bank_account
  • Operation: write
  • Entities: person, bank account
  • Summary: This API endpoint allows the creation of a bank account associated with a specific person. The request requires a 'personId' to associate the bank account with a person. Optional parameters include 'bankName', 'nameOnAccount', 'accountNumber', 'swiftCode', 'sortCode', and 'routingNumber'. The request must include an Authorization header with a Bearer token and a Content-Type header set to 'application/json'. Upon success, the API returns the details of the created bank account, including its unique ID, associated person ID, bank name, account holder's name, account number, swift code, sort code, routing number, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Custom Field

  • ID: post_create_custom_field
  • Operation: write
  • Entities: type, custom field
  • Summary: This API endpoint allows the creation of a custom field in the specified profile section. The request requires a name, section, and type for the custom field, with optional subsection and configuration parameters. The type can be one of several options, and if the section is 'diversity', the type is limited to text, select, or multiSelect. The response returns the details of the created custom field, including its ID, company ID, name, section, subsection, type, configuration, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Custom Value

  • ID: post_create_custom_value
  • Operation: write
  • Entities: custom value, person, custom field
  • Summary: This API endpoint allows the creation of a custom value associated with a person in the Humaans system. The request requires a personId, customFieldId, and a value, which can be a string, array, or null depending on the custom field type. An optional resourceId can be provided if the field is a subresource. The response returns the created custom value with its ID, associated person ID, custom field ID, resource ID, value, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Document Type

  • ID: post_create_document_type
  • Operation: write
  • Entities: company, name, document type
  • Summary: This API endpoint allows the creation of a new document type in the system. The request requires an authorization bearer token and a content type header. The body of the request must include the 'name' parameter, which is a string representing the label of the document type. This label is used to organize documents and restrict access based on document permissions set in the Admin area. Upon successful creation, the API returns the document type details including its unique ID, company ID, name, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create an Emergency Contact

  • ID: post_create_emergency_contact
  • Operation: write
  • Entities: person, emergency contact
  • Summary: This API endpoint allows the creation of an emergency contact for a specified person. The request requires a personId, which is the ID of the person the emergency contact is associated with. Optional fields include the name, email, phone number, relationship, and whether the contact is primary. The response returns the details of the created emergency contact, including its ID, associated personId, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create Equipment

  • ID: post_create_equipment
  • Operation: write
  • Entities: person, file, equipment
  • Summary: The Create Equipment API allows you to create a new equipment record associated with a person. It requires the person ID, equipment type, name, and issue date as mandatory fields. Optional fields include serial number, cost, currency, note, file attachment, receipt date, and collection date. The API returns the created equipment object upon success or an error if the parameters are invalid.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create an Identity Document

  • ID: post_create_identity_document
  • Operation: write
  • Entities: person, identity document, file
  • Summary: This API endpoint allows the creation of an identity document associated with a person. It requires the person ID, document type, and file ID as mandatory fields. Optional fields include document number, country code, expiry date, note, and verifier ID. The API returns the created identity document details, including its ID, associated person ID, document type, file details, verification status, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Job Role

  • ID: post_create_job_role
  • Operation: write
  • Entities: job role, department, employee
  • Summary: This API endpoint allows the creation of a job role for an employee. Multiple job roles can be created for each employee, but only the role with the highest effectiveDate that is not in the future will be considered active. The request requires the personId, jobTitle, and effectiveDate as mandatory fields. Optional fields include department, note, and reportingTo. The response returns the details of the created job role, including its unique ID, associated person ID, job title, department, effective and end dates, manager ID, note, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Time Away Adjustment

  • ID: post_create_time_away_adjustment
  • Operation: write
  • Entities: time away adjustment, person, time away type
  • Summary: This API creates a time away adjustment for a specified person. It requires the person ID, date of adjustment, number of days to adjust (deltaDays), reason for the adjustment, and the time away type ID. Optionally, a valid until date can be provided. The API returns the created time away adjustment details including the ID, person ID, date, deltaDays, reason, valid until date, time away type ID, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Time Away Allocation

  • ID: post_create_time_away_allocation
  • Operation: write
  • Entities: time away policy, person, time away allocation
  • Summary: This API endpoint is used to create a time away allocation for a person. It requires the personId, type of allocation, and effectiveDate as mandatory fields. The type of allocation can be 'placeOfWork', 'specific', or 'custom'. Depending on the type, either timeAwayPolicyId or timeAwayPolicy must be provided. The API returns the created time away allocation details, including the policy information if applicable.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Time Away Entry

  • ID: post_create_time_away_entry
  • Operation: write
  • Entities: time away, person, location
  • Summary: This API endpoint allows the creation of a time away entry for a specified person. The request requires the person's ID, start and end dates, and the time away type ID. Optional parameters include start and end periods, a note, working location ID, request status, and a review note. The response returns the details of the created time away entry, including breakdown by date, total days, request status, and timestamps for creation and updates.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Time Away Policy

  • ID: post_create_time_away_policy
  • Operation: write
  • Entities: rule, time away policy version, time away policy
  • Summary: This API endpoint allows the creation of a time away policy. The request requires a policy name and detailed time away policy version information, including rules and limits for time away types. The response returns the created time away policy with its details, including the unique identifiers, policy name, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Time Away Type

  • ID: post_create_time_away_type
  • Operation: write
  • Entities: company, category, time away type
  • Summary: This API endpoint allows the creation of a new time away type in the system. It requires the name, emoji, and category of the time away type as input parameters. The category must be either 'workingAway' or 'timeOff'. The request must include an authorization bearer token in the headers. Upon successful creation, the API returns the details of the newly created time away type, including its ID, company ID, name, emoji, emoji label, category, base type, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Timesheet Entry

  • ID: post_create_timesheet_entry
  • Operation: write
  • Entities: timesheet entry, person, duration
  • Summary: This API endpoint allows the creation of a timesheet entry for a specified person. The request requires the person's ID, the date of the entry, and the start time. The end time is optional. The request must include an authorization bearer token and specify the content type as application/json. Upon success, the API returns the created timesheet entry, including its ID, associated person ID, date, start and end times, duration, and timestamps for creation and last update.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Create a Timesheet Submission

  • ID: post_create_timesheet_submission
  • Operation: write
  • Entities: person, timesheet submission, duration
  • Summary: This API endpoint allows the creation of a timesheet submission for a specified person. The request requires the person's ID and the start date of the month the timesheet covers. The response includes details of the timesheet submission, such as its ID, status, submission and review timestamps, and duration in both time and days. The API requires authorization via a Bearer token.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Update Document Type

  • ID: post_update_document_type
  • Operation: write
  • Entities: company, document type
  • Summary: This API updates a document type in the Humaans application. It requires the document type ID as a path parameter and the new name of the document type in the request body. The request must include an Authorization header with a Bearer token and a Content-Type header set to application/json. If the update is successful, the API returns the updated document type details, including its ID, company ID, name, creation timestamp, and last update timestamp. If the parameters are invalid, an error is returned.
  • Input Fields: Input Fields
  • Output Fields: Output Fields

Updated about 1 month ago