{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"c5dd8d61-f2e1-4920-9a3a-85d3905ff7e5","name":"ZenHR APIs Documentation","description":"## Introduction\n\nThe ZenHR API, short for Application Programming Interface, is built around REST. This API lets external applications integrate with ZenHR on various levels to achieve different integration objectives.\n\nThe ZenHR API responds in JSON format and follows standard HTTP response codes and authentication protocols. Each endpoint comes with a detailed description and sample responses.\n\nUsing the ZenHR API, you can connect ZenHR with your own software. This API allows you to build applications, automate interactions with ZenHR, or create other integrations. This documentation covers the REST resources available in ZenHR, including HTTP response codes and sample requests and responses.\n\nThis guide provides a detailed overview of the OAuth 2.0 authorization process, a crucial step in securing access to ZenHR’s APIs. Understanding and implementing this process is essential for developers aiming to establish a secure connection between their apps and ZenHR’s services. The guide also covers the key parameters and path variables needed in API requests, offering examples and formats for better understanding.\n\nImportant Note Our limitations: \n\\- on production , the limit is: 15 requests every 4 seconds. \n\\- on sandbox link, max is: 10 requests every 5 seconds.\n\n## Authorization\n\nBefore initiating the utilization of ZenHR APIs for your integration, it is imperative to be well-versed in the following authorization details:\n\n- **Type:** OAuth 2.0\n \n- **Add auth data to:** Request Headers\n \n- **Header Prefix:** Bearer\n \n- **Token Name:** Your Application Name\n \n- **Grant Type:** Authorization Code\n \n- **Callback URL:** [https://oauth.pstmn.io/v1/callback](https://oauth.pstmn.io/v1/callback)\n \n- **Auth URL:** {{protocol}}://{{baseURL}}/oauth/authorize?app={your application name}\n \n- **Access Token URL:** {{protocol}}://{{baseURL}}/oauth/token\n \n- **Client ID:** client-id\n \n- **Client Secret:** client-secret\n \n- **Scope:** Specifies the scopes accessible to the application\n \n\n**Example**\n\n- **Scope:** read.branch, read.employee, read.financial_info, read.professional_info, read.timeoff, read.financial_transaction, read.attendance_record\n \n\n## How To Create Your Application On ZenHR?\n\nA new page has been added to ZenHR that enables Global Super Admin users to create integration apps with the ability to grant permissions based on required authorities.\n\n#### Prerequisites\n\n- A ZenHR account with **global admin permissions** to create OAuth applications.\n \n\n## Part 1: Your Apps Page On ZenHR\n\n#### **1.Access the Application Creation Page:**\n\n- Append **/en/oauth/applications** to your ZenHR instance URL (e.g., [https://app.zenhr.com/en/oauth/applications](https://app.zenhr.com/en/oauth/applications)).\n \n\n\n\n#### 2\\. Configure the Application\n\n- Click on the button \"**New Application**\" to display the new application form.\n \n- **Redirect URL:** For testing with Postman, use [https://oauth.pstmn.io/v1/callback](https://oauth.pstmn.io/v1/callback). For production, use your application's callback URL.\n \n- **Company Level:** Select the appropriate company level for your application ( Preferred **Company** )\n \n- **Scope:** Select the scopes corresponding to the API endpoints you intend to access.\n \n\n\n\n\\> **Note:** For the data access level, select \"Company\" and make sure that you are the **Global Admin**\n\n#### **3.Save Application Credentials**\n\n- After submitting, note down the **UID** and **Secret** provided. These are essential for authentication.\n \n\n\n\n#### **4.Authorize the Application**\n\n- Click the \"Authorize\" button to finalize the setup. (Which is shown at the end of the above picture)\n \n\n\n\nBy clicking the \"Authorize\" button, you will be redirected to the redirect URL that you added during setup. Subsequently, the app credentials (UID & secret) will be prepared for immediate utilization.\n\n## Part 2: Obtain an Access Token Using Postman\n\n#### **1.Import the ZenHR API Collection:**\n\n- Click the \"**Run in Postman**\" button in this documentation to load the collection into Postman.\n \n\n\n\n#### **2.Configure Authorization:**\n\n1. In Postman, select the **ZenHR collection** and go to the \"Authorization\" tab.\n \n2. Set the **Callback URL** to [https://oauth.pstmn.io/v1/callback](https://oauth.pstmn.io/v1/callback).\n \n\n\n\n#### **3.Set Environment Variables:**\n\n- In the collection's variables, set:\n \n - **Protocol**: https\n \n - **Baseurl**: Your ZenHR instance URL (e.g., [app.zenhr.com](https://app.zenhr.com) or [sa.zenhr.com](https://sa.zenhr.com))\n \n\n\n\n#### **4.Enter Client Credentials:**\n\n- Input the **UID** and **Secret** from your ZenHR application into the corresponding fields.\n \n\n\n\n#### **5\\. Insert Right Scopes:**\n\n- Based ont the scopes you choosed on your application insert them in the below field:\n \n\n\n\n- Below you will find all the scopes which you can choose from:\n \n\n```\nread:attendance_record currencies:exchange_rate conversion_details:exchange_rate create:attendance_detail bulk_insert:attendance_detail qr_clocking:attendance_detail destroy:provision_history read:integration_map create:integration_map update:integration_map read:work_location read:branch create:branch update:branch destroy:branch read:termination_setup create:termination_setup update:termination_setup destroy:termination_setup read:termination create:termination destroy:termination read:employee create:employee update:employee accessed_employees_branches:employee read_company_employees:employee read:financial_info create:financial_info update:financial_info destroy:financial_info read:overtime_request create:overtime_request read:overtime create:overtime update:overtime destroy:overtime read:financial_transaction_request create:financial_transaction_request read:governmental_information read:loan create:loan update:loan destroy:loan read:loan_request create:loan_request read:country read:family create:family update:family destroy:family read:timeoff_transaction_request create:timeoff_transaction_request read:timeoff_transaction create:timeoff_transaction read:vacation_resumption_transaction create:vacation_resumption_transaction update:vacation_resumption_transaction read:financial_transaction create:financial_transaction update:financial_transaction destroy:financial_transaction grouped_financial_transaction_types_options:financial_transaction read:hr_letter read:professional_info create:professional_info update:professional_info destroy:professional_info read:timeoff grouped_timeoffs_options:timeoff read:employee_shift create:employee_shift update:employee_shift destroy:employee_shift read:work_shift create:work_shift update:work_shift destroy:work_shift read:overtime_type create:overtime_type update:overtime_type destroy:overtime_type read:overtime create:overtime update:overtime destroy:overtime read:loan_type create:loan_type update:loan_type destroy:loan_type read:loan create:loan update:loan destroy:loan read:miscellaneous_request read:bank_account create:bank_account read:bank read:bank_branch read:branch_bank_account read:miscellaneous_type create:miscellaneous_type update:miscellaneous_type destroy:miscellaneous_type read:missing_punch create:missing_punch update:missing_punch destroy:missing_punch read:recurring_transaction create:recurring_transaction update:recurring_transaction destroy:recurring_transaction read:request_event read:competencies create:competencies update:competencies destroy:competencies read:airticket_policy read:employee_airticket_balance read:airticket_transaction create:airticket_transaction update:airticket_transaction destroy:airticket_transaction read:document create:document update:document destroy:document read:document_type create:document_type update:document_type destroy:document_type read:asset_type create:asset_type update:asset_type destroy:asset_type read:asset create:asset update:asset destroy:asset read:self_onboarding read:attendance_transaction read:asset_assignment create:asset_assignment update:asset_assignment destroy:asset_assignment take_asset:asset_assignment read:approval_template create:approval_template update:approval_template destroy:approval_template read:employee_airtickets read:asset_activity read:organization_level read:task create:task update:task destroy:task task_across_branches:task read:boarding_template create:boarding_template update:boarding_template destroy:boarding_template read:boarding create:boarding update:boarding read:password_setup read:position read:encashment create:encashment destroy:encashment read:business_travel_setup update:business_travel_setup read:business_travel_policy create:business_travel_policy update:business_travel_policy destroy:business_travel_policy read:employee_airtickets read:business_trip create:business_trip update:business_trip destroy:business_trip read:stb read:time_sheet create:time_sheet update:time_sheet destroy:time_sheet read:approval read:salary_slip_template\n\n ```\n\n#### **6.Request an Access Token:**\n\n1. Click \"**Get New Access Token**\"\n \n2. You will be redirected to ZenHR's login page. Enter the **credentials** of the **Global Admin** on ZenHR and **authorize** the application.\n \n3. Upon successful authorization, Postman will receive and store the access token.\n \n\n> **Note:** Make sure to fill the **Branch ID** variable when wanting to use any of API's (In Zenhr go to **System Prefrences** > **Branch Setup** > **Edit the Preferred Branch** > you will find the **ID** in the **URL**. \n \n\n#### 1- Guide to Sharing ZenHR Access Token in Postman\n\n- To **Share** your access token on postman, activate the below:\n \n\n\n\n#### 2- Guide to Renewing ZenHR Access Token (Without Global Admin Credentials)\n\n**Step 1: Locate the Refresh Token and URL**\n\n- **Via Manage Tokens:** Navigate to the \"Manage Tokens\" section in ZenHR to retrieve the Refresh Token and Refresh Token URL.\n \n\n\n\n- **Via Console:** Access the Console from the bottom-left corner of the ZenHR page to locate these details.\n \n\n\n\n**Step 2: Obtain Authorization Header**\n\n- Log in to ZenHR using Global Admin Credentials to acquire a new Access Token.\n \n- Open the Console and click the \"Refresh Token\" button.\n \n\n\n\n- A request for \"POST [https://app.zenhr.com/oauth/token\"](https://app.zenhr.com/oauth/token) will appear in the Console.\n \n- Go to the \"Request Header\" section, copy the \"Authorization\" header and its value, and save it for the next step.\n \n\n\n\n##### **Step 3: Use the Refresh Token in Postman or Code-Level Integration**\n\n- In Postman (or your code-level environment), set up a new request using the Refresh Token URL: \"POST [https://app.zenhr.com/oauth/token\"](https://app.zenhr.com/oauth/token).\n \n- Add the \"Authorization\" header copied from Step 2 to the request headers.\n \n- In the request body, use the raw format and include:\n \n - **Grant Type:** Specify the grant type (e.g., refresh_token).\n \n - **Refresh Token:** Input the Refresh Token obtained from \"Manage Tokens\" or the Console’s \"Response Body.\"\n \n\n```\n{\n \"refresh_token\": \"a7b9c3d2e8f1g4h6j9k2m5n8p0q3r7s9\",\n \"grant_type\": \"refresh_token\"\n}\n\n ```\n\n> Upon successful execution, you will receive a new Access Token, which can be used for authentication. Repeat this process as needed to maintain continuous access.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"34627729","team":6321075,"collectionId":"c5dd8d61-f2e1-4920-9a3a-85d3905ff7e5","publishedId":"2sA3dxDWwR","public":true,"publicUrl":"https://api-docs.zenhr.com","privateUrl":"https://go.postman.co/documentation/34627729-c5dd8d61-f2e1-4920-9a3a-85d3905ff7e5","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"008483"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":"ZenHR API Docs"},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/0c779186-523f-4dca-93c6-adf2cc291acd/WmVuSFIgTG9nbyAoNCkucG5n","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"008483"}},{"name":"light","logo":"https://content.pstmn.io/b1a76fa7-5d05-4725-b15e-0c4e97606ed9/WmVuSFIgTG9nbyAoNSkucG5n","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"008483"}}]}},"version":"8.10.1","publishDate":"2024-07-24T14:37:41.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":"ZenHR API Docs"},"logos":{"logoLight":"https://content.pstmn.io/b1a76fa7-5d05-4725-b15e-0c4e97606ed9/WmVuSFIgTG9nbyAoNSkucG5n","logoDark":"https://content.pstmn.io/0c779186-523f-4dca-93c6-adf2cc291acd/WmVuSFIgTG9nbyAoNCkucG5n"}},"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/422d68aa5b5c029b2ac4883475507fd94a7f43d5b25519d157ad9c95afceb09b","favicon":"https://zenhr.com/favicon.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://api-docs.zenhr.com/view/metadata/2sA3dxDWwR"}