How do I install the Zohopeople skill?

Run npx skillmds@latest add kernel8901/zohopeople in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Zohopeople skill do?

Zoho People API integration with managed OAuth. Manage employees, departments, designations, attendance, and leave. Use this skill when users want to read, create, update, or query HR data like employees, departments, designations, and forms in Zoho People. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). Requires network access and valid Maton API key. It is listed under Integrations & APIs on SkillMD.

Is Zohopeople safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Zohopeople?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Zohopeople free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Zohopeople?

kernel8901 (@kernel8901) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Zohopeople by kernel8901 — Agent Skill

Name: Zohopeople
Author: kernel8901

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

# 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:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

Sign in or create an account at maton.ai
Go to maton.ai/settings
Copy your API key

Connection Management

Manage your Zoho People OAuth connections at https://ctrl.maton.ai.

List Connections

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

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

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:

{
  "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

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:

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.

GET /zoho-people/people/api/forms

Example:

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:

{
  "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)

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:

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:

{
  "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)

GET /zoho-people/api/forms/{viewName}/records?rec_limit={limit}

Example:

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

GET /zoho-people/people/api/forms/employee/getRecords?SearchColumn=EMPLOYEEID&SearchValue={employeeId}

Example:

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

GET /zoho-people/people/api/forms/employee/getRecords?SearchColumn=EMPLOYEEMAILALIAS&SearchValue={email}

Department Operations

List Departments

GET /zoho-people/people/api/forms/department/getRecords?sIndex={startIndex}&limit={limit}

Example:

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:

{
  "response": {
    "result": [
      {
        "943596000000294315": [
          {
            "Department": "IT",
            "Department_Lead": "",
            "Parent_Department": "",
            "Zoho_ID": 943596000000294315
          }
        ]
      }
    ],
    "message": "Data fetched successfully",
    "status": 0
  }
}

Designation Operations

List Designations

GET /zoho-people/people/api/forms/designation/getRecords?sIndex={startIndex}&limit={limit}

Example:

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:

{
  "response": {
    "result": [
      {
        "943596000000294399": [
          {
            "Designation": "Team Member",
            "EEO_Category": "Professionals",
            "Zoho_ID": 943596000000294399
          }
        ]
      }
    ],
    "message": "Data fetched successfully",
    "status": 0
  }
}

Insert Record

Add a new record to any form.

POST /zoho-people/people/api/forms/json/{formLinkName}/insertRecord
Content-Type: application/x-www-form-urlencoded

inputData={field1:'value1',field2:'value2'}

Example - Create Department:

python <<'EOF'
import urllib.request, os, json
from urllib.parse import urlencode

inputData = json.dumps({"Department": "Engineering"})
data = urlencode({"inputData": inputData}).encode()

req = urllib.request.Request('https://gateway.maton.ai/zoho-people/people/api/forms/json/department/insertRecord', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/x-www-form-urlencoded')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "response": {
    "result": {
      "pkId": "943596000000300001",
      "message": "Successfully Added"
    },
    "message": "Data added successfully",
    "status": 0
  }
}

Update Record

Modify an existing record.

POST /zoho-people/people/api/forms/json/{formLinkName}/updateRecord
Content-Type: application/x-www-form-urlencoded

inputData={field1:'newValue'}&recordId={recordId}

Example - Update Employee:

python <<'EOF'
import urllib.request, os, json
from urllib.parse import urlencode

inputData = json.dumps({"Department": "Engineering"})
data = urlencode({
    "inputData": inputData,
    "recordId": "943596000000294355"
}).encode()

req = urllib.request.Request('https://gateway.maton.ai/zoho-people/people/api/forms/json/employee/updateRecord', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/x-www-form-urlencoded')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Leave Operations

List Leave Records

GET /zoho-people/people/api/forms/leave/getRecords?sIndex={startIndex}&limit={limit}

Add Leave

POST /zoho-people/people/api/forms/json/leave/insertRecord
Content-Type: application/x-www-form-urlencoded

inputData={Employee_ID:'EMP001',Leavetype:'123456',From:'01-Feb-2026',To:'02-Feb-2026'}

Attendance Operations

Note: Attendance endpoints require additional OAuth scopes.

Get Attendance Entries

GET /zoho-people/people/api/attendance/getAttendanceEntries?date={date}&dateFormat={format}

Parameters:

Parameter	Type	Description
`date`	string	Date in organization format
`dateFormat`	string	Date format (e.g., `dd-MMM-yyyy`)
`empId`	string	Employee ID (optional)
`emailId`	string	Employee email (optional)

Check-In/Check-Out

POST /zoho-people/people/api/attendance
Content-Type: application/x-www-form-urlencoded

dateFormat=dd/MM/yyyy HH:mm:ss&checkIn={datetime}&checkOut={datetime}&empId={empId}

Common Form Link Names

Form	formLinkName	Description
Employee	`employee`	Employee records
Department	`department`	Departments
Designation	`designation`	Job titles
Leave	`leave`	Leave requests
Clients	`P_ClientDetails`	Client information

Pagination

Zoho People uses index-based pagination:

GET /zoho-people/people/api/forms/{formLinkName}/getRecords?sIndex=1&limit=200

sIndex: Starting index (1-based)
limit: Number of records per request (max 200)

For subsequent pages:

Page 1: sIndex=1&limit=200
Page 2: sIndex=201&limit=200
Page 3: sIndex=401&limit=200

Code Examples

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/zoho-people/people/api/forms/employee/getRecords?sIndex=1&limit=10',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/zoho-people/people/api/forms/employee/getRecords',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'sIndex': 1, 'limit': 10}
)
data = response.json()

Notes

Record IDs are numeric strings (e.g., 943596000000294355)
The Zoho_ID field in responses contains the record ID
Maximum 200 records per GET request
Insert/Update operations use form-urlencoded data with inputData JSON
Date format varies by field and organization settings
Some endpoints (attendance, leave) require additional OAuth scopes. If you receive an INVALID_OAUTHSCOPE error, contact Maton support at support@maton.ai with the specific operations/APIs you need and your use-case
Response structure wraps data in response.result[] array
IMPORTANT: When using curl commands, use curl -g when URLs contain special characters
IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

Error Handling

Status	Meaning
400	Missing Zoho People connection or invalid request
401	Invalid or missing Maton API key, or invalid OAuth scope
429	Rate limited
4xx/5xx	Passthrough error from Zoho People API

Common Error Codes

Code	Description
7011	Invalid form name
7012	Invalid view name
7021	Maximum record limit exceeded (200)
7024	No records found
7042	Invalid search value
7218	Invalid OAuth scope

Troubleshooting: Invalid API Key

When you receive a "Invalid API key" error, ALWAYS follow these steps before concluding there is an issue:

Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

Verify the API key is valid by listing connections:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Zohopeople

File contents

Zoho People

Quick Start

Base URL

Authentication

Getting Your API Key

Connection Management

List Connections

Create Connection

Get Connection

Delete Connection

Specifying Connection

API Reference

Forms Operations

List All Forms

Employee Operations

List Employees (Bulk Records)

List Employees (View-based)

Search Employee by ID

Search Employee by Email

Department Operations

List Departments

Designation Operations

List Designations

Insert Record

Update Record

Leave Operations

List Leave Records

Add Leave

Attendance Operations

Get Attendance Entries

Check-In/Check-Out

Common Form Link Names

Pagination

Code Examples

JavaScript

Python

Notes

Error Handling

Common Error Codes

Troubleshooting: Invalid API Key

Resources

Related skills

Frequently asked questions

How do I install the Zohopeople skill?

What does the Zohopeople skill do?

Is Zohopeople safe to use?

Which AI agents work with Zohopeople?

Is Zohopeople free to use?

Who published Zohopeople?