canonical: https://jentic.com/apis/payrun.io/payrun-api # PayRun.IO Jentic publishes the only available OpenAPI specification for PayRun.IO (v23), keeping it validated and agent-ready. PayRun.IO version 23.24.2.136 is the latest release of the UK payroll processing API, providing 390 endpoints for employer management, employee records, pay runs, pension calculations, CIS transactions, RTI submissions, and permission management. This version adds user-permission mapping for role-based access control over payroll operations. ## For AI agents Run UK payroll calculations, manage employees, submit RTI to HMRC, and control user permissions through the latest version of the PayRun.IO payroll engine. ## Scope Does not handle recruitment, time tracking, or employee performance reviews - use for UK payroll calculation, HMRC reporting, and pension administration only. ## Capabilities - Execute pay runs with automatic PAYE, NI, and pension calculations for UK employees - Submit Real Time Information (RTI) reports including FPS and EPS to HMRC - Manage user permissions with role-based access control over payroll operations - Process Construction Industry Scheme (CIS) deductions and subcontractor records - Generate payslips, P45s, P60s, and employer payment summaries - Administer pension auto-enrolment assessments and contribution tracking - Configure pay codes, schedules, and journal instructions for accounting systems ## Use cases ### UK Payroll Processing with Access Control Execute monthly or weekly pay runs with the latest PayRun.IO engine while controlling who has access to payroll operations through permission management. Version 23 adds the ability to map users to specific permissions, enabling role-based access so only authorized personnel can run payroll, view pay data, or submit RTI reports. Example prompt: List users assigned to a specific permission via GET `/Permission/{PermissionId}/Users`, then execute a pay run for the authorized employer ### HMRC Compliance Reporting Generate and submit all required HMRC reports including Full Payment Submissions (FPS) after each pay event, Employer Payment Summaries (EPS) monthly, and end-of-year P60 certificates. The API handles RTI data formatting, submission tracking, and HMRC acknowledgement monitoring. Example prompt: Trigger an RTI FPS submission for employer emp_001 after the latest pay run and verify HMRC acknowledgement status ### Pension and Benefits Administration Manage workplace pension obligations including auto-enrolment assessments, contribution calculations based on qualifying earnings, and pension scheme configuration. The API evaluates each employee's eligibility at every pay period and calculates the correct employer and employee contributions automatically. Example prompt: Retrieve AE assessments for all employees under employer emp_001 and identify any requiring re-assessment or opt-out processing ### AI Agent Payroll Automation AI agents use the PayRun.IO v23 API through Jentic to automate UK payroll operations across 390 endpoints without managing OAuth tokens or navigating the complex resource hierarchy. Jentic provides intent-based discovery to find the right operation among employers, employees, pay runs, and reporting resources. Example prompt: Search Jentic for 'check payroll permissions', load the permission-users schema, and verify which users can execute pay runs ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/Employer/{EmployerId}` | Retrieve employer details | | GET | `/Employer/{EmployerId}/Employees` | List all employees | | GET | `/Employer/{EmployerId}/PayRuns` | List pay runs | | GET | `/Employer/{EmployerId}/PaySchedules` | List pay schedules | | GET | `/Employer/{EmployerId}/RtiTransactions` | List RTI submissions | | GET | `/Permission/{PermissionId}/Users` | List users with a permission | | GET | `/Employer/{EmployerId}/Employee/{EmployeeId}/AEAssessments` | Get pension assessments | | GET | `/Employer/{EmployerId}/CisTransactions` | List CIS transactions | ## Key resources - **Employers** — Create and manage employer accounts and payroll settings - **Employees** — Manage employee records, pay instructions, and journal lines - **Pay Runs** — Execute payroll calculations and retrieve results - **Permissions** — Map users to permissions for role-based payroll access - **Pensions** — Configure pension schemes and auto-enrolment - **RTI Transactions** — Submit and track HMRC filings - **CIS Transactions** — Manage Construction Industry Scheme records ## Why Jentic - **Setup:** Wiring PayRun.IO by hand means learning its OAuth 2.0 flow with token refresh and navigating a 390-endpoint UK payroll resource hierarchy yourself. Through Jentic you install once, import PayRun.IO from the API Directory, store the credentials once, and your agent calls it. - **Permission scoping:** PayRun.IO puts the employer id in the URL path (`/Employer/{EmployerId}/...`), so a rule can pin your agent to one employer: it can read that employer's employees, pay runs, and RTI transactions and nothing else. You choose the operations it may call, so writes to permissions or pay schedules are not included unless you add them. - **Credential handling:** Your PayRun.IO OAuth client credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time with refresh handled for you. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'submit RTI to HMRC' or 'list an employer's pay runs', and Jentic returns the matching PayRun.IO operation with its input schema so the agent calls the right endpoint without navigating the resource hierarchy in the reference docs. ## Related APIs - **PayRun.IO (v22)** — Previous version of the same payroll engine with 389 endpoints - **Xero Payroll** — Accounting-integrated payroll focused on Australia - **Gusto** — US payroll and HR platform with benefits administration ## FAQ ### Why is there no official OpenAPI spec for PayRun.IO? PayRun.IO does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call PayRun.IO 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 PayRun API use? PayRun.IO uses OAuth 2.0 authentication. You obtain access tokens via the OAuth flow and include them in the Authorization header. Through Jentic, OAuth tokens are stored encrypted in your Jentic One instance with automatic refresh, so agents never handle client secrets directly. ### How does this version differ from the older PayRun.IO API? Version 23.24.2.136 adds the GET `/Permission/{PermissionId}/Users` endpoint for mapping users to specific payroll permissions. This enables role-based access control over who can run payroll, submit RTI, or view sensitive pay data. All other endpoints remain consistent with version 22. ### How do I manage payroll permissions through Jentic? Use Jentic to search for 'list payroll permission users', load the schema for GET `/Permission/{PermissionId}/Users`, and execute with the permission ID. This returns all users assigned to that permission, enabling audit and access control verification. ### Can I generate end-of-year tax documents? Yes. The API provides endpoints for P60 generation (end-of-year employee summary), P45 (leaving certificate), and P32 (employer payment summary). These are accessible under the Employer and Employee resource hierarchy and generate the correct HMRC-compliant output. ### Does the PayRun API handle pension auto-enrolment? Yes. The AE Assessment endpoints evaluate each employee's pension eligibility at every pay period, calculate qualifying earnings, and determine correct contribution rates. The API tracks opt-in, opt-out, and postponement status for each employee under the employer's pension scheme. ### Can I limit what my agent is allowed to do with the PayRun API? Yes. Because you run Jentic One yourself, your own rules decide which PayRun.IO operations and credentials the agent may use. Since the employer id sits in the URL path (`/Employer/{EmployerId}/...`), you can pin the agent to a single employer and let it read only that employer's employees, pay runs, and RTI transactions. You also pick the exact operations it may call, so writes to permissions or pay schedules stay out of reach unless you explicitly allow them.