{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"39f4121a-d6e2-48c3-a941-0c031292b69c","name":"TalentHR API","description":"The TalentHR provides many API products, tools, and resources that enable you to integrate TalentHR with your internal software.\n\n## 🚀 **Getting started guide**\n\nTo start using the TalentHR API, you need to:\n\n- You must use a valid API Key to send requests to the API endpoints. You can get your API key from TalentHR settings -> domain settings -> API.\n- The API has rate and usage limits (2000 requests per minute).\n- The API only responds to HTTPS-secured communications.\n- The API returns request responses in JSON format. When an API request returns an error, it is sent in the JSON response as an error key (All calls must have an Accept: application/json header value).\n    \n\n## 🔒Authentication\n\nThe TalentHR API uses \"basic authentication\" for authentication.\n\nTalentHR uses API keys for authentication. You can generate a TalentHR API key in the API section of your TalentHR domain settings.\n\nWhen using **Basic Auth** within the TalentHR API, the **username** must be set as the <u>API Key</u> obtained from the system. However, the **password** field can be left <u>blank</u> or set to a <u>random string</u>, as it has no impact on the authentication process at this time. You can fill these fields in the global variables of TalentHR API.\n\n## You can construct and send basic auth headers following these steps:\n\n1. Generate an API key for TalentHR ([How to generate an API key](https://help.talenthr.io/hc/en-us/articles/17627841146909-Can-I-integrate-my-site-with-TalentHR-Do-you-offer-an-API)).\n2. Build a string of the form `api_key:123`. The username part is set to “api_key” and the password part is set to a random string “123”, in this case.\n3. BASE64 encode the string.\n    \n\n- Linux/Unix/MacOS:\n    \n\n``` bash\necho -n api_key:random_string | base64\n\n ```\n\n- Windows 7 and later, using Microsoft Powershell:\n    \n\n``` powershell\n$Text = ‘api_key:random_string’$Bytes = [System.Text.Encoding]::UTF8.GetBytes($Text)$EncodedText = [Convert]::ToBase64String($Bytes)$EncodedText\n\n ```\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:\n\n``` bash\ncurl -D- \\   -X GET \\   -H \"Authorization: Basic c2FtcGxla2V5OjEyMw==\" \\   -H \"Content-Type: application/json\" \\\"https://pubapi.talenthr.io/v1/directory\"\n\n ```\n\n### Authentication error response\n\nIf an API key is missing, malformed, or invalid, you will receive an HTTP 401 Unauthorized response code.\n\n## Rate and usage limits\n\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.\n\n### ℹ️ **Need some help?**\n\nIn case you have questions, please go through our [Knowledge Base](https://help.talenthr.io/hc/en-us) or you can contact our support at [support@talenthr.io](https://mailto:support@talenthr.io)\n\n---\n\n## **Additional Information**\n\n<h5>1. 📖 Pagination mechanism :</h5>\n\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 pagination <u>can be disabled</u> by setting the offset parameter to -1. The limit parameter determines the maximum number of records returned per call, 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.\n\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.\n\n<h5>2. 🛠️ Custom Fields :</h5>\n\nThe system offers three distinct categories of custom fields for managing information: **pre-existing** , **employees** and **assets** custom fields.\n\n**Pre-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).\n\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:\n\n- Address\n- City\n- Citizenship\n- Country\n- Employee Number\n- LinkedIn\n- Marital Status\n- Nationality\n- Personal Email\n- Postal Code\n- SSN\n    \n\nTo access additional pre-existing custom fields, a subscription is necessary. These fields encompass a wider range of attributes and they are the following:\n\n- Allergies\n- Behance\n- Driver License\n- Facebook\n- Family\n- GitHub\n- Instagram\n- Languages\n- Passport\n- Personal Phone\n- Pinterest\n- Secondary Address\n- Shirt-Size\n- Skype\n- T-Shirt Size\n- Twitter\n- Visa\n    \n\n_**Note:**_ _The type or visibility of these pre-existing custom fields cannot be modified, as they are predefined._\n\n**Employee 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.\n\n**Asset 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.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":true,"owner":"32971767","collectionId":"39f4121a-d6e2-48c3-a941-0c031292b69c","publishedId":"2sA35HX1mC","public":true,"publicUrl":"https://apidocs.talenthr.io","privateUrl":"https://go.postman.co/documentation/32971767-39f4121a-d6e2-48c3-a941-0c031292b69c","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":"TalentHR API documentation"},{"name":"title","value":"TalentHR API documentation"}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/d4545601-fba8-48e7-a8a8-23d4ba56957d/ZnVsbC1zcXVhcmUucG5n","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":"https://content.pstmn.io/57233ad8-15d0-46d4-a5ff-f48d146a430b/ZnVsbC1zcXVhcmUucG5n","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.1","publishDate":"2024-04-01T12:38:43.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"TalentHR API documentation","description":"TalentHR API documentation"},"logos":{"logoLight":"https://content.pstmn.io/57233ad8-15d0-46d4-a5ff-f48d146a430b/ZnVsbC1zcXVhcmUucG5n","logoDark":"https://content.pstmn.io/d4545601-fba8-48e7-a8a8-23d4ba56957d/ZnVsbC1zcXVhcmUucG5n"}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/149851744fb15596cd24fd5292dca991b18d53d09f4e7fc1540b8d3b870b8205","favicon":"https://res.cloudinary.com/postman/image/upload/v1709310827/team/i9vuzolcntnnycosgcep.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://apidocs.talenthr.io/view/metadata/2sA35HX1mC"}