Skip to main content
This page is written for the agent. If you are a human setting up a connector, start at Connect a client instead.

​
Endpoint and auth

JSON-RPC. Standard MCP tools/list and tools/call.

​
Ground yourself first

Call ontime_whoami before anything else. It is not optional politeness — nearly every mistake an agent makes on this API comes from not knowing who it is.
It tells you: It also tells you the organization and today’s date in the organization’s timezone, which you need for date arithmetic.

​
Discovery

1

List tools

tools/list returns exactly what your credential can call. There is no hidden surface — listing and calling share the same predicate, so an invisible tool is an uncallable one. Do not guess at tool names you cannot see.
2

Use bare `search` to find things

A generic search across the organization. Returns records with identifiers you can then act on.
3

Use bare `fetch` to read one

Retrieves a single record by the identifier search returned.
The search and fetch pair exists for hosts that expect that shape (ChatGPT’s deep research, among others). If you have the specific tools available — ontime_employee_search, ontime_leave_get — prefer them; they return richer, better-typed results.

​
Self-service versus on-behalf

Most domains are two separate tools, not one tool with an optional employeeId.This is the single most common source of agent errors on this API. ontime_leave_request files leave for you. ontime_leave_request_for files it for somebody else and needs leave:approve.Picking the wrong one does not silently do the right thing — it either fails, or files correctly against the wrong person.
Decide which you are doing before choosing the tool.

​
Conventions

YYYY-MM-DD for a date, YYYY-MM for a month. Always. Never a locale format, never a natural-language date.Use the current date from ontime_whoami — the organization’s timezone is what matters, not yours.
Employees are identified by UUID, not by employee code or name. Resolve a name to an ID with ontime_employee_search first.Never construct or guess an ID.
List tools return a page. Check the total against what you have before concluding a queue is empty.
A failing mutation returns the domain’s own error verbatim — "bad_stage" (HTTP 409): …. Read it and change your input. Retrying the same call produces the same failure.

​
Confirm-gated writes

Four tools require an explicit human “yes” in the conversation before you call them. They are consequential and hard to reverse:
  • ontime_payroll_disburse — creates payslips and closes the cycle. Not reversible.
  • ontime_compliance_file — records a statutory return as filed.
  • ontime_form16_generate — generates tax certificates for a whole financial year.
  • ontime_holiday_delete — removes a holiday, changing how days reconcile.
State what you are about to do, wait for confirmation, then act. Do not infer consent from a general instruction like “run payroll”.

​
Before any write

1

Read the current state

Use the matching read tool. Payroll in particular is a state machine — ontime_payroll_overview tells you which stage the cycle is at, and calling a stage out of order fails.
2

Confirm the subject

If you are acting on somebody, confirm you have the right person. ontime_employee_get on the ID you resolved.
3

Expect scope refusals

A 403 about approval scope means you are not the subject’s direct manager and lack hr:approve. That is not retryable and not a transitive check — being the manager’s manager does not help.

​
Things that will not work

  • Approving your own request. The same-actor rule applies to you as it does to a human.
  • Writing to a frozen payroll month. Punches and attendance-affecting approvals are refused.
  • Reaching another organization. Your credential is bound to one.
  • Guessing a tool that is not in tools/list. It is not there because you cannot call it.

​
This documentation is machine-readable

Every page on this site has a plain-Markdown twin at the same URL with .md appended, and /llms.txt indexes the site. Fetch those rather than parsing HTML.