The TalentHR provides many API products, tools, and resources that enable you to integrate TalentHR with your internal software.
\nTo start using the TalentHR API, you need to:
\nThe TalentHR API uses \"basic authentication\" for authentication.
\nTalentHR uses API keys for authentication. You can generate a TalentHR API key in the API section of your TalentHR domain settings.
\nWhen using Basic Auth within the TalentHR API, the username must be set as the API Key obtained from the system. However, the password field can be left blank or set to a random string, as it has no impact on the authentication process at this time. You can fill these fields in the global variables of TalentHR API.
\napi_key:123. The username part is set to βapi_keyβ and the password part is set to a random string β123β, in this case.echo -n api_key:random_string | base64\n\n$Text = βapi_key:random_stringβ$Bytes = [System.Text.Encoding]::UTF8.GetBytes($Text)$EncodedText = [Convert]::ToBase64String($Bytes)$EncodedText\n\nSupply an Authorization header with content Basic followed by the encoded string. For example, the string samplekey:123 encodes to c2FtcGxla2V5OjEyMw== in base64, so you would make the request as follows:
curl -D- \\ -X GET \\ -H \"Authorization: {{vault:basic-auth}}\" \\ -H \"Content-Type: application/json\" \\\"https://pubapi.talenthr.io/v1/directory\"\n\nIf an API key is missing, malformed, or invalid, you will receive an HTTP 401 Unauthorized response code.
\nAPI access rate limits apply at a per-API key basis in unit time. The limit is 2000 requests per minute. Also, depending on your plan, you may have usage limits. If you exceed either limit, your request will return an HTTP 429 Too Many Requests status code.
\nIn case you have questions, please go through our Knowledge Base or you can contact our support at support@talenthr.io
\nSome endpoints in the talentHR API implement a paging mechanism to efficiently break large datasets into smaller, more manageable chunks. The pagination mechanism is consisted of two essential attributes: offset & limit. The limit parameter determines the maximum number of records returned per call (maximum 100), while the offset parameter indicates the current page. In case the limit parameter is not specified in a request, the system defaults to a limit of 10.
\nPagination starts from an offset of 0, with subsequent pages based on the defined limit. For instance, if the limit is set to 10 records, the offset for the next page would be calculated as previous_offset + limit. For example, if the previous offset is 0 and the limit is 10, the offset for the next page would be 0 + 10 = 10, and so forth.
\nThe system offers three distinct categories of custom fields for managing information: pre-existing , employees and assets custom fields.
\nPre-existing custom fields are fields that already exist in the system and have an essential part to employee's information. They include a variety of types, such as text, single and multiple choice, links, and blended options. Among these, the blended option is a complex field that comprises additional attributes. (e.g. driver's license blended option consists of 4 fields; Number, Issued date, Expiry date, Issuing country).
\nSome pre-existing custom fields are enabled by default from the system's initiation, allowing immediate use without requiring a subscription. These readily accessible custom fields include:
\nTo access additional pre-existing custom fields, a subscription is necessary. These fields encompass a wider range of attributes and they are the following:
\nNote: The type or visibility of these pre-existing custom fields cannot be modified, as they are predefined.
\nEmployee custom fields can be used to capture information for employees. The type of them can vary from text to long text, from single to multiple-choice, links, references to employees, or dates. In addition, these custom fields have adjustable visibility settings, allowing access exclusively to the employee, to the manager, both to the employee and his/her manager, or universally to all. You have the ability to create an employee custom field even without a subscription; this means the field exists in an idle state until the necessary subscription is acquired, enabling its use.
\nAsset custom fields can be used to capture information for assets. The type of them can vary from text to long text, from single to multiple-choice, links, references to employees, or dates. In addition, these custom fields have adjustable visibility settings, allowing access exclusively to the employee, to the manager, both to the employee and his/her manager, or universally to all. Also, an additional option is available that allows these fields to be specifically applied to inventory, memberships, or universally across all asset types. You have the ability to create an asset custom field even without a subscription; this means the field exists in an idle state until the necessary subscription is acquired, enabling its use.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"32971705","collectionId":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","publishedId":"2sBXwmSDRi","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-05-28T08:42:05.000Z"},"item":[{"name":"Domain Settings","item":[{"name":"Get all system's timezones","id":"3456a3f7-b8fb-4485-8984-7fdb3eefbacf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Accept","value":"application/json"}],"url":"https://pubapi.talenthr.io/v1/timezones","description":"This API endpoint retrieves a list of available timezones supported by the system.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":""},{"key":"password","value":""}]},"isInherited":true,"source":{"_postman_id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","name":"TalentHR API","type":"collection"}},"urlObject":{"path":["timezones"],"host":["https://pubapi.talenthr.io/v1"],"query":[],"variable":[]}},"response":[{"id":"2699bd71-a9cc-4603-b260-a5672ce80e82","name":"OK","originalRequest":{"method":"GET","header":[{"description":"Added as a part of security scheme: basic","key":"Authorization","value":"BasicThis API endpoint retrieves a list of available languages supported by the system.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":""},{"key":"password","value":""}]},"isInherited":true,"source":{"_postman_id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","name":"TalentHR API","type":"collection"}},"urlObject":{"path":["languages"],"host":["https://pubapi.talenthr.io/v1"],"query":[],"variable":[]}},"response":[{"id":"2d4af386-56d6-4357-883a-1ba79739d03b","name":"OK","originalRequest":{"method":"GET","header":[{"description":"Added as a part of security scheme: basic","key":"Authorization","value":"BasicThis API endpoint retrieves a list of available countries supported by the system.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":""},{"key":"password","value":""}]},"isInherited":true,"source":{"_postman_id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","name":"TalentHR API","type":"collection"}},"urlObject":{"path":["countries"],"host":["https://pubapi.talenthr.io/v1"],"query":[],"variable":[]}},"response":[{"id":"3b9f0553-2e64-4ec7-bc57-37db86d43c18","name":"OK","originalRequest":{"method":"GET","header":[{"description":"Added as a part of security scheme: basic","key":"Authorization","value":"BasicReturns the catalogue of supported fiat currencies used by the product for forms, validation, and integrations. The response includes a boolean success indicator and a data array of objects.
Each object includes code (ISO 4217 alphabetic code) and name (human-readable label). Some entries MAY include an exchange string when the row represents a currency priced or reported against another code (see the application configuration for the authoritative list).
The sequence and membership of the catalogue are defined by server configuration and MAY change between releases. Clients SHOULD NOT assume a fixed length.
Authorization. The caller MUST authenticate with a valid API key for the tenant (same requirements as other public v1 resources).
","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":""},{"key":"password","value":""}]},"isInherited":true,"source":{"_postman_id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","name":"TalentHR API","type":"collection"}},"urlObject":{"path":["currencies"],"host":["https://pubapi.talenthr.io/v1"],"query":[],"variable":[]}},"response":[{"id":"865875b0-4c1c-4592-abd0-53ac3400d54a","name":"OK (200)","originalRequest":{"method":"GET","header":[{"description":"Added as a part of security scheme: basic","key":"Authorization","value":"BasicThis API endpoint retrieves a list of available nationalities supported by the system.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":""},{"key":"password","value":""}]},"isInherited":true,"source":{"_postman_id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","name":"TalentHR API","type":"collection"}},"urlObject":{"path":["nationalities"],"host":["https://pubapi.talenthr.io/v1"],"query":[],"variable":[]}},"response":[{"id":"d516467c-0e62-443e-b442-6cb46ef705b1","name":"OK","originalRequest":{"method":"GET","header":[{"description":"Added as a part of security scheme: basic","key":"Authorization","value":"BasicThis API endpoint retrieves a list of available education levels supported by the system.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":""},{"key":"password","value":""}]},"isInherited":true,"source":{"_postman_id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","name":"TalentHR API","type":"collection"}},"urlObject":{"path":["education-levels"],"host":["https://pubapi.talenthr.io/v1"],"query":[],"variable":[]}},"response":[{"id":"307082d9-6341-4e02-a382-59f6e1bf1e2b","name":"OK","originalRequest":{"method":"GET","header":[{"description":"Added as a part of security scheme: basic","key":"Authorization","value":"BasicThis API endpoint retrieves a list of available employment statuses supported by the system.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":""},{"key":"password","value":""}]},"isInherited":true,"source":{"_postman_id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","name":"TalentHR API","type":"collection"}},"urlObject":{"path":["employment-statuses"],"host":["https://pubapi.talenthr.io/v1"],"query":[],"variable":[]}},"response":[{"id":"8adcf9aa-e857-4140-a42c-d5fd2cb7069d","name":"OK","originalRequest":{"method":"GET","header":[{"description":"Added as a part of security scheme: basic","key":"Authorization","value":"BasicThis API endpoint retrieves a list of available relationship types supported by the system.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":""},{"key":"password","value":""}]},"isInherited":true,"source":{"_postman_id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","name":"TalentHR API","type":"collection"}},"urlObject":{"path":["relationship-types"],"host":["https://pubapi.talenthr.io/v1"],"query":[],"variable":[]}},"response":[{"id":"dd251084-5270-4751-8c74-0637c6abb151","name":"OK","originalRequest":{"method":"GET","header":[{"description":"Added as a part of security scheme: basic","key":"Authorization","value":"BasicReturns the consolidated system configuration for the authenticated tenant, comprising domain-level and company-level attributes that are exposed through this version of the public HTTP API.
The response includes a boolean success indicator and a data object. Property names follow the public v1 contract (for example, language denotes the UI language code, domain denotes the tenant subdomain hostname, and logo_url denotes a signed or public logo URL when configured). The currency field, when present, is the tenant default ISO code; see GET https://pubapi.talenthr.io/v1/currencies (List currencies). The login_method property is a JSON array of string slugs; each element MUST be a member of the platform allow list. At the time of publication, the permitted values are: local, google, microsoft, and apple. Additional identifiers MAY be introduced in a future release and are subject to the same validation rules.
Further scalar flags (including, where applicable, two_factor_auth, ai_assistant_company_data, and ai_files_summary) are included when relevant to the tenant subscription and configuration. The effective set of properties returned in data is constrained by the caller's authorizations and by tenant-level feature availability.
Authorization. The caller MUST possess permission to view domain settings.
","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":""},{"key":"password","value":""}]},"isInherited":true,"source":{"_postman_id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","name":"TalentHR API","type":"collection"}},"urlObject":{"path":["system-settings"],"host":["https://pubapi.talenthr.io/v1"],"query":[],"variable":[]}},"response":[{"id":"9abe5ae7-644f-44d2-a88d-67c12e98da0a","name":"OK (200)","originalRequest":{"method":"GET","header":[{"description":"Added as a part of security scheme: basic","key":"Authorization","value":"BasicUpdates permitted domain-level and company-level system attributes for the authenticated tenant. All request payloads are validated prior to persistence; a failed validation results in an error response and no partial update.
For the tenant subdomain, the request body MUST use the property name domain. A property named name, if present, is not interpreted for subdomain updates on this route. The property name language MUST match the public GET response contract for the same resource.
The login_method property MUST be a JSON array whose elements are string slugs drawn exclusively from the platform allow list. At the time of publication, the permitted values are: local, google, microsoft, and apple. The request MUST NOT supply the internal JSON envelope that nests the array (that pattern is rejected by this API version). Each submitted slug MUST appear at most once; the array denotes the set of methods enabled for the tenant.
The currency property is the tenant default ISO currency code (at most three characters); use a code value from GET https://pubapi.talenthr.io/v1/currencies (List currencies).
Required company-level attributes in the submitted payload include company_name, theme, and currency. Optional company-level attributes include working_days, logo_url or multipart logo, two_factor_auth, ai_assistant_company_data, and ai_files_summary. If the ai-files-summary subscription feature is not enabled for the tenant, a submitted ai_files_summary field MAY be removed from the request prior to validation.
Authorization. The caller MUST possess permission to update system settings for each logical field group represented in the submitted payload.
\n\nRequest body:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":""},{"key":"password","value":""}]},"isInherited":true,"source":{"_postman_id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","name":"TalentHR API","type":"collection"}},"urlObject":{"path":["system-settings"],"host":["https://pubapi.talenthr.io/v1"],"query":[],"variable":[]}},"response":[{"id":"33e0e23e-ccbc-47cf-b2d4-0bf8ca89fc6e","name":"OK (200)","originalRequest":{"method":"POST","header":[{"description":"Added as a part of security scheme: basic","key":"Authorization","value":"BasicThis endpoint returns a paginated list of the tenantβs default employee document folders (data.total and data.rows). Requires permission to list default document folders. Query parameter behaviour is described in the Params list; the saved OK (200) example illustrates the response shape.
(integer) Optional. Pagination offset used together with limit (page-bucket semantics: offset 0 with limit 10 is page 1; offset 10 with limit 10 is page 2). Default when omitted: 0. Non-integer or negative values yield HTTP 422.
\n","type":"text/plain"},"key":"offset","value":"(integer) Optional. Rows per page. Default when omitted: 10. Minimum: 1; maximum: 100 inclusive. Values outside 1β100 yield HTTP 422.
\n","type":"text/plain"},"key":"limit","value":"(string) Optional. Sort field. Allowed: name, created_at, updated_at. Other values are normalized to name.
\n","type":"text/plain"},"key":"sort","value":"(string) Optional. Sort direction. Allowed: asc, desc. Invalid values are normalized to the default for the resource (asc).
\n","type":"text/plain"},"key":"order","value":"This endpoint returns one default employee document folder, including aggregated permissions rows for folder view/edit by user role (same shape as create and update success payloads). Requires permission to view default document folders. The saved OK (200) example illustrates the response shape.
(integer) Default document folder id (numeric path segment).
\n","type":"text/plain"},"type":"any","value":"Creates a default employee document folder with a display name and role-based permissions for who can view and edit documents in that folder.
\nRequires permission to create default document folders.
\nUse List user roles (GET https://pubapi.talenthr.io/v1/user-roles) for user_role_id values. Use Get type and permission values (GET https://pubapi.talenthr.io/v1/custom-fields-values) for allowed action and condition tokens under data.permission_values.
Request body:
\nThere are no path parameters.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":""},{"key":"password","value":""}]},"isInherited":true,"source":{"_postman_id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","name":"TalentHR API","type":"collection"}},"urlObject":{"path":["domain","default-folders"],"host":["https://pubapi.talenthr.io/v1"],"query":[],"variable":[]}},"response":[{"id":"1212c231-50bb-4cf5-bb66-b55bd9b935c5","name":"OK (200)","originalRequest":{"method":"POST","header":[{"description":"Added as a part of security scheme: basic","key":"Authorization","value":"BasicUpdates a default employee document folder identified in the path. Replaces the folder display name (when allowed) and the permission matrix for folder view and edit.
\nRequires permission to update default document folders.
\nFor the system folder with slug employee-home-folder, permission changes are applied; a submitted name is not persisted.
Use List user roles (GET https://pubapi.talenthr.io/v1/user-roles) for user_role_id values. Use Get type and permission values (GET https://pubapi.talenthr.io/v1/custom-fields-values) for allowed action and condition tokens under data.permission_values.
Request body:
\nPath parameters are documented under Params.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":""},{"key":"password","value":""}]},"isInherited":true,"source":{"_postman_id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","name":"TalentHR API","type":"collection"}},"urlObject":{"path":["domain","default-folders",":default_document_folder"],"host":["https://pubapi.talenthr.io/v1"],"query":[],"variable":[{"description":{"content":"(integer) Default document folder id.
\n","type":"text/plain"},"type":"any","value":"This endpoint removes the default folder identified in the path. On success returns a boolean flag in success. Use the Params list for the optional query flag; Not found (HTTP 404) and Conflict (HTTP 409) examples are illustrative.
(integer) Optional. When set to 1, allows deleting a folder that still contains documents. When omitted or 0, the API rejects deletion with HTTP 409 if any documents remain. The Employee Home Folder is never deletable regardless of force.
\n","type":"text/plain"},"key":"force","value":"(integer) Default document folder id to delete.
\n","type":"text/plain"},"type":"any","value":"This API endpoint facilitates the creation of an employee within the system. When creating an employee, it's necessary to provide essential personal information such as first name, last name, and email address. Additionally, the endpoint requires details regarding the employee's hire date, employment status, and manager.
\nWhen we are adding a new employee, we should avoid creating loops or circles in the organization hierarchy.
\nIf the is_existing parameter is set to true the onboarding process is bypassed. Otherwise, if it's set to false, the employee is considered a new hire, and the system initiates the onboarding process for the newly hired employee.
In cases where no manager is specified, the employee becomes the head of the company hierarchy.
\nYou can choose to disable the initial system invite.
\nIn case you want to provide some additional information on onboarding new hires at the organization, you should fill in the hire packet object with the necessary information. This allow you to send an a email to the hiring employee containing detailed instructions for their first day of work.
\nAfter the successful creation of a newly hired employee's profile, an email is dispatched to the new hire containing essential information required for registering with the domain. This includes details such as login credentials, and any other relevant information to facilitate their smooth integration into the company's systems. Additionally, emails are sent to existing employees who are assigned the responsibility of conducting the onboarding tasks for the new employee.
\nRequest body:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":""},{"key":"password","value":""}]},"isInherited":true,"source":{"_postman_id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","name":"TalentHR API","type":"collection"}},"urlObject":{"path":["employees","hire"],"host":["https://pubapi.talenthr.io/v1"],"query":[],"variable":[]}},"response":[{"id":"cc259a18-e923-4394-9913-f7e324e824dc","name":"OK (200)","originalRequest":{"method":"POST","header":[{"description":"Added as a part of security scheme: basic","key":"Authorization","value":"BasicThis API endpoint retrieves the basic information of a specific employee from the system based on the provided employee ID.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":""},{"key":"password","value":""}]},"isInherited":true,"source":{"_postman_id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","name":"TalentHR API","type":"collection"}},"urlObject":{"path":["employees",":employee"],"host":["https://pubapi.talenthr.io/v1"],"query":[],"variable":[{"description":{"content":"(Required) The id of the employee
\n","type":"text/plain"},"type":"any","value":"This API endpoint enables the updating of an employee's information within the system based on the provided employee ID. You can modify various aspects of an employee's record, including personal details, contact information, designation, and any other relevant data stored within the system.
\nWhen updating an employee's profile, you can modify the custom fields associated with that employee. However, it is important to note that the availability of this feature is dependent on your TalentHR subscription (Refer to the Introductory chapter for further details). The custom fields associated with an employee can be retrieved using the 'Get employee's custom fields' endpoint.
\nRequest body:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":""},{"key":"password","value":""}]},"isInherited":true,"source":{"_postman_id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","id":"282b1908-49ef-4074-8ea7-67fdb51c9b4a","name":"TalentHR API","type":"collection"}},"urlObject":{"path":["employees",":employee"],"host":["https://pubapi.talenthr.io/v1"],"query":[],"variable":[{"description":{"content":"(Required) The id of the employee
\n","type":"text/plain"},"type":"any","value":"![https://cdn.example.com/tenant/logo.png](\"https://cdn.example.com/tenant/logo.png\"){kind=link}