canonical: https://jentic.com/apis/parim.co/parim-clocking

# PARiM Clocking API

PARiM Clocking API enables workforce scheduling and time-tracking integration by allowing external applications to submit clock events (clock in, clock out, breaks, check-ins) and retrieve user information for staff members. Authentication uses a signature-based custom scheme with timestamp, nonce, public key, and HMAC signature headers. The API requires published shifts to exist for clock events to succeed.

## For AI agents

Record employee clock events and retrieve user lists for workforce scheduling and attendance tracking in PARiM.

## Scope

Does not create shifts, manage schedules, or handle payroll calculations - use only for recording attendance events and retrieving user lists. Shift existence is a prerequisite.

## Capabilities

- Submit clock events including clock in, clock out, break start/end, check-in, and checkpoint check-in
- Record geolocation (latitude, longitude, accuracy) alongside clock events for location verification
- Associate clock events with published shifts by user and timestamp
- Retrieve a collection of users (staff, candidates, subcontractors) with their status and identifiers
- Support custom authentication with HMAC-based signature verification

## Use cases

### Mobile Time Clock Integration

Build a mobile app or kiosk that lets staff clock in and out of shifts without direct PARiM access. POST /clock_events accepts timestamp, location, and event type; PARiM validates against published shifts and records attendance. The signature-based auth ensures only authorized devices can submit clock events on behalf of users.

Example prompt: POST /clock_events with type, user_id, exact_timestamp, latitude, and longitude. Ensure the domain subdomain matches the PARiM instance and the signature headers are correctly computed.

### Workforce Synchronization

Sync staff rosters between PARiM and an external HR or payroll system by periodically fetching the user collection. GET /users returns all active, approved, and incomplete users with their external IDs and PARiM UUIDs, allowing bidirectional lookups. Use external_id to map PARiM users to records in your system.

Example prompt: GET /users and iterate the returned array, using external_id and parim_id to reconcile with your HR database.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/clock_events` | Submit a new clock event (clock in, out, break, or check-in) |
| GET | `/users` | Retrieve the collection of users (staff, candidates, subcontractors) |

## Key resources

- **ClockEvent** — Time-stamped attendance events (clock in/out, breaks, check-ins) tied to users and shifts
- **User** — Staff members, candidates, and subcontractors with status and external identifiers

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 64 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 70 / 100
  - Developer Experience & Jentic Compatibility: 69 / 100
  - AI-Readiness & Agent Experience: 57 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 50 / 100
- **View full report:** https://jentic.com/apis/parim.co/parim-clocking/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the PARiM Clocking API by hand means resolving your per-tenant domain host and computing the x-auth-parim-signature over a key, timestamp, and nonce for every request. Through Jentic you install once, import PARiM from the API Directory, store the key and secret once, and your agent calls it.
- **Permission scoping:** PARiM carries the employee and shift references in the request body, so scoping is by operation: limit the agent to the operations it needs, such as recording clock events and listing users. You choose the operations it may call, so it stays limited to attendance recording and user lookup.
- **Credential handling:** Your PARiM key and signing secret are stored once, encrypted, by your own Jentic One instance and used to compute the signature header at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'clock in an employee' or 'get the PARiM user list', and Jentic returns the matching PARiM operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## FAQ

### What authentication does the PARiM Clocking API use?

The API uses a custom signature-based authentication with five required headers: x-auth-parim-key (public API key), x-auth-parim-timestamp (current unix timestamp), x-auth-parim-nonce (unique value), x-auth-parim-signature (HMAC signature), and X-PARiM-Domain (subdomain). Jentic can store the key and secret and construct the signature headers at execution time.

### Can I submit clock events for any user?

No. Clock events require a published shift to exist for the user at the specified time. If no published shift is found, the API returns HTTP 428. This ensures clock events are tied to actual work schedules.

### Does the API support geolocation for clock events?

Yes. Each clock event can include latitude, longitude, and accuracy (in meters). These fields are optional but recommended for location verification of mobile clocking.

### Can I limit what my agent is allowed to do with the PARiM Clocking API?

Yes. Because you run Jentic One yourself, your own rules decide which PARiM operations the agent may call, and it only ever reaches the two operations this API exposes: recording clock events (POST /clock_events) and listing users (GET /users). You can allow just the user lookup for read-only synchronization, or grant clock-event submission as well when the agent needs to record attendance. The stored key and signing secret are held by your own instance and applied at execution time, so the agent never sees them and stays limited to the operations you permit.