canonical: https://jentic.com/apis/deputy.com/deputy # Deputy API Jentic publishes the only available OpenAPI specification for Deputy API, keeping it validated and agent-ready. Deputy is a workforce management platform for shift-based businesses covering employee records, rostering, timesheets, leave, locations, and sales metrics. The API exposes 27 endpoints across employee lifecycle, roster publishing, time clock operations, leave management, sales metrics, and the authenticated user's own roster and timesheets. Authentication uses Bearer tokens and the base URL is parameterised by install and geographic region. ## For AI agents Manage Deputy employees, rosters, timesheets, leave, locations, departments, and sales metrics, plus retrieve the signed-in user's own schedule. ## Scope Does not handle payroll runs, tax filings, or applicant tracking - use for Deputy employee, roster, timesheet, leave, and sales metric operations only. ## Capabilities - Add, update, terminate, and re-activate employees through the supervise/employee endpoints - Publish rosters and list scheduled shifts via /v1/supervise/roster endpoints - Start and end timesheets to drive a clock-on and clock-off flow - Add and read employee leave records via /v1/supervise/leave - Push and pull sales metrics for forecasting through /v2/metrics endpoints - Retrieve the authenticated user's roster, timesheets, and leave through the /v1/my endpoints ## Use cases ### Employee Onboarding Automation Push new joiners from an HRIS into Deputy by calling POST /v1/supervise/employee, then send the welcome invite via POST /v1/supervise/employee/{employeeid}/invite. Termination flows mirror this with the terminate endpoint, keeping Deputy in sync with the HR source of truth without manual data entry. Example prompt: Call POST /v1/supervise/employee with the new hire details, then POST /v1/supervise/employee/{employeeid}/invite to send the app invite. ### Roster Publishing Workflow Build draft schedules in an external planner and publish them into Deputy via POST /v1/supervise/roster/publish, using GET /v1/supervise/roster to confirm the published shifts. This pattern is common for operations teams that prefer a custom forecasting tool but still want Deputy as the system of record for shifts. Example prompt: Call POST /v1/supervise/roster/publish with the prepared schedule payload, then GET /v1/supervise/roster to verify the publish. ### Time Clock for Custom Apps Power a branded clock-on and clock-off experience by calling POST /v1/supervise/timesheet/start and POST /v1/supervise/timesheet/end from a kiosk app. GET /v1/supervise/timesheet/{timesheetid}/details closes the loop for confirmation and audit, replacing the default Deputy app where the use case demands a custom UI. Example prompt: When the employee taps clock on, call POST /v1/supervise/timesheet/start with their employee id; on tap clock off, call POST /v1/supervise/timesheet/end. ### Sales-Driven Forecasting Feed sales metrics from the POS into Deputy via POST /v2/metrics, and pull historical data with GET /v2/metrics/raw to evaluate roster effectiveness. This closes the loop between revenue and labour planning for retail and hospitality operators. Example prompt: Each evening, push the day's sales totals via POST /v2/metrics keyed by location id. ### AI Agent Integration via Jentic An ops agent can use Jentic to handle one-off Deputy tasks like terminating an employee, publishing a roster, or pulling the signed-in user's schedule for a question. Jentic resolves the Bearer token and the install/geo base URL parameters, so the agent does not need to manage tenant-specific URL building. Example prompt: Use Jentic to search for 'publish a deputy roster', load POST /v1/supervise/roster/publish, and execute it with the prepared schedule. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /v1/supervise/employee | Add a new employee | | POST | /v1/supervise/employee/{employeeid}/invite | Invite an employee to Deputy | | POST | /v1/supervise/roster/publish | Publish a roster | | POST | /v1/supervise/timesheet/start | Start a timesheet (clock on) | | POST | /v1/supervise/timesheet/end | End a timesheet (clock off) | | POST | /v1/supervise/leave | Add leave for an employee | | POST | /v2/metrics | Add a sales metric | | GET | /v1/my/roster | Get my roster | ## Key resources - **Employees** — Add, update, terminate, re-activate, and invite employees - **Rosters** — List rosters and publish new schedules - **Timesheets** — Start, end, and inspect timesheets - **Leave** — Read and add employee leave - **Locations and Departments** — Manage locations and departments - **Sales Metrics** — Push and pull sales data for forecasting - **My** — The authenticated user's roster, timesheets, leave, and notifications ## Why Jentic - **Setup:** Wiring Deputy by hand means learning its bearer auth, resolving the install and geo parts of the per-tenant host (https://{install}.{geo}.deputy.com/api), and building the employee, roster, timesheet, leave, and metrics calls yourself. Through Jentic you install once, import the Deputy API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Deputy carries the employee, roster, and timesheet details in the request body, so you limit the agent to the operations it needs, such as reading its own roster or clocking a timesheet on, and roster publishing or employee creation is included only if you add those operations. - **Credential handling:** Your Deputy bearer token is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'publish a Deputy roster' or 'clock an employee on', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without reading Deputy's documentation. ## Related APIs - **7shifts API** — Restaurant-focused scheduling and labour platform with similar shift and timesheet endpoints. - **Rippling API** — Unified HR, payroll, and IT platform that overlaps with Deputy on employee records. - **Gusto API** — US payroll provider that consumes timesheets exported from Deputy. - **BambooHR API** — HRIS that owns employee records often synced into Deputy on hire. ## FAQ ### Why is there no official OpenAPI spec for Deputy API? Deputy does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Deputy API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Deputy API use? The Deputy API uses HTTP Bearer token authentication. Tokens are issued from your Deputy install and passed in the Authorization header. Through Jentic, tokens are stored encrypted in the vault and never exposed to the agent. ### Can I publish a roster with the Deputy API? Yes. POST /v1/supervise/roster/publish publishes a prepared schedule, and GET /v1/supervise/roster lists existing rosters so you can confirm what shifts are now live. ### How do I clock an employee on and off through the Deputy API? Call POST /v1/supervise/timesheet/start to clock the employee on and POST /v1/supervise/timesheet/end to clock them off. GET /v1/supervise/timesheet/{timesheetid}/details lets you fetch the resulting timesheet for review. ### What is the base URL for the Deputy API? Deputy uses a tenant-specific URL of the form https://{install}.{geo}.deputy.com/api, where install is your Deputy subdomain and geo is the regional cluster (for example au, na, or eu). Both placeholders must be substituted before calling any endpoint. ### How do I add a new employee through Jentic? Run `pip install jentic`, search for 'add a deputy employee', execute POST /v1/supervise/employee with the new hire payload, and follow up with POST /v1/supervise/employee/{employeeid}/invite. Jentic uses the stored Bearer token for both calls. ### Can I limit what my agent is allowed to do with the Deputy API? Yes. Because you run Jentic One yourself, you decide which Deputy operations the agent may call and which credential it uses, so you can grant only read-only actions like fetching its own roster (GET /v1/my/roster) or clocking a timesheet on and off (POST /v1/supervise/timesheet/start and /end). Higher-impact operations such as publishing a roster (POST /v1/supervise/roster/publish), creating or terminating employees (POST /v1/supervise/employee), or pushing sales metrics (POST /v2/metrics) are available to the agent only if you add them. The Deputy bearer token is held by your own instance and injected at execution time, so the agent never sees it.