canonical: https://jentic.com/apis/humanity.com/humanity # Humanity API Jentic publishes the only available OpenAPI specification for the Humanity API, keeping it validated and agent-ready. Humanity, formerly known as ShiftPlanning, is a workforce management platform for shift scheduling, time and attendance tracking, leave requests, and labour reporting. The API exposes the same scheduling, employee, and time-clock surfaces the Humanity web and mobile apps use, so payroll integrations, HRIS sync tools, and shift-aware AI agents can read and write rosters, time-off, and timesheets directly. Jentic is generating and maintaining the structured spec because Humanity does not publish one of its own. ## For AI agents Read and write Humanity workforce schedules, employee records, leave requests, and timesheets for shift-based teams. ## Scope Does not run payroll, calculate taxes, or process payments - use for Humanity shift scheduling, employee, leave, and timesheet operations only. ## Capabilities - Read and write shift schedules across employees and locations - List and update employee records including roles, wages, and contact details - Submit and approve leave and time-off requests on behalf of staff - Pull timesheet entries and clock-in events for payroll integration - List the locations, positions, and skills configured on the account - Create and modify scheduled shifts in bulk for a roster import ## Use cases ### Payroll export from Humanity timesheets Pull approved timesheet entries from Humanity at payroll cutoff and post them into the payroll provider so hours, breaks, and overtime flow into the pay run without re-keying. Mapping happens once between Humanity employee IDs and payroll IDs, after which weekly export becomes a scheduled API run. Example prompt: List approved timesheets for the previous pay period via the Humanity timesheets endpoint, then post each employee's hours to the payroll provider keyed by employee ID. ### Auto-cover for sick calls When an employee calls in sick, find available staff for the missed shift based on position, location, and existing schedule, and send them a shift offer. The schedule, employee, and availability endpoints together provide enough state to make the offer programmatically rather than relying on a manager to text round. Example prompt: Read the unfilled shift, list eligible employees by position and availability, then create a shift offer record for the top candidates. ### HRIS to Humanity employee sync Mirror the corporate HRIS roster into Humanity nightly so new hires appear in the schedule the moment they start, and leavers can no longer pick up shifts. The employees endpoint accepts the full record including position and wage so most HRIS fields map directly. Example prompt: Read joiners and leavers from the HRIS, create the joiners via Humanity's create-employee operation, and deactivate leavers by setting their status to inactive. ### Agent-driven scheduling through Jentic An AI assistant for shift managers reads inbound time-off requests and finds coverage by calling Humanity through Jentic. Jentic injects the OAuth credential at execution time so the agent operates against the right account without holding the raw token. Example prompt: Through Jentic, search 'list Humanity shifts for this week', load the schema for the shift listing operation, and execute it filtered to the manager's location. ## Key resources - **Employees** — Read, create, and update the workforce roster including positions and wages - **Schedules** — Read and write shift schedules across locations and weeks - **Time-off** — Submit, list, and approve leave and time-off requests - **Timesheets** — Pull clock-in entries and approved hours for payroll export ## Why Jentic - **Setup:** Wiring the Humanity API by hand means running its OAuth flow, targeting www.humanity.com/api/v2, and threading access tokens through scheduling and timesheet calls yourself. Through Jentic you install once, import the Humanity API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** You choose which Humanity operations the agent may call, so limit it to the operations it needs, such as listing shifts or reading timesheets. Operations you do not add, like submitting a time-off request or editing an employee record, stay out of reach. - **Credential handling:** Your Humanity OAuth access token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list Humanity shifts' or 'submit a Humanity time-off request', and Jentic returns the matching operation with its input schema, including filters like location and date range, so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Deputy** — Workforce management platform with similar shift scheduling, time clock, and award interpretation features - **7shifts** — Restaurant-focused shift scheduling and labour cost platform - **BambooHR** — HRIS that holds the source-of-truth employee roster mirrored into Humanity - **Gusto** — Payroll provider that consumes the timesheet hours exported from Humanity ## FAQ ### Why is there no official OpenAPI spec for Humanity API? Humanity does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Humanity 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 Humanity API use? Humanity uses OAuth 2.0 with a client ID and secret issued from the Humanity developer portal, exchanged for a Bearer access token. Through Jentic the token sits in your encrypted Jentic One instance and is injected at execution time so the agent never sees the raw credential. ### Can I export timesheets to a payroll provider? Yes. Read approved timesheet entries through Humanity's timesheets resource, map Humanity employee IDs to your payroll provider's employee IDs, and submit the hours via the payroll provider's API. The two together cover the full pay-period export. ### What are the rate limits for the Humanity API? Humanity does not publish a hard rate-limit table; in practice they apply per-account fair-use throttling. Batch reads where possible and keep nightly sync jobs to a few requests per second to stay well within tolerance. ### How do I list this week's shifts through Jentic? Search Jentic for 'list Humanity shifts', load the schema for the schedule listing operation, and execute it with location and date-range filters. Jentic returns the parsed shift rows ready for the agent to use. ### Can I submit time-off requests on behalf of employees? Yes. The time-off resource accepts a request payload with employee ID, start and end dates, and reason. Once submitted it appears in the manager's approval queue exactly as an employee-submitted request would. ### Can I limit what my agent is allowed to do with the Humanity API? Yes. Because Jentic One is self-hosted, you decide which Humanity operations the agent can reach, so you can limit it to what it needs, such as listing shifts or reading timesheets. Operations you do not add, like submitting a time-off request or editing an employee record, stay out of reach. The OAuth token is held by your own Jentic One instance and injected at execution time, so the agent calls only the operations you permitted without ever seeing the raw credential.