--- title: Justworks API Integration on Truto slug: justworks category: HRIS canonical: "https://truto.one/integrations/detail/justworks/" --- # Justworks API Integration on Truto **Category:** HRIS **Status:** Beta ## Unified APIs ### Unified HRIS API - **Companies** — Companies represent the companies in HRIS - **Employee Compensations** — Represent the compensation configuration for an Employee - **Employee Payroll Runs** — Employee Payroll Runs represent the Employee Payroll Runs for an Employee - **Employees** — Represents an employee in HRIS - **Employments** — Employments represent a job position at a company. - **Fields** — Represent the fields for various entities in the company - **Groups** — Groups represent the groups for an Employee - **Locations** — Locations represent the locations in HRIS - **Payroll Runs** — Payrollruns represent a group of pay statements for a specific pay schedule. - **Timeoff Policies** — Represent the time off policies in a company - **Timeoff Requests** — Represent the time off requests for an Employee ## MCP-ready AI tools Truto exposes 24 tools for Justworks that AI agents can call directly. - **list_all_justworks_company** — Get the Justworks company that authorized this connection (every token is scoped to one company), returned as a single-item list. Includes id, display_name, country_data, addresses, phones, departments, offices, created_at and updated_at. legal_name, tax_id and office addresses are present only when the company.detail:read scope was granted; empty single-value fields are omitted. - **list_all_justworks_company_bank_account** — Get the bank account on file for the connected Justworks company, returned as a single-item list with account_type, bank_name, account_number_tail (last four digits only) and routing_number. Fields without a value are omitted. Requires the company.bank_account:read scope. - **list_all_justworks_company_business_info** — Get the connected Justworks company's verified business information, returned as a single-item list: officers (name and titles) and entity_identifiers (state, issue_date, file_number). Requires the company.detail:read scope. - **list_all_justworks_company_custom_fields** — List the custom fields defined for the connected Justworks company: id, label, category, type (text, selection or unknown), cardinality and, for selection fields, the allowed options. Not paginated. A member's values for these fields come from member_custom_field_values list. Requires the company.detail:read scope. - **list_all_justworks_company_jurisdictions** — List the jurisdictions (e.g. US states) of the connected Justworks company; each item has a zone_code. Not paginated. Requires both the company.detail:read and member.detail:read scopes. - **list_all_justworks_members** — List the members (employees, contractors, owners and other types) of the connected Justworks company. Cursor-paginated, up to 100 per page. Filters: status (active or terminated); updated_at, updated_at_gt, updated_at_gte, updated_at_lt, updated_at_lte, updated_at_ne (YYYY-MM-DD). Scope-gated fields are omitted without their scope: type, emails, phones, addresses, manager (member.detail:read); date_of_birth (member.dob:read); sex_assigned_at_birth (member.sex:read); pay fields (member.pay:read); employment fields (member.employment:read). Empty values are omitted. - **get_single_justworks_member_by_id** — Get one member of the connected Justworks company; id is the member ID (member_...). Returns name, type, active, job_title, emails, phones, addresses, department, office, manager, current_pay, pay_history, current_employment, employment_history and dates. Fields behind optional scopes (member.detail:read, member.dob:read, member.sex:read, member.pay:read, member.employment:read) are omitted when the scope was not granted, as are empty values. pay_rate is in cents. - **update_a_justworks_member_by_id** — Update a member of the connected Justworks company (id is the member ID): send only the fields to change among job_title, department_id (dept_...) and manager_id (member_...). Requires the member:write scope. Returns 204 No Content (an empty result) on success. - **list_all_justworks_member_custom_field_values** — List one member's custom field values. Requires member_id (member_...). Each item has id (the custom field ID from company_custom_fields list) and values (an array of strings). Not paginated. Requires the member.detail:read scope. - **get_single_justworks_member_tax_id_by_id** — Get a member's US Social Security number; id is the member ID (member_...). Returns US.ssn. Domestic members only: international_contractor members return 400, and employee_eor or international_employee members return 404 (no SSN on file). Requires the member.tax_id:read scope. - **list_all_justworks_payrolls** — List payrolls of the connected Justworks company processed between start_date and end_date (both required, YYYY-MM-DD). Cursor-paginated, up to 100 per page. Each payroll has id, debit_date, pay_date, payment_method, currency and totals in cents (4500 = $45.00): company_debit, gross_pay, net_pay, employee_taxes, employer_taxes. Pass id as payroll_id to payroll_fees list and paystubs list. - **list_all_justworks_payroll_fees** — List the fees charged for one payroll. Requires payroll_id (from payrolls list). Cursor-paginated, up to 100 per page. Each fee has name, amount (in cents), currency and, when set, type, member_id, reference_type (member or paystub) and reference_id. - **list_all_justworks_paystubs** — List the paystubs of one payroll. Requires payroll_id (from payrolls list). Cursor-paginated, up to 100 per page. Each item has paystub_id, member_id, pay_period_start, pay_period_end, pay_date, currency, gross_pay and net_pay (in cents) and pay_group. Use paystubs get for the line items. - **get_single_justworks_paystub_by_id** — Get one paystub; id is the paystub_id from paystubs list. Returns member_id, pay_period_start, pay_period_end, pay_date, currency, gross_pay, net_pay and pay_group plus the earnings, employee_deductions and employer_contributions line items. All amounts are integers in cents (4500 = $45.00). Requires the paystub:read scope. - **list_all_justworks_deduction_types** — List the deduction types available to the connected Justworks company. Each item has a code and a description; pass code as deduction_type_code when creating deductions. Not paginated. Requires the deductions:read scope. - **list_all_justworks_deductions** — List payroll deductions of the connected Justworks company. Cursor-paginated, up to 100 per page. Optional filters: member_id, deduction_type, frequency, description. Each deduction has id, member_id, deduction_type_code, frequency, description, currency, amount_type (fixed or percent), amount, start_date and end_date. Fixed amounts are in cents (4500 = $45.00); percent amounts carry 4 decimal places (37000 = 3.7%). - **create_a_justworks_deduction** — Create one or more deductions in one call. Body: items, an array whose entries need member_id, deduction_type_code, frequency, description, amount_type (fixed or percent), amount and start_date (currency too when fixed; end_date and operation_id optional). Returns 201 with items: one result per entry with deduction_id, member_id, success and error_message. A 201 can still contain failed entries, so check success on each. Amounts: fixed in cents (4500 = $45.00), percent with 4 decimals (37000 = 3.7%). - **justworks_deductions_bulk_update** — Update one or more existing deductions in one call. Body: items, an array whose entries need deduction_id plus any of deduction_type_code, frequency, description, amount_type, currency, amount, start_date, end_date. Returns items: one result per entry with deduction_id, member_id, success and error_message. A 200 can still contain failed entries, so check success on each. Amounts: fixed in cents, percent with 4 decimals (37000 = 3.7%). - **justworks_deductions_cancel** — Cancel one or more deductions: send deduction_ids (an array of deduction IDs). Returns items with one result per ID (deduction_id, member_id, success, error_message); a 200 can still contain failed entries, so check success on each. Requires the deductions:write scope. - **list_all_justworks_subscriptions** — List the Justworks product subscriptions of the connected company (e.g. PEO, Payroll PEPM, Payroll Base). Expired subscriptions are left out unless include_expired=true. Not paginated. Each subscription has id, company_id, product_name, status (ACTIVE, EXPIRED or PENDING), start_date, end_date, prices, discounts and add_ons (child subscriptions with the same fields). - **list_all_justworks_time_off_requests** — List time off requests of the connected Justworks company. start_date and end_date (YYYY-MM-DD) are required; member_id, policy_id and status (requested, approved, declined, cancelled, deleted, manual) are optional filters. Cursor-paginated, up to 100 per page. Each request has id, member_id, policy_id, start_date, end_date, amount with its unit_type (minutes, hours or days), status, notes, created_at and updated_at. - **list_all_justworks_time_off_policies** — List the time off policies of the connected Justworks company, optionally filtered by status (active or inactive). Cursor-paginated, up to 100 per page. Each policy has id, name, status, type (vacation, sick_leave, other or international), effective_date and deactivation_date. - **create_a_justworks_time_off_balance_report** — Start an asynchronous time off balances report. Body fields are all optional: as_of_date (YYYY-MM-DD, the date to calculate balances as of), member_id and policy_id (filters). Returns report_id; then poll time_off_balance_reports get with that ID until status is ready. Requires the time_off:read scope. - **get_single_justworks_time_off_balance_report_by_id** — Get a time off balances report; id is the report_id returned by time_off_balance_reports create. status is pending, ready or error: poll until it is ready, then read items (member_id, policy_id, available, used, unit_type); message explains the status or error. Requires the time_off:read scope. ## How it works 1. **Link your customer's Justworks account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Justworks.** The Proxy API is a 1-to-1 mapping of the Justworks API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Sync employee directory for performance and engagement tools** — Performance review, pulse survey, and OKR platforms can pull Justworks members, employments, and manager relationships to automatically keep org charts and review cycles up to date without HR admins exporting CSVs. - **Automate 401k and benefits deductions** — Retirement, commuter benefits, and HSA providers can push contribution rates directly into Justworks payroll as pre-tax or post-tax deductions, eliminating manual deferral updates before each pay run. - **Trigger IT provisioning and offboarding workflows** — ITSM, MDM, and identity platforms can detect new hires and terminations in Justworks to automate laptop shipping, SSO account creation, and access revocation the moment employment status changes. - **Feed payroll data into accounting and FP&A tools** — Accounting, ERP, and financial planning platforms can extract payroll runs, paystubs, and Justworks fees to post journal entries and reconcile labor costs against the general ledger. - **Power compliance and security audits** — Compliance platforms can treat Justworks as the source of truth for active employment, mapping members to systems access and routing escalations through the manager hierarchy for SOC 2 and ISO audits. ## What you can build - **Incremental employee sync with write-back** — Continuously sync Justworks members into your app and write back updates to job title, department, and manager using the Employees and Employments models. - **Automated payroll deduction management** — Let your users create, bulk update, and cancel pre-tax or post-tax deductions in Justworks directly from your UI, with support for fixed amounts or percentages. - **Paystub and payroll run reporting** — Pull per-employee paystubs, aggregated payroll runs, and payroll fees to render reconciliation dashboards or export line items to accounting systems. - **Time off visibility and balance reports** — Display upcoming PTO, policy details, and generate on-demand time off balance reports inside your scheduling, project management, or capacity planning product. - **Org chart and group hierarchy builder** — Use Groups, Employments, and manager relationships to render a live org chart in your app without asking admins to maintain it separately. - **Custom field passthrough** — Read company-defined custom fields and member custom field values from Justworks to surface attributes like cost center or employee ID in your workflows. ## FAQs ### How does authentication work for the Justworks integration? Truto handles the full auth flow with Justworks on your behalf. Your end users connect their Justworks account through Truto's hosted link or your embedded flow, and Truto manages token storage and refresh so you never touch credentials. ### Can we write data back to Justworks, or is it read-only? Justworks supports write operations through Truto. You can update member records (job title, department, manager), create and bulk update payroll deductions, and cancel deductions. Payroll runs, paystubs, and time off data are read-only. ### How fresh is the data from Justworks? Truto polls Justworks on a configurable schedule and supports incremental sync using updated_at filters, so you only fetch records that changed since the last run. You can also trigger on-demand syncs when your users expect immediate updates. ### Does the integration expose custom fields defined by the customer in Justworks? Yes. You can list company-level custom field definitions and read per-member custom field values, then map them into your own schema or expose them through Truto's Fields model. ### How are time off balances handled given Justworks uses async reports? Truto wraps the asynchronous balance report flow: you trigger a balance report creation, and Truto handles polling the report ID until it's ready so your app receives the final data without managing the async handshake. ### Can we use the Unified HRIS API and Justworks-specific endpoints together? Yes. Use the Unified HRIS API for portable models like Employees, Employments, Groups, Payroll Runs, and Timeoff Requests across multiple HRIS providers, and drop down to Justworks-native tools (like deductions or paystubs) when you need provider-specific capabilities.