canonical: https://jentic.com/apis/officient.io/officient

# Officient API

Officient API is the integration surface for Officient's HRIS, used to manage personnel records, contracts, payroll inputs, time off, expenses, assets, fleet, and performance reviews. Ninety-eight endpoints cover people, contracts, calendar requests, expenses, vehicles, documents, departments, and webhooks. Use it to sync employee data into payroll or BI systems, automate onboarding and offboarding, and trigger workflows from HR events.

## For AI agents

Read and update Officient employee, contract, time-off, expense, and asset records, and subscribe to HR events through webhooks.

## Scope

Does not run payroll calculations, recruit candidates, or handle benefits enrolment - use for Officient HRIS records, time off, and expense management only.

## Capabilities

- List employees and read individual personnel profiles with contracts and wages
- Submit and approve calendar requests for time off and absences
- Manage employee assets, fleet vehicles, and assigned documents
- Record and categorise employee expenses for reimbursement
- Subscribe to HR events through webhooks for downstream automation
- Read department, team, and cost-unit structures for org-chart sync
- Generate self-service invitation links to onboard new hires

## Use cases

### Payroll-input synchronisation

Pull current wage, contract, and expense data from Officient into a payroll engine each cycle. The API exposes per-person wage and expense endpoints, plus contract listings, so payroll operators can produce a complete monthly input file without re-keying. This compresses the prep step from a half-day spreadsheet exercise to an automated job.

Example prompt: List all active employees, fetch current wage for each, sum approved expenses for the month, and produce a payroll-input CSV

### Automated onboarding

When a new hire is created in an ATS, push the record into Officient and generate a self-service invitation link so the employee fills in their personal details directly. Combined with department and team endpoints, this can also place the new hire on the org chart and assign starting assets.

Example prompt: Create a person record in Officient, generate a self-service invite link, and assign the new hire to a department and team

### Time-off and absence reporting

Submit, list, and report on calendar requests for sick leave, vacation, and other absences. Managers can approve requests through the API, and downstream BI dashboards can pull the calendar request history to track absence patterns by team. The webhook channel lets messaging tools post a notification when a request lands.

Example prompt: List all calendar requests in pending state, approve those from a specific manager's direct reports, and post a Slack notification per approval

### Asset and fleet tracking

Track laptops, phones, and company vehicles assigned to each employee through the assets and fleet endpoints. When an employee leaves, list their assets and trigger a return workflow; when a new hire starts, assign the standard kit. The fleet endpoints expose vehicle detail for company cars and fuel cards.

Example prompt: Retrieve all assets assigned to a leaving employee and create a return ticket for each in the IT helpdesk system

### AI agent HR assistant via Jentic

An HR-facing AI agent uses Jentic to answer questions like 'who is on leave next week?' or 'what is the wage history for employee 42?' The agent searches Jentic for the right Officient operation, loads the schema, and executes through OAuth credentials managed in your Jentic One instance.

Example prompt: Search Jentic for 'list calendar requests', load the schema, and execute it for the next 7 days filtered to a specific department

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/1.0/people/list` | List employees in the company |
| POST | `/1.0/token` | Exchange OAuth credentials for an access token |
| GET | `/1.0/wages/{person_id}/current` | Get current wage for an employee |
| POST | `/1.0/people/selfservice/invite_link` | Generate a self-service invitation link for a new hire |
| GET | `/1.0/assets/list` | List company-issued assets |
| GET | `/1.0/fleet/{vehicle_id}/detail` | Get fleet vehicle detail |
| GET | `/1.0/wages/{person_id}/history` | Get wage history for an employee |

## Key resources

- **Person** — Employee profiles, wages, contracts, and self-service invitations
- **Contract** — Employment contracts with start and end dates and terms
- **CalendarRequest** — Time-off, sick leave, and absence requests with approval workflow
- **Expense** — Employee expense records with categories and approval state
- **Asset** — Company-issued equipment assigned to employees
- **Vehicle** — Fleet vehicles and assignment to drivers
- **Department** — Organisational structure with departments, teams, and functions
- **Webhook** — Event subscriptions for HR lifecycle events

## Why Jentic

- **Setup:** Wiring the Officient API by hand means running its OAuth flow, refreshing tokens, and navigating 98 endpoints across people, wages, assets, fleet, and calendar yourself. Through Jentic you install once, import Officient from the API Directory, store the client credentials once, and your agent calls it.
- **Permission scoping:** Officient puts the person id in the URL path (for example `/1.0/wages/{person_id}/current`), so a rule can pin your agent to one person's records, and across the wider surface you limit it to the operations it needs, such as listing people or reading time off. You choose the operations it may call, so a wage read is not included unless you add it.
- **Credential handling:** Your Officient OAuth client credentials are stored once, encrypted, by your own Jentic One instance, which mints and refreshes tokens and injects them at execution time. The client secret and refresh token never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list employees on leave next week', and Jentic returns the matching Officient calendar operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Personio API** — European HRIS with similar people, time-off, and payroll-input scope as an alternative to Officient
- **BambooHR API** — US-leaning HRIS alternative with employee records and time-off endpoints
- **Gusto API** — Payroll engine that ingests employee and wage data the Officient API exports

## FAQ

### What authentication does the Officient API use?

The API uses OAuth 2.0. Obtain an access token via the `/1.0/token` endpoint and pass it as a bearer credential on subsequent calls. Through Jentic, the OAuth client is stored encrypted in the vault and tokens are refreshed automatically, so the raw client secret never enters the agent's context.

### Can I list all employees with the Officient API?

Yes. GET `/1.0/people/list` returns the employee directory. Per-person endpoints under `/1.0/people/{id}` and `/1.0/wages/{person_id}/current` expose contract, wage, and contact details. Combine with `/1.0/contracts` to read employment-history records.

### What are the rate limits for the Officient API?

Officient applies per-token rate limits but does not publish exact thresholds in the spec. Excessive requests return 429 with a Retry-After hint. For bulk syncs, batch by department or team rather than iterating one person at a time, and respect the Retry-After value before resuming.

### How do I submit a time-off request through Jentic?

Search Jentic for 'submit calendar request', load the schema for the calendar-request POST operation, and execute with the person_id, start and end dates, and request type. Jentic handles the OAuth bearer and returns the created request ID.

### Does the Officient API support webhooks for HR events?

Yes. The Webhook resource lets you register endpoints for HR lifecycle events. Subscribed URLs receive a JSON payload when the event fires, which you can route into Slack notifications, payroll reconciliation, or audit logs.

### Can I generate a self-service invitation link for a new hire?

Yes. Use POST `/1.0/people/selfservice/invite_link` with the person_id to generate a one-time link the new hire follows to fill in personal data, upload a contract signature, and set up self-service access. This removes the manual step of HR transcribing onboarding forms.

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

Yes. Because you self-host Jentic One, your own rules decide which Officient operations and credentials the agent may use, so you can allow only the calls it needs, such as GET `/1.0/people/list` or reading time-off requests, and leave everything else out. Officient puts the person id in the URL path, for example `/1.0/wages/{person_id}/current`, so a rule can pin the agent to a single person's records. A sensitive call like a wage read is never included unless you explicitly add it, and the OAuth credentials stay under your control.