PLETOX / DEVELOPERS

REST API documentation.

Build secure, company-scoped integrations with explicit permissions, strict validation, and auditable requests.

Base URL https://{tenant-domain}/api/integrations/v1

Replace {tenant-domain} with the domain used to access your Pletox workspace.

API version 1 · JSON · Bearer authentication

Documentation section

GETTING STARTED

Authenticate every request.

Generate an integration key in your Pletox console, store it in the connector’s secret manager, and send it as a bearer token. The key determines tenant, company, location, permissions, and rate limit.

Example requestGET /context

curl --request GET "https://{tenant-domain}/api/integrations/v1/context" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "X-Device-Name: Reporting Connector" \
  --header "Accept: application/json"

Keep the key secret. Never place a real key in source code, documentation, screenshots, chat, or logs. Rotate it immediately if exposed.

Available permissions

Grant only the abilities required by the connector.

context:readWorkspace context

employees:readEmployee directory

employees:writeCreate and update employees

attendance:readAttendance information

attendance:writeAttendance and timesheet actions

leaves:readLeave information

reports:readHeadcount, joining, and exit reports

payroll:readAggregate payroll summaries

AI CONNECTORS

Give any AI the complete API context.

Copy this message into Codex, Claude, ChatGPT, or another AI assistant. The assistant can study this documentation and then guide your integration.

Copy-paste message

Open and study the complete Pletox REST API documentation at:
https://pletox.com/api/doc

Use this documentation as the only source of truth for the Base URL, authentication, permissions, tenant/company/location scope, endpoints, HTTP methods, request fields, pagination, validation, responses, and errors.

This workspace's company-specific Pletox API Base URL is:
https://{tenant-domain}/api/integrations/v1

Never hardcode, guess, or reuse another company's Base URL. If the URL above contains {tenant-domain}, tell me how to replace it with the domain of the Pletox workspace I am connecting.

Read the real Bearer token securely from the PLETOX_API_TOKEN environment variable or the platform's secret manager. Never ask me to paste it into chat. Never display, log, commit, or include it in source code. Show tokens in examples, previews, and output only as [REDACTED].

After studying the documentation, perform a connection-readiness check before proposing or sending an API request. If the Base URL still contains {tenant-domain}, ask me only for the domain used to access the Pletox workspace, then construct the Base URL from the documented pattern. Do not guess the domain or call the API until the placeholder is resolved. Check whether PLETOX_API_TOKEN is configured in the execution environment or platform secret manager without reading, displaying, or logging its value. If you cannot verify that it is configured, tell me where to store it securely and ask me to confirm only that configuration is complete. Never ask me to paste, type, or reveal the token value in chat.

Understand my request in simple language, then select only a documented GET, POST, PATCH, PUT, or DELETE endpoint. Do not invent endpoints, methods, parameters, fields, or values. Validate the required permission, tenant/company/location scope, IDs, request fields, allowed values, pagination, and documented validation rules before making a request.

Before any create, update, or delete request, show me a safe preview containing the method, company-specific URL, required permission and scope, redacted headers, and request body. Wait for my explicit confirmation before sending it. Read-only requests do not need confirmation.

If you can access my code or execution environment, implement the requested integration and verify the result without exposing secrets. Otherwise, provide complete working code and simple setup and run instructions that read PLETOX_API_TOKEN securely.

After reviewing the documentation, briefly summarize the available Pletox API capabilities and ask exactly:

“What would you like to do with Pletox?”

API RESOURCE

Workspace context

Resolve the tenant, companies, locations, and access scope available to the API key.

GET /context

Workspace, company, location, and API key context.

Required permissioncontext:read

API RESOURCE

Employees

Search, retrieve, create, and update employee records inside the key’s assigned scope.

GET /employees

Paginated employee directory with supported filters.

Required permissionemployees:read

POST /employees

Create an employee in the explicitly supplied company and location scope. company_id is required; employment_type defaults to employee.

Required permissionemployees:write

Employee write payload

Send the required employee fields to POST /employees. Unsupported and privileged fields are rejected.

Example JSON bodyPOST /employees

{
  "employee_id": "EMP-001",
  "name": "Example Employee",
  "email": "employee@example.com",
  "phone": "+919876543210",
  "gender": "male",
  "date_of_joining": "2026-01-15",
  "employment_type": "employee",
  "employee_type": "contractor",
  "contractor_start_date": "2026-01-15",
  "contractor_end_date": "2026-12-31",
  "company_id": 1,
  "location_id": 10,
  "designation_id": 25,
  "department_ids": [4, 7]
}

GET /employees/options/departments?company_id={company_id}

Paginated departments available within the API key company and location scope.

Required permissionemployees:write

GET /employees/options/designations

Paginated designation IDs and names available for employee writes.

Required permissionemployees:write

GET /employees/options/types

Allowed employee type values and whether contractor dates are required.

Required permissionemployees:write

GET /employees/{employee}

Details for one employee within the key scope.

Required permissionemployees:read

PATCH /employees/{employee}

Update supported fields for an employee within the API key scope.

Required permissionemployees:write

Employee update payload

Send only the fields that should change to PATCH /employees/{employee}. Unsupported and privileged fields are rejected.

Example JSON bodyPATCH /employees/{employee}

{
  "employee_id": "EMP-001",
  "name": "Updated Employee Name",
  "email": "updated.employee@example.com",
  "phone": "+919876543210",
  "gender": "male",
  "date_of_joining": "2026-01-15",
  "employment_type": "employee",
  "employee_type": "contractor",
  "contractor_start_date": "2026-01-15",
  "contractor_end_date": "2026-12-31",
  "company_id": 1,
  "location_id": 10,
  "designation_id": 25,
  "department_ids": [4, 7]
}

API RESOURCE

Attendance

Read attendance summaries and records, update daily attendance states, and create, update, or delete scoped timesheet entries.

GET /attendance/summary?date=YYYY-MM-DD

Daily presence, absence, late arrival, and worked-hour totals.

Required permissionattendance:read

GET /attendance/monthly-summary?month=YYYY-MM

Paginated employee attendance days, late-arrival records, and worked hours for a month.

Required permissionattendance:read

GET /attendance?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD

Paginated attendance records for a date range.

Required permissionattendance:read

POST /attendance/actions

Perform attendance status actions or create, update, and delete scoped timesheet entries. Supported actions: mark_present, mark_absent, mark_half_day, mark_week_off, mark_on_tour, remove_late_mark, create_timesheet, update_timesheet, and delete_timesheet.

Required permissionattendance:write

Attendance action payloads

Every request requires action and employee_id. The employee and any supplied timesheet must be inside the API key’s company and location scope. Attendance locks and finalized payroll periods are enforced.

Allowed actions

mark_present, mark_absent, mark_half_day, mark_week_off, mark_on_tour, remove_late_mark, create_timesheet, update_timesheet, and delete_timesheet.

Parameter	Required for	Description
`action`	All actions	One of the nine documented action values.
`employee_id`	All actions	Employee database ID within the API key scope.
`date`	Status actions	`YYYY-MM-DD` attendance date.
`enabled`	Half-day, week-off	Boolean desired state. Explicit state makes retries safe.
`timesheet_id`	Update, delete	Timesheet ID belonging to the supplied employee.
`start_time`	Create, update	Valid date-time, interpreted in the employee company timezone when no offset is supplied.
`end_time`	Optional create, update	Nullable date-time later than `start_time`.
`remark`	Optional create, update	Nullable text, maximum 1,000 characters.

Status action example

Use enabled only with mark_half_day and mark_week_off. Other status actions require only the action, employee, and date.

Example JSON bodyMark half-day

{
  "action": "mark_half_day",
  "employee_id": 123,
  "date": "2026-10-29",
  "enabled": true
}

Timesheet CRUD examples

Create returns HTTP 201. Update and delete return HTTP 200.

Example JSON bodyCreate timesheet

{
  "action": "create_timesheet",
  "employee_id": 123,
  "start_time": "2026-10-29T09:00:00+05:30",
  "end_time": "2026-10-29T17:30:00+05:30",
  "remark": "Client-site attendance"
}

Example JSON bodyUpdate timesheet

{
  "action": "update_timesheet",
  "employee_id": 123,
  "timesheet_id": 456,
  "start_time": "2026-10-29T08:45:00+05:30",
  "end_time": "2026-10-29T17:30:00+05:30",
  "remark": "Corrected clock-in"
}

Example JSON bodyDelete timesheet

{
  "action": "delete_timesheet",
  "employee_id": 123,
  "timesheet_id": 456
}

Response behavior. Repeating an explicit half-day or week-off state is safe. Validation failures return 422; inaccessible employees or timesheets return 404; missing ability or scope conflicts return 403.

API RESOURCE

Leave

Read leave totals, employee balances, and paginated leave requests.

GET /leaves/overview

Pending, approved, rejected, and total leave counts.

Required permissionleaves:read

GET /leaves/balances

Employee leave balances by leave type.

Required permissionleaves:read

GET /leaves

Paginated employee leave records.

Required permissionleaves:read

API RESOURCE

Reports

Retrieve headcount and employee joining or exit movement summaries.

GET /reports/headcount

Active, exited, company, and location headcount.

Required permissionreports:read

GET /reports/joining-exit?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD

Employee joining and exit movements for a date range.

Required permissionreports:read

API RESOURCE

Payroll

Retrieve privacy-protected aggregate payroll summaries for an authorized month.

GET /payroll/summary?month=YYYY-MM

Privacy-protected aggregate payroll summary.

Required permissionpayroll:read

RESPONSES

Errors and status codes.

List endpoints return pagination details. Preserve validation details returned with unsuccessful requests and back off when a rate limit is reached.

200

Success

The request completed successfully.

201

Created

The employee or timesheet was created successfully.

401

Unauthenticated

The key is missing, invalid, expired, or revoked.

403

Forbidden

The key lacks permission or conflicts with its assigned scope.

404

Not found

The requested employee or timesheet does not exist inside the key scope.

422

Validation error

A filter, field, or request value is invalid.

429

Rate limited

The configured requests-per-minute limit was exceeded.

Learn

Company

Free Tools

Authenticate every request.

Available permissions

Give any AI the complete API context.

Workspace context

Employees

Attendance

Allowed actions

Status action example

Timesheet CRUD examples

Leave

Reports

Payroll

Errors and status codes.

Success

Created

Unauthenticated

Forbidden

Not found

Validation error

Rate limited

Your privacy choices