zohopeople

# Zoho People Access the Zoho People API with managed OAuth authentication. Manage employees, departments, designations, attendance, leave, and custom HR forms with full CRUD operations. ## Quick Start ```bash # List all employees python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-people/people/api/forms/employee/getRecords?sIndex=1&limit=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ## Base URL ``` https://gateway.maton.ai/zoho-people/{native-api-path} ``` Replace `{native-api-path}` with the actual Zoho People API endpoint path. The gateway proxies requests to `people.zoho.com` and automatically injects your OAuth token. ## Authentication All requests require the Maton API key in the Authorization header: ``` Authorization: Bearer $MATON_API_KEY ``` **Environment Variable:** Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ### Getting Your API Key 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key ## Connection Management Manage your Zoho People OAuth connections at `https://ctrl.maton.ai`. ### List Connections ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=zoho-people&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Create Connection ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'zoho-people'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Get Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "connection": { "connection_id": "7d11ea2e-c580-43fe-bc56-d9d4765b9bc6", "status": "ACTIVE", "creation_time": "2026-02-06T07:42:07.681370Z", "last_updated_time": "2026-02-06T07:46:12.648445Z", "url": "https://connect.maton.ai/?session_token=...", "app": "zoho-people", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Specifying Connection If you have multiple Zoho People connections, specify which one to use with the `Maton-Connection` header: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-people/people/api/forms') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '7d11ea2e-c580-43fe-bc56-d9d4765b9bc6') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If omitted, the gateway uses the default (oldest) active connection. ## API Reference ### Forms Operations #### List All Forms Get a list of all available forms in your Zoho People account. ```bash GET /zoho-people/people/api/forms ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-people/people/api/forms') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "response": { "result": [ { "componentId": 943596000000035679, "iscustom": false, "displayName": "Employee", "formLinkName": "employee", "PermissionDetails": { "Add": 3, "Edit": 3, "View": 3 }, "isVisible": true, "viewDetails": { "view_Id": 943596000000035705, "view_Name": "P_EmployeeView" } } ], "message": "Data fetched successfully", "status": 0 } } ``` ### Employee Operations #### List Employees (Bulk Records) ```bash GET /zoho-people/people/api/forms/employee/getRecords?sIndex={startIndex}&limit={limit} ``` **Query Parameters:** | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `sIndex` | integer | 1 | Starting index (1-based) | | `limit` | integer | 200 | Number of records (max 200) | | `SearchColumn` | string | - | `EMPLOYEEID` or `EMPLOYEEMAILALIAS` | | `SearchValue` | string | - | Value to search for | | `modifiedtime` | long | - | Timestamp in milliseconds for modified records | **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-people/people/api/forms/employee/getRecords?sIndex=1&limit=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "response": { "result": [ { "943596000000294355": [ { "FirstName": "Christopher", "LastName": "Brown", "EmailID": "christopherbrown@zylker.com", "EmployeeID": "S20", "Department": "Management", "Designation": "Administration", "Employeestatus": "Active", "Gender": "Male", "Date_of_birth": "02-Feb-1987", "Zoho_ID": 943596000000294355 } ] } ], "message": "Data fetched successfully", "status": 0 } } ``` #### List Employees (View-based) ```bash GET /zoho-people/api/forms/{viewName}/records?rec_limit={limit} ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-people/api/forms/P_EmployeeView/records?rec_limit=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` #### Search Employee by ID ```bash GET /zoho-people/people/api/forms/employee/getRecords?SearchColumn=EMPLOYEEID&SearchValue={employeeId} ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-people/people/api/forms/employee/getRecords?SearchColumn=EMPLOYEEID&SearchValue=S20') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` #### Search Employee by Email ```bash GET /zoho-people/people/api/forms/employee/getRecords?SearchColumn=EMPLOYEEMAILALIAS&SearchValue={email} ``` ### Department Operations #### List Departments ```bash GET /zoho-people/people/api/forms/department/getRecords?sIndex={startIndex}&limit={limit} ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-people/people/api/forms/department/getRecords?sIndex=1&limit=50') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "response": { "result": [ { "943596000000294315": [ { "Department": "IT", "Department_Lead": "", "Parent_Department": "", "Zoho_ID": 943596000000294315 } ] } ], "message": "Data fetched successfully", "status": 0 } } ``` ### Designation Operations #### List Designations ```bash GET /zoho-people/people/api/forms/designation/getRecords?sIndex={startIndex}&limit={limit} ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-people/people/api/forms/designation/getRecords?sIndex=1&limit=50') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "response": { "result": [ { "943596000000294399": [ {