{"openapi":"3.1.0","info":{"title":"Lightning Payroll API","description":"Backend services for the Lightning Payroll web & mobile apps, partner white-label integrations, OAuth-based partner onboarding, and AU/NZ payroll compliance (Superstream, payday filing).","version":"0.1.0"},"paths":{"/api/company/{company_id}":{"get":{"tags":["Company"],"summary":"Get Company","description":"Get detailed company data (including basic info on all employees) by ID.","operationId":"get_company_api_company__company_id__get","parameters":[{"description":"The unique LP-generated ID of the company.","required":true,"schema":{"type":"integer","title":"Company Id","description":"The unique LP-generated ID of the company."},"example":1,"name":"company_id","in":"path"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Get Company Api Company  Company Id  Get"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]},"delete":{"tags":["Company"],"summary":"Delete Company","description":"Delete a company by its ID. Only accessible to users with permission.","operationId":"delete_company_api_company__company_id__delete","parameters":[{"description":"The unique LP-generated ID of the company.","required":true,"schema":{"type":"integer","title":"Company Id","description":"The unique LP-generated ID of the company."},"example":1,"name":"company_id","in":"path"}],"responses":{"204":{"description":"Successful Response"},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]},"patch":{"tags":["Company"],"summary":"Patch Company","description":"Partial **update** – supply only the fields you want to change.\nAn empty body is permitted (no-op).  \nTo clear a value entirely, pass it as `null` (provided the DB column is\nnullable).","operationId":"patch_company_api_company__company_id__patch","parameters":[{"description":"Company ID","required":true,"schema":{"type":"integer","title":"Company Id","description":"Company ID"},"example":1,"name":"company_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyPartialUpdate"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/company/{company_id}/pay-rates":{"get":{"tags":["Company"],"summary":"Get Company Pay Rates","description":"Get company pay rates grouped by award and classification (company pay-rate group). By default this returns all awards, including a no-award bucket where `award_id`/`award_name` are null. Use `award` and/or `classification` query filters to narrow results by id or exact name (case-insensitive). Set `include_employees=true` to include employee summaries for each classification.\n\nEach returned pay rate includes a stable `reference` value in the format `company:{id}`. That reference can be supplied as `hours[].rate_reference` in `/api/company/{company_id}/pays/create` so your integration can map external award-engine outputs to LP company rates without sending a fixed dollar rate.","operationId":"get_company_pay_rates_api_company__company_id__pay_rates_get","parameters":[{"description":"The unique LP-generated ID of the company.","required":true,"schema":{"type":"integer","title":"Company Id","description":"The unique LP-generated ID of the company."},"example":1,"name":"company_id","in":"path"},{"description":"Optional award selector. Match by award id or exact name (case-insensitive). Use `none` or `null` for no-award classifications.","required":false,"schema":{"type":"string","title":"Award","description":"Optional award selector. Match by award id or exact name (case-insensitive). Use `none` or `null` for no-award classifications."},"example":"Hospitality Award","name":"award","in":"query"},{"description":"Optional classification selector. Match by company pay-rate group id or exact group name (case-insensitive).","required":false,"schema":{"type":"string","title":"Classification","description":"Optional classification selector. Match by company pay-rate group id or exact group name (case-insensitive)."},"example":"Level 1","name":"classification","in":"query"},{"description":"Set to `true` to include employees nested under each classification with `id`, `format_name`, and `number`.","required":false,"schema":{"type":"boolean","title":"Include Employees","description":"Set to `true` to include employees nested under each classification with `id`, `format_name`, and `number`.","default":false},"example":false,"name":"include_employees","in":"query"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyPayRatesResponse"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/redirect/company/{company_id}":{"get":{"tags":["Company"],"summary":"Redirect an authenticated user straight to the Pays screen for the given company.","description":"Authenticated helper that mirrors selecting a company then navigating to the Pays screen.\n\nIt validates the user's access to the company, updates the customer's default company,\nand issues a 302 redirect to the front-end route that will open Pays for that company.","operationId":"redirect_to_company_pays_api_redirect_company__company_id__get","parameters":[{"description":"Target company id to open in the UI.","required":true,"schema":{"type":"integer","title":"Company Id","description":"Target company id to open in the UI."},"name":"company_id","in":"path"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/company/create":{"put":{"tags":["Company"],"summary":"Create Company","description":"Create a **new** company record.\n\n* `id` is **ignored** if supplied (it is generated by Lightning Payroll).\n* `employees` may be omitted (you can add them later).","operationId":"create_company_api_company_create_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/company":{"get":{"tags":["Company"],"summary":"Get All Companies","description":"Get detailed list of all accessible companies, including basic employee information.","operationId":"get_all_companies_api_company_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{},"type":"array","title":"Response Get All Companies Api Company Get"}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/company/{company_id}/employees":{"get":{"tags":["Employee"],"summary":"Get Employees","description":"Get detailed info for all employees in a company.","operationId":"get_employees_api_company__company_id__employees_get","parameters":[{"description":"The unique LP-generated ID of the company.","required":true,"schema":{"type":"integer","title":"Company Id","description":"The unique LP-generated ID of the company."},"example":1,"name":"company_id","in":"path"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{},"type":"array","title":"Response Get Employees Api Company  Company Id  Employees Get"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/address/autocomplete":{"get":{"tags":["Address"],"summary":"Address Autocomplete","description":"Type-ahead address suggestions for AU/NZ. Server-side geocoder proxy (Geoapify when configured, else keyless Photon) so the API key never reaches the browser. Always returns 200; an empty list means the lookup is unavailable and the form falls back to manual entry.","operationId":"address_autocomplete_api_address_autocomplete_get","parameters":[{"description":"Partial address text.","required":true,"schema":{"type":"string","maxLength":200,"minLength":3,"title":"Text","description":"Partial address text."},"name":"text","in":"query"},{"description":"Comma-separated 2-letter country filter.","required":false,"schema":{"type":"string","title":"Country","description":"Comma-separated 2-letter country filter.","default":"au,nz"},"name":"country","in":"query"},{"description":"Max suggestions to return.","required":false,"schema":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Limit","description":"Max suggestions to return.","default":5},"name":"limit","in":"query"},{"description":"2-letter country code to rank first (bias only; nothing is excluded).","required":false,"schema":{"type":"string","maxLength":2,"title":"Primary","description":"2-letter country code to rank first (bias only; nothing is excluded).","default":""},"name":"primary","in":"query"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Address Autocomplete Api Address Autocomplete Get"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/company/{company_id}/employees/create":{"put":{"tags":["Employee"],"summary":"Create one or more new employees for a company","description":"Accepts a list of EmployeeCreate models, attempts to create each one, and returns a list of EmployeeResult indicating success or per-item errors. Note that required fields have an asterisk (*) in the model definition.","operationId":"create_employees_api_company__company_id__employees_create_put","parameters":[{"description":"The unique Lightning Payroll–generated ID of the company.","required":true,"schema":{"type":"integer","title":"Company Id","description":"The unique Lightning Payroll–generated ID of the company."},"example":1,"name":"company_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/EmployeeCreate"},"type":"array","title":"Employees"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/EmployeeResult"},"type":"array","title":"Response Create Employees Api Company  Company Id  Employees Create Put"}}}},"404":{"description":"Company not found.","content":{"application/json":{"example":{"status_code":10404,"message":"Company not found"}}}},"400":{"description":"Bad request, e.g., empty employee list.","content":{"application/json":{"example":{"status_code":10400,"message":"Employee list cannot be empty."}}}},"422":{"description":"Validation error for one or more employees.","content":{"application/json":{"example":{"status_code":10422,"message":"[{'loc': ('body', 0, 'email'), 'msg': 'Invalid email format.', 'type': 'value_error'}]"}}}},"207":{"description":"Partial success – some creations had validation errors.","content":{"application/json":{"example":[{"employee":{"id":456,"first_name":"Bob","last_name":"Jones","email":"bob.jones@example.com"},"errors":{}},{"errors":{"tax_file_number":"Invalid TFN checksum."}}]}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/company/{company_id}/employees/update":{"patch":{"tags":["Employee"],"summary":"Update Employees","description":"Update one or more existing employees for a company.","operationId":"update_employees_api_company__company_id__employees_update_patch","parameters":[{"description":"The unique LP-generated ID of the company.","required":true,"schema":{"type":"integer","title":"Company Id","description":"The unique LP-generated ID of the company."},"example":1,"name":"company_id","in":"path"},{"description":"Specify which employee identifier is used in `employee_ids`:\n- `employee_id`: Use LP-internal database IDs (integers).\n- `employee_number`: Use your own external employee numbers (strings).\n\nDefault is `employee_id`. These identifiers must be unique for each employee across **all** companies.","required":false,"schema":{"type":"string","pattern":"^(employee_id|employee_number)$","title":"Identifier Type","description":"Specify which employee identifier is used in `employee_ids`:\n- `employee_id`: Use LP-internal database IDs (integers).\n- `employee_number`: Use your own external employee numbers (strings).\n\nDefault is `employee_id`. These identifiers must be unique for each employee across **all** companies.","default":"employee_id"},"example":"employee_id","name":"identifier_type","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/EmployeeUpdate"},"type":"array","title":"Employees"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/EmployeeResult"},"type":"array","title":"Response Update Employees Api Company  Company Id  Employees Update Patch"}}}},"404":{"description":"Not found"},"422":{"description":"Validation error for one or more employees.","content":{"application/json":{"example":{"status_code":10422,"message":"[{'loc': ('body', 0, 'tax_file_number'), 'msg': 'Invalid tax file number (fails ATO checksum).', 'type': 'value_error'}, {'loc': ('body', 1, 'tax_file_number'), 'msg': 'Invalid tax file number (fails ATO checksum).', 'type': 'value_error'}]"}}}},"207":{"description":"Partial success – some employee updates had validation errors.","content":{"application/json":{"example":{"employee":{"tax_file_number":"111111111","first_name":"Harry","last_name":"Stone","date_of_birth":"1990-01-01","pay_method":"DIRECT BANK ENTRY","pay_period":"WEEKLY","standard_hours_per_day":7.6,"standard_days_per_week":5,"stp_employment_status":"F","active_pay_recipient":true,"start_date":"2024-07-01","employment_status":"Full time","tfnd_signed_date":"2024-07-01","has_claimed_tax_free_threshold":true,"super_rate":0.115,"is_super_enabled":true,"is_leave_enabled":true,"accrue_holiday_leave_per_hour":276923,"accrue_sick_leave_per_hour":138463,"accrue_lsl_per_hour":60023,"num_holiday_leave_days_per_year":63,"is_lsl_enabled":true,"lsl_x_years":10,"lsl_accrued_x_years":8,"id":32,"company_id":2,"readable_stp_employment_status":"Full Time","is_australian_resident":true,"income_stream":"SAW","stp_id":32,"tax_treatment_code":"NAXXXX","single_touch_residency_status":"Resident","is_terminated":false},"errors":{}}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/employees/{employee_id}/pay-rates":{"get":{"tags":["Employee"],"summary":"Get Employee Pay Rates","description":"Get all pay-rate options available to a given employee. Returns three categories: system rates, employee-specific rates, and company rates attached to the employee. Each row includes a stable `reference` key for integration mapping.","operationId":"get_employee_pay_rates_api_employees__employee_id__pay_rates_get","parameters":[{"description":"The employee identifier. Interpreted as LP employee_id or employee_number based on identifier_type.","required":true,"schema":{"type":"string","title":"Employee Id","description":"The employee identifier. Interpreted as LP employee_id or employee_number based on identifier_type."},"example":1,"name":"employee_id","in":"path"},{"description":"Specify which employee identifier to use:\n- 'employee_id': Use LP-internal database IDs (integers).\n- 'employee_number': Use your own external employee numbers (strings).\nDefault is 'employee_id'. These must be unique for each employee across all companies.","required":false,"schema":{"type":"string","pattern":"^(employee_id|employee_number)$","title":"Identifier Type","description":"Specify which employee identifier to use:\n- 'employee_id': Use LP-internal database IDs (integers).\n- 'employee_number': Use your own external employee numbers (strings).\nDefault is 'employee_id'. These must be unique for each employee across all companies.","default":"employee_id"},"example":"employee_id","name":"identifier_type","in":"query"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeePayRatesResponse"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/employees/{employee_id}":{"get":{"tags":["Employee"],"summary":"Get Employee","description":"Get employee data by Lightning Payroll ID.","operationId":"get_employee_api_employees__employee_id__get","parameters":[{"description":"The unique LP-generated ID of the employee.","required":true,"schema":{"type":"integer","title":"Employee Id","description":"The unique LP-generated ID of the employee."},"example":1,"name":"employee_id","in":"path"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Get Employee Api Employees  Employee Id  Get"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/employees/payroll-number/{employee_number}":{"get":{"tags":["Employee"],"summary":"Get Employee By Payroll Number","description":"Get detailed employee data by their user-controlled payroll number, rather than their unique LP ID.","operationId":"get_employee_by_payroll_number_api_employees_payroll_number__employee_number__get","parameters":[{"description":"The user-controlled payroll number of the employee. Must be unique across all companies.","required":true,"schema":{"type":"string","title":"Employee Number","description":"The user-controlled payroll number of the employee. Must be unique across all companies."},"example":"12345","name":"employee_number","in":"path"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Get Employee By Payroll Number Api Employees Payroll Number  Employee Number  Get"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/pay-run/{pay_run_id}":{"get":{"tags":["Pay Runs"],"summary":"Get Pay Run","description":"Get pay run data by ID.","operationId":"get_pay_run_api_pay_run__pay_run_id__get","parameters":[{"description":"The unique LP-generated ID of the pay run.","required":true,"schema":{"type":"integer","title":"Pay Run Id","description":"The unique LP-generated ID of the pay run."},"example":1,"name":"pay_run_id","in":"path"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Get Pay Run Api Pay Run  Pay Run Id  Get"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/pay-run/{pay_run_id}/gl-postings":{"get":{"tags":["Pay Runs"],"summary":"Get Gl Postings For Pay Run","description":"Retrieve detailed General Ledger (GL) postings for a specific pay run.","operationId":"get_gl_postings_for_pay_run_api_pay_run__pay_run_id__gl_postings_get","parameters":[{"description":"The unique LP-generated ID of the pay run.","required":true,"schema":{"type":"integer","title":"Pay Run Id","description":"The unique LP-generated ID of the pay run."},"example":1,"name":"pay_run_id","in":"path"}],"responses":{"200":{"description":"A list of GL postings for the specified pay run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GLPostingsResponse"},"example":{"pay_run_id":1,"postings":[{"account_id":"00-00-0001","description":"Gross Wages","amount":1500.0,"date":"14/01/2025"},{"account_id":"00-00-0002","description":"Superannuation (incl Super levy and Salary sacrifice)","amount":172.5,"date":"14/01/2025"},{"account_id":"00-00-0004","description":"Bank/Net","amount":-1335.0,"date":"14/01/2025"},{"account_id":"00-00-0005","description":"Group Tax Clearing","amount":-165.0,"date":"14/01/2025"},{"account_id":"00-00-0006","description":"Superannuation Clearing (incl Super levy and Salary sacrifice)","amount":-172.5,"date":"14/01/2025"}]}}}},"404":{"description":"Not found"},"400":{"description":"Bad request due to invalid pay run ID or incomplete data.","content":{"application/json":{"example":{"detail":"No pay run found with the given pay_run_id"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/company/{company_id}/pay-runs":{"post":{"tags":["Pay Runs"],"summary":"Get Pay Runs","description":"Get pay runs ending between the given dates (or processed within the given dates.","operationId":"get_pay_runs_api_company__company_id__pay_runs_post","parameters":[{"description":"The ID of the company.","required":true,"schema":{"type":"integer","title":"Company Id","description":"The ID of the company."},"example":1,"name":"company_id","in":"path"},{"description":"The start date for the pay run search in `YYYY-MM-DD` format. Defaults to today if not provided.","required":false,"schema":{"type":"string","title":"Start Date","description":"The start date for the pay run search in `YYYY-MM-DD` format. Defaults to today if not provided."},"example":"2024-07-01","name":"start_date","in":"query"},{"description":"The end date for the pay run search in `YYYY-MM-DD` format. Defaults to today if not provided.","required":false,"schema":{"type":"string","title":"End Date","description":"The end date for the pay run search in `YYYY-MM-DD` format. Defaults to today if not provided."},"example":"2025-06-30","name":"end_date","in":"query"},{"description":"Set to `True` to search for pay runs processed within the given date range. The alternative is to search by pay run end date. Searching by pay run end date can be problematic because ATO records are reported based on the processed date, not the pay run end date.","required":false,"schema":{"type":"boolean","title":"Use Processed Date","description":"Set to `True` to search for pay runs processed within the given date range. The alternative is to search by pay run end date. Searching by pay run end date can be problematic because ATO records are reported based on the processed date, not the pay run end date.","default":false},"example":false,"name":"use_processed_date","in":"query"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/company/{company_id}/pays":{"post":{"tags":["Pays"],"summary":"Get Pays","description":"Get summarised list of all completed pays within a given date range. Pay results can be grouped by pay run or employee, or neither (flat Pay list). Request body is a list of employee IDs to filter. If no employee identifiers are provided, all employees for the company_id are included. The identifier_type query parameter can be used to specify whether the employee_ids are LP IDs (employee_id) or user-controlled payroll numbers (employee_number). If using the employee_number, please be aware that they must be unique across ALL companies.","operationId":"get_pays_api_company__company_id__pays_post","parameters":[{"description":"The ID of the company.","required":true,"schema":{"type":"integer","title":"Company Id","description":"The ID of the company."},"example":1,"name":"company_id","in":"path"},{"description":"The start date for the pays in `YYYY-MM-DD` format. Defaults to today if not provided.","required":false,"schema":{"type":"string","title":"Start Date","description":"The start date for the pays in `YYYY-MM-DD` format. Defaults to today if not provided."},"example":"2024-07-01","name":"start_date","in":"query"},{"description":"The end date for the pays in `YYYY-MM-DD` format. Defaults to today if not provided.","required":false,"schema":{"type":"string","title":"End Date","description":"The end date for the pays in `YYYY-MM-DD` format. Defaults to today if not provided."},"example":"2025-06-30","name":"end_date","in":"query"},{"description":"Set to `True` to group pay results by pay run.","required":false,"schema":{"type":"boolean","title":"Group By Pay Run","description":"Set to `True` to group pay results by pay run.","default":false},"example":false,"name":"group_by_pay_run","in":"query"},{"description":"Set to `True` to group pay results by employee.","required":false,"schema":{"type":"boolean","title":"Group By Employee","description":"Set to `True` to group pay results by employee.","default":false},"example":false,"name":"group_by_employee","in":"query"},{"description":"Specify which employee identifier provided in `employee_ids`:\n- `employee_id`: Use LP-internal database IDs (integers).\n- `employee_number`: Use your own external employee numbers (strings).\n\nDefault is `employee_id`. These identifiers must be unique for each employee across **all** companies.","required":false,"schema":{"type":"string","pattern":"^(employee_id|employee_number)$","title":"Identifier Type","description":"Specify which employee identifier provided in `employee_ids`:\n- `employee_id`: Use LP-internal database IDs (integers).\n- `employee_number`: Use your own external employee numbers (strings).\n\nDefault is `employee_id`. These identifiers must be unique for each employee across **all** companies.","default":"employee_id"},"example":"employee_id","name":"identifier_type","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"items":{"anyOf":[{"type":"integer"},{"type":"string"}]},"type":"array","title":"Employee Ids","description":"A list of employee identifiers to filter the pays. The type of identifiers is specified by the `identifier_type` parameter.","default":[]}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/company/{company_id}/pays/create":{"put":{"tags":["Pays"],"summary":"Create Pays For Date","description":"Create pays for a given date. The identifier_type query parameter can be used to specify whether the employee_ids are LP IDs (employee_id) or user-controlled payroll numbers (employee_number). If using the employee_number, please be aware that they must be unique across ALL companies.","operationId":"create_pays_for_date_api_company__company_id__pays_create_put","parameters":[{"description":"The unique LP-generated ID of the company.","required":true,"schema":{"type":"integer","title":"Company Id","description":"The unique LP-generated ID of the company."},"example":1,"name":"company_id","in":"path"},{"description":"Set to `True` to group pay results by pay run.","required":false,"schema":{"type":"boolean","title":"Group By Pay Run","description":"Set to `True` to group pay results by pay run.","default":false},"example":false,"name":"group_by_pay_run","in":"query"},{"description":"Set to `True` to group pay results by employee (using either employee_id or employee_number depending on identifier_type).","required":false,"schema":{"type":"boolean","title":"Group By Employee","description":"Set to `True` to group pay results by employee (using either employee_id or employee_number depending on identifier_type).","default":false},"example":false,"name":"group_by_employee","in":"query"},{"description":"If True, and this request creates multiple pays for the same employee in the same pay run with different departments, redistribute the combined tax for those new pays in proportion to each pay's gross. Only affects pays created by this call.","required":false,"schema":{"type":"boolean","title":"Redistribute Tax By Gross","description":"If True, and this request creates multiple pays for the same employee in the same pay run with different departments, redistribute the combined tax for those new pays in proportion to each pay's gross. Only affects pays created by this call.","default":true},"example":true,"name":"redistribute_tax_by_gross","in":"query"},{"description":"Specify which employee identifier to use in 'workers_comp_pays' and when grouping pays by employee:\n- 'employee_id': Use LP-internal database IDs (integers).\n- 'employee_number': Use your own external employee numbers (strings).\nDefault is 'employee_id'. These must be unique for each employee across all companies.","required":false,"schema":{"type":"string","pattern":"^(employee_id|employee_number)$","title":"Identifier Type","description":"Specify which employee identifier to use in 'workers_comp_pays' and when grouping pays by employee:\n- 'employee_id': Use LP-internal database IDs (integers).\n- 'employee_number': Use your own external employee numbers (strings).\nDefault is 'employee_id'. These must be unique for each employee across all companies.","default":"employee_id"},"example":"employee_id","name":"identifier_type","in":"query"},{"description":"The date when these pays were processed, in `YYYY-MM-DD` format. Defaults to today if not provided. The pay run chosen will be the one that matches this date.","required":false,"schema":{"type":"string","title":"Pay Date","description":"The date when these pays were processed, in `YYYY-MM-DD` format. Defaults to today if not provided. The pay run chosen will be the one that matches this date.","default":"2026-07-25"},"example":"2026-07-25","name":"pay_date","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/PayCreate"},"type":"array","title":"Pays","description":"A list of new pay objects to create, which were paid or to be paid on the given pay_date. Provide a single `pay_department` string (unique name or code) per pay to assign a cost centre to all pay items."},"example":[{"employee_id":1234,"hours":[{"description":"Ordinary Time","rate":"30.00","units":"hours","is_overtime":false,"value":"37.5"},{"description":"Saturday Overtime","multiplier":"1.5","units":"hours","is_overtime":true,"value":"5.0"},{"description":"Travel Reimbursement","rate":"0.85","units":"kms","is_overtime":false,"value":"120"},{"description":"Piece Work - Sheep Shearing","rate":"3.50","units":"sheep","is_overtime":false,"value":"90"}],"leave":[{"description":"Annual Leave","leave_type":"HOLIDAY","multiplier":"1.0","hours":"7.6","leave_loading_amount":"3.80","date":"2023-08-15"},{"description":"Personal Leave","leave_type":"SICK","rate":"38.00","hours":"4.0","date":"2023-08-15"}],"pay_department":"Engineering","allowances":[{"description":"Tool Allowance","amount":"50.00","allowance_category":"TD"},{"description":"Car Allowance","amount":"200.00","is_taxable":true,"is_itemised":true,"is_included_in_super_calculations":false,"allowance_category":"AD"}],"deductions":[{"description":"Union Fees","amount":"25.00","classification":"Child Support Deduction"},{"description":"Health Insurance","amount":"100.00","classification":"Normal","is_included_in_super_calculations":true}],"bonuses":[{"description":"Performance Bonus","amount":"500.00","tax_method":"NORMAL_EARNINGS"},{"description":"Director's Fee","amount":"1000.00","tax_method":"SPREAD_OVER_SPECIFIC_RANGE","start_date":"2023-01-01","end_date":"2023-01-31","is_included_in_super_calculations":false,"is_directors_fees":true}],"pay_sacrifices":[{"description":"Laptop Salary Sacrifice","amount":"150.00"},{"amount":"300.00","description":"Car Salary Sacrifice","is_included_in_super_calculations":false,"is_super":true}],"back_payments":[{"description":"Back Pay Adjustment","amount":"200.00","stp_category":"DIRECTOR_S_FEES","tax_method":"NORMAL_EARNINGS","start_date":"2023-01-01","end_date":"2023-01-31"},{"description":"Award Increase Adjustment","amount":"120.00","stp_category":"OVERTIME","tax_method":"NORMAL_EARNINGS","start_date":"2023-02-01","end_date":"2023-02-28"}]}]}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"items":{"$ref":"#/components/schemas/EmployeeNumberPays"},"type":"array"},{"items":{"$ref":"#/components/schemas/EmployeeIDPays"},"type":"array"},{"items":{"$ref":"#/components/schemas/PayRunPays"},"type":"array"},{"items":{"$ref":"#/components/schemas/Pay"},"type":"array"}],"title":"Response Create Pays For Date Api Company  Company Id  Pays Create Put"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/company/{company_id}/pays/{pay_id}":{"get":{"tags":["Pays"],"summary":"Get Single Pay","description":"Get **one** pay record (identified by `pay_id`) that belongs to the specified company. Pass the updated pay data in the request body.","operationId":"get_single_pay_api_company__company_id__pays__pay_id__get","parameters":[{"description":"The unique LP-generated ID of the company.","required":true,"schema":{"type":"integer","title":"Company Id","description":"The unique LP-generated ID of the company."},"example":1,"name":"company_id","in":"path"},{"description":"The unique LP-generated pay ID you want to update.","required":true,"schema":{"type":"integer","title":"Pay Id","description":"The unique LP-generated pay ID you want to update."},"example":42,"name":"pay_id","in":"path"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]},"put":{"tags":["Pays"],"summary":"Update Single Pay","description":"Update **one** pay record (identified by `pay_id`) that belongs to the specified company. Pass the updated pay data in the request body.","operationId":"update_single_pay_api_company__company_id__pays__pay_id__put","parameters":[{"description":"The unique LP-generated ID of the company.","required":true,"schema":{"type":"integer","title":"Company Id","description":"The unique LP-generated ID of the company."},"example":1,"name":"company_id","in":"path"},{"description":"The unique LP-generated pay ID you want to update.","required":true,"schema":{"type":"integer","title":"Pay Id","description":"The unique LP-generated pay ID you want to update."},"example":42,"name":"pay_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PayUpdate"}],"title":"Pay Update","description":"The updated pay object."}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pay"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/company/{company_id}/create-workers-comp-pays":{"put":{"tags":["Pays"],"summary":"Create Workers Comp Pays For Date","description":"Create worker's compensation pays for a given date. This route is a custom route for a single client. For full pay creation use the /pays/create endpoint. The identifier_type query parameter can be used to specify whether the employee_ids are LP IDs (employee_id) or user-controlled payroll numbers (employee_number). If using the employee_number, please be aware that they must be unique across ALL companies.","operationId":"create_workers_comp_pays_for_date_api_company__company_id__create_workers_comp_pays_put","parameters":[{"description":"The unique LP-generated ID of the company.","required":true,"schema":{"type":"integer","title":"Company Id","description":"The unique LP-generated ID of the company."},"example":1,"name":"company_id","in":"path"},{"description":"Set to `True` to group pay results by pay run.","required":false,"schema":{"type":"boolean","title":"Group By Pay Run","description":"Set to `True` to group pay results by pay run.","default":false},"example":false,"name":"group_by_pay_run","in":"query"},{"description":"Set to `True` to group pay results by employee (using either employee_id or employee_number depending on identifier_type).","required":false,"schema":{"type":"boolean","title":"Group By Employee","description":"Set to `True` to group pay results by employee (using either employee_id or employee_number depending on identifier_type).","default":false},"example":false,"name":"group_by_employee","in":"query"},{"description":"Specify which employee identifier to use in 'workers_comp_pays' and when grouping pays by employee:\n- 'employee_id': Use LP-internal database IDs (integers).\n- 'employee_number': Use your own external employee numbers (strings).\nDefault is 'employee_id'. These must be unique for each employee across all companies.","required":false,"schema":{"type":"string","pattern":"^(employee_id|employee_number)$","title":"Identifier Type","description":"Specify which employee identifier to use in 'workers_comp_pays' and when grouping pays by employee:\n- 'employee_id': Use LP-internal database IDs (integers).\n- 'employee_number': Use your own external employee numbers (strings).\nDefault is 'employee_id'. These must be unique for each employee across all companies.","default":"employee_id"},"example":"employee_id","name":"identifier_type","in":"query"},{"description":"The date when these pays were processed, in `YYYY-MM-DD` format. Defaults to today if not provided.","required":false,"schema":{"type":"string","title":"Pay Date","description":"The date when these pays were processed, in `YYYY-MM-DD` format. Defaults to today if not provided.","default":"2026-07-25"},"example":"2024-07-01","name":"pay_date","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/NewWorkersCompensationPay"},"type":"array","title":"Workers Comp Pays","description":"A list of workers' compensation pay objects to create, which were paid or to be paid on the given date."},"example":[{"employee_id":"1","workers_compensation_amount":100.0,"tax":10.0},{"employee_id":"2","workers_compensation_amount":200.0,"tax":20.0}]}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"items":{"$ref":"#/components/schemas/EmployeeNumberPays"},"type":"array"},{"items":{"$ref":"#/components/schemas/EmployeeIDPays"},"type":"array"},{"items":{"$ref":"#/components/schemas/PayRunPays"},"type":"array"},{"items":{"$ref":"#/components/schemas/Pay"},"type":"array"}],"title":"Response Create Workers Comp Pays For Date Api Company  Company Id  Create Workers Comp Pays Put"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/company/{company_id}/update-workers-comp-pay/{pay_id}":{"patch":{"tags":["Pays"],"summary":"Update Workers Comp Pay","description":"Modify the value of a worker's compensation pay for a given date. This route is a custom route for a single client. For full pay creation use the /pays/create endpoint. The identifier_type query parameter can be used to specify whether the employee_ids are LP IDs (employee_id) or user-controlled payroll numbers (employee_number). If using the employee_number, please be aware that they must be unique across ALL companies.","operationId":"update_workers_comp_pay_api_company__company_id__update_workers_comp_pay__pay_id__patch","parameters":[{"description":"The unique LP-generated ID of the company.","required":true,"schema":{"type":"integer","title":"Company Id","description":"The unique LP-generated ID of the company."},"example":1,"name":"company_id","in":"path"},{"description":"The unique LP-generated ID of the pay object.","required":true,"schema":{"type":"integer","title":"Pay Id","description":"The unique LP-generated ID of the pay object."},"example":1,"name":"pay_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/NewWorkersCompensationPay"}],"title":"Workers Comp Pay","description":"A single compensation pay object with values to override and existing pay."},"example":{"employee_id":"1","workers_compensation_amount":100.0,"tax":10.0}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pay"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/pays/{pay_id}":{"delete":{"tags":["Pays"],"summary":"Delete Pay","description":"Delete a pay by ID. This action is irreversible. If the pay has STP history it cannot be deleted.","operationId":"delete_pay_api_pays__pay_id__delete","parameters":[{"description":"The unique LP-generated ID of the pay.","required":true,"schema":{"type":"integer","title":"Pay Id","description":"The unique LP-generated ID of the pay."},"example":1,"name":"pay_id","in":"path"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/company/{company_id}/unsubmitted-stp-pays":{"get":{"tags":["Single Touch"],"summary":"Get Unsubmitted Stp Pays","description":"AU only. Get all pays which either have not been STP-submitted or were unsuccessfully submitted to the ATO, within a given date range. Pay results can be grouped by pay run or employee, or neither (flat Pay list).","operationId":"get_unsubmitted_stp_pays_api_company__company_id__unsubmitted_stp_pays_get","parameters":[{"description":"The unique LP-generated ID of the company.","required":true,"schema":{"type":"integer","title":"Company Id","description":"The unique LP-generated ID of the company."},"example":1,"name":"company_id","in":"path"},{"description":"The start date of the search range in `YYYY-MM-DD` format. Defaults to today if not provided.","required":false,"schema":{"type":"string","title":"Start Date","description":"The start date of the search range in `YYYY-MM-DD` format. Defaults to today if not provided.","default":"2026-07-25"},"example":"2024-07-01","name":"start_date","in":"query"},{"description":"The end date of the search range in `YYYY-MM-DD` format. Defaults to today if not provided.","required":false,"schema":{"type":"string","title":"End Date","description":"The end date of the search range in `YYYY-MM-DD` format. Defaults to today if not provided.","default":"2026-07-25"},"example":"2025-06-30","name":"end_date","in":"query"},{"description":"Set to `True` to group pay results by pay run.","required":false,"schema":{"type":"boolean","title":"Group By Pay Run","description":"Set to `True` to group pay results by pay run.","default":false},"example":false,"name":"group_by_pay_run","in":"query"},{"description":"Set to `True` to group pay results by employee.","required":false,"schema":{"type":"boolean","title":"Group By Employee","description":"Set to `True` to group pay results by employee.","default":false},"example":false,"name":"group_by_employee","in":"query"},{"description":"Specify which employee identifier to return when grouping pays by employee:\n- 'employee_id': Use LP-internal database IDs (integers).\n- 'employee_number': Use your own external employee numbers (strings).\nDefault is 'employee_id'. These must be unique for each employee across all companies.","required":false,"schema":{"type":"string","pattern":"^(employee_id|employee_number)$","title":"Identifier Type","description":"Specify which employee identifier to return when grouping pays by employee:\n- 'employee_id': Use LP-internal database IDs (integers).\n- 'employee_number': Use your own external employee numbers (strings).\nDefault is 'employee_id'. These must be unique for each employee across all companies.","default":"employee_id"},"example":"employee_id","name":"identifier_type","in":"query"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/single-touch/{company_id}/submit-stp-pays":{"post":{"tags":["Single Touch"],"summary":"Submit Stp Pays","description":"AU only. Submit Single Touch for the given pay IDs. They must all share the same pay_run_id and only one pay_id per employee per submission is allowed.","operationId":"submit_stp_pays_api_single_touch__company_id__submit_stp_pays_post","parameters":[{"description":"The unique LP-generated ID of the company.","required":true,"schema":{"type":"integer","title":"Company Id","description":"The unique LP-generated ID of the company."},"example":1,"name":"company_id","in":"path"},{"description":"Set to `True` to group pay results by pay run.","required":false,"schema":{"type":"boolean","title":"Group By Pay Run","description":"Set to `True` to group pay results by pay run.","default":false},"example":false,"name":"group_by_pay_run","in":"query"},{"description":"Set to `True` to group pay results by employee.","required":false,"schema":{"type":"boolean","title":"Group By Employee","description":"Set to `True` to group pay results by employee.","default":false},"example":false,"name":"group_by_employee","in":"query"},{"description":"Set to `True` if this STP submission is an update event and only includes pre-submitted pay IDs.","required":false,"schema":{"type":"boolean","title":"Is Update Event","description":"Set to `True` if this STP submission is an update event and only includes pre-submitted pay IDs.","default":false},"example":false,"name":"is_update_event","in":"query"},{"description":"Specify which employee identifier to return when grouping pays by employee:\n- 'employee_id': Use LP-internal database IDs (integers).\n- 'employee_number': Use your own external employee numbers (strings).\nDefault is 'employee_id'. These must be unique for each employee across all companies.","required":false,"schema":{"type":"string","pattern":"^(employee_id|employee_number)$","title":"Identifier Type","description":"Specify which employee identifier to return when grouping pays by employee:\n- 'employee_id': Use LP-internal database IDs (integers).\n- 'employee_number': Use your own external employee numbers (strings).\nDefault is 'employee_id'. These must be unique for each employee across all companies.","default":"employee_id"},"example":"employee_id","name":"identifier_type","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"items":{"type":"integer"},"type":"array","title":"Pay IDs","description":"A list of pay IDs to submit to the ATO. They must all share the same pay_run_id and only one pay_id per employee per submission is allowed."},"example":[1,2,3]}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/single-touch/{company_id}/check-stp-responses":{"post":{"tags":["Single Touch"],"summary":"Check Stp Responses","description":"AU only. Force an ATO Single Touch response check for the given company and pay_ids and return pays.","operationId":"check_stp_responses_api_single_touch__company_id__check_stp_responses_post","parameters":[{"description":"The unique LP-generated ID of the company.","required":true,"schema":{"type":"integer","title":"Company Id","description":"The unique LP-generated ID of the company."},"example":1,"name":"company_id","in":"path"},{"description":"Set to `True` to group pay results by pay run.","required":false,"schema":{"type":"boolean","title":"Group By Pay Run","description":"Set to `True` to group pay results by pay run.","default":false},"example":false,"name":"group_by_pay_run","in":"query"},{"description":"Set to `True` to group pay results by employee.","required":false,"schema":{"type":"boolean","title":"Group By Employee","description":"Set to `True` to group pay results by employee.","default":false},"example":false,"name":"group_by_employee","in":"query"},{"description":"Specify which employee identifier to return when grouping pays by employee:\n- 'employee_id': Use LP-internal database IDs (integers).\n- 'employee_number': Use your own external employee numbers (strings).\nDefault is 'employee_id'. These must be unique for each employee across all companies.","required":false,"schema":{"type":"string","pattern":"^(employee_id|employee_number)$","title":"Identifier Type","description":"Specify which employee identifier to return when grouping pays by employee:\n- 'employee_id': Use LP-internal database IDs (integers).\n- 'employee_number': Use your own external employee numbers (strings).\nDefault is 'employee_id'. These must be unique for each employee across all companies.","default":"employee_id"},"example":"employee_id","name":"identifier_type","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"items":{"type":"integer"},"type":"array","title":"Pay Ids","description":"A list of pay IDs to gather STP response information about."},"example":[1,2,3]}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/init-api-client":{"get":{"tags":["Admin"],"summary":"Init Api Client","description":"Provision an OAuth client for the current customer.\nReturns the client secret only the first time (or when regenerated).","operationId":"init_api_client_api_init_api_client_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/update-api-client":{"post":{"tags":["Admin"],"summary":"Update Api Client","description":"Accepted keys in `payload`:\n  - redirect_uris: list[str]\n  - regenerate_secret: bool\n  - timezone: string (IANA timezone, e.g. \"UTC\" or \"Australia/Brisbane\")","operationId":"update_api_client_api_update_api_client_post","requestBody":{"content":{"application/json":{"schema":{"type":"object","title":"Payload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/api-client/whitelabel-logo":{"get":{"tags":["Admin"],"summary":"Get Api Client Whitelabel Logo","operationId":"get_api_client_whitelabel_logo_api_api_client_whitelabel_logo_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]},"post":{"tags":["Admin"],"summary":"Upload Api Client Whitelabel Logo","operationId":"upload_api_client_whitelabel_logo_api_api_client_whitelabel_logo_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_api_client_whitelabel_logo_api_api_client_whitelabel_logo_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]},"delete":{"tags":["Admin"],"summary":"Delete Api Client Whitelabel Logo","operationId":"delete_api_client_whitelabel_logo_api_api_client_whitelabel_logo_delete","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/api-client/whitelabel-style":{"get":{"tags":["Admin"],"summary":"Get Api Client Whitelabel Style","operationId":"get_api_client_whitelabel_style_api_api_client_whitelabel_style_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]},"post":{"tags":["Admin"],"summary":"Upload Api Client Whitelabel Style","operationId":"upload_api_client_whitelabel_style_api_api_client_whitelabel_style_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_api_client_whitelabel_style_api_api_client_whitelabel_style_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]},"delete":{"tags":["Admin"],"summary":"Delete Api Client Whitelabel Style","operationId":"delete_api_client_whitelabel_style_api_api_client_whitelabel_style_delete","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/api-client/whitelabel-dark-logo":{"get":{"tags":["Admin"],"summary":"Get Api Client Whitelabel Dark Logo","operationId":"get_api_client_whitelabel_dark_logo_api_api_client_whitelabel_dark_logo_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]},"post":{"tags":["Admin"],"summary":"Upload Api Client Whitelabel Dark Logo","operationId":"upload_api_client_whitelabel_dark_logo_api_api_client_whitelabel_dark_logo_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_api_client_whitelabel_dark_logo_api_api_client_whitelabel_dark_logo_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]},"delete":{"tags":["Admin"],"summary":"Delete Api Client Whitelabel Dark Logo","operationId":"delete_api_client_whitelabel_dark_logo_api_api_client_whitelabel_dark_logo_delete","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/api-client/whitelabel-favicon":{"get":{"tags":["Admin"],"summary":"Get Api Client Whitelabel Favicon","operationId":"get_api_client_whitelabel_favicon_api_api_client_whitelabel_favicon_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]},"post":{"tags":["Admin"],"summary":"Upload Api Client Whitelabel Favicon","operationId":"upload_api_client_whitelabel_favicon_api_api_client_whitelabel_favicon_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_api_client_whitelabel_favicon_api_api_client_whitelabel_favicon_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]},"delete":{"tags":["Admin"],"summary":"Delete Api Client Whitelabel Favicon","operationId":"delete_api_client_whitelabel_favicon_api_api_client_whitelabel_favicon_delete","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/api-client/whitelabel-banner":{"get":{"tags":["Admin"],"summary":"Get Api Client Whitelabel Banner","operationId":"get_api_client_whitelabel_banner_api_api_client_whitelabel_banner_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]},"post":{"tags":["Admin"],"summary":"Upload Api Client Whitelabel Banner","operationId":"upload_api_client_whitelabel_banner_api_api_client_whitelabel_banner_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_api_client_whitelabel_banner_api_api_client_whitelabel_banner_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]},"delete":{"tags":["Admin"],"summary":"Delete Api Client Whitelabel Banner","operationId":"delete_api_client_whitelabel_banner_api_api_client_whitelabel_banner_delete","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/api-client/email-domain":{"get":{"tags":["Admin"],"summary":"Get Api Client Email Domain","operationId":"get_api_client_email_domain_api_api_client_email_domain_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]},"post":{"tags":["Admin"],"summary":"Set Api Client Email Domain","description":"Configure (or replace) the reseller's whitelabel sending domain. Registers\nit with Mailgun and returns the DNS records the reseller must publish. The\ndomain stays ``pending`` until verified, so sends keep falling back to the\nLightning Payroll sender until then.","operationId":"set_api_client_email_domain_api_api_client_email_domain_post","requestBody":{"content":{"application/json":{"schema":{"type":"object","title":"Payload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]},"delete":{"tags":["Admin"],"summary":"Delete Api Client Email Domain","operationId":"delete_api_client_email_domain_api_api_client_email_domain_delete","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/api-client/email-domain/verify":{"post":{"tags":["Admin"],"summary":"Verify Api Client Email Domain","description":"Ask Mailgun to re-check the domain's DNS now and update our status.","operationId":"verify_api_client_email_domain_api_api_client_email_domain_verify_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/api-client/email-domain/test":{"post":{"tags":["Admin"],"summary":"Send Api Client Email Domain Test","description":"Send a test email through the verified sending domain to the api-admin's\nown address, so they can confirm branded delivery end-to-end.","operationId":"send_api_client_email_domain_test_api_api_client_email_domain_test_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/faqs":{"get":{"tags":["FAQs"],"summary":"List published FAQs (knowledge base articles)","description":"List active FAQ knowledge-base articles for API-admin clients.\n\nScoped to the requested ``site_mode`` (``au`` or ``nz``). Optionally filter by ``category``\n(case-insensitive exact match) or ``search`` (case-insensitive substring over heading and message).\n\nThe ``format`` parameter controls how the FAQ body HTML is rendered:\n\n- ``raw`` (default) — original HTML returned byte-for-byte; caller is responsible for sanitisation.\n- ``sanitized`` — bleach-cleaned to a safe HTML subset; scripts, event handlers, and ``javascript:``\n  URLs are stripped.\n- ``text`` — all tags stripped; plain text suitable for previews or search indexing.\n\nResults are ordered by ``last_edited`` descending (most recently edited first), with ``id``\ndescending as a stable tiebreak. Use ``limit`` / ``offset`` for pagination; ``total`` in the\nresponse reflects the full unpaginated match count.","operationId":"list_faqs_api_faqs_get","parameters":[{"description":"Region scope for FAQs. One of 'au' or 'nz'.","required":false,"schema":{"type":"string","enum":["au","nz"],"title":"Site Mode","description":"Region scope for FAQs. One of 'au' or 'nz'.","default":"au"},"example":"au","name":"site_mode","in":"query"},{"description":"Optional exact category filter (case-insensitive).","required":false,"schema":{"type":"string","title":"Category","description":"Optional exact category filter (case-insensitive)."},"example":"Single Touch Payroll","name":"category","in":"query"},{"description":"Optional case-insensitive substring match against heading and message.","required":false,"schema":{"type":"string","maxLength":128,"title":"Search","description":"Optional case-insensitive substring match against heading and message."},"example":"payday filing","name":"search","in":"query"},{"description":"How to render the FAQ body. 'raw' = original HTML, 'text' = HTML stripped to plain text, 'sanitized' = safe HTML subset.","required":false,"schema":{"type":"string","enum":["raw","text","sanitized"],"title":"Format","description":"How to render the FAQ body. 'raw' = original HTML, 'text' = HTML stripped to plain text, 'sanitized' = safe HTML subset.","default":"raw"},"example":"raw","name":"format","in":"query"},{"description":"Maximum FAQs to return.","required":false,"schema":{"type":"integer","maximum":200.0,"minimum":1.0,"title":"Limit","description":"Maximum FAQs to return.","default":50},"example":50,"name":"limit","in":"query"},{"description":"Number of FAQs to skip (for pagination).","required":false,"schema":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of FAQs to skip (for pagination).","default":0},"example":0,"name":"offset","in":"query"}],"responses":{"200":{"description":"Active FAQs for the requested site mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FaqListResponse"}}}},"404":{"description":"Not found"},"403":{"description":"Forbidden: caller is not an API admin."},"422":{"description":"Invalid query parameter value."}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/partner-checkout/options":{"get":{"tags":["Admin"],"summary":"List partner checkout product options","description":"Return the currently valid partner-checkout subscription and add-on products for the authenticated\ngroup-9 API-admin customer.\n\nUse this before checkout requests so product IDs, per-employee rules, and add-on availability do\nnot need to be hard-coded by the integrator.","operationId":"get_partner_checkout_options_api_partner_checkout_options_get","responses":{"200":{"description":"Partner checkout options for the authenticated API-admin referrer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCheckoutOptionsResponse"}}}},"404":{"description":"Not found"},"403":{"description":"Forbidden: caller is not a group-9 API admin or lacks the required scope"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/partner-checkout/availability":{"get":{"tags":["Admin"],"summary":"Check partner checkout availability for email, ABN, or IRD","description":"Check whether one or more proposed identifiers are already in use before calling the main\npartner-checkout order endpoint.\n\nYou can supply any combination of `email`, `abn`, and `irdNumber` in one request.","operationId":"get_partner_checkout_availability_api_partner_checkout_availability_get","parameters":[{"description":"Customer email to check.","required":false,"schema":{"type":"string","title":"Email","description":"Customer email to check."},"example":"alice@example.com","name":"email","in":"query"},{"description":"ABN to check.","required":false,"schema":{"type":"string","title":"Abn","description":"ABN to check."},"example":"10000000000","name":"abn","in":"query"},{"description":"Employer IRD number to check.","required":false,"schema":{"type":"string","title":"Irdnumber","description":"Employer IRD number to check."},"example":"49091850","name":"irdNumber","in":"query"}],"responses":{"200":{"description":"Availability check results for the provided identifiers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCheckoutAvailabilityResponse"}}}},"404":{"description":"Not found"},"403":{"description":"Forbidden: caller is not a group-9 API admin or lacks the required scope"},"422":{"description":"No identifiers were provided"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/partner-checkout/zones":{"get":{"tags":["Admin"],"summary":"List allowed countries and their states/regions for partner checkout","description":"Return the allowed countries and their states/regions for partner checkout billing addresses.\n\nUse the returned `zone_code` values when constructing `billing_address.zone_code` in checkout requests.","operationId":"get_partner_checkout_zones_api_partner_checkout_zones_get","responses":{"200":{"description":"Allowed countries (AU, NZ) with their states/regions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCheckoutZonesResponse"}}}},"404":{"description":"Not found"},"403":{"description":"Forbidden: caller is not a group-9 API admin or lacks the required scope"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/partner-checkout/orders":{"get":{"tags":["Admin"],"summary":"List partner checkout orders you generated","description":"Paginated list of partner-checkout orders generated by this API admin, newest-first.","operationId":"list_partner_checkout_orders_api_partner_checkout_orders_get","parameters":[{"description":"Filter by order_status_id (e.g. 5 = completed, 7 = cancelled).","required":false,"schema":{"type":"integer","minimum":0.0,"title":"Status","description":"Filter by order_status_id (e.g. 5 = completed, 7 = cancelled)."},"name":"status","in":"query"},{"description":"Maximum number of results to return.","required":false,"schema":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","description":"Maximum number of results to return.","default":25},"name":"limit","in":"query"},{"description":"Number of results to skip.","required":false,"schema":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of results to skip.","default":0},"name":"offset","in":"query"}],"responses":{"200":{"description":"Paginated list of partner-checkout orders generated by this API admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCheckoutOrderListResponse"}}}},"404":{"description":"Not found"},"403":{"description":"Forbidden: caller is not a group-9 API admin or lacks the required scope."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]},"post":{"tags":["Admin"],"summary":"Preview or execute a partner checkout order","description":"Create a new customer, billed-account order, and initial subscription for an authenticated\ngroup-9 API-admin partner.\n\nRecommended sequence:\n1. `GET /api/partner-checkout/options`\n2. `POST /api/partner-checkout/orders` with `dry_run=true`\n3. Repeat the same payload with `dry_run=false` and an `Idempotency-Key` header","operationId":"create_partner_checkout_order_api_partner_checkout_orders_post","parameters":[{"description":"Required for non-dry-run requests. Reuse the same key to safely retry the same execution request.","required":false,"schema":{"type":"string","title":"Idempotency-Key","description":"Required for non-dry-run requests. Reuse the same key to safely retry the same execution request."},"name":"Idempotency-Key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCheckoutRequest"}}},"required":true},"responses":{"200":{"description":"Validated preview or completed partner checkout order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCheckoutResponse"}}}},"404":{"description":"Not found"},"400":{"description":"Invalid product combination, missing idempotency key, or other bad request"},"403":{"description":"Forbidden: caller is not a group-9 API admin or lacks the required scope"},"409":{"description":"Duplicate email/ABN/IRD, or reused Idempotency-Key with a different payload"},"422":{"description":"Payload validation error"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/partner-checkout/upgrades":{"post":{"tags":["Admin"],"summary":"Preview or execute a partner-driven subscription upgrade","description":"Upgrade an existing customer subscription that this API admin originally onboarded.\n\nMirrors `payroll_web/catalog/view/theme/payroll/template/checkout/store.tpl`'s three upgrade modes:\n\n- **`order.mode = \"addon\"`** — leave the existing base subscription and its add-ons untouched; bolt\n  on one or more new add-ons priced prorata to the existing subscription's remaining term. No new\n  subscription row is created; new `subscription_add_on` rows are attached to the existing sub.\n\n- **`order.mode = \"base\"`** — replace the existing base subscription with `new_product_id`. The\n  remaining inc-tax value of the existing base + eligible add-ons is applied as a single\n  `upgrade_credit` line on the new order. The existing subscription's `renewal_id` is set to point\n  at the new subscription. Existing add-ons are **not** carried over unless re-listed in\n  `add_on_product_ids`.\n\n- **`order.mode = \"both\"`** — same as `base`, but the partner also picks the full final add-on set\n  for the new subscription.\n\nRecommended sequence:\n1. `GET /api/partner-checkout/options` (browse subscription/add-on products)\n2. `GET /api/partner-checkout/orders/{order_id}` (recover the `subscription_id` of the target sub)\n3. `POST /api/partner-checkout/upgrades` with `dry_run=true` to preview totals\n4. Repeat with `dry_run=false` and an `Idempotency-Key` header\n\nConstraints:\n- Welcome-offer promos are never applied on upgrades (mirrors PHP behavior).\n- Downgrades (where the new order value ≤ existing credit + $0.009 inc-tax) are rejected with 400.\n- Upgrading an already-expired subscription returns 409 — onboard a fresh subscription via\n  `POST /api/partner-checkout/orders` instead.\n- The mandatory training session product is **not** appended on upgrade orders.\n- The 60-day cancel window on the new upgrade order is calculated from the existing customer's\n  original `date_added`, not from the upgrade order's own date.","operationId":"create_partner_checkout_upgrade_api_partner_checkout_upgrades_post","parameters":[{"description":"Required for non-dry-run requests. Reuse the same key to safely retry the same upgrade.","required":false,"schema":{"type":"string","title":"Idempotency-Key","description":"Required for non-dry-run requests. Reuse the same key to safely retry the same upgrade."},"name":"Idempotency-Key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCheckoutUpgradeRequest"}}},"required":true},"responses":{"200":{"description":"Validated preview or completed partner upgrade order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCheckoutUpgradeResponse"}}}},"404":{"description":"Target subscription not found."},"400":{"description":"Invalid mode/field combination, downgrade attempt, or other bad request."},"403":{"description":"Forbidden: caller is not a group-9 API admin, lacks the required scope, or did not onboard the target subscription."},"409":{"description":"Subscription already renewed/upgraded, already expired, or Idempotency-Key reused with different payload."},"422":{"description":"Payload validation error."}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/partner-checkout/orders/cancel":{"post":{"tags":["Admin"],"summary":"Cancel a partner checkout order generated by this API admin","description":"Cancel an order that the authenticated group-9 API-admin partner previously generated via\n`POST /api/partner-checkout/orders`.\n\nRequires `partner.checkout.cancel` (preferred) or `partner.checkout.write` and must target\nan order this partner generated.\nOrders are only cancellable within 60 days of the customer being added.\n\nSets `order.order_status_id = 7` and appends an `order_history` note explaining the cancellation.","operationId":"cancel_partner_checkout_order_api_partner_checkout_orders_cancel_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCheckoutCancelOrderRequest"}}},"required":true},"responses":{"200":{"description":"Order was cancelled. order_status_id is set to 7.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCheckoutCancelOrderResponse"}}}},"404":{"description":"Order not found."},"403":{"description":"Forbidden: caller is not a group-9 API admin, lacks the required scope, or did not generate the order."},"409":{"description":"Order is already cancelled, or past the 60-day cancellation window."},"422":{"description":"Payload validation error."}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/partner-checkout/orders/{order_id}":{"get":{"tags":["Admin"],"summary":"Look up a partner checkout order you generated","description":"Return the current status, totals, subscription, and order_history for a partner-checkout order\nthis API admin previously generated.","operationId":"get_partner_checkout_order_api_partner_checkout_orders__order_id__get","parameters":[{"description":"The order.order_id to look up.","required":true,"schema":{"type":"integer","exclusiveMinimum":0.0,"title":"Order Id","description":"The order.order_id to look up."},"example":192484,"name":"order_id","in":"path"}],"responses":{"200":{"description":"Order details including current status, subscription, and history.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCheckoutOrderDetailResponse"}}}},"404":{"description":"Order not found."},"403":{"description":"Forbidden: caller is not a group-9 API admin, lacks the required scope, or did not generate the order."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/partner-checkout/orders/{order_id}/resend-onboarding-link":{"post":{"tags":["Admin"],"summary":"Resend a customer's OAuth magic onboarding link","description":"Re-issue and email a fresh single-use OAuth magic onboarding link to the customer created by a\npartner-checkout order this API admin generated.\n\nUse when the original 24-hour link expired before the customer used it. Requires\n`partner.checkout.write`, and that the customer was originally provisioned with `oauth_onboarding`\nand has not yet completed onboarding. Supply the same `oauth_onboarding` block as the original order\n(it is re-validated against your current OAuth client). Any previously issued, unused link is\ninvalidated. The link itself is emailed only to the customer and is never returned.","operationId":"resend_partner_checkout_onboarding_link_api_partner_checkout_orders__order_id__resend_onboarding_link_post","parameters":[{"description":"The order.order_id whose customer should be re-sent their onboarding link.","required":true,"schema":{"type":"integer","exclusiveMinimum":0.0,"title":"Order Id","description":"The order.order_id whose customer should be re-sent their onboarding link."},"example":192484,"name":"order_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCheckoutResendOnboardingRequest"}}},"required":true},"responses":{"200":{"description":"A fresh single-use magic onboarding link was emailed to the customer. The link is never returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCheckoutResendOnboardingResponse"}}}},"404":{"description":"Order or customer not found."},"400":{"description":"oauth_onboarding is missing or no longer valid against your OAuth client."},"403":{"description":"Forbidden: caller is not a group-9 API admin, lacks partner.checkout.write, or did not generate the order."},"409":{"description":"Customer was not OAuth-onboarded, or has already completed onboarding."},"502":{"description":"The onboarding email could not be sent; no new link was issued."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/api-client/overview":{"get":{"tags":["Admin"],"summary":"Get Api Client Overview","operationId":"get_api_client_overview_api_api_client_overview_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/api-client/connections":{"get":{"tags":["Admin"],"summary":"List Api Client Connections","operationId":"list_api_client_connections_api_api_client_connections_get","parameters":[{"description":"Filter connections by status.","required":false,"schema":{"type":"string","enum":["all","active","inactive"],"title":"Status","description":"Filter connections by status.","default":"all"},"name":"status","in":"query"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/api-client/connections/{customer_id}":{"delete":{"tags":["Admin"],"summary":"Revoke Api Client Connection","operationId":"revoke_api_client_connection_api_api_client_connections__customer_id__delete","parameters":[{"description":"Customer ID to revoke access for.","required":true,"schema":{"type":"integer","title":"Customer Id","description":"Customer ID to revoke access for."},"name":"customer_id","in":"path"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/api-client/activity":{"get":{"tags":["Admin"],"summary":"Get Api Client Activity","operationId":"get_api_client_activity_api_api_client_activity_get","parameters":[{"description":"Optional customer filter.","required":false,"schema":{"type":"integer","title":"Customer Id","description":"Optional customer filter."},"name":"customer_id","in":"query"},{"description":"Maximum activity entries to return.","required":false,"schema":{"type":"integer","maximum":250.0,"minimum":1.0,"title":"Limit","description":"Maximum activity entries to return.","default":50},"name":"limit","in":"query"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/api-client/errors":{"get":{"tags":["Admin"],"summary":"Get Api Client Errors","operationId":"get_api_client_errors_api_api_client_errors_get","parameters":[{"description":"Optional customer filter.","required":false,"schema":{"type":"integer","title":"Customer Id","description":"Optional customer filter."},"name":"customer_id","in":"query"},{"description":"Maximum error entries to return.","required":false,"schema":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Limit","description":"Maximum error entries to return.","default":100},"name":"limit","in":"query"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/employees/{employee_id}/bank-accounts":{"get":{"tags":["Employee"],"summary":"Get Employee Bank Accounts","description":"Get employee bank accounts by Lightning Payroll Employee ID.","operationId":"get_employee_bank_accounts_api_employees__employee_id__bank_accounts_get","parameters":[{"description":"The unique LP-generated ID of the employee.","required":true,"schema":{"type":"integer","title":"Employee Id","description":"The unique LP-generated ID of the employee."},"example":1,"name":"employee_id","in":"path"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{},"type":"array","title":"Response Get Employee Bank Accounts Api Employees  Employee Id  Bank Accounts Get"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/employees/{employee_id}/bank-accounts/{bank_account_id}":{"delete":{"tags":["Employee"],"summary":"Delete Employee Bank Account","description":"Delete a specific bank account for an employee by account ID.","operationId":"delete_employee_bank_account_api_employees__employee_id__bank_accounts__bank_account_id__delete","parameters":[{"description":"The unique LP-generated ID of the employee.","required":true,"schema":{"type":"integer","title":"Employee Id","description":"The unique LP-generated ID of the employee."},"example":1,"name":"employee_id","in":"path"},{"description":"The unique ID of the bank account to delete.","required":true,"schema":{"type":"integer","title":"Bank Account Id","description":"The unique ID of the bank account to delete."},"example":123,"name":"bank_account_id","in":"path"}],"responses":{"204":{"description":"Successful Response"},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/employees/{employee_id}/super-funds":{"get":{"tags":["Employee"],"summary":"Get Employee Super Funds","description":"AU only. Get employee super fund information by Lightning Payroll Employee ID.","operationId":"get_employee_super_funds_api_employees__employee_id__super_funds_get","parameters":[{"description":"The unique LP-generated ID of the employee.","required":true,"schema":{"type":"integer","title":"Employee Id","description":"The unique LP-generated ID of the employee."},"example":1,"name":"employee_id","in":"path"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{},"type":"array","title":"Response Get Employee Super Funds Api Employees  Employee Id  Super Funds Get"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/employees/{employee_id}/super-funds/{super_fund_id}":{"delete":{"tags":["Employee"],"summary":"Delete Employee Super Fund","description":"AU only. Delete an employee super fund by its ID and associated Lightning Payroll Employee ID.","operationId":"delete_employee_super_fund_api_employees__employee_id__super_funds__super_fund_id__delete","parameters":[{"description":"The unique LP-generated ID of the employee.","required":true,"schema":{"type":"integer","title":"Employee Id","description":"The unique LP-generated ID of the employee."},"example":1,"name":"employee_id","in":"path"},{"description":"The unique ID of the employee super fund to be deleted.","required":true,"schema":{"type":"integer","title":"Super Fund Id","description":"The unique ID of the employee super fund to be deleted."},"example":10,"name":"super_fund_id","in":"path"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/api/public-branding":{"get":{"tags":["Authentication"],"summary":"Fetch public branding for unauthenticated flows","operationId":"public_branding_api_public_branding_get","parameters":[{"description":"OAuth client ID for partner login flows","required":false,"schema":{"type":"string","title":"Client Id","description":"OAuth client ID for partner login flows"},"name":"client_id","in":"query"},{"description":"Public branding token for partner-branded public pages","required":false,"schema":{"type":"string","title":"Branding Token","description":"Public branding token for partner-branded public pages"},"name":"branding_token","in":"query"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/public-branding/logo":{"get":{"tags":["Authentication"],"summary":"Fetch a public branding logo","operationId":"public_branding_logo_api_public_branding_logo_get","parameters":[{"required":false,"schema":{"type":"string","title":"Client Id"},"name":"client_id","in":"query"},{"required":false,"schema":{"type":"string","title":"Branding Token"},"name":"branding_token","in":"query"},{"description":"Set to 'dark' for the dark mode logo, 'favicon' for the favicon, or 'banner' for the email banner","required":false,"schema":{"type":"string","title":"Mode","description":"Set to 'dark' for the dark mode logo, 'favicon' for the favicon, or 'banner' for the email banner"},"name":"mode","in":"query"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/oauth/authorize":{"get":{"tags":["Authentication"],"summary":"Starts the OAuth 2.0 Authorization Code Flow (302 redirect to sign-in/consent screen)","description":"Redirects the user to the front-end login/consent page to initiate the OAuth 2.0 Authorization Code flow.\n\nThis endpoint:\n- Validates the `client_id` and `redirect_uri` (must be URL-encoded per RFC 3986).\n- Ensures the owning customer has API admin privileges.\n- Stores a unique internal `state`.\n- Issues an HTTP 302 redirect to the front-end with OAuth parameters.\n\n**Note:** When redirecting, ensure your application URL-encodes the `redirect_uri` parameter (e.g., `https%3A%2F%2Fyourapp.com%2Foauth%2Fcallback`).\n\nUpon successful interaction, the front-end will obtain a one-time-use `code` (valid for 10 minutes) and return it to your `redirect_uri` as `?code=...&state=...`.","operationId":"oauth_authorize_api_oauth_authorize_get","parameters":[{"name":"client_id","in":"query","required":true,"schema":{"title":"Client Id","description":"Unique client ID issued to the API consumer.","examples":{"client_id":{"summary":"Example Client ID","value":"abc123xyz"}},"type":"string"},"description":"Unique client ID issued to the API consumer."},{"name":"redirect_uri","in":"query","required":true,"schema":{"title":"Redirect Uri","description":"Callback URI where the authorization code is sent. Must be URL-encoded according to RFC 3986.","examples":{"redirect_uri":{"summary":"Example Redirect URI (URL-encoded)","value":"https%3A%2F%2Fyourapp.com%2Foauth%2Fcallback"}},"type":"string"},"description":"Callback URI where the authorization code is sent. Must be URL-encoded according to RFC 3986."},{"name":"state","in":"query","required":true,"schema":{"title":"State","description":"Opaque value to maintain state between the request and callback. Returned unchanged by the authorization server.","examples":{"state":{"summary":"Example State Value","value":"xyz456customstate"}},"type":"string"},"description":"Opaque value to maintain state between the request and callback. Returned unchanged by the authorization server."},{"name":"scope","in":"query","required":false,"schema":{"title":"Scope","description":"Space-delimited list of scopes requested by the client. Required: `openid`. Other scopes: `payroll.read`, `payroll.write`, `mcp.read`.","default":"openid","examples":{"openid_only":{"summary":"Default identity scope","value":"openid"},"openid_with_write":{"summary":"Include write access","value":"openid payroll.write"},"mcp":{"summary":"MCP read-only","value":"openid mcp.read"}},"type":"string"},"description":"Space-delimited list of scopes requested by the client. Required: `openid`. Other scopes: `payroll.read`, `payroll.write`, `mcp.read`."},{"name":"code_challenge","in":"query","required":false,"schema":{"title":"Code Challenge","description":"PKCE code challenge (RFC 7636). Required for public clients (e.g. Claude MCP).","type":"string"},"description":"PKCE code challenge (RFC 7636). Required for public clients (e.g. Claude MCP)."},{"name":"code_challenge_method","in":"query","required":false,"schema":{"title":"Code Challenge Method","description":"PKCE method. Only 'S256' is accepted.","type":"string"},"description":"PKCE method. Only 'S256' is accepted."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"302":{"description":"Redirect to front-end login/consent screen"},"400":{"description":"Invalid `client_id` or `redirect_uri`"},"403":{"description":"Forbidden: Customer lacks API admin privileges"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/oauth/token":{"post":{"tags":["Authentication"],"summary":"OAuth 2.0 token exchange","description":"Exchange an **authorization code** *or* **refresh token** for a fresh pair of tokens.\n\n## Typical workflow\n1. **End-user login** ➡️ you redirect to `/oauth/authorize`.\n2. You receive `?code=…` on your `redirect_uri`.\n3. POST the `code` here with `grant_type=authorization_code` to obtain:\n   * a short-lived **JWT access token** (`access_token`)\n   * a long-lived **opaque refresh token** (`refresh_token`)\n4. When the access token expires, call this endpoint again\n   (`grant_type=refresh_token`) with the stored `refresh_token`.\n\n## Scopes\nThe access token inherits the scope granted during the original\nauthorization request. Request narrower scopes – e.g. `payroll.read` – to\nfollow the principle of least privilege.\n\n## Security recommendations for partners\n* **Always** transmit `client_secret` over TLS (HTTPS).\n* Store **refresh tokens** server-side only; treat them like passwords.\n* Rotate refresh tokens **immediately** after use (this endpoint does it for you).\n* Use the `expires_in` field to schedule token renewal **before** expiry.\n* Treat the access token as a bearer token; do not depend on undocumented JWT claims.\n\n## Error handling\n* `400 Bad Request` – missing params, invalid `grant_type`, code expired, etc.\n* `401 Unauthorized` – bad `client_id`/`client_secret`.\n* `404 Not Found` – customer linked to the token no longer exists.\n\n---\n\n**Notes for Lightning Payroll internal maintainers**\n\n* Client secrets are stored **bcrypt-hashed** and compared constant-time.\n* Authorization codes & refresh tokens are **SHA-256** hashed in DB.\n* Refresh-token rotation is **single-use** (row marked `revoked=True`).\n* Access tokens are generated via `security.refresh_access_token`.","operationId":"oauth_token_api_oauth_token_post","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Body_oauth_token_api_oauth_token_post"}}},"required":true},"responses":{"200":{"description":"Access token + new refresh token issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"404":{"description":"Referenced customer not found"},"400":{"description":"Malformed request, missing/invalid parameters"},"401":{"description":"Invalid `client_id` / `client_secret` combination"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health_check":{"get":{"tags":["Public","API Health"],"summary":"Health Check","operationId":"health_check_health_check_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}}}},"/admin/upsell/surfaces":{"get":{"tags":["Admin","Upsell"],"summary":"List Surfaces","operationId":"list_surfaces_admin_upsell_surfaces_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]},"post":{"tags":["Admin","Upsell"],"summary":"Upsert Surface","description":"Create or update one surface row.","operationId":"upsert_surface_admin_upsell_surfaces_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/admin/upsell/surfaces/toggle":{"post":{"tags":["Admin","Upsell"],"summary":"Toggle Surface","description":"Single-shot flag flip.","operationId":"toggle_surface_admin_upsell_surfaces_toggle_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/admin/upsell/metrics":{"get":{"tags":["Admin","Upsell"],"summary":"Get Metrics","description":"Per-surface impressions / clicks / purchases / attach rate / revenue.","operationId":"get_metrics_admin_upsell_metrics_get","parameters":[{"required":false,"schema":{"type":"integer","title":"Since Days","default":30},"name":"since_days","in":"query"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"OAuth2PasswordBearer":[]},{"HTTPBearer":[]}]}},"/.well-known/oauth-protected-resource":{"get":{"tags":["MCP"],"summary":"MCP protected resource metadata (RFC 9728)","description":"Tells Claude which authorization server protects /mcp.","operationId":"oauth_protected_resource__well_known_oauth_protected_resource_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/oauth-protected-resource/mcp":{"get":{"tags":["MCP"],"summary":"MCP protected resource metadata, resource-specific path (RFC 9728)","description":"Mirror of the base path so clients that look up\n``/.well-known/oauth-protected-resource/<resource_path>`` first\n(per RFC 9728 section 3) get the same payload.","operationId":"oauth_protected_resource_for_mcp__well_known_oauth_protected_resource_mcp_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/oauth-authorization-server":{"get":{"tags":["MCP"],"summary":"OAuth authorization server metadata (RFC 8414)","description":"Advertises the existing LP OAuth flow as the AS for Claude's PKCE.\n\nThe /oauth/* endpoints live under the /api router prefix — that's where\nthe partner OAuth flow has always shipped, so we point Claude there\nrather than adding unprefixed aliases.","operationId":"oauth_authorization_server__well_known_oauth_authorization_server_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/oauth/register":{"get":{"tags":["MCP"],"summary":"DCR endpoint info (GET probe target for some clients)","description":"Some OAuth clients (Claude.ai included) probe the registration\nendpoint with GET before POSTing, and treat a 405 as 'endpoint is\nbroken'. Return a small advisory payload so the probe succeeds and\nthe client proceeds with POST.","operationId":"oauth_register_info_api_oauth_register_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"tags":["MCP"],"summary":"Dynamic Client Registration (RFC 7591) for MCP clients","description":"RFC 7591 endpoint -- validates-and-echoes only; does NOT mutate state.\n\nEvery MCP client shares the pre-seeded ``claude-mcp`` client_id. The\ncanonical callback list is baked into the seeded row by the\nmigration. This endpoint accepts a registration request, verifies the\nsubmitted ``redirect_uris`` are exact matches of the canonical set,\nand echoes the RFC 7591 response without writing to the database.\n\nWhy no-mutation: an unauthenticated DCR endpoint that persisted\narbitrary caller-supplied redirect_uris to the shared client row\nallowed a pre-seeded-loopback phishing chain (RFC 8252 7.3 anti-\npattern). Loopback URIs for Claude Desktop are accepted at\n/api/oauth/authorize time via :func:`is_ephemeral_loopback_redirect_uri`,\nbound to a single in-flight authorize state, not persisted.","operationId":"oauth_register_api_oauth_register_post","requestBody":{"content":{"application/json":{"schema":{"type":"object","title":"Payload"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"BackPayments":{"properties":{"description":{"type":"string","maxLength":60,"minLength":1,"title":"Description","description":"A brief description of the back payment. Required when creating a new back payment.","example":"Back Pay Adjustment"},"amount":{"type":"number","title":"Amount","description":"The dollar amount for the back payment. Required when creating a new back payment.","example":"200.00"},"stp_category":{"type":"string","title":"Stp Category","description":"The back payment category code (use underscores). Codes are required when creating a new back payment. Codes: BONUS_COMMISSION_NON_DIRECTOR_S_FEES, DIRECTOR_S_FEES, GROSS, ITEMISED_ALLOWANCESAD, ITEMISED_ALLOWANCESCD, ITEMISED_ALLOWANCESKN, ITEMISED_ALLOWANCESLD, ITEMISED_ALLOWANCESMD, ITEMISED_ALLOWANCESOD, ITEMISED_ALLOWANCESQN, ITEMISED_ALLOWANCESRD, ITEMISED_ALLOWANCESTD, LEAVEA, LEAVEC, LEAVEO, LEAVEP, LEAVEU, LEAVEW, OVERTIME, UNCLASSIFIED.","example":"GROSS"},"tax_method":{"type":"string","title":"Tax Method","description":"The tax method applied to the back payment.Required when creating a new back payment.Allowed codes with labels: NORMAL_EARNINGS = As normal earnings; SPREAD_OVER_SPECIFIC_RANGE = Use date range; SPREAD_OVER_FINANCIAL_YEAR = Over this financial year; METHOD_A_WHOLE_YEAR = Method A (Whole Year); METHOD_A_SPECIFIC_RANGE = Method A (Use Date Range); METHOD_B1 = Method B(i)(Use Date Range); METHOD_B2 = Method B(ii)(Whole Year).","example":"NORMAL_EARNINGS"},"start_date":{"type":"string","format":"date","title":"Start Date","description":"The start date for the back payment period.","example":"2023-01-01"},"end_date":{"type":"string","format":"date","title":"End Date","description":"The end date for the back payment period.","example":"2023-01-31"}},"additionalProperties":false,"type":"object","required":["description","amount"],"title":"BackPayments"},"Body_oauth_token_api_oauth_token_post":{"properties":{"grant_type":{"type":"string","enum":["authorization_code","refresh_token"],"title":"Grant Type","description":"OAuth 2.0 grant type to use. `authorization_code` ▶ exchange an auth-code; `refresh_token` ▶ rotate an existing refresh token."},"code":{"type":"string","title":"Code","description":"Authorization **code** obtained from `/oauth/authorize`. Required when `grant_type=authorization_code`."},"refresh_token":{"type":"string","title":"Refresh Token","description":"Existing refresh token. Required when `grant_type=refresh_token`."},"client_id":{"type":"string","title":"Client Id","description":"Public identifier for your integration, supplied during app registration."},"client_secret":{"type":"string","title":"Client Secret","description":"Confidential secret linked to `client_id`. **Transmitted in the request body** – never log or expose this value. Omit for public PKCE clients (Claude MCP)."},"redirect_uri":{"type":"string","title":"Redirect Uri","description":"Must exactly match the `redirect_uri` used when the authorization code was issued. Required for `grant_type=authorization_code`. HTTPS required in production."},"code_verifier":{"type":"string","title":"Code Verifier","description":"PKCE verifier (RFC 7636). Required when the `code` was issued with a `code_challenge`."}},"type":"object","required":["grant_type","client_id"],"title":"Body_oauth_token_api_oauth_token_post"},"Body_upload_api_client_whitelabel_banner_api_api_client_whitelabel_banner_post":{"properties":{"file":{"type":"string","format":"binary","title":"File"},"overwrite_existing":{"type":"boolean","title":"Overwrite Existing","default":false}},"type":"object","required":["file"],"title":"Body_upload_api_client_whitelabel_banner_api_api_client_whitelabel_banner_post"},"Body_upload_api_client_whitelabel_dark_logo_api_api_client_whitelabel_dark_logo_post":{"properties":{"file":{"type":"string","format":"binary","title":"File"},"overwrite_existing":{"type":"boolean","title":"Overwrite Existing","default":false}},"type":"object","required":["file"],"title":"Body_upload_api_client_whitelabel_dark_logo_api_api_client_whitelabel_dark_logo_post"},"Body_upload_api_client_whitelabel_favicon_api_api_client_whitelabel_favicon_post":{"properties":{"file":{"type":"string","format":"binary","title":"File"},"overwrite_existing":{"type":"boolean","title":"Overwrite Existing","default":false}},"type":"object","required":["file"],"title":"Body_upload_api_client_whitelabel_favicon_api_api_client_whitelabel_favicon_post"},"Body_upload_api_client_whitelabel_logo_api_api_client_whitelabel_logo_post":{"properties":{"file":{"type":"string","format":"binary","title":"File"},"overwrite_existing":{"type":"boolean","title":"Overwrite Existing","default":false}},"type":"object","required":["file"],"title":"Body_upload_api_client_whitelabel_logo_api_api_client_whitelabel_logo_post"},"Body_upload_api_client_whitelabel_style_api_api_client_whitelabel_style_post":{"properties":{"file":{"type":"string","format":"binary","title":"File"},"overwrite_existing":{"type":"boolean","title":"Overwrite Existing","default":false}},"type":"object","required":["file"],"title":"Body_upload_api_client_whitelabel_style_api_api_client_whitelabel_style_post"},"Company":{"properties":{"name":{"type":"string","title":"Name","example":"Tech Solutions Pty Ltd"},"address1":{"type":"string","title":"Address1","example":"456 Business Road"},"address2":{"type":"string","title":"Address2","example":"Suite 12"},"city":{"type":"string","title":"City","example":"Melbourne"},"state":{"type":"string","title":"State","example":"VIC"},"postcode":{"type":"string","title":"Postcode","example":"3000"},"country":{"type":"string","title":"Country","description":"Two-letter country code. Common values are `AU` and `NZ`.","example":"AU"},"jurisdiction":{"type":"string","title":"Jurisdiction","description":"Payroll jurisdiction code. Common values are `AU` and `NZ`.","example":"AU"},"phone":{"type":"string","title":"Phone","example":"03 1234 5678"},"email":{"type":"string","format":"email","title":"Email","example":"contact@techsolutions.com.au"},"abn":{"type":"string","title":"Abn","description":"Australian Business Number. AU only.","example":"12 345 678 901"},"employer_ird_number":{"type":"string","title":"Employer Ird Number","description":"Employer IRD number. NZ only.","example":"49091850"},"location_id":{"type":"integer","title":"Location Id","example":1},"contact_first_name":{"type":"string","title":"Contact First Name","example":"Alice"},"contact_middle_name":{"type":"string","title":"Contact Middle Name","example":"Marie"},"contact_last_name":{"type":"string","title":"Contact Last Name","example":"Smith"},"employees":{"items":{"$ref":"#/components/schemas/EmployeeBasic"},"type":"array","title":"Employees","description":"Optional list of employees; each item is `EmployeeBasic`."},"id":{"type":"integer","title":"Id","description":"Unique company identifier.","example":1}},"type":"object","required":["name","id"],"title":"Company","example":{"name":"Techy town Solutions Pty Ltd","address1":"123 Business Road","address2":"Suite 234234","city":"Perth","state":"WA","postcode":"6000","country":"AU","jurisdiction":"AU","phone":"03 1234 1111","email":"billy@techsolutions.com.au","abn":"10000000000","location_id":1,"contact_first_name":"billy","contact_last_name":"bob","id":2}},"CompanyCreate":{"properties":{"name":{"type":"string","maxLength":60,"minLength":1,"title":"Name"},"address1":{"type":"string","maxLength":100,"minLength":1,"title":"Address1"},"address2":{"type":"string","maxLength":100,"minLength":0,"title":"Address2"},"city":{"type":"string","maxLength":60,"minLength":1,"title":"City"},"state":{"type":"string","maxLength":60,"minLength":0,"title":"State","description":"State or region. Optional for NZ companies.","example":"WA"},"postcode":{"type":"string","pattern":"^\\d{4}$","title":"Postcode","description":"Postal code.","example":"6000"},"country":{"type":"string","title":"Country","description":"Defaults from the request host when omitted.","example":"AU"},"jurisdiction":{"type":"string","title":"Jurisdiction","description":"Defaults from the request host when omitted.","example":"AU"},"phone":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Phone"},"email":{"type":"string","format":"email","title":"Email"},"abn":{"type":"string","title":"Abn","description":"Required for AU companies, optional for NZ companies."},"employer_ird_number":{"type":"string","title":"Employer Ird Number","description":"NZ only.","example":"49091850"},"location_id":{"type":"integer","title":"Location Id"},"contact_first_name":{"type":"string","maxLength":60,"minLength":1,"title":"Contact First Name"},"contact_last_name":{"type":"string","maxLength":60,"minLength":1,"title":"Contact Last Name"},"contact_middle_name":{"type":"string","maxLength":60,"minLength":0,"title":"Contact Middle Name"}},"additionalProperties":false,"type":"object","required":["name","address1","city","email","location_id","contact_first_name","contact_last_name"],"title":"CompanyCreate","example":{"name":"Techy town Solutions Pty Ltd","address1":"123 Business Road","address2":"Level 3","city":"Perth","state":"WA","postcode":"6000","country":"AU","jurisdiction":"AU","phone":"03 1234 1111","email":"billy@techsolutions.com.au","abn":"10000000000","location_id":1,"contact_first_name":"billy","contact_last_name":"bob"}},"CompanyPartialUpdate":{"properties":{"name":{"type":"string","maxLength":60,"minLength":1,"title":"Name","description":"The registered name of the company."},"address1":{"type":"string","maxLength":100,"minLength":1,"title":"Address1","description":"The main street address of the company."},"address2":{"type":"string","maxLength":100,"minLength":0,"title":"Address2","description":"Optional second line of the address."},"city":{"type":"string","maxLength":60,"minLength":1,"title":"City","description":"The suburb or city of the company's address."},"state":{"type":"string","maxLength":60,"minLength":0,"title":"State","description":"State or region. Optional for NZ companies."},"postcode":{"type":"string","pattern":"^\\d{4}$","title":"Postcode","description":"Postal code."},"country":{"type":"string","title":"Country","description":"Two-letter country code such as `AU` or `NZ`."},"jurisdiction":{"type":"string","title":"Jurisdiction","description":"Payroll jurisdiction. `AU` or `NZ`."},"phone":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Phone","description":"Optional company contact phone number."},"email":{"type":"string","format":"email","title":"Email","description":"Contact email address for the company."},"abn":{"type":"string","title":"Abn","description":"Australian Business Number. AU only."},"employer_ird_number":{"type":"string","title":"Employer Ird Number","description":"Employer IRD number. NZ only."},"location_id":{"type":"integer","title":"Location Id","description":"Internal location identifier."},"contact_first_name":{"type":"string","maxLength":60,"minLength":1,"title":"Contact First Name","description":"Primary contact first name."},"contact_middle_name":{"type":"string","maxLength":60,"minLength":0,"title":"Contact Middle Name","description":"Primary contact middle name."},"contact_last_name":{"type":"string","maxLength":60,"minLength":1,"title":"Contact Last Name","description":"Primary contact last name."}},"additionalProperties":false,"type":"object","title":"CompanyPartialUpdate","example":{"name":"Techy Bros Solutions Pty Ltd","email":"billybro@techsolutions.com.au","jurisdiction":"AU"}},"CompanyPayRateAwardGroup":{"properties":{"award_id":{"type":"integer","title":"Award Id"},"award_name":{"type":"string","title":"Award Name"},"classifications":{"items":{"$ref":"#/components/schemas/CompanyPayRateClassificationGroup"},"type":"array","title":"Classifications"}},"type":"object","required":["classifications"],"title":"CompanyPayRateAwardGroup"},"CompanyPayRateClassificationGroup":{"properties":{"classification_id":{"type":"integer","title":"Classification Id"},"classification_name":{"type":"string","title":"Classification Name"},"pay_rates":{"items":{"$ref":"#/components/schemas/CompanyPayRateOption"},"type":"array","title":"Pay Rates"},"employees":{"items":{"$ref":"#/components/schemas/CompanyPayRateEmployeeSummary"},"type":"array","title":"Employees"}},"type":"object","required":["classification_id","pay_rates"],"title":"CompanyPayRateClassificationGroup"},"CompanyPayRateEmployeeSummary":{"properties":{"id":{"type":"integer","title":"Id"},"format_name":{"type":"string","title":"Format Name"},"number":{"type":"string","title":"Number"}},"type":"object","required":["id","format_name"],"title":"CompanyPayRateEmployeeSummary"},"CompanyPayRateOption":{"properties":{"reference":{"type":"string","title":"Reference"},"id":{"type":"integer","title":"Id"},"description":{"type":"string","title":"Description"},"rate_type":{"type":"string","title":"Rate Type"},"multiplier":{"type":"number","title":"Multiplier"},"rate":{"type":"number","title":"Rate"},"units":{"type":"string","title":"Units"},"is_hours":{"type":"boolean","title":"Is Hours"},"is_overtime":{"type":"boolean","title":"Is Overtime"}},"type":"object","required":["reference","id","description","rate_type","is_hours","is_overtime"],"title":"CompanyPayRateOption"},"CompanyPayRatesResponse":{"properties":{"company_id":{"type":"integer","title":"Company Id"},"awards":{"items":{"$ref":"#/components/schemas/CompanyPayRateAwardGroup"},"type":"array","title":"Awards"}},"type":"object","required":["company_id","awards"],"title":"CompanyPayRatesResponse"},"Employee":{"properties":{"is_super_only_contractor":{"type":"boolean","title":"Is Super Only Contractor","description":"Australia only. Whether the employee is a contractor paid super only (no TFN, excluded from STP, PAYG and payment summaries).","example":false},"tax_file_number":{"type":"string","title":"Tax File Number","example":"123456789"},"ird_number":{"type":"string","title":"Ird Number","description":"IRD number. NZ only.","example":"49091850"},"nz_tax_code":{"type":"string","title":"Nz Tax Code","description":"NZ tax code. NZ only.","example":"M"},"first_name":{"type":"string","maxLength":60,"minLength":0,"title":"First Name","example":"John"},"middle_name":{"type":"string","maxLength":60,"minLength":0,"title":"Middle Name","example":"Richard"},"last_name":{"type":"string","maxLength":60,"minLength":0,"title":"Last Name","example":"Smith"},"date_of_birth":{"type":"string","pattern":"^$|^\\d{4}-\\d{2}-\\d{2}$","title":"Date Of Birth","example":"1985-07-15"},"address1":{"type":"string","maxLength":100,"minLength":0,"title":"Address1","example":"123 Elm St"},"address2":{"type":"string","maxLength":100,"minLength":0,"title":"Address2","example":"123 Elm St"},"city":{"type":"string","maxLength":60,"minLength":0,"title":"City","example":"Sydney"},"state":{"type":"string","maxLength":3,"minLength":2,"title":"State","example":"NSW"},"country":{"type":"string","maxLength":2,"title":"Country","example":"AU"},"postcode":{"type":"string","pattern":"^\\d{4}$","title":"Postcode","example":"2000"},"email_address":{"type":"string","format":"email","title":"Email Address","description":"Email address of the employee.","example":"tonytiger@gmail.com"},"phone_home":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Phone Home","description":"Home phone number of the employee.","example":"02 1234 5678"},"phone_mobile":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Phone Mobile","description":"Mobile phone number of the employee.","example":"0412 345 678"},"phone_medical":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Phone Medical","description":"Medical contact phone number of the employee.","example":"02 8765 4321"},"gender":{"type":"string","enum":["MALE","FEMALE","INDETERMINATE","UNKNOWN"],"title":"Gender","description":"Gender of the employee. Must be one of MALE, FEMALE, INDETERMINATE, or UNKNOWN.","example":"MALE"},"kin_name":{"type":"string","maxLength":60,"minLength":0,"title":"Kin Name","description":"Name of the next of kin.","example":"Jane Smith"},"kin_relationship":{"type":"string","maxLength":60,"minLength":0,"title":"Kin Relationship","description":"Relationship of the next of kin to the employee.","example":"Sister"},"kin_address1":{"type":"string","maxLength":100,"minLength":0,"title":"Kin Address1","description":"Address line 1 of the next of kin.","example":"456 Oak St"},"kin_address2":{"type":"string","maxLength":100,"minLength":0,"title":"Kin Address2","description":"Address line 2 of the next of kin.","example":"Apt 5B"},"kin_city":{"type":"string","maxLength":60,"minLength":0,"title":"Kin City","description":"City of the next of kin.","example":"Melbourne"},"kin_state":{"type":"string","maxLength":3,"minLength":2,"title":"Kin State","description":"State of the next of kin.","example":"VIC"},"kin_postcode":{"type":"string","pattern":"^\\d{4}$","title":"Kin Postcode","description":"Postcode of the next of kin.","example":"3000"},"kin_phone_home":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Kin Phone Home","description":"Home phone number of the next of kin.","example":"03 1234 5678"},"kin_phone_work":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Kin Phone Work","description":"Work phone number of the next of kin.","example":"03 8765 4321"},"kin_phone_mobile":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Kin Phone Mobile","description":"Mobile phone number of the next of kin.","example":"0412 345 678"},"kin_notes":{"type":"string","title":"Kin Notes","description":"Additional notes about the next of kin.","example":"Emergency contact"},"pay_method":{"type":"string","enum":["CASH","DIRECT BANK ENTRY","OTHER"],"title":"Pay Method","description":"The method of payment for the employee.","default":"DIRECT BANK ENTRY","example":"CASH"},"pay_period":{"type":"string","enum":["WEEKLY","FORTNIGHTLY","MONTHLY"],"title":"Pay Period","description":"The pay period frequency for the employee. Valid values: WEEKLY, FORTNIGHTLY, MONTHLY","default":"WEEKLY","example":"WEEKLY"},"pay_rate_per_hour":{"type":"number","title":"Pay Rate Per Hour","description":"Hourly pay rate for the employee. This is used to calculate the employee's gross pay based on hours worked.","example":"25.00"},"standard_hours_per_day":{"type":"number","title":"Standard Hours Per Day","example":"7.6"},"standard_days_per_week":{"type":"integer","title":"Standard Days Per Week","description":"Number of standard working days per week for the employee. This is used to calculate leave accruals and RDOs.","example":"5"},"stp_employment_status":{"type":"string","title":"Stp Employment Status","description":"Employment status for STP reporting. On reads, unexpected values are passed through unchanged.","example":"F"},"active_pay_recipient":{"type":"boolean","title":"Active Pay Recipient","description":"Whether the employee is an active pay recipient. If False, the employee will not have pending pays generated for them, but they will still count towards licence limits and be included in reports. This is useful for employees who are on leave or not currently receiving pay but are not terminated.","example":true},"start_date":{"type":"string","pattern":"^$|^\\d{4}-\\d{2}-\\d{2}$","title":"Start Date","example":"2025-06-04"},"employment_status":{"type":"string","title":"Employment Status","description":"Employment status derived from the employee's employment type. Usually 'Full time', 'Part time', 'Casual', or 'Contractor', and empty when no employment type is set (e.g. employees created via this API). Read-only and not guaranteed to round-trip the value sent on create/update — for the authoritative status use stp_employment_status / readable_stp_employment_status, which are always populated.","example":"Full time"},"tfnd_signed_date":{"type":"string","pattern":"^$|^\\d{4}-\\d{2}-\\d{2}$","title":"Tfnd Signed Date","description":"Date the employee signed the TFN declaration.","example":"2025-06-04"},"is_foreign_resident":{"type":"boolean","title":"Is Foreign Resident"},"is_closely_held":{"type":"boolean","title":"Is Closely Held","description":"Whether the employee is a closely held employee. Closely held employees are typically family members of the business owner or directors of the company.","example":false},"has_claimed_tax_free_threshold":{"type":"boolean","title":"Has Claimed Tax Free Threshold"},"has_stsl_liability":{"type":"boolean","title":"Has Stsl Liability"},"has_student_loan":{"type":"boolean","title":"Has Student Loan","description":"Whether the employee has an NZ student loan. NZ only.","example":false},"no_declaration":{"type":"boolean","title":"No Declaration","description":"Whether the employee is using NZ non-declaration handling. NZ only.","example":false},"include_email_and_phone_in_stp":{"type":"boolean","title":"Include Email And Phone In Stp","description":"Whether to include the employee's email address and phone number in STP reports sent to the ATO. Defaults to False if not set.","example":false},"abn":{"type":"string","title":"Abn","description":"Australian Business Number (ABN) of the employee, if applicable. Required for non-standard employees who bill as contractors.","example":"12345678901"},"working_holiday_tax_scale_applies":{"type":"boolean","title":"Working Holiday Tax Scale Applies","description":"Whether the employee is subject to the Working Holiday Maker tax scale. If True, the employee's tax calculations will use the WHM tax scale instead of the standard tax scale.","example":false},"leave_loading_percentage":{"type":"number","title":"Leave Loading Percentage","description":"Leave loading percentage, e.g. 0.175 for 17.5%","example":"0.175"},"position":{"type":"string","maxLength":60,"minLength":0,"title":"Position","description":"Position or job title of the employee.","example":"Manager"},"employee_portal_active":{"type":"boolean","title":"Employee Portal Active","description":"Whether the employee has access to the online portal.","example":false},"allow_edit_timesheet":{"type":"boolean","title":"Allow Edit Timesheet","description":"Whether the employee is allowed to edit their own timesheets in the online portal.","example":false},"allow_edit_timeclock":{"type":"boolean","title":"Allow Edit Timeclock","description":"Whether the employee is allowed to use the timeclock in the online portal.","example":false},"allow_edit_account_details":{"type":"boolean","title":"Allow Edit Account Details","description":"Whether the employee is allowed to edit their own personal details in the online portal.","example":false},"allow_edit_tax_settings":{"type":"boolean","title":"Allow Edit Tax Settings","description":"Whether the employee is allowed to edit their tax settings in the online portal.","example":false},"allow_edit_bank_accounts":{"type":"boolean","title":"Allow Edit Bank Accounts","description":"Whether the employee is allowed to edit their own bank account details in the online portal.","example":false},"allow_edit_super_details":{"type":"boolean","title":"Allow Edit Super Details","description":"Whether the employee is allowed to edit their super details in the online portal.","example":false},"allow_edit_leave_requests":{"type":"boolean","title":"Allow Edit Leave Requests","description":"Whether the employee is allowed to make leave requests through the online portal.","example":false},"allow_edit_leave_requests_when_negative":{"type":"boolean","title":"Allow Edit Leave Requests When Negative","description":"Whether the employee is allowed to make leave requests even when they have, or will reach, a negative leave balance.","example":false},"allow_view_holiday_leave_balance":{"type":"boolean","title":"Allow View Holiday Leave Balance","description":"Whether the employee is allowed to view their holiday leave balance in the online portal.","example":false},"allow_view_sick_leave_balance":{"type":"boolean","title":"Allow View Sick Leave Balance","description":"Whether the employee is allowed to view their sick leave balance in the online portal.","example":false},"allow_view_long_service_leave_balance":{"type":"boolean","title":"Allow View Long Service Leave Balance","description":"Whether the employee is allowed to view their long service leave balance in the online portal.","example":false},"allow_view_payslips":{"type":"boolean","title":"Allow View Payslips","description":"Whether the employee is allowed to view their payslips in the online portal.","example":false},"department":{"type":"string","maxLength":60,"minLength":0,"title":"Department","example":"Human Resources"},"number":{"type":"string","maxLength":60,"minLength":0,"title":"Number","description":"User-controlled unique employee payroll number/code. This is not the same as the internal database ID.","example":"EMP001"},"honorific":{"type":"string","maxLength":18,"minLength":0,"title":"Honorific","description":"Honorific title for the employee (e.g., Mr, Ms, Dr).","example":"Mr"},"show_roster_summary_on_payslip":{"type":"boolean","title":"Show Roster Summary On Payslip","description":"Whether to show the roster summary on the payslip.","example":false},"show_position_on_payslip":{"type":"boolean","title":"Show Position On Payslip","description":"Whether to show the employee's position on the payslip.","example":false},"show_department_on_payslip":{"type":"boolean","title":"Show Department On Payslip","description":"Whether to show the employee's department on the payslip.","example":false},"payslip_show_holiday_leave_balance":{"type":"boolean","title":"Payslip Show Holiday Leave Balance","description":"Whether to show the employee's holiday leave balance on the payslip.","example":false},"payslip_show_sick_leave_balance":{"type":"boolean","title":"Payslip Show Sick Leave Balance","description":"Whether to show the employee's sick leave balance on the payslip.","example":false},"payslip_show_lsl_balance":{"type":"boolean","title":"Payslip Show Lsl Balance","description":"Whether to show the employee's long service leave balance on the payslip.","example":false},"payslip_show_negative_leave_balances":{"type":"boolean","title":"Payslip Show Negative Leave Balances","description":"Whether to show negative leave balances on the payslip.","example":false},"payslip_show_custom_balances":{"type":"boolean","title":"Payslip Show Custom Balances","description":"Whether to show custom leave balances on the payslip.","example":false},"payslip_leave_units":{"type":"string","enum":["HOURS","DAYS"],"title":"Payslip Leave Units","description":"The unit of measurement for leave balances shown on the payslip. Valid values: HOURS, DAYS","example":"HOURS"},"payslip_show_hours_and_rate":{"type":"boolean","title":"Payslip Show Hours And Rate","description":"Whether to show hours worked and pay rate on the payslip.","example":false},"payslip_show_allowance_units":{"type":"boolean","title":"Payslip Show Allowance Units","description":"Whether to show allowance units on the payslip.","example":false},"payslip_show_base_ordinary_rate":{"type":"boolean","title":"Payslip Show Base Ordinary Rate","description":"Whether to show the base ordinary rate on the payslip.","example":false},"payslip_show_super_ytd":{"type":"boolean","title":"Payslip Show Super Ytd","description":"Whether to show the year-to-date superannuation contributions on the payslip.","example":false},"payslip_note":{"type":"string","title":"Payslip Note","description":"An added note to be displayed on each upcoming payslip for this employee.","example":"Thank you for your hard work!"},"payslip_show_ytd":{"type":"boolean","title":"Payslip Show Ytd","description":"Whether to show year-to-date totals on the payslip.","example":false},"payslip_show_zero_dollar_leave":{"type":"boolean","title":"Payslip Show Zero Dollar Leave","description":"Whether to show zero dollar leave balances on the payslip.","example":false},"payslip_time_non_decimal":{"type":"boolean","title":"Payslip Time Non Decimal","description":"Whether to show time in non-decimal format (e.g., 1:30 instead of 1.5 hours) on the payslip.","example":false},"primary_bank_bsb":{"type":"string","pattern":"$|^\\d{3}-\\d{3}$","title":"Primary Bank Bsb","example":"987-654"},"primary_bank_account_number":{"type":"string","maxLength":12,"title":"Primary Bank Account Number","example":"87654321"},"primary_bank_account_name":{"type":"string","maxLength":32,"minLength":0,"title":"Primary Bank Account Name","example":"John Smith"},"secondary_bank_bsb":{"type":"string","pattern":"$|^\\d{3}-\\d{3}$","title":"Secondary Bank Bsb","example":"123-456"},"secondary_bank_account_number":{"type":"string","maxLength":12,"title":"Secondary Bank Account Number","example":"12345678"},"secondary_bank_account_name":{"type":"string","maxLength":32,"minLength":0,"title":"Secondary Bank Account Name","example":"John Smith"},"secondary_bank_reference":{"type":"string","maxLength":18,"minLength":0,"title":"Secondary Bank Reference","example":"Child Support"},"secondary_bank_amount_per_period":{"type":"number","title":"Secondary Bank Amount Per Period","description":"Amount to be paid to the secondary bank account per pay period. Remaining pay will be paid to the primary bank account.","example":"100.00"},"default_employee_fund_member_number":{"type":"string","maxLength":20,"title":"Default Employee Fund Member Number","example":"12345678"},"default_employee_fund_usi":{"type":"string","maxLength":20,"title":"Default Employee Fund Usi","example":"STA0100AU"},"super_rate":{"type":"number","title":"Super Rate","description":"Total superannuation rate used on the employee's upcoming pays, expressed as a decimal (e.g., 0.115 for 11.5%). This is the rate applied to the employee's ordinary time earnings for superannuation contributions. Any excess above the compulsory_super_rate is categorised as RESC (Reportable Employer Super Contributions).","example":"0.115"},"compulsory_super_rate":{"type":"number","title":"Compulsory Super Rate","description":"Compulsory superannuation rate used on the employee's upcoming pays, expressed as a decimal (e.g., 0.105 for 10.5%). This is the minimum rate required by law for superannuation contributions.","example":"0.105"},"is_super_enabled":{"type":"boolean","title":"Is Super Enabled","description":"Whether superannuation contributions are enabled for this employee. If False, no super calculations will be performed for this employee, regardless of the super_rate or compulsory_super_rate settings.","example":true},"is_super_age_threshold_enabled":{"type":"boolean","title":"Is Super Age Threshold Enabled","description":"Whether the superannuation age threshold is enabled for this employee. If True, the employee's age will be considered when calculating super contributions. If False, the employee's age will not affect super calculations.","example":true},"super_based_on":{"type":"string","enum":["OTE","GROSS"],"title":"Super Based On","description":"The basis for superannuation calculations for this employee. Valid values: OTE (Ordinary Time Earnings, recommended) or GROSS (Gross Pay). If OTE, super is calculated based on the employee's ordinary time earnings. If GROSS, super is calculated based on the employee's gross pay.","example":"OTE"},"kiwisaver_employee_rate":{"type":"number","title":"Kiwisaver Employee Rate","description":"Employee KiwiSaver contribution rate. NZ only.","example":"0.03"},"kiwisaver_employer_rate":{"type":"number","title":"Kiwisaver Employer Rate","description":"Employer KiwiSaver contribution rate. NZ only.","example":"0.03"},"kiwisaver_status_code":{"type":"string","title":"Kiwisaver Status Code","description":"KiwiSaver status code. NZ only.","example":"KS"},"kiwisaver_existing_action":{"type":"string","title":"Kiwisaver Existing Action","description":"KiwiSaver existing member action. NZ only.","example":"EXISTING_MEMBER"},"esct_rate":{"type":"number","title":"Esct Rate","description":"Employer superannuation contribution tax rate. NZ only.","example":"0.105"},"employer_contrib_tax_method":{"type":"string","title":"Employer Contrib Tax Method","description":"NZ employer contribution tax method.","example":"ESCT"},"employer_contrib_paye_fraction":{"type":"number","title":"Employer Contrib Paye Fraction","description":"NZ employer contribution PAYE fraction.","example":"0.0"},"kiwisaver_cec_obligation":{"type":"string","title":"Kiwisaver Cec Obligation","description":"KiwiSaver CEC obligation. NZ only.","example":"NONE"},"is_leave_enabled":{"type":"boolean","title":"Is Leave Enabled","description":"Whether leave calculations are enabled for this employee. If False, no leave accruals will be calculated for this employee.","example":true},"include_leave_loading_in_super":{"type":"boolean","title":"Include Leave Loading In Super","description":"Whether to include leave loading in superannuation calculations for this employee. If True, leave loading will be included in the superannuation contributions. If False, leave loading will not be included in super calculations.","example":false},"accrue_leave_on_hours_worked":{"type":"boolean","title":"Accrue Leave On Hours Worked","description":"Whether to accrue leave based on hours worked (pro rata). If True, leave will be accrued based on the number of hours worked by the employee. If False, leave will be accrued by the pay period.","example":true},"accrue_leave_on_overtime_hours":{"type":"boolean","title":"Accrue Leave On Overtime Hours","description":"Whether to accrue leave based on overtime hours worked. If True, leave will be accrued based on the number of overtime hours worked by the employee. If False, overtime hours will not contribute to leave accruals.","example":false},"accrue_holiday_leave_per_hour":{"type":"number","title":"Accrue Holiday Leave Per Hour","description":"Holiday leave accrual rate per hour worked, expressed as a decimal (e.g., 0.076923 for 20 days per year). Used when both accrue_leave_on_hours_worked and is_leave_enabled are enabled. This is used to calculate the number of holiday leave hours accrued by the employee based on their hours worked.","example":"0.076923"},"accrue_sick_leave_per_hour":{"type":"number","title":"Accrue Sick Leave Per Hour","description":"Sick leave accrual rate per hour worked, expressed as a decimal (e.g., 0.038462 for 10 days per year). Used when both accrue_leave_on_hours_worked and is_leave_enabled are enabled. This is used to calculate the number of sick leave hours accrued by the employee based on their hours worked.","example":"0.038462"},"accrue_lsl_per_hour":{"type":"number","title":"Accrue Lsl Per Hour","description":"Long Service Leave (LSL) accrual rate per hour worked, expressed as a decimal (e.g., 0.016667 for 8.6667 weeks per 10 years; 0.025 for SA/NT's 13 weeks). The per-state default is derived from the lump entitlement (weeks/years/52). Used when both accrue_leave_on_hours_worked and is_leave_enabled are enabled. This is used to calculate the number of LSL hours accrued by the employee based on their hours worked.","example":"0.016667"},"num_sick_leave_days_per_year":{"type":"integer","title":"Num Sick Leave Days Per Year","description":"Number of personal/sick days per year for the employee. This is used to calculate the number of personal leave hours accrued by the employee based on their hours worked.","example":10},"num_holiday_leave_days_per_year":{"type":"integer","title":"Num Holiday Leave Days Per Year","description":"Number of annual/holiday days per year for the employee. This is used to calculate the number of holiday leave hours accrued by the employee based on their hours worked.","example":20},"is_lsl_enabled":{"type":"boolean","title":"Is Lsl Enabled","description":"Whether Long Service Leave (LSL) calculations are enabled for this employee. If False, no LSL accruals will be calculated for this employee.","example":true},"lsl_x_years":{"type":"integer","title":"Lsl X Years","description":"Number of years of service required to qualify for Long Service Leave (LSL). This is used to determine when the employee is eligible for LSL based on their length of service.","example":10},"lsl_accrued_x_years":{"type":"integer","title":"Lsl Accrued X Years","description":"Number of weeks LSL accrued for every lsl_x_years years of service. This is used to calculate the number of LSL hours accrued by the employee based on their length of service.","example":10},"hourly_amount_for_workers_comp_leave":{"type":"number","title":"Hourly Amount For Workers Comp Leave","example":"25.50"},"hourly_amount_for_paid_parental_leave":{"type":"number","title":"Hourly Amount For Paid Parental Leave","example":"30.75"},"rdo_hours":{"type":"number","title":"Rdo Hours","description":"Total hours of Rostered Days Off (RDOs) accrued by the employee as at their most recent pay.","example":"55.42"},"toil_hours":{"type":"number","title":"Toil Hours","description":"Total hours of Time Off In Lieu (TOIL) accrued by the employee as at their most recent pay.","example":"20.00"},"id":{"type":"integer","title":"Id"},"company_id":{"type":"integer","title":"Company Id"},"readable_stp_employment_status":{"type":"string","title":"Readable Stp Employment Status","description":"Human-readable employment status for Single Touch Payroll (STP) reporting. This is derived from the stp_employment_status field and is used for display purposes in reports and the online portal.","example":"Full time"},"is_australian_resident":{"type":"boolean","title":"Is Australian Resident","description":"Whether the employee is an Australian resident for tax purposes. This is used to determine the employee's tax treatment and reporting in Single Touch Payroll (STP). To control this value, use the is_foreign_resident field. If is_foreign_resident is True, this field will be set to False automatically.","example":true},"income_stream":{"type":"string","enum":["SAW","CHP","WHM","VOL"],"title":"Income Stream","description":"Income stream type for the employee. Valid values: SAW (Salary and Wages), CHP (Closely held), WHM (Working Holiday Maker), VOL (Voluntary).","example":"SAW"},"stp_id":{"type":"integer","title":"Stp Id","description":"Unique identifier for the employee in the Single Touch Payroll (STP) system. This is used to identify the employee in STP reports sent to the ATO.","example":1},"has_leave_loading":{"type":"boolean","title":"Has Leave Loading","description":"Whether the employee is set to receive annual leave loading.","example":true},"username":{"type":"string","maxLength":60,"minLength":0,"title":"Username","description":"Username for the employee, used for online portal login purposes.","example":"smithjohnjames"},"standard_hours_per_week":{"type":"number","title":"Standard Hours Per Week","description":"Standard hours worked by the employee per week. This is calculated as standard_hours_per_day * standard_days_per_week.","example":"38"},"rdo_days":{"type":"number","title":"Rdo Days","description":"Number of Rostered Days Off (RDOs) accrued by the employee as at their most recent pay. This is calculated based on the employee's rdo_hours / standard_hours_per_day.","example":"12"},"toil_days":{"type":"number","title":"Toil Days","description":"Number of Time Off In Lieu (TOIL) days accrued by the employee as at their most recent pay. This is calculated based on the employee's toil_hours / standard_hours_per_day.","example":"5"},"holiday_leave_hours":{"type":"number","title":"Holiday Leave Hours","description":"Total hours of Annual Leave accrued by the employee as at their most recent pay.","example":"120"},"sick_leave_hours":{"type":"number","title":"Sick Leave Hours","description":"Total hours of Personal Leave accrued by the employee as at their most recent pay.","example":"80"},"lsl_leave_hours":{"type":"number","title":"Lsl Leave Hours","description":"Total hours of Long Service Leave (LSL) accrued by the employee as at their most recent pay.","example":"30"},"pay_period_gross":{"type":"number","title":"Pay Period Gross","description":"Typical gross pay for the employee, based on their current pay settings.","example":"5000.00"},"annual_gross":{"type":"number","title":"Annual Gross","description":"Estimated annual gross pay for the employee, based on their current pay settings. This is calculated as pay_period_gross * (52 weeks / pay_period frequency).","example":"130000.00"},"current_ytd_gross":{"type":"number","title":"Current Ytd Gross","description":"Year-to-date gross pay for the employee, based on the YTD of their most recent completed pay.","example":"50000.00"},"last_pay_date":{"type":"string","pattern":"^$|^\\d{4}-\\d{2}-\\d{2}$","title":"Last Pay Date","description":"Pay run end date of the employee's most recent completed pay. This is used to determine the employee's last pay date and is important for leave calculations and reporting.","example":"2023-06-30"},"last_pay_processed_date":{"type":"string","pattern":"^$|^\\d{4}-\\d{2}-\\d{2}$","title":"Last Pay Processed Date","description":"Processed date of the employee's most recent completed pay. This is used to determine when the employee's last pay was processed and is important for leave calculations and reporting.","example":"2023-07-01"},"format_name":{"type":"string","title":"Format Name","description":"Formatted name of the employee, typically in 'Last, First Middle' format. This is used for display purposes in reports and the online portal.","example":"Smith, John James"},"format_name_shorter":{"type":"string","title":"Format Name Shorter","description":"Shortened formatted name of the employee, typically in 'Last, First Initials' format. This is used for display purposes in some reports and the online portal.","example":"Smith, John J."},"default_employee_fund_name":{"type":"string","title":"Default Employee Fund Name","description":"Name of the default superannuation fund for the employee. This is used for superannuation contributions and reporting.","example":"Super Fund Pty Ltd"},"lsl_eligible_date":{"type":"string","pattern":"^$|^\\d{4}-\\d{2}-\\d{2}$","title":"Lsl Eligible Date","description":"Date when the employee becomes eligible for Long Service Leave (LSL). This is calculated based on the employee's start date and lsl_x_years setting. If the employee has not yet reached the required years of service, this will be None.","example":"2025-06-04"},"default_lsl_over_ten_years":{"type":"number","title":"Default Lsl Over Ten Years","description":"Recommended number of weeks of Long Service Leave (LSL) accrued for every 10 years of service, based on the company's state/territory regulations. This is used to calculate the number of LSL hours accrued by the employee based on their length of service. ","example":"8.6667"},"tax_treatment_code":{"type":"string","title":"Tax Treatment Code","description":"Tax treatment code for the employee, used for Single Touch Payroll (STP) reporting. This is used to describe how the employee's earnings are taxed and reported to the ATO.","example":"RTSXXX"},"single_touch_residency_status":{"type":"string","title":"Single Touch Residency Status","description":"Residency status of the employee for Single Touch Payroll (STP) reporting. This is used to describe if the employee is a resident, non-resident or working holiday maker for tax purposes.","example":"RESIDENT"},"income_stream_country_code":{"type":"string","title":"Income Stream Country Code","description":"Income stream country code. NZ only.","example":"NZ"},"period_student_loan_cir":{"type":"number","title":"Period Student Loan Cir","description":"Period student loan CIR amount. NZ only.","example":"0.00"},"period_student_loan_bor":{"type":"number","title":"Period Student Loan Bor","description":"Period student loan BOR amount. NZ only.","example":"0.00"},"opted_out":{"type":"boolean","title":"Opted Out","description":"Whether the employee opted out of KiwiSaver. NZ only.","example":false},"opted_out_signature_date":{"type":"string","pattern":"^$|^\\d{4}-\\d{2}-\\d{2}$","title":"Opted Out Signature Date","description":"Date the employee signed a KiwiSaver opt-out. NZ only.","example":"2025-06-04"},"late_opt_out_reason":{"type":"string","title":"Late Opt Out Reason","description":"Late KiwiSaver opt-out reason. NZ only.","example":"NEW_EMPLOYMENT"},"other_late_opt_out_reason":{"type":"string","title":"Other Late Opt Out Reason","description":"Free-text late KiwiSaver opt-out reason. NZ only.","example":"Employer correction"},"is_terminated":{"type":"boolean","title":"Is Terminated","default":false,"example":false},"termination_date":{"type":"string","pattern":"^$|^\\d{4}-\\d{2}-\\d{2}$","title":"Termination Date","example":"2023-06-30"},"cessation_type_code":{"type":"string","enum":["","V","I","R","F","C"],"title":"Cessation Type Code","description":"Cessation type code for the employee's termination.","example":"V"}},"additionalProperties":false,"type":"object","required":["id"],"title":"Employee","description":"Full employee record returned by the API, used in get requests."},"EmployeeBasic":{"properties":{"id":{"type":"integer","title":"Id","description":"The unique identifier of the employee.","example":1234},"number":{"type":"string","title":"Number","description":"The external unique employee number.","example":"EMP001"},"company_id":{"type":"integer","title":"Company Id","description":"The unique identifier of the company the employee belongs to.","example":5678},"first_name":{"type":"string","title":"First Name","description":"The first name of the employee.","example":"John"},"last_name":{"type":"string","title":"Last Name","description":"The last name of the employee.","example":"Doe"},"date_of_birth":{"type":"string","format":"date","title":"Date Of Birth","description":"The date of birth of the employee.","example":"1990-01-01"},"start_date":{"type":"string","format":"date","title":"Start Date","description":"The date the employee started working.","example":"2020-01-15"},"is_terminated":{"type":"boolean","title":"Is Terminated","description":"Indicates whether the employee has been terminated.","example":false},"termination_date":{"type":"string","format":"date","title":"Termination Date","description":"The date the employee was terminated, if applicable.","example":"2021-12-31"},"address1":{"type":"string","title":"Address1","description":"The first line of the employee's address.","example":"123 Main Street"},"address2":{"type":"string","title":"Address2","description":"The second line of the employee's address.","example":"Apt 4B"},"city":{"type":"string","title":"City","description":"The city where the employee resides.","example":"Sydney"},"state":{"type":"string","title":"State","description":"The state or province where the employee resides.","example":"NSW"},"postcode":{"type":"string","title":"Postcode","description":"The postal code of the employee's address.","example":"2000"},"country":{"type":"string","title":"Country","description":"The country where the employee resides.","example":"Australia"},"tax_file_number":{"type":"string","title":"Tax File Number","description":"The tax file number of the employee.","example":"123456789"},"ird_number":{"type":"string","title":"Ird Number","description":"The IRD number of the employee. NZ only.","example":"49091850"},"nz_tax_code":{"type":"string","title":"Nz Tax Code","description":"The NZ tax code of the employee. NZ only.","example":"M"},"has_student_loan":{"type":"boolean","title":"Has Student Loan","description":"Indicates whether the employee has an NZ student loan. NZ only.","example":false},"no_declaration":{"type":"boolean","title":"No Declaration","description":"Indicates whether the employee is on NZ non-declaration settings. NZ only.","example":false},"has_claimed_tax_free_threshold":{"type":"boolean","title":"Has Claimed Tax Free Threshold","description":"Indicates whether the employee has claimed the tax-free threshold.","example":true},"is_australian_resident":{"type":"boolean","title":"Is Australian Resident","description":"Indicates whether the employee is an Australian resident for tax purposes.","example":true},"has_help_liability":{"type":"boolean","title":"Has Help Liability","description":"Indicates whether the employee has a HELP (Higher Education Loan Program), TSL or any other STSL(Study or Training Support Loans) liability.","example":false},"stp_employment_status":{"type":"string","title":"Stp Employment Status","description":"The Single Touch Payroll (STP) employment status of the employee.","example":"full_time"},"hourly_amount_for_workers_comp_leave":{"type":"number","title":"Hourly Amount For Workers Comp Leave","description":"The hourly amount for workers' compensation leave.","example":"25.50"}},"type":"object","title":"EmployeeBasic"},"EmployeeCreate":{"properties":{"is_super_only_contractor":{"type":"boolean","title":"Is Super Only Contractor"},"tax_file_number":{"type":"string","title":"Tax File Number","description":"Tax File Number (TFN) of the employee. Required for AU companies, not used for NZ companies.","example":"123456789"},"ird_number":{"type":"string","title":"Ird Number","description":"IRD number. NZ only.","example":"49091850"},"nz_tax_code":{"type":"string","title":"Nz Tax Code","description":"NZ tax code. NZ only.","example":"M"},"first_name":{"type":"string","maxLength":60,"minLength":1,"title":"First Name"},"middle_name":{"type":"string","maxLength":60,"minLength":0,"title":"Middle Name","example":"Richard"},"last_name":{"type":"string","maxLength":60,"minLength":1,"title":"Last Name"},"date_of_birth":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","title":"Date Of Birth"},"address1":{"type":"string","maxLength":100,"minLength":1,"title":"Address1"},"address2":{"type":"string","maxLength":100,"minLength":0,"title":"Address2","example":"123 Elm St"},"city":{"type":"string","maxLength":60,"minLength":1,"title":"City"},"state":{"type":"string","maxLength":3,"minLength":2,"title":"State"},"country":{"type":"string","maxLength":2,"title":"Country"},"postcode":{"type":"string","pattern":"^\\d{4}$","title":"Postcode"},"email_address":{"type":"string","format":"email","title":"Email Address","description":"Email address of the employee.","example":"tonytiger@gmail.com"},"phone_home":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Phone Home","description":"Home phone number of the employee.","example":"02 1234 5678"},"phone_mobile":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Phone Mobile","description":"Mobile phone number of the employee.","example":"0412 345 678"},"phone_medical":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Phone Medical","description":"Medical contact phone number of the employee.","example":"02 8765 4321"},"gender":{"type":"string","enum":["MALE","FEMALE","INDETERMINATE","UNKNOWN"],"title":"Gender","description":"Gender of the employee. Must be one of MALE, FEMALE, INDETERMINATE, or UNKNOWN.","example":"MALE"},"kin_name":{"type":"string","maxLength":60,"minLength":0,"title":"Kin Name","description":"Name of the next of kin.","example":"Jane Smith"},"kin_relationship":{"type":"string","maxLength":60,"minLength":0,"title":"Kin Relationship","description":"Relationship of the next of kin to the employee.","example":"Sister"},"kin_address1":{"type":"string","maxLength":100,"minLength":0,"title":"Kin Address1","description":"Address line 1 of the next of kin.","example":"456 Oak St"},"kin_address2":{"type":"string","maxLength":100,"minLength":0,"title":"Kin Address2","description":"Address line 2 of the next of kin.","example":"Apt 5B"},"kin_city":{"type":"string","maxLength":60,"minLength":0,"title":"Kin City","description":"City of the next of kin.","example":"Melbourne"},"kin_state":{"type":"string","maxLength":3,"minLength":2,"title":"Kin State","description":"State of the next of kin.","example":"VIC"},"kin_postcode":{"type":"string","pattern":"^\\d{4}$","title":"Kin Postcode","description":"Postcode of the next of kin.","example":"3000"},"kin_phone_home":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Kin Phone Home","description":"Home phone number of the next of kin.","example":"03 1234 5678"},"kin_phone_work":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Kin Phone Work","description":"Work phone number of the next of kin.","example":"03 8765 4321"},"kin_phone_mobile":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Kin Phone Mobile","description":"Mobile phone number of the next of kin.","example":"0412 345 678"},"kin_notes":{"type":"string","title":"Kin Notes","description":"Additional notes about the next of kin.","example":"Emergency contact"},"pay_method":{"type":"string","enum":["CASH","DIRECT BANK ENTRY","OTHER"],"title":"Pay Method","description":"The method of payment for the employee.","default":"DIRECT BANK ENTRY","example":"CASH"},"pay_period":{"type":"string","enum":["WEEKLY","FORTNIGHTLY","MONTHLY"],"title":"Pay Period","description":"The pay period frequency for the employee. Valid values: WEEKLY, FORTNIGHTLY, MONTHLY","default":"WEEKLY","example":"WEEKLY"},"pay_rate_per_hour":{"type":"number","title":"Pay Rate Per Hour","description":"Hourly pay rate for the employee. This is used to calculate the employee's gross pay based on hours worked.","example":"25.00"},"standard_hours_per_day":{"type":"number","title":"Standard Hours Per Day","example":"7.6"},"standard_days_per_week":{"type":"integer","title":"Standard Days Per Week","description":"Number of standard working days per week for the employee. This is used to calculate leave accruals and RDOs.","example":"5"},"stp_employment_status":{"type":"string","enum":["C","P","F"],"title":"Stp Employment Status","description":"The employment status of the employee for Single Touch Payroll (STP) reporting. Valid values: C, P, F. This is used to determine how the employee's earnings are reported to the ATO.","default":"F","example":"F"},"active_pay_recipient":{"type":"boolean","title":"Active Pay Recipient","description":"Whether the employee is an active pay recipient. If False, the employee will not have pending pays generated for them, but they will still count towards licence limits and be included in reports. This is useful for employees who are on leave or not currently receiving pay but are not terminated.","example":true},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","title":"Start Date"},"employment_status":{"type":"string","pattern":"(?i)^(full[-\\s]?time|part[-\\s]?time|casual|labour[\\s-]?hire)$","title":"Employment Status","description":"Employment status. One of 'Full-time', 'Part-time', 'Casual', or 'Labour Hire' (matched case-insensitively; hyphen/space tolerant). Sets the employee's STP employment status and the default leave / long-service-leave accrual configuration.","example":"Full-time"},"tfnd_signed_date":{"type":"string","pattern":"^$|^\\d{4}-\\d{2}-\\d{2}$","title":"Tfnd Signed Date","description":"Date the employee signed the TFN declaration.","example":"2025-06-04"},"is_foreign_resident":{"type":"boolean","title":"Is Foreign Resident"},"is_closely_held":{"type":"boolean","title":"Is Closely Held"},"has_claimed_tax_free_threshold":{"type":"boolean","title":"Has Claimed Tax Free Threshold"},"has_stsl_liability":{"type":"boolean","title":"Has Stsl Liability"},"has_student_loan":{"type":"boolean","title":"Has Student Loan","description":"Whether the employee has an NZ student loan. NZ only.","example":false},"no_declaration":{"type":"boolean","title":"No Declaration","description":"Whether the employee is using NZ non-declaration handling. NZ only.","example":false},"include_email_and_phone_in_stp":{"type":"boolean","title":"Include Email And Phone In Stp","description":"Whether to include the employee's email address and phone number in STP reports sent to the ATO. Defaults to False if not set.","example":false},"abn":{"type":"string","title":"Abn","description":"Australian Business Number (ABN) of the employee, if applicable. Required for non-standard employees who bill as contractors.","example":"12345678901"},"working_holiday_tax_scale_applies":{"type":"boolean","title":"Working Holiday Tax Scale Applies","description":"Whether the employee is subject to the Working Holiday Maker tax scale. If True, the employee's tax calculations will use the WHM tax scale instead of the standard tax scale.","example":false},"leave_loading_percentage":{"type":"number","title":"Leave Loading Percentage","description":"Leave loading percentage, e.g. 0.175 for 17.5%","example":"0.175"},"position":{"type":"string","maxLength":60,"minLength":0,"title":"Position","description":"Position or job title of the employee.","example":"Manager"},"employee_portal_active":{"type":"boolean","title":"Employee Portal Active","description":"Whether the employee has access to the online portal.","example":false},"allow_edit_timesheet":{"type":"boolean","title":"Allow Edit Timesheet","description":"Whether the employee is allowed to edit their own timesheets in the online portal.","example":false},"allow_edit_timeclock":{"type":"boolean","title":"Allow Edit Timeclock","description":"Whether the employee is allowed to use the timeclock in the online portal.","example":false},"allow_edit_account_details":{"type":"boolean","title":"Allow Edit Account Details","description":"Whether the employee is allowed to edit their own personal details in the online portal.","example":false},"allow_edit_tax_settings":{"type":"boolean","title":"Allow Edit Tax Settings","description":"Whether the employee is allowed to edit their tax settings in the online portal.","example":false},"allow_edit_bank_accounts":{"type":"boolean","title":"Allow Edit Bank Accounts","description":"Whether the employee is allowed to edit their own bank account details in the online portal.","example":false},"allow_edit_super_details":{"type":"boolean","title":"Allow Edit Super Details","description":"Whether the employee is allowed to edit their super details in the online portal.","example":false},"allow_edit_leave_requests":{"type":"boolean","title":"Allow Edit Leave Requests","description":"Whether the employee is allowed to make leave requests through the online portal.","example":false},"allow_edit_leave_requests_when_negative":{"type":"boolean","title":"Allow Edit Leave Requests When Negative","description":"Whether the employee is allowed to make leave requests even when they have, or will reach, a negative leave balance.","example":false},"allow_view_holiday_leave_balance":{"type":"boolean","title":"Allow View Holiday Leave Balance","description":"Whether the employee is allowed to view their holiday leave balance in the online portal.","example":false},"allow_view_sick_leave_balance":{"type":"boolean","title":"Allow View Sick Leave Balance","description":"Whether the employee is allowed to view their sick leave balance in the online portal.","example":false},"allow_view_long_service_leave_balance":{"type":"boolean","title":"Allow View Long Service Leave Balance","description":"Whether the employee is allowed to view their long service leave balance in the online portal.","example":false},"allow_view_payslips":{"type":"boolean","title":"Allow View Payslips","description":"Whether the employee is allowed to view their payslips in the online portal.","example":false},"department":{"type":"string","maxLength":60,"minLength":0,"title":"Department","example":"Human Resources"},"number":{"type":"string","maxLength":60,"minLength":0,"title":"Number","description":"User-controlled unique employee payroll number/code. This is not the same as the internal database ID.","example":"EMP001"},"honorific":{"type":"string","maxLength":18,"minLength":0,"title":"Honorific","description":"Honorific title for the employee (e.g., Mr, Ms, Dr).","example":"Mr"},"show_roster_summary_on_payslip":{"type":"boolean","title":"Show Roster Summary On Payslip","description":"Whether to show the roster summary on the payslip.","example":false},"show_position_on_payslip":{"type":"boolean","title":"Show Position On Payslip","description":"Whether to show the employee's position on the payslip.","example":false},"show_department_on_payslip":{"type":"boolean","title":"Show Department On Payslip","description":"Whether to show the employee's department on the payslip.","example":false},"payslip_show_holiday_leave_balance":{"type":"boolean","title":"Payslip Show Holiday Leave Balance","description":"Whether to show the employee's holiday leave balance on the payslip.","example":false},"payslip_show_sick_leave_balance":{"type":"boolean","title":"Payslip Show Sick Leave Balance","description":"Whether to show the employee's sick leave balance on the payslip.","example":false},"payslip_show_lsl_balance":{"type":"boolean","title":"Payslip Show Lsl Balance","description":"Whether to show the employee's long service leave balance on the payslip.","example":false},"payslip_show_negative_leave_balances":{"type":"boolean","title":"Payslip Show Negative Leave Balances","description":"Whether to show negative leave balances on the payslip.","example":false},"payslip_show_custom_balances":{"type":"boolean","title":"Payslip Show Custom Balances","description":"Whether to show custom leave balances on the payslip.","example":false},"payslip_leave_units":{"type":"string","enum":["HOURS","DAYS"],"title":"Payslip Leave Units","description":"The unit of measurement for leave balances shown on the payslip. Valid values: HOURS, DAYS","example":"HOURS"},"payslip_show_hours_and_rate":{"type":"boolean","title":"Payslip Show Hours And Rate","description":"Whether to show hours worked and pay rate on the payslip.","example":false},"payslip_show_allowance_units":{"type":"boolean","title":"Payslip Show Allowance Units","description":"Whether to show allowance units on the payslip.","example":false},"payslip_show_base_ordinary_rate":{"type":"boolean","title":"Payslip Show Base Ordinary Rate","description":"Whether to show the base ordinary rate on the payslip.","example":false},"payslip_show_super_ytd":{"type":"boolean","title":"Payslip Show Super Ytd","description":"Whether to show the year-to-date superannuation contributions on the payslip.","example":false},"payslip_note":{"type":"string","title":"Payslip Note","description":"An added note to be displayed on each upcoming payslip for this employee.","example":"Thank you for your hard work!"},"payslip_show_ytd":{"type":"boolean","title":"Payslip Show Ytd","description":"Whether to show year-to-date totals on the payslip.","example":false},"payslip_show_zero_dollar_leave":{"type":"boolean","title":"Payslip Show Zero Dollar Leave","description":"Whether to show zero dollar leave balances on the payslip.","example":false},"payslip_time_non_decimal":{"type":"boolean","title":"Payslip Time Non Decimal","description":"Whether to show time in non-decimal format (e.g., 1:30 instead of 1.5 hours) on the payslip.","example":false},"primary_bank_bsb":{"type":"string","pattern":"$|^\\d{3}-\\d{3}$","title":"Primary Bank Bsb","example":"987-654"},"primary_bank_account_number":{"type":"string","maxLength":12,"title":"Primary Bank Account Number","example":"87654321"},"primary_bank_account_name":{"type":"string","maxLength":32,"minLength":0,"title":"Primary Bank Account Name","example":"John Smith"},"secondary_bank_bsb":{"type":"string","pattern":"$|^\\d{3}-\\d{3}$","title":"Secondary Bank Bsb","example":"123-456"},"secondary_bank_account_number":{"type":"string","maxLength":12,"title":"Secondary Bank Account Number","example":"12345678"},"secondary_bank_account_name":{"type":"string","maxLength":32,"minLength":0,"title":"Secondary Bank Account Name","example":"John Smith"},"secondary_bank_reference":{"type":"string","maxLength":18,"minLength":0,"title":"Secondary Bank Reference","example":"Child Support"},"secondary_bank_amount_per_period":{"type":"number","title":"Secondary Bank Amount Per Period","description":"Amount to be paid to the secondary bank account per pay period. Remaining pay will be paid to the primary bank account.","example":"100.00"},"default_employee_fund_member_number":{"type":"string","maxLength":20,"title":"Default Employee Fund Member Number","example":"12345678"},"default_employee_fund_usi":{"type":"string","maxLength":20,"title":"Default Employee Fund Usi","example":"STA0100AU"},"super_rate":{"type":"number","title":"Super Rate","description":"Total superannuation rate used on the employee's upcoming pays, expressed as a decimal (e.g., 0.115 for 11.5%). This is the rate applied to the employee's ordinary time earnings for superannuation contributions. Any excess above the compulsory_super_rate is categorised as RESC (Reportable Employer Super Contributions).","example":"0.115"},"compulsory_super_rate":{"type":"number","title":"Compulsory Super Rate","description":"Compulsory superannuation rate used on the employee's upcoming pays, expressed as a decimal (e.g., 0.105 for 10.5%). This is the minimum rate required by law for superannuation contributions.","example":"0.105"},"is_super_enabled":{"type":"boolean","title":"Is Super Enabled","description":"Whether superannuation contributions are enabled for this employee. If False, no super calculations will be performed for this employee, regardless of the super_rate or compulsory_super_rate settings.","example":true},"is_super_age_threshold_enabled":{"type":"boolean","title":"Is Super Age Threshold Enabled","description":"Whether the superannuation age threshold is enabled for this employee. If True, the employee's age will be considered when calculating super contributions. If False, the employee's age will not affect super calculations.","example":true},"super_based_on":{"type":"string","enum":["OTE","GROSS"],"title":"Super Based On","description":"The basis for superannuation calculations for this employee. Valid values: OTE (Ordinary Time Earnings, recommended) or GROSS (Gross Pay). If OTE, super is calculated based on the employee's ordinary time earnings. If GROSS, super is calculated based on the employee's gross pay.","example":"OTE"},"kiwisaver_employee_rate":{"type":"number","title":"Kiwisaver Employee Rate","description":"Employee KiwiSaver contribution rate. NZ only.","example":"0.03"},"kiwisaver_employer_rate":{"type":"number","title":"Kiwisaver Employer Rate","description":"Employer KiwiSaver contribution rate. NZ only.","example":"0.03"},"kiwisaver_status_code":{"type":"string","title":"Kiwisaver Status Code","description":"KiwiSaver status code. NZ only.","example":"KS"},"kiwisaver_existing_action":{"type":"string","title":"Kiwisaver Existing Action","description":"KiwiSaver existing member action. NZ only.","example":"EXISTING_MEMBER"},"esct_rate":{"type":"number","title":"Esct Rate","description":"Employer superannuation contribution tax rate. NZ only.","example":"0.105"},"employer_contrib_tax_method":{"type":"string","title":"Employer Contrib Tax Method","description":"NZ employer contribution tax method.","example":"ESCT"},"employer_contrib_paye_fraction":{"type":"number","title":"Employer Contrib Paye Fraction","description":"NZ employer contribution PAYE fraction.","example":"0.0"},"kiwisaver_cec_obligation":{"type":"string","title":"Kiwisaver Cec Obligation","description":"KiwiSaver CEC obligation. NZ only.","example":"NONE"},"is_leave_enabled":{"type":"boolean","title":"Is Leave Enabled","description":"Whether leave calculations are enabled for this employee. If False, no leave accruals will be calculated for this employee.","example":true},"include_leave_loading_in_super":{"type":"boolean","title":"Include Leave Loading In Super","description":"Whether to include leave loading in superannuation calculations for this employee. If True, leave loading will be included in the superannuation contributions. If False, leave loading will not be included in super calculations.","example":false},"accrue_leave_on_hours_worked":{"type":"boolean","title":"Accrue Leave On Hours Worked","description":"Whether to accrue leave based on hours worked (pro rata). If True, leave will be accrued based on the number of hours worked by the employee. If False, leave will be accrued by the pay period.","example":true},"accrue_leave_on_overtime_hours":{"type":"boolean","title":"Accrue Leave On Overtime Hours","description":"Whether to accrue leave based on overtime hours worked. If True, leave will be accrued based on the number of overtime hours worked by the employee. If False, overtime hours will not contribute to leave accruals.","example":false},"accrue_holiday_leave_per_hour":{"type":"number","title":"Accrue Holiday Leave Per Hour","description":"Holiday leave accrual rate per hour worked, expressed as a decimal (e.g., 0.076923 for 20 days per year). Used when both accrue_leave_on_hours_worked and is_leave_enabled are enabled. This is used to calculate the number of holiday leave hours accrued by the employee based on their hours worked.","example":"0.076923"},"accrue_sick_leave_per_hour":{"type":"number","title":"Accrue Sick Leave Per Hour","description":"Sick leave accrual rate per hour worked, expressed as a decimal (e.g., 0.038462 for 10 days per year). Used when both accrue_leave_on_hours_worked and is_leave_enabled are enabled. This is used to calculate the number of sick leave hours accrued by the employee based on their hours worked.","example":"0.038462"},"accrue_lsl_per_hour":{"type":"number","title":"Accrue Lsl Per Hour","description":"Long Service Leave (LSL) accrual rate per hour worked, expressed as a decimal (e.g., 0.016667 for 8.6667 weeks per 10 years; 0.025 for SA/NT's 13 weeks). The per-state default is derived from the lump entitlement (weeks/years/52). Used when both accrue_leave_on_hours_worked and is_leave_enabled are enabled. This is used to calculate the number of LSL hours accrued by the employee based on their hours worked.","example":"0.016667"},"num_sick_leave_days_per_year":{"type":"integer","title":"Num Sick Leave Days Per Year","description":"Number of personal/sick days per year for the employee. This is used to calculate the number of personal leave hours accrued by the employee based on their hours worked.","example":10},"num_holiday_leave_days_per_year":{"type":"integer","title":"Num Holiday Leave Days Per Year","description":"Number of annual/holiday days per year for the employee. This is used to calculate the number of holiday leave hours accrued by the employee based on their hours worked.","example":20},"is_lsl_enabled":{"type":"boolean","title":"Is Lsl Enabled","description":"Whether Long Service Leave (LSL) calculations are enabled for this employee. If False, no LSL accruals will be calculated for this employee.","example":true},"lsl_x_years":{"type":"integer","title":"Lsl X Years","description":"Number of years of service required to qualify for Long Service Leave (LSL). This is used to determine when the employee is eligible for LSL based on their length of service.","example":10},"lsl_accrued_x_years":{"type":"integer","title":"Lsl Accrued X Years","description":"Number of weeks LSL accrued for every lsl_x_years years of service. This is used to calculate the number of LSL hours accrued by the employee based on their length of service.","example":10},"hourly_amount_for_workers_comp_leave":{"type":"number","title":"Hourly Amount For Workers Comp Leave","example":"25.50"},"hourly_amount_for_paid_parental_leave":{"type":"number","title":"Hourly Amount For Paid Parental Leave","example":"30.75"},"rdo_hours":{"type":"number","title":"Rdo Hours","description":"Total hours of Rostered Days Off (RDOs) accrued by the employee as at their most recent pay.","example":"55.42"},"toil_hours":{"type":"number","title":"Toil Hours","description":"Total hours of Time Off In Lieu (TOIL) accrued by the employee as at their most recent pay.","example":"20.00"}},"additionalProperties":false,"type":"object","required":["first_name","last_name","date_of_birth","address1","city","state","country","postcode","start_date","employment_status"],"title":"EmployeeCreate","description":"Payload required when *creating* an employee.","example":{"tax_file_number":"111111111","first_name":"Alice","last_name":"Smith","date_of_birth":"1990-01-01","address1":"123 Example Street","city":"Sydney","state":"NSW","country":"AU","postcode":"2000","start_date":"2024-07-01","employment_status":"Full time","is_foreign_resident":false,"is_closely_held":false,"is_super_only_contractor":false,"has_claimed_tax_free_threshold":true,"has_stsl_liability":false}},"EmployeeIDPays":{"properties":{"employee_id":{"type":"integer","title":"Employee Id"},"pays":{"items":{"$ref":"#/components/schemas/Pay"},"type":"array","minItems":0,"title":"Pays"}},"type":"object","required":["employee_id","pays"],"title":"EmployeeIDPays"},"EmployeeNumberPays":{"properties":{"employee_number":{"type":"string","title":"Employee Number"},"pays":{"items":{"$ref":"#/components/schemas/Pay"},"type":"array","minItems":0,"title":"Pays"}},"type":"object","required":["employee_number","pays"],"title":"EmployeeNumberPays"},"EmployeePayRateCategorySet":{"properties":{"system":{"items":{"$ref":"#/components/schemas/EmployeePayRateOption"},"type":"array","title":"System","description":"System-generated rates based on employee pay_rate_per_hour."},"employee":{"items":{"$ref":"#/components/schemas/EmployeePayRateOption"},"type":"array","title":"Employee","description":"Employee-specific pay rates."},"company":{"items":{"$ref":"#/components/schemas/EmployeePayRateOption"},"type":"array","title":"Company","description":"Company pay rates linked to this employee."}},"type":"object","title":"EmployeePayRateCategorySet"},"EmployeePayRateOption":{"properties":{"reference":{"type":"string","title":"Reference","description":"Stable identifier for this rate option. Format examples: 'system:ordinary_time', 'employee:123', 'company:456'.","example":"employee:42"},"source":{"type":"string","enum":["system","employee","company"],"title":"Source","description":"The category this rate belongs to.","example":"employee"},"id":{"type":"integer","title":"Id","description":"Database id for employee/company rates. Null for system rates.","example":42},"description":{"type":"string","title":"Description","description":"Rate description shown to users.","example":"Ordinary Time"},"rate":{"type":"number","title":"Rate","description":"Resolved decimal rate value for the employee.","example":"30.00000"},"units":{"type":"string","title":"Units","description":"Units for this rate (for example Hours, kms, sheep).","example":"Hours"},"is_overtime":{"type":"boolean","title":"Is Overtime","description":"Whether this rate is treated as overtime.","default":false,"example":false},"display_label":{"type":"string","title":"Display Label","description":"Convenience label in the UI-friendly format 'Description ($rate)'.","example":"Ordinary Time ($30.00000)"}},"type":"object","required":["reference","source","description","rate","display_label"],"title":"EmployeePayRateOption"},"EmployeePayRatesResponse":{"properties":{"employee_id":{"type":"integer","title":"Employee Id","description":"The LP employee id this rate list was generated for.","example":1234},"rates":{"allOf":[{"$ref":"#/components/schemas/EmployeePayRateCategorySet"}],"title":"Rates","description":"Rates grouped by category."},"all":{"items":{"$ref":"#/components/schemas/EmployeePayRateOption"},"type":"array","title":"All","description":"Flat list of all rate options (system + employee + company)."},"duplicate_descriptions":{"items":{"type":"string"},"type":"array","title":"Duplicate Descriptions","description":"Descriptions that appear more than once (case-insensitive) across categories. If non-empty, API consumers should prefer 'reference' over description matching."}},"type":"object","required":["employee_id","rates"],"title":"EmployeePayRatesResponse"},"EmployeeResult":{"properties":{"employee":{"allOf":[{"$ref":"#/components/schemas/Employee"}],"title":"Employee","description":"The employee object if creation succeeded.","example":{"id":123,"first_name":"Alice","last_name":"Smith","email":"alice@example.com"}},"errors":{"additionalProperties":{"type":"string"},"type":"object","title":"Errors","description":"Field-level validation or creation errors, if any.","example":{"email":"Invalid email address","tax_file_number":"Duplicate TFN"}}},"type":"object","title":"EmployeeResult"},"EmployeeUpdate":{"properties":{"is_super_only_contractor":{"type":"boolean","title":"Is Super Only Contractor","description":"Australia only. Whether the employee is a contractor paid super only (no TFN, excluded from STP, PAYG and payment summaries).","example":false},"tax_file_number":{"type":"string","title":"Tax File Number","example":"123456789"},"ird_number":{"type":"string","title":"Ird Number","description":"IRD number. NZ only.","example":"49091850"},"nz_tax_code":{"type":"string","title":"Nz Tax Code","description":"NZ tax code. NZ only.","example":"M"},"first_name":{"type":"string","maxLength":60,"minLength":0,"title":"First Name","example":"John"},"middle_name":{"type":"string","maxLength":60,"minLength":0,"title":"Middle Name","example":"Richard"},"last_name":{"type":"string","maxLength":60,"minLength":0,"title":"Last Name","example":"Smith"},"date_of_birth":{"type":"string","pattern":"^$|^\\d{4}-\\d{2}-\\d{2}$","title":"Date Of Birth","example":"1985-07-15"},"address1":{"type":"string","maxLength":100,"minLength":0,"title":"Address1","example":"123 Elm St"},"address2":{"type":"string","maxLength":100,"minLength":0,"title":"Address2","example":"123 Elm St"},"city":{"type":"string","maxLength":60,"minLength":0,"title":"City","example":"Sydney"},"state":{"type":"string","maxLength":3,"minLength":2,"title":"State","example":"NSW"},"country":{"type":"string","maxLength":2,"title":"Country","example":"AU"},"postcode":{"type":"string","pattern":"^\\d{4}$","title":"Postcode","example":"2000"},"email_address":{"type":"string","format":"email","title":"Email Address","description":"Email address of the employee.","example":"tonytiger@gmail.com"},"phone_home":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Phone Home","description":"Home phone number of the employee.","example":"02 1234 5678"},"phone_mobile":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Phone Mobile","description":"Mobile phone number of the employee.","example":"0412 345 678"},"phone_medical":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Phone Medical","description":"Medical contact phone number of the employee.","example":"02 8765 4321"},"gender":{"type":"string","enum":["MALE","FEMALE","INDETERMINATE","UNKNOWN"],"title":"Gender","description":"Gender of the employee. Must be one of MALE, FEMALE, INDETERMINATE, or UNKNOWN.","example":"MALE"},"kin_name":{"type":"string","maxLength":60,"minLength":0,"title":"Kin Name","description":"Name of the next of kin.","example":"Jane Smith"},"kin_relationship":{"type":"string","maxLength":60,"minLength":0,"title":"Kin Relationship","description":"Relationship of the next of kin to the employee.","example":"Sister"},"kin_address1":{"type":"string","maxLength":100,"minLength":0,"title":"Kin Address1","description":"Address line 1 of the next of kin.","example":"456 Oak St"},"kin_address2":{"type":"string","maxLength":100,"minLength":0,"title":"Kin Address2","description":"Address line 2 of the next of kin.","example":"Apt 5B"},"kin_city":{"type":"string","maxLength":60,"minLength":0,"title":"Kin City","description":"City of the next of kin.","example":"Melbourne"},"kin_state":{"type":"string","maxLength":3,"minLength":2,"title":"Kin State","description":"State of the next of kin.","example":"VIC"},"kin_postcode":{"type":"string","pattern":"^\\d{4}$","title":"Kin Postcode","description":"Postcode of the next of kin.","example":"3000"},"kin_phone_home":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Kin Phone Home","description":"Home phone number of the next of kin.","example":"03 1234 5678"},"kin_phone_work":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Kin Phone Work","description":"Work phone number of the next of kin.","example":"03 8765 4321"},"kin_phone_mobile":{"type":"string","pattern":"$|^[0-9 +()-]{8,15}$","title":"Kin Phone Mobile","description":"Mobile phone number of the next of kin.","example":"0412 345 678"},"kin_notes":{"type":"string","title":"Kin Notes","description":"Additional notes about the next of kin.","example":"Emergency contact"},"pay_method":{"type":"string","enum":["CASH","DIRECT BANK ENTRY","OTHER"],"title":"Pay Method","description":"The method of payment for the employee.","default":"DIRECT BANK ENTRY","example":"CASH"},"pay_period":{"type":"string","enum":["WEEKLY","FORTNIGHTLY","MONTHLY"],"title":"Pay Period","description":"The pay period frequency for the employee. Valid values: WEEKLY, FORTNIGHTLY, MONTHLY","default":"WEEKLY","example":"WEEKLY"},"pay_rate_per_hour":{"type":"number","title":"Pay Rate Per Hour","description":"Hourly pay rate for the employee. This is used to calculate the employee's gross pay based on hours worked.","example":"25.00"},"standard_hours_per_day":{"type":"number","title":"Standard Hours Per Day","example":"7.6"},"standard_days_per_week":{"type":"integer","title":"Standard Days Per Week","description":"Number of standard working days per week for the employee. This is used to calculate leave accruals and RDOs.","example":"5"},"stp_employment_status":{"type":"string","enum":["C","P","F"],"title":"Stp Employment Status","description":"The employment status of the employee for Single Touch Payroll (STP) reporting. Valid values: C, P, F. This is used to determine how the employee's earnings are reported to the ATO.","default":"F","example":"F"},"active_pay_recipient":{"type":"boolean","title":"Active Pay Recipient","description":"Whether the employee is an active pay recipient. If False, the employee will not have pending pays generated for them, but they will still count towards licence limits and be included in reports. This is useful for employees who are on leave or not currently receiving pay but are not terminated.","example":true},"start_date":{"type":"string","pattern":"^$|^\\d{4}-\\d{2}-\\d{2}$","title":"Start Date","example":"2025-06-04"},"employment_status":{"type":"string","pattern":"(?i)^(full[-\\s]?time|part[-\\s]?time|casual|labour[\\s-]?hire)$","title":"Employment Status","description":"Employment status. One of 'Full-time', 'Part-time', 'Casual', or 'Labour Hire' (matched case-insensitively; hyphen/space tolerant). Sets the employee's STP employment status and the default leave / long-service-leave accrual configuration.","example":"Full-time"},"tfnd_signed_date":{"type":"string","pattern":"^$|^\\d{4}-\\d{2}-\\d{2}$","title":"Tfnd Signed Date","description":"Date the employee signed the TFN declaration.","example":"2025-06-04"},"is_foreign_resident":{"type":"boolean","title":"Is Foreign Resident"},"is_closely_held":{"type":"boolean","title":"Is Closely Held","description":"Whether the employee is a closely held employee. Closely held employees are typically family members of the business owner or directors of the company.","example":false},"has_claimed_tax_free_threshold":{"type":"boolean","title":"Has Claimed Tax Free Threshold"},"has_stsl_liability":{"type":"boolean","title":"Has Stsl Liability"},"has_student_loan":{"type":"boolean","title":"Has Student Loan","description":"Whether the employee has an NZ student loan. NZ only.","example":false},"no_declaration":{"type":"boolean","title":"No Declaration","description":"Whether the employee is using NZ non-declaration handling. NZ only.","example":false},"include_email_and_phone_in_stp":{"type":"boolean","title":"Include Email And Phone In Stp","description":"Whether to include the employee's email address and phone number in STP reports sent to the ATO. Defaults to False if not set.","example":false},"abn":{"type":"string","title":"Abn","description":"Australian Business Number (ABN) of the employee, if applicable. Required for non-standard employees who bill as contractors.","example":"12345678901"},"working_holiday_tax_scale_applies":{"type":"boolean","title":"Working Holiday Tax Scale Applies","description":"Whether the employee is subject to the Working Holiday Maker tax scale. If True, the employee's tax calculations will use the WHM tax scale instead of the standard tax scale.","example":false},"leave_loading_percentage":{"type":"number","title":"Leave Loading Percentage","description":"Leave loading percentage, e.g. 0.175 for 17.5%","example":"0.175"},"position":{"type":"string","maxLength":60,"minLength":0,"title":"Position","description":"Position or job title of the employee.","example":"Manager"},"employee_portal_active":{"type":"boolean","title":"Employee Portal Active","description":"Whether the employee has access to the online portal.","example":false},"allow_edit_timesheet":{"type":"boolean","title":"Allow Edit Timesheet","description":"Whether the employee is allowed to edit their own timesheets in the online portal.","example":false},"allow_edit_timeclock":{"type":"boolean","title":"Allow Edit Timeclock","description":"Whether the employee is allowed to use the timeclock in the online portal.","example":false},"allow_edit_account_details":{"type":"boolean","title":"Allow Edit Account Details","description":"Whether the employee is allowed to edit their own personal details in the online portal.","example":false},"allow_edit_tax_settings":{"type":"boolean","title":"Allow Edit Tax Settings","description":"Whether the employee is allowed to edit their tax settings in the online portal.","example":false},"allow_edit_bank_accounts":{"type":"boolean","title":"Allow Edit Bank Accounts","description":"Whether the employee is allowed to edit their own bank account details in the online portal.","example":false},"allow_edit_super_details":{"type":"boolean","title":"Allow Edit Super Details","description":"Whether the employee is allowed to edit their super details in the online portal.","example":false},"allow_edit_leave_requests":{"type":"boolean","title":"Allow Edit Leave Requests","description":"Whether the employee is allowed to make leave requests through the online portal.","example":false},"allow_edit_leave_requests_when_negative":{"type":"boolean","title":"Allow Edit Leave Requests When Negative","description":"Whether the employee is allowed to make leave requests even when they have, or will reach, a negative leave balance.","example":false},"allow_view_holiday_leave_balance":{"type":"boolean","title":"Allow View Holiday Leave Balance","description":"Whether the employee is allowed to view their holiday leave balance in the online portal.","example":false},"allow_view_sick_leave_balance":{"type":"boolean","title":"Allow View Sick Leave Balance","description":"Whether the employee is allowed to view their sick leave balance in the online portal.","example":false},"allow_view_long_service_leave_balance":{"type":"boolean","title":"Allow View Long Service Leave Balance","description":"Whether the employee is allowed to view their long service leave balance in the online portal.","example":false},"allow_view_payslips":{"type":"boolean","title":"Allow View Payslips","description":"Whether the employee is allowed to view their payslips in the online portal.","example":false},"department":{"type":"string","maxLength":60,"minLength":0,"title":"Department","example":"Human Resources"},"number":{"type":"string","maxLength":60,"minLength":0,"title":"Number","description":"User-controlled unique employee payroll number/code. This is not the same as the internal database ID.","example":"EMP001"},"honorific":{"type":"string","maxLength":18,"minLength":0,"title":"Honorific","description":"Honorific title for the employee (e.g., Mr, Ms, Dr).","example":"Mr"},"show_roster_summary_on_payslip":{"type":"boolean","title":"Show Roster Summary On Payslip","description":"Whether to show the roster summary on the payslip.","example":false},"show_position_on_payslip":{"type":"boolean","title":"Show Position On Payslip","description":"Whether to show the employee's position on the payslip.","example":false},"show_department_on_payslip":{"type":"boolean","title":"Show Department On Payslip","description":"Whether to show the employee's department on the payslip.","example":false},"payslip_show_holiday_leave_balance":{"type":"boolean","title":"Payslip Show Holiday Leave Balance","description":"Whether to show the employee's holiday leave balance on the payslip.","example":false},"payslip_show_sick_leave_balance":{"type":"boolean","title":"Payslip Show Sick Leave Balance","description":"Whether to show the employee's sick leave balance on the payslip.","example":false},"payslip_show_lsl_balance":{"type":"boolean","title":"Payslip Show Lsl Balance","description":"Whether to show the employee's long service leave balance on the payslip.","example":false},"payslip_show_negative_leave_balances":{"type":"boolean","title":"Payslip Show Negative Leave Balances","description":"Whether to show negative leave balances on the payslip.","example":false},"payslip_show_custom_balances":{"type":"boolean","title":"Payslip Show Custom Balances","description":"Whether to show custom leave balances on the payslip.","example":false},"payslip_leave_units":{"type":"string","enum":["HOURS","DAYS"],"title":"Payslip Leave Units","description":"The unit of measurement for leave balances shown on the payslip. Valid values: HOURS, DAYS","example":"HOURS"},"payslip_show_hours_and_rate":{"type":"boolean","title":"Payslip Show Hours And Rate","description":"Whether to show hours worked and pay rate on the payslip.","example":false},"payslip_show_allowance_units":{"type":"boolean","title":"Payslip Show Allowance Units","description":"Whether to show allowance units on the payslip.","example":false},"payslip_show_base_ordinary_rate":{"type":"boolean","title":"Payslip Show Base Ordinary Rate","description":"Whether to show the base ordinary rate on the payslip.","example":false},"payslip_show_super_ytd":{"type":"boolean","title":"Payslip Show Super Ytd","description":"Whether to show the year-to-date superannuation contributions on the payslip.","example":false},"payslip_note":{"type":"string","title":"Payslip Note","description":"An added note to be displayed on each upcoming payslip for this employee.","example":"Thank you for your hard work!"},"payslip_show_ytd":{"type":"boolean","title":"Payslip Show Ytd","description":"Whether to show year-to-date totals on the payslip.","example":false},"payslip_show_zero_dollar_leave":{"type":"boolean","title":"Payslip Show Zero Dollar Leave","description":"Whether to show zero dollar leave balances on the payslip.","example":false},"payslip_time_non_decimal":{"type":"boolean","title":"Payslip Time Non Decimal","description":"Whether to show time in non-decimal format (e.g., 1:30 instead of 1.5 hours) on the payslip.","example":false},"primary_bank_bsb":{"type":"string","pattern":"$|^\\d{3}-\\d{3}$","title":"Primary Bank Bsb","example":"987-654"},"primary_bank_account_number":{"type":"string","maxLength":12,"title":"Primary Bank Account Number","example":"87654321"},"primary_bank_account_name":{"type":"string","maxLength":32,"minLength":0,"title":"Primary Bank Account Name","example":"John Smith"},"secondary_bank_bsb":{"type":"string","pattern":"$|^\\d{3}-\\d{3}$","title":"Secondary Bank Bsb","example":"123-456"},"secondary_bank_account_number":{"type":"string","maxLength":12,"title":"Secondary Bank Account Number","example":"12345678"},"secondary_bank_account_name":{"type":"string","maxLength":32,"minLength":0,"title":"Secondary Bank Account Name","example":"John Smith"},"secondary_bank_reference":{"type":"string","maxLength":18,"minLength":0,"title":"Secondary Bank Reference","example":"Child Support"},"secondary_bank_amount_per_period":{"type":"number","title":"Secondary Bank Amount Per Period","description":"Amount to be paid to the secondary bank account per pay period. Remaining pay will be paid to the primary bank account.","example":"100.00"},"default_employee_fund_member_number":{"type":"string","maxLength":20,"title":"Default Employee Fund Member Number","example":"12345678"},"default_employee_fund_usi":{"type":"string","maxLength":20,"title":"Default Employee Fund Usi","example":"STA0100AU"},"super_rate":{"type":"number","title":"Super Rate","description":"Total superannuation rate used on the employee's upcoming pays, expressed as a decimal (e.g., 0.115 for 11.5%). This is the rate applied to the employee's ordinary time earnings for superannuation contributions. Any excess above the compulsory_super_rate is categorised as RESC (Reportable Employer Super Contributions).","example":"0.115"},"compulsory_super_rate":{"type":"number","title":"Compulsory Super Rate","description":"Compulsory superannuation rate used on the employee's upcoming pays, expressed as a decimal (e.g., 0.105 for 10.5%). This is the minimum rate required by law for superannuation contributions.","example":"0.105"},"is_super_enabled":{"type":"boolean","title":"Is Super Enabled","description":"Whether superannuation contributions are enabled for this employee. If False, no super calculations will be performed for this employee, regardless of the super_rate or compulsory_super_rate settings.","example":true},"is_super_age_threshold_enabled":{"type":"boolean","title":"Is Super Age Threshold Enabled","description":"Whether the superannuation age threshold is enabled for this employee. If True, the employee's age will be considered when calculating super contributions. If False, the employee's age will not affect super calculations.","example":true},"super_based_on":{"type":"string","enum":["OTE","GROSS"],"title":"Super Based On","description":"The basis for superannuation calculations for this employee. Valid values: OTE (Ordinary Time Earnings, recommended) or GROSS (Gross Pay). If OTE, super is calculated based on the employee's ordinary time earnings. If GROSS, super is calculated based on the employee's gross pay.","example":"OTE"},"kiwisaver_employee_rate":{"type":"number","title":"Kiwisaver Employee Rate","description":"Employee KiwiSaver contribution rate. NZ only.","example":"0.03"},"kiwisaver_employer_rate":{"type":"number","title":"Kiwisaver Employer Rate","description":"Employer KiwiSaver contribution rate. NZ only.","example":"0.03"},"kiwisaver_status_code":{"type":"string","title":"Kiwisaver Status Code","description":"KiwiSaver status code. NZ only.","example":"KS"},"kiwisaver_existing_action":{"type":"string","title":"Kiwisaver Existing Action","description":"KiwiSaver existing member action. NZ only.","example":"EXISTING_MEMBER"},"esct_rate":{"type":"number","title":"Esct Rate","description":"Employer superannuation contribution tax rate. NZ only.","example":"0.105"},"employer_contrib_tax_method":{"type":"string","title":"Employer Contrib Tax Method","description":"NZ employer contribution tax method.","example":"ESCT"},"employer_contrib_paye_fraction":{"type":"number","title":"Employer Contrib Paye Fraction","description":"NZ employer contribution PAYE fraction.","example":"0.0"},"kiwisaver_cec_obligation":{"type":"string","title":"Kiwisaver Cec Obligation","description":"KiwiSaver CEC obligation. NZ only.","example":"NONE"},"is_leave_enabled":{"type":"boolean","title":"Is Leave Enabled","description":"Whether leave calculations are enabled for this employee. If False, no leave accruals will be calculated for this employee.","example":true},"include_leave_loading_in_super":{"type":"boolean","title":"Include Leave Loading In Super","description":"Whether to include leave loading in superannuation calculations for this employee. If True, leave loading will be included in the superannuation contributions. If False, leave loading will not be included in super calculations.","example":false},"accrue_leave_on_hours_worked":{"type":"boolean","title":"Accrue Leave On Hours Worked","description":"Whether to accrue leave based on hours worked (pro rata). If True, leave will be accrued based on the number of hours worked by the employee. If False, leave will be accrued by the pay period.","example":true},"accrue_leave_on_overtime_hours":{"type":"boolean","title":"Accrue Leave On Overtime Hours","description":"Whether to accrue leave based on overtime hours worked. If True, leave will be accrued based on the number of overtime hours worked by the employee. If False, overtime hours will not contribute to leave accruals.","example":false},"accrue_holiday_leave_per_hour":{"type":"number","title":"Accrue Holiday Leave Per Hour","description":"Holiday leave accrual rate per hour worked, expressed as a decimal (e.g., 0.076923 for 20 days per year). Used when both accrue_leave_on_hours_worked and is_leave_enabled are enabled. This is used to calculate the number of holiday leave hours accrued by the employee based on their hours worked.","example":"0.076923"},"accrue_sick_leave_per_hour":{"type":"number","title":"Accrue Sick Leave Per Hour","description":"Sick leave accrual rate per hour worked, expressed as a decimal (e.g., 0.038462 for 10 days per year). Used when both accrue_leave_on_hours_worked and is_leave_enabled are enabled. This is used to calculate the number of sick leave hours accrued by the employee based on their hours worked.","example":"0.038462"},"accrue_lsl_per_hour":{"type":"number","title":"Accrue Lsl Per Hour","description":"Long Service Leave (LSL) accrual rate per hour worked, expressed as a decimal (e.g., 0.016667 for 8.6667 weeks per 10 years; 0.025 for SA/NT's 13 weeks). The per-state default is derived from the lump entitlement (weeks/years/52). Used when both accrue_leave_on_hours_worked and is_leave_enabled are enabled. This is used to calculate the number of LSL hours accrued by the employee based on their hours worked.","example":"0.016667"},"num_sick_leave_days_per_year":{"type":"integer","title":"Num Sick Leave Days Per Year","description":"Number of personal/sick days per year for the employee. This is used to calculate the number of personal leave hours accrued by the employee based on their hours worked.","example":10},"num_holiday_leave_days_per_year":{"type":"integer","title":"Num Holiday Leave Days Per Year","description":"Number of annual/holiday days per year for the employee. This is used to calculate the number of holiday leave hours accrued by the employee based on their hours worked.","example":20},"is_lsl_enabled":{"type":"boolean","title":"Is Lsl Enabled","description":"Whether Long Service Leave (LSL) calculations are enabled for this employee. If False, no LSL accruals will be calculated for this employee.","example":true},"lsl_x_years":{"type":"integer","title":"Lsl X Years","description":"Number of years of service required to qualify for Long Service Leave (LSL). This is used to determine when the employee is eligible for LSL based on their length of service.","example":10},"lsl_accrued_x_years":{"type":"integer","title":"Lsl Accrued X Years","description":"Number of weeks LSL accrued for every lsl_x_years years of service. This is used to calculate the number of LSL hours accrued by the employee based on their length of service.","example":10},"hourly_amount_for_workers_comp_leave":{"type":"number","title":"Hourly Amount For Workers Comp Leave","example":"25.50"},"hourly_amount_for_paid_parental_leave":{"type":"number","title":"Hourly Amount For Paid Parental Leave","example":"30.75"},"rdo_hours":{"type":"number","title":"Rdo Hours","description":"Total hours of Rostered Days Off (RDOs) accrued by the employee as at their most recent pay.","example":"55.42"},"toil_hours":{"type":"number","title":"Toil Hours","description":"Total hours of Time Off In Lieu (TOIL) accrued by the employee as at their most recent pay.","example":"20.00"},"id":{"type":"integer","title":"Id","description":"Internal Lightning Payroll employee id"},"delete_non_rdo_and_toil_leave_items":{"type":"boolean","title":"Delete Non Rdo And Toil Leave Items","description":"If True, all non-RDO and non-TOIL leave items will be deleted from the employee's leave balances. This is useful for resetting leave balances when an employee's leave settings have been potentially misconfigured.","example":false}},"additionalProperties":false,"type":"object","required":["id"],"title":"EmployeeUpdate","description":"Payload for *partial* updates (PATCH). Only id is mandatory."},"FaqItem":{"properties":{"id":{"type":"integer","title":"Id","description":"Stable FAQ identifier.","example":123},"category":{"type":"string","title":"Category","description":"FAQ category/grouping.","example":"Single Touch Payroll"},"heading":{"type":"string","title":"Heading","description":"FAQ title.","example":"How do I lodge STP?"},"message":{"type":"string","title":"Message","description":"FAQ body. Basic HTML by default; see the request 'format' arg.","example":"<p>Open the STP screen and ...</p>"},"tags":{"type":"string","title":"Tags","description":"Comma/space separated tags, if any.","example":"stp,reporting"},"site_mode":{"type":"string","title":"Site Mode","description":"Region this FAQ belongs to ('au' or 'nz').","example":"au"},"created":{"type":"string","format":"date-time","title":"Created","description":"When the FAQ was first created (UTC server time)."},"last_edited":{"type":"string","format":"date-time","title":"Last Edited","description":"When the FAQ was last edited."}},"type":"object","required":["id","category","heading","message","site_mode"],"title":"FaqItem"},"FaqListResponse":{"properties":{"site_mode":{"type":"string","title":"Site Mode","description":"Echo of the requested site mode.","example":"au"},"format":{"type":"string","title":"Format","description":"Echo of the requested body format ('raw'|'text'|'sanitized').","example":"raw"},"count":{"type":"integer","title":"Count","description":"Number of FAQ items returned in this page.","example":12},"total":{"type":"integer","title":"Total","description":"Total active FAQs matching the filters (ignoring limit/offset).","example":37},"limit":{"type":"integer","title":"Limit","description":"The limit applied.","example":50},"offset":{"type":"integer","title":"Offset","description":"The offset applied.","example":0},"faqs":{"items":{"$ref":"#/components/schemas/FaqItem"},"type":"array","title":"Faqs","description":"The FAQ items for this page, newest first."}},"type":"object","required":["site_mode","format","count","total","limit","offset","faqs"],"title":"FaqListResponse"},"GLPosting":{"properties":{"account_id":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Account Id","description":"The account identifier associated with the GL posting.","example":"00-00-0001"},"description":{"type":"string","title":"Description","description":"A brief description of the GL posting.","example":"Gross Wages"},"amount":{"type":"number","title":"Amount","description":"The monetary amount for the GL posting. Positive for debits, negative for credits.","example":"1500.00"},"date":{"type":"string","title":"Date","description":"The date of the GL posting in DD/MM/YYYY format.","example":"14/01/2025"}},"type":"object","required":["account_id","description","amount","date"],"title":"GLPosting"},"GLPostingsResponse":{"properties":{"pay_run_id":{"type":"integer","title":"Pay Run Id","description":"The unique LP-generated ID of the pay run.","example":1},"postings":{"items":{"$ref":"#/components/schemas/GLPosting"},"type":"array","title":"Postings","description":"A list of GL postings associated with the specified pay run."}},"type":"object","required":["pay_run_id","postings"],"title":"GLPostingsResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HoursOut":{"properties":{"description":{"type":"string","maxLength":60,"minLength":1,"title":"Description","example":"Ordinary Time"},"rate":{"type":"number","title":"Rate","description":"The dollar amount per unit for this hours row. Provide either `rate` or `multiplier`.","example":"30.00"},"multiplier":{"type":"number","title":"Multiplier","description":"Alternative to `rate`. Multiplies the employee's pay_rate_per_hour (e.g., 1.5 for time-and-a-half, 2.0 for double time).","example":"1.5"},"rate_reference":{"type":"string","title":"Rate Reference","description":"Optional stable pay-rate reference from `GET /api/employees/{employee_id}/pay-rates` (for example `system:ordinary_time`, `employee:42`, `company:73`). Use as an alternative to sending a raw `rate`.","example":"employee:42"},"rate_description":{"type":"string","maxLength":60,"minLength":0,"title":"Rate Description","description":"Optional pay-rate description to resolve a rate by description for this employee. Use when you do not send `rate`. If multiple rates share the same description, the API will return a validation error and require `rate_reference`.","example":"Ordinary Time"},"units":{"type":"string","maxLength":32,"minLength":0,"title":"Units","example":"hours"},"is_overtime":{"type":"boolean","title":"Is Overtime","default":false,"example":false},"value":{"type":"number","title":"Value","example":"37.5"},"id":{"type":"integer","title":"Id"},"pay_amount":{"type":"number","title":"Pay Amount","description":"The total amount for this pay hours row, calculated as rate * value.","example":"1125.00"}},"type":"object","required":["description","units","value","id","pay_amount"],"title":"HoursOut"},"Leave":{"properties":{"description":{"type":"string","maxLength":60,"minLength":1,"title":"Description","description":"A brief description of the leave.","example":"Annual Leave"},"leave_type":{"type":"string","title":"Leave Type","description":"A short identifier for the type of leave. Provide the code with underscores (e.g., ALT_HOLIDAY, ANCILLARY, ANNUAL_HOLIDAYS, COMPASSIONATE, EMPLOYER_FUNDED_PAID_PARENTAL, HOLIDAY, LONG_SERVICE, NZ_BEREAVEMENT, NZ_DEFENCE_FORCE, NZ_EMPLOYMENT_RELATIONS_EDUCATION, NZ_FAMILY_VIOLENCE, NZ_JURY_SERVICE, NZ_TIME_OFF_TO_VOTE, OTHER, PAID_PARENTAL, PAID_PUBLIC_HOLIDAY, SICK, UNPAID, WORKERS_COMP).","example":"HOLIDAY"},"rate":{"type":"number","title":"Rate","description":"The dollar amount per unit for this leave (e.g., hourly rate). Optional if using `multiplier` or to default to the employee's pay_rate_per_hour.","example":"38.00"},"multiplier":{"type":"number","title":"Multiplier","description":"Alternative to `rate`. Multiplies the employee's pay_rate_per_hour (e.g., 1.0 for base rate, 1.5 for time-and-a-half).","example":"1.0"},"date":{"type":"string","title":"Date","description":"The date of the leave.","example":"2023-01-01"},"hours":{"type":"number","title":"Hours","description":"The number of hours leave taken.","example":"7.6"},"leave_loading_amount":{"type":"number","title":"Leave Loading Amount","description":"The dollar amount of leave loading, if applicable.","example":"3.80"}},"additionalProperties":false,"type":"object","required":["description","leave_type","date","hours"],"title":"Leave"},"LeaveBalanceRow":{"properties":{"leave_type":{"type":"string","title":"Leave Type","description":"Short code or internal key for the leave type.","example":"HOLIDAY"},"name":{"type":"string","title":"Name","description":"User-facing name of the leave type.","example":"Annual Leave"},"hours":{"type":"number","title":"Hours","description":"Decimal quantity of leave hours remaining.","example":"32.0"}},"type":"object","required":["leave_type","name"],"title":"LeaveBalanceRow","description":"Return schema for leave balance objects exposed via the API."},"LeaveBase":{"properties":{"name":{"type":"string","title":"Name","example":"Annual Leave"},"leave_type":{"type":"string","title":"Leave Type","example":"annual"},"rate":{"type":"number","title":"Rate","description":"The dollar amount per unit for this leave (e.g., hourly rate). Optional if using `multiplier` or to default to the employee's pay_rate_per_hour.","example":"38.00"},"multiplier":{"type":"number","title":"Multiplier","description":"Alternative to `rate`. Multiplies the employee's pay_rate_per_hour (e.g., 1.0 for base rate, 1.5 for time-and-a-half).","example":"1.0"},"hours":{"type":"number","title":"Hours","example":"7.6"},"value":{"type":"number","title":"Value","description":"Alias for hours to allow legacy payloads providing 'value'.","example":"7.6"},"leave_loading_amount":{"type":"number","title":"Leave Loading Amount","description":"Extra dollar loading applied to the leave (if any).","example":"3.80"}},"type":"object","required":["name","leave_type","hours"],"title":"LeaveBase","description":"Core attributes that describe a single leave line or entitlement."},"LeaveOut":{"properties":{"name":{"type":"string","title":"Name","example":"Annual Leave"},"leave_type":{"type":"string","title":"Leave Type","example":"annual"},"rate":{"type":"number","title":"Rate","description":"The dollar amount per unit for this leave (e.g., hourly rate). Optional if using `multiplier` or to default to the employee's pay_rate_per_hour.","example":"38.00"},"multiplier":{"type":"number","title":"Multiplier","description":"Alternative to `rate`. Multiplies the employee's pay_rate_per_hour (e.g., 1.0 for base rate, 1.5 for time-and-a-half).","example":"1.0"},"hours":{"type":"number","title":"Hours","example":"7.6"},"value":{"type":"number","title":"Value","description":"Alias for hours to allow legacy payloads providing 'value'.","example":"7.6"},"leave_loading_amount":{"type":"number","title":"Leave Loading Amount","description":"Extra dollar loading applied to the leave (if any).","example":"3.80"},"id":{"type":"integer","title":"Id"},"amount":{"type":"number","title":"Amount","description":"The total amount for this leave row, calculated as rate * time_taken.","example":"288.80"}},"type":"object","required":["name","leave_type","hours","id","amount"],"title":"LeaveOut","description":"What the API returns after create / read."},"LeaveUpdate":{"properties":{"name":{"type":"string","title":"Name","example":"Annual Leave"},"leave_type":{"type":"string","title":"Leave Type","example":"annual"},"rate":{"type":"number","title":"Rate","description":"The dollar amount per unit for this leave (e.g., hourly rate). Optional if using `multiplier` or to default to the employee's pay_rate_per_hour.","example":"38.00"},"multiplier":{"type":"number","title":"Multiplier","description":"Alternative to `rate`. Multiplies the employee's pay_rate_per_hour (e.g., 1.0 for base rate, 1.5 for time-and-a-half).","example":"1.0"},"hours":{"type":"number","title":"Hours","example":"7.6"},"value":{"type":"number","title":"Value","description":"Alias for hours to allow legacy payloads providing 'value'.","example":"7.6"},"leave_loading_amount":{"type":"number","title":"Leave Loading Amount","description":"Extra dollar loading applied to the leave (if any).","example":"3.80"},"id":{"type":"integer","title":"Id","example":42}},"type":"object","required":["name","leave_type","hours","id"],"title":"LeaveUpdate","description":"Full payload for a PATCH/PUT – requires the primary-key `id`."},"NewWorkersCompensationPay":{"properties":{"employee_id":{"type":"integer","title":"Employee Id","description":"The internal unique identifier for the employee.","example":1234},"employee_number":{"type":"string","title":"Employee Number","description":"The external unique identifier (employee number) for the employee.","example":"EMP001"},"workers_compensation_amount":{"type":"number","title":"Workers Compensation Amount","description":"The amount of workers' compensation to be paid.","example":"1500.00"},"tax":{"type":"number","title":"Tax","description":"The tax amount associated with the workers' compensation payment.","example":"300.00"}},"type":"object","required":["workers_compensation_amount","tax"],"title":"NewWorkersCompensationPay"},"PartnerCheckoutAvailabilityItem":{"properties":{"provided":{"type":"boolean","title":"Provided","description":"Whether this identifier was included in the availability request."},"normalized":{"type":"string","title":"Normalized","description":"Normalized identifier used by the API for validation and lookup."},"valid_format":{"type":"boolean","title":"Valid Format","description":"Whether the identifier passed format validation."},"exists":{"type":"boolean","title":"Exists","description":"Whether a matching existing customer or company record was found."},"available":{"type":"boolean","title":"Available","description":"True only when the identifier was provided, valid, and not already in use."},"message":{"type":"string","title":"Message","description":"Developer-facing availability summary."},"required_owned_add_ons":{"items":{"$ref":"#/components/schemas/RequiredOwnedAddOn"},"type":"array","title":"Required Owned Add Ons","description":"If an existing customer was matched, shows whether they already have the reseller's required branded add-ons."},"has_all_required_owned_add_ons":{"type":"boolean","title":"Has All Required Owned Add Ons","description":"Summary flag for `required_owned_add_ons`. Null when the check does not apply."}},"additionalProperties":false,"type":"object","required":["provided","valid_format","exists","available","message"],"title":"PartnerCheckoutAvailabilityItem"},"PartnerCheckoutAvailabilityResponse":{"properties":{"email":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutAvailabilityItem"}],"title":"Email","description":"Availability result for the supplied email, or a placeholder result when no email was supplied."},"abn":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutAvailabilityItem"}],"title":"Abn","description":"Availability result for the supplied ABN, or a placeholder result when no ABN was supplied."},"ird_number":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutAvailabilityItem"}],"title":"Ird Number","description":"Availability result for the supplied NZ employer IRD number, or a placeholder result when none was supplied."}},"additionalProperties":false,"type":"object","required":["email","abn","ird_number"],"title":"PartnerCheckoutAvailabilityResponse"},"PartnerCheckoutBillingAddress":{"properties":{"address_1":{"type":"string","maxLength":128,"minLength":3,"title":"Address 1","example":"1 Eagle Street"},"address_2":{"type":"string","maxLength":128,"title":"Address 2","example":"Level 12"},"city":{"type":"string","maxLength":128,"minLength":2,"title":"City","example":"Brisbane"},"postcode":{"type":"string","maxLength":10,"minLength":2,"title":"Postcode","example":"4000"},"zone_code":{"type":"string","maxLength":32,"minLength":1,"title":"Zone Code","description":"State or region code. Use GET /api/partner-checkout/zones to list valid codes.","example":"QLD"}},"additionalProperties":false,"type":"object","required":["address_1","city","postcode","zone_code"],"title":"PartnerCheckoutBillingAddress"},"PartnerCheckoutCancelOrderRequest":{"properties":{"order_id":{"type":"integer","exclusiveMinimum":0.0,"title":"Order Id","description":"The order.order_id to cancel.","example":192484},"reason":{"type":"string","maxLength":500,"title":"Reason","description":"Optional free-text reason stored on the order_history note.","example":"Customer requested cancellation - signed up in error."}},"additionalProperties":false,"type":"object","required":["order_id"],"title":"PartnerCheckoutCancelOrderRequest"},"PartnerCheckoutCancelOrderResponse":{"properties":{"order_id":{"type":"integer","title":"Order Id","description":"Cancelled order ID."},"previous_order_status_id":{"type":"integer","title":"Previous Order Status Id","description":"Order status before cancellation."},"order_status_id":{"type":"integer","title":"Order Status Id","description":"New order status after cancellation. Expected value is 7."},"order_history_id":{"type":"integer","title":"Order History Id","description":"Order-history record created for the cancellation event."},"comment":{"type":"string","title":"Comment","description":"Cancellation comment stored in order history."}},"additionalProperties":false,"type":"object","required":["order_id","previous_order_status_id","order_status_id","order_history_id","comment"],"title":"PartnerCheckoutCancelOrderResponse"},"PartnerCheckoutCompanyCreate":{"properties":{"legal_name":{"type":"string","maxLength":128,"minLength":1,"title":"Legal Name","example":"Sunrise Hospitality Pty Ltd"},"abn":{"type":"string","title":"Abn","description":"Australian Business Number (AU customers). Mutually exclusive with ird_number.","example":"10000000000"},"ird_number":{"type":"string","title":"Ird Number","description":"Employer IRD number (NZ customers). Mutually exclusive with abn.","example":"49091850"}},"additionalProperties":false,"type":"object","required":["legal_name"],"title":"PartnerCheckoutCompanyCreate"},"PartnerCheckoutCountryItem":{"properties":{"country_id":{"type":"integer","title":"Country Id","description":"Internal country ID."},"iso_code_2":{"type":"string","title":"Iso Code 2","description":"ISO 3166-1 alpha-2 country code."},"name":{"type":"string","title":"Name","description":"Human-readable country name."},"zones":{"items":{"$ref":"#/components/schemas/PartnerCheckoutZoneItem"},"type":"array","title":"Zones","description":"Allowed active zones for this country."}},"additionalProperties":false,"type":"object","required":["country_id","iso_code_2","name","zones"],"title":"PartnerCheckoutCountryItem"},"PartnerCheckoutCountryPricing":{"properties":{"country_code":{"type":"string","title":"Country Code","description":"Country this pricing row applies to."},"currency_code":{"type":"string","title":"Currency Code","description":"Currency for this pricing row."},"tax_rate":{"type":"number","title":"Tax Rate","description":"Tax rate applied for this country."},"unit_price_ex_tax":{"type":"number","title":"Unit Price Ex Tax","description":"Partner unit price excluding tax."},"unit_tax":{"type":"number","title":"Unit Tax","description":"Tax component for one unit at partner pricing."},"unit_price_inc_tax":{"type":"number","title":"Unit Price Inc Tax","description":"Partner unit price including tax."},"rrp_unit_price_ex_tax":{"type":"number","title":"Rrp Unit Price Ex Tax","description":"Mapped retail recommended unit price excluding tax when a retail counterpart exists."},"rrp_unit_tax":{"type":"number","title":"Rrp Unit Tax","description":"Mapped retail tax amount per unit when a retail counterpart exists."},"rrp_unit_price_inc_tax":{"type":"number","title":"Rrp Unit Price Inc Tax","description":"Mapped retail recommended unit price including tax when a retail counterpart exists."}},"additionalProperties":false,"type":"object","required":["country_code","currency_code","tax_rate","unit_price_ex_tax","unit_tax","unit_price_inc_tax"],"title":"PartnerCheckoutCountryPricing"},"PartnerCheckoutCustomerCreate":{"properties":{"first_name":{"type":"string","maxLength":32,"minLength":1,"title":"First Name","example":"Alice"},"last_name":{"type":"string","maxLength":32,"minLength":1,"title":"Last Name","example":"Nguyen"},"email":{"type":"string","format":"email","title":"Email","example":"alice@example.com"},"phone":{"type":"string","maxLength":32,"minLength":3,"title":"Phone","example":"+61 7 3000 0000"}},"additionalProperties":false,"type":"object","required":["first_name","last_name","email","phone"],"title":"PartnerCheckoutCustomerCreate"},"PartnerCheckoutLineItem":{"properties":{"line_type":{"type":"string","enum":["subscription","add_on","training_session","upgrade_credit"],"title":"Line Type","description":"Type of line produced by partner checkout. `upgrade_credit` is a negative line representing the remaining value of the customer's existing subscription (and add-ons) credited against a base/both upgrade order."},"product_id":{"type":"integer","title":"Product Id","description":"Product ID used for this priced line."},"name":{"type":"string","title":"Name","description":"Product display name at the time of checkout."},"model":{"type":"string","title":"Model","description":"Product model code."},"quantity":{"type":"integer","title":"Quantity","description":"Final quantity priced for this line."},"unit_price_ex_tax":{"type":"number","title":"Unit Price Ex Tax","description":"Per-unit partner price excluding tax."},"unit_price_inc_tax":{"type":"number","title":"Unit Price Inc Tax","description":"Per-unit partner price including tax (AU: ex_tax + 10% GST; NZ: equal to ex_tax — GST-Free Export)."},"line_subtotal_ex_tax":{"type":"number","title":"Line Subtotal Ex Tax","description":"Line subtotal excluding tax before promo discount."},"line_tax":{"type":"number","title":"Line Tax","description":"Tax amount for this line."},"line_total_inc_tax":{"type":"number","title":"Line Total Inc Tax","description":"Line total including tax before promo discount."},"tax_rate":{"type":"number","title":"Tax Rate","description":"Effective tax rate applied to this line. 0.1000 for AU GST; 0.0000 for NZ (GST-Free Export — no NZ GST line)."},"currency_code":{"type":"string","title":"Currency Code","description":"Currency this line is priced in (AUD or NZD)."},"rrp_unit_price_ex_tax":{"type":"number","title":"Rrp Unit Price Ex Tax","description":"Retail recommended per-unit price excluding tax. Prorated when subscription_end_date is set. Null when no retail counterpart exists (e.g. Figtree, per-employee REF SKUs)."},"rrp_unit_price_inc_tax":{"type":"number","title":"Rrp Unit Price Inc Tax","description":"Retail recommended per-unit price including tax. Same GST rules as unit_price_inc_tax."},"rrp_line_total_inc_tax":{"type":"number","title":"Rrp Line Total Inc Tax","description":"Retail recommended line total including tax (rrp_unit_price_inc_tax × quantity)."},"notes":{"items":{"type":"string"},"type":"array","title":"Notes","description":"Informational notes about how this line was derived."}},"additionalProperties":false,"type":"object","required":["line_type","product_id","name","model","quantity","unit_price_ex_tax","unit_price_inc_tax","line_subtotal_ex_tax","line_tax","line_total_inc_tax","tax_rate","currency_code"],"title":"PartnerCheckoutLineItem"},"PartnerCheckoutMandatoryRequirements":{"properties":{"requires_training_session":{"type":"boolean","title":"Requires Training Session","description":"Whether every partner checkout order must include the mandatory training session product.","default":true},"training_session_product_id":{"type":"integer","title":"Training Session Product Id","description":"Product ID expected for the mandatory training session line."},"training_session_product_available":{"type":"boolean","title":"Training Session Product Available","description":"Whether the training session product is currently configured and available."},"training_session_product_name":{"type":"string","title":"Training Session Product Name","description":"Display name of the mandatory training session product, when configured."},"training_session_prices":{"items":{"$ref":"#/components/schemas/PartnerCheckoutCountryPricing"},"type":"array","title":"Training Session Prices","description":"Per-country retail pricing for the mandatory training session line. Matches the one-off training_session line in preview/execute: full retail price, no partner discount, RRP equal to its own price."},"has_owned_add_on_requirements":{"type":"boolean","title":"Has Owned Add On Requirements","description":"Whether this reseller has branded add-on requirements that affect signup."},"required_owned_add_on_keys":{"items":{"type":"string"},"type":"array","title":"Required Owned Add On Keys","description":"Branding add-on keys that this reseller must provision for new client connections."}},"additionalProperties":false,"type":"object","required":["training_session_product_id","training_session_product_available","has_owned_add_on_requirements"],"title":"PartnerCheckoutMandatoryRequirements"},"PartnerCheckoutOAuthOnboarding":{"properties":{"redirect_uri":{"type":"string","maxLength":2048,"minLength":1,"title":"Redirect Uri","description":"Your OAuth callback URI. Must EXACTLY match one of the redirect URIs registered on your OAuth client. After the customer opens the emailed magic link, signs in, and grants consent, their browser is redirected here with `?code=...&state=...`. Exchange the code at POST /api/oauth/token for a `payroll.write` access token, then create their company with PUT /api/company/create — no second login required.","example":"https://partner.example.com/oauth/callback"},"scope":{"type":"string","maxLength":512,"title":"Scope","description":"Space-delimited OAuth scopes to request. `openid` (legacy `openapi` also accepted) is required, and `payroll.write` is required so you can create the customer's payroll company after consent. Defaults to `openid payroll.write`.","default":"openid payroll.write","example":"openid payroll.write"},"state":{"type":"string","maxLength":512,"title":"State","description":"Opaque value echoed back unchanged to your `redirect_uri` for CSRF/correlation. If omitted, the API generates one.","example":"partner-corr-abc123"}},"additionalProperties":false,"type":"object","required":["redirect_uri"],"title":"PartnerCheckoutOAuthOnboarding"},"PartnerCheckoutOptionsResponse":{"properties":{"customer_group_id":{"type":"integer","title":"Customer Group Id","description":"Required reseller customer group for partner checkout."},"requires_api_admin":{"type":"boolean","title":"Requires Api Admin","description":"Always true for this feature; caller must be an API admin."},"show_per_employee_pricing":{"type":"boolean","title":"Show Per Employee Pricing","description":"Whether this reseller account may use per-employee base products."},"per_employee_minimum":{"type":"integer","title":"Per Employee Minimum","description":"Minimum employee quantity required for per-employee products."},"allowed_countries":{"items":{"type":"string"},"type":"array","title":"Allowed Countries","description":"Country codes currently supported by partner checkout."},"required_scopes":{"additionalProperties":{"type":"string"},"type":"object","title":"Required Scopes","description":"Helpful scope mapping for discovery, preview, and execute flows."},"mandatory_requirements":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutMandatoryRequirements"}],"title":"Mandatory Requirements","description":"Reseller-specific mandatory signup requirements."},"subscription_products":{"items":{"$ref":"#/components/schemas/PartnerCheckoutProductOption"},"type":"array","title":"Subscription Products","description":"Base subscription products that can be used as `order.product_id`."},"add_on_products":{"items":{"$ref":"#/components/schemas/PartnerCheckoutProductOption"},"type":"array","title":"Add On Products","description":"Available add-ons for partner checkout."}},"additionalProperties":false,"type":"object","required":["customer_group_id","requires_api_admin","show_per_employee_pricing","per_employee_minimum","allowed_countries","required_scopes","mandatory_requirements","subscription_products","add_on_products"],"title":"PartnerCheckoutOptionsResponse"},"PartnerCheckoutOrder":{"properties":{"product_id":{"type":"integer","exclusiveMinimum":0.0,"title":"Product Id","description":"Subscription product ID from GET /api/partner-checkout/options.","example":243},"add_on_product_ids":{"items":{"type":"integer"},"type":"array","maxItems":50,"title":"Add On Product Ids","description":"Optional add-on product IDs. Must match the base product billing cycle.","example":[300]},"extra_company_qty":{"type":"integer","maximum":1000.0,"minimum":0.0,"title":"Extra Company Qty","description":"Extra company slots to add to the subscription.","example":2},"per_employee_qty":{"type":"integer","maximum":50000.0,"minimum":1.0,"title":"Per Employee Qty","description":"Required for per-employee products. Must meet the partner minimum.","example":25},"add_free_trial_month":{"type":"boolean","title":"Add Free Trial Month","description":"When true (default), add an extra free trial month to the subscription expiry so monthly signups get 2 months and annual signups get 13 months.","default":true},"subscription_end_date":{"type":"string","format":"date","title":"Subscription End Date","description":"Optional aligned subscription expiry date. When supplied, the base subscription and any recurring add-ons are prorated to this date; the mandatory training session is still charged at full price. Must be strictly after today and within +365 days (annual products) or +30 days (monthly products). When add_free_trial_month is also true, 30 days are deducted from the prorated paid period to account for the free month; if that leaves no paid days the line is charged $0.","example":"2026-08-21"},"client_reference":{"type":"string","maxLength":255,"title":"Client Reference","description":"Your internal reference for this order.","example":"crm-12345"},"metadata":{"type":"object","title":"Metadata","description":"Arbitrary key-value data stored in the order comment for auditability.","example":{"source":"partner-crm","sales_rep":"jsmith"}}},"additionalProperties":false,"type":"object","required":["product_id"],"title":"PartnerCheckoutOrder"},"PartnerCheckoutOrderDetailResponse":{"properties":{"order_id":{"type":"integer","title":"Order Id","description":"Order ID."},"order_status_id":{"type":"integer","title":"Order Status Id","description":"Current order status."},"invoice_prefix":{"type":"string","title":"Invoice Prefix","description":"Invoice prefix used for the order."},"total":{"type":"number","title":"Total","description":"Current order total."},"currency_code":{"type":"string","title":"Currency Code","description":"Order currency code."},"date_added":{"type":"string","format":"date-time","title":"Date Added","description":"When the order was created."},"date_modified":{"type":"string","format":"date-time","title":"Date Modified","description":"When the order was last modified."},"customer_id":{"type":"integer","title":"Customer Id","description":"Customer created for the order."},"customer_email":{"type":"string","format":"email","title":"Customer Email","description":"Customer email associated with the order."},"customer_date_added":{"type":"string","format":"date-time","title":"Customer Date Added","description":"Customer creation timestamp used for the 60-day cancellation window."},"company_name":{"type":"string","title":"Company Name","description":"Company name attached to the order."},"subscription_id":{"type":"integer","title":"Subscription Id","description":"Subscription created from the order, when present."},"subscription_expiry":{"type":"string","format":"date","title":"Subscription Expiry","description":"Subscription expiry date, when present."},"cancel_window_closes":{"type":"string","format":"date-time","title":"Cancel Window Closes","description":"Timestamp when the partner cancellation window closes."},"cancellable":{"type":"boolean","title":"Cancellable","description":"Whether the order is currently eligible for partner cancellation."},"history":{"items":{"$ref":"#/components/schemas/PartnerCheckoutOrderHistoryEntry"},"type":"array","title":"History","description":"Order history entries in ascending order."},"subtotal_ex_tax":{"type":"number","title":"Subtotal Ex Tax","description":"Order subtotal excluding tax, summed across the persisted order_product rows. Pre-promo: does not reflect any welcome-offer discount."},"tax":{"type":"number","title":"Tax","description":"Order tax total, summed across the persisted order_product rows. Pre-promo: does not reflect any welcome-offer discount."},"total_inc_tax":{"type":"number","title":"Total Inc Tax","description":"Order total including tax (subtotal_ex_tax + tax). Pre-promo: does not reflect any welcome-offer discount. When a promo applied, partners should bill the lower `total_after_promo_inc_tax` (or the legacy `total` field)."},"tax_rate":{"type":"number","title":"Tax Rate","description":"Current country-level tax rate (10% for AU GST, 0% for NZ GST-Free Exports)."},"order_lines":{"items":{"$ref":"#/components/schemas/PartnerCheckoutLineItem"},"type":"array","title":"Order Lines","description":"Order lines reconstructed from the persisted order_product rows. Line amounts are pre-promo."},"billing_address":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutResolvedAddress"}],"title":"Billing Address","description":"Billing address rebuilt from the order's payment_* columns."},"supplier":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutSupplier"}],"title":"Supplier","description":"Supplier (Intellitron / Lightning Payroll) details for partner-issued tax invoices."},"promo_discount":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutPromoDiscount"}],"title":"Promo Discount","description":"Welcome-offer promo discount applied to this order, reconstructed from the persisted promo assignment. Null when no promo applied."},"total_after_promo_inc_tax":{"type":"number","title":"Total After Promo Inc Tax","description":"Final billed total including tax after promo discount. Null when no promo applied. Mirrors the legacy `total` field for promo orders."}},"additionalProperties":false,"type":"object","required":["order_id","order_status_id","invoice_prefix","total","date_added","date_modified","customer_id","customer_email","company_name","cancellable","subtotal_ex_tax","tax","total_inc_tax","tax_rate","billing_address","supplier"],"title":"PartnerCheckoutOrderDetailResponse"},"PartnerCheckoutOrderHistoryEntry":{"properties":{"order_history_id":{"type":"integer","title":"Order History Id","description":"Order-history record ID."},"order_status_id":{"type":"integer","title":"Order Status Id","description":"Order status recorded at this history entry."},"notify":{"type":"boolean","title":"Notify","description":"Whether the original workflow marked this history entry for notification."},"comment":{"type":"string","title":"Comment","description":"History comment text."},"date_added":{"type":"string","format":"date-time","title":"Date Added","description":"Timestamp when this history entry was created."}},"additionalProperties":false,"type":"object","required":["order_history_id","order_status_id","notify","comment","date_added"],"title":"PartnerCheckoutOrderHistoryEntry"},"PartnerCheckoutOrderListItem":{"properties":{"order_id":{"type":"integer","title":"Order Id","description":"Order ID."},"order_status_id":{"type":"integer","title":"Order Status Id","description":"Current order status."},"total":{"type":"number","title":"Total","description":"Current order total."},"currency_code":{"type":"string","title":"Currency Code","description":"Order currency code."},"date_added":{"type":"string","format":"date-time","title":"Date Added","description":"Order creation timestamp."},"customer_id":{"type":"integer","title":"Customer Id","description":"Customer ID created by the order."},"customer_email":{"type":"string","format":"email","title":"Customer Email","description":"Customer email."},"company_name":{"type":"string","title":"Company Name","description":"Company name for the order."},"cancellable":{"type":"boolean","title":"Cancellable","description":"Whether this order is still within the reseller cancellation window."}},"additionalProperties":false,"type":"object","required":["order_id","order_status_id","total","date_added","customer_id","customer_email","company_name","cancellable"],"title":"PartnerCheckoutOrderListItem"},"PartnerCheckoutOrderListResponse":{"properties":{"orders":{"items":{"$ref":"#/components/schemas/PartnerCheckoutOrderListItem"},"type":"array","title":"Orders","description":"Orders created by the authenticated reseller, newest first."},"limit":{"type":"integer","title":"Limit","description":"Applied page size."},"offset":{"type":"integer","title":"Offset","description":"Applied result offset."},"total_count":{"type":"integer","title":"Total Count","description":"Total matching orders before pagination."}},"additionalProperties":false,"type":"object","required":["orders","limit","offset","total_count"],"title":"PartnerCheckoutOrderListResponse"},"PartnerCheckoutProductOption":{"properties":{"product_id":{"type":"integer","title":"Product Id","description":"Product ID to use in partner checkout requests."},"name":{"type":"string","title":"Name","description":"Product display name."},"model":{"type":"string","title":"Model","description":"Internal model code useful for stable partner-side mapping."},"description":{"type":"string","title":"Description","description":"Product description."},"meta_description":{"type":"string","title":"Meta Description","description":"Additional catalog description text."},"billing_cycle":{"type":"string","enum":["annual","monthly","other"],"title":"Billing Cycle","description":"Billing cycle for the product. Add-ons must match the selected base product cycle."},"product_kind":{"type":"string","enum":["subscription","add_on"],"title":"Product Kind","description":"Whether this product is a base subscription or an add-on."},"product_type_id":{"type":"integer","title":"Product Type Id","description":"Underlying product type ID from the catalog."},"product_class_id":{"type":"integer","title":"Product Class Id","description":"Underlying product class ID where available."},"is_per_employee":{"type":"boolean","title":"Is Per Employee","description":"Whether quantity is based on employees rather than a single subscription unit.","default":false},"supports_extra_company_qty":{"type":"boolean","title":"Supports Extra Company Qty","description":"Whether `order.extra_company_qty` can be used with this product.","default":false},"min_quantity":{"type":"integer","title":"Min Quantity","description":"Minimum quantity accepted for this option.","default":1},"max_employees":{"type":"integer","title":"Max Employees","description":"Maximum supported employees, when defined by product attributes."},"max_companies":{"type":"integer","title":"Max Companies","description":"Maximum supported companies, when defined by product attributes."},"seats":{"type":"integer","title":"Seats","description":"Seat count, when defined by product attributes."},"duration_text":{"type":"string","title":"Duration Text","description":"Human-readable subscription duration text such as `12 months`."},"compatible_add_on_product_ids":{"items":{"type":"integer"},"type":"array","title":"Compatible Add On Product Ids","description":"Add-on product IDs that are valid alongside this subscription product."},"is_required_for_signup":{"type":"boolean","title":"Is Required For Signup","description":"True when the reseller owns a branded add-on integration that requires this add-on family on signup.","default":false},"prices":{"items":{"$ref":"#/components/schemas/PartnerCheckoutCountryPricing"},"type":"array","title":"Prices","description":"Partner pricing rows for supported countries."}},"additionalProperties":false,"type":"object","required":["product_id","name","model","billing_cycle","product_kind","product_type_id","prices"],"title":"PartnerCheckoutProductOption"},"PartnerCheckoutPromoDiscount":{"properties":{"promo_name":{"type":"string","title":"Promo Name","description":"Rendered promo name shown to the reseller."},"discount_percent":{"type":"number","title":"Discount Percent","description":"Promo percentage applied to the eligible base subscription amount."},"duration_months":{"type":"integer","title":"Duration Months","description":"Promo duration in months."},"discount_ex_tax":{"type":"number","title":"Discount Ex Tax","description":"Discount amount excluding tax."},"discount_tax":{"type":"number","title":"Discount Tax","description":"Tax component removed by the promo."},"discount_inc_tax":{"type":"number","title":"Discount Inc Tax","description":"Total discount including tax."}},"additionalProperties":false,"type":"object","required":["promo_name","discount_percent","duration_months","discount_ex_tax","discount_tax","discount_inc_tax"],"title":"PartnerCheckoutPromoDiscount"},"PartnerCheckoutRequest":{"properties":{"dry_run":{"type":"boolean","title":"Dry Run","description":"`true` validates and prices only. `false` creates records."},"send_customer_welcome_email":{"type":"boolean","title":"Send Customer Welcome Email","description":"When true (the default), send the new customer a branded onboarding email with a password reset link. Set false to suppress it if you send your own invite — but note the customer's password is a random secret, so without this email (or your own) they cannot sign in. Ignored when `oauth_onboarding` is supplied (the magic onboarding email is sent instead).","default":true},"oauth_onboarding":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutOAuthOnboarding"}],"title":"Oauth Onboarding","description":"Optional single-flow OAuth onboarding. When supplied on an execute (non-dry-run) request, the new customer is emailed a single-use, time-limited magic link that signs them in WITHOUT a password and drops them straight into your OAuth consent screen, so they authorise your integration in one flow. This REPLACES the default password-reset welcome email. The magic link is emailed only to the customer's verified address and is never returned in the API response. On a dry-run the block is validated (OAuth client, redirect_uri, scope) but no email is sent. Omit entirely for the default behaviour."},"customer":{"$ref":"#/components/schemas/PartnerCheckoutCustomerCreate"},"company":{"$ref":"#/components/schemas/PartnerCheckoutCompanyCreate"},"billing_address":{"$ref":"#/components/schemas/PartnerCheckoutBillingAddress"},"order":{"$ref":"#/components/schemas/PartnerCheckoutOrder"}},"additionalProperties":false,"type":"object","required":["dry_run","customer","company","billing_address","order"],"title":"PartnerCheckoutRequest","examples":[{"summary":"AU dry-run preview","value":{"dry_run":true,"customer":{"first_name":"Alice","last_name":"Nguyen","email":"alice@example.com","phone":"+61 7 3000 0000"},"company":{"legal_name":"Sunrise Hospitality Pty Ltd","abn":"10000000000"},"billing_address":{"address_1":"1 Eagle Street","address_2":"Level 12","city":"Brisbane","postcode":"4000","zone_code":"QLD"},"order":{"product_id":243,"extra_company_qty":2,"client_reference":"crm-12345","metadata":{"source":"partner-crm","sales_rep":"jsmith"}}}},{"summary":"NZ execute order","value":{"dry_run":false,"customer":{"first_name":"Aroha","last_name":"Williams","email":"aroha@example.co.nz","phone":"+64 9 123 4567"},"company":{"legal_name":"Kiwi Payroll Ltd","ird_number":"49091850"},"billing_address":{"address_1":"23 Customs Street East","city":"Auckland","postcode":"1010","zone_code":"AUK"},"order":{"product_id":243,"client_reference":"nz-onboard-001","metadata":{"source":"partner-portal"}}}}]},"PartnerCheckoutResendOnboardingRequest":{"properties":{"oauth_onboarding":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutOAuthOnboarding"}],"title":"Oauth Onboarding","description":"The OAuth onboarding context used to rebuild the magic link. The original redirect_uri/scope/state are never stored, so they must be supplied again here — and are re-validated against your CURRENT OAuth client, so a deleted client or changed redirect URI fails fast rather than minting a dead link. Mirrors the `oauth_onboarding` block of POST /api/partner-checkout/orders."}},"additionalProperties":false,"type":"object","required":["oauth_onboarding"],"title":"PartnerCheckoutResendOnboardingRequest"},"PartnerCheckoutResendOnboardingResponse":{"properties":{"customer_id":{"type":"integer","title":"Customer Id","description":"The end customer the onboarding link was re-issued for."},"order_id":{"type":"integer","title":"Order Id","description":"The order the resend was requested against."},"email_sent":{"type":"boolean","title":"Email Sent","description":"Whether the onboarding email was queued. Always true on a 200 response (a send failure returns 502 and issues no new link)."},"expires_in_hours":{"type":"integer","title":"Expires In Hours","description":"Hours until the newly issued single-use magic link expires (24). Any previously issued, unused link is invalidated."},"scope_used":{"type":"string","title":"Scope Used","description":"The partner-checkout OAuth scope used to authorise this call."}},"additionalProperties":false,"type":"object","required":["customer_id","order_id","email_sent","expires_in_hours","scope_used"],"title":"PartnerCheckoutResendOnboardingResponse"},"PartnerCheckoutResolvedAddress":{"properties":{"company":{"type":"string","title":"Company","description":"Company name written onto the billing and shipping address records."},"address_1":{"type":"string","title":"Address 1","description":"Resolved billing address line 1."},"address_2":{"type":"string","title":"Address 2","description":"Resolved billing address line 2."},"city":{"type":"string","title":"City","description":"Resolved billing city or locality."},"postcode":{"type":"string","title":"Postcode","description":"Resolved billing postcode."},"country_code":{"type":"string","title":"Country Code","description":"Inferred ISO country code. Derived from ABN vs IRD."},"country_id":{"type":"integer","title":"Country Id","description":"Internal country ID resolved by the API."},"country_name":{"type":"string","title":"Country Name","description":"Human-readable country name."},"zone_code":{"type":"string","title":"Zone Code","description":"Resolved state or region code."},"zone_id":{"type":"integer","title":"Zone Id","description":"Internal zone ID resolved by the API."},"zone_name":{"type":"string","title":"Zone Name","description":"Human-readable state or region name."}},"additionalProperties":false,"type":"object","required":["company","address_1","city","postcode","country_code","country_id","country_name","zone_code","zone_id","zone_name"],"title":"PartnerCheckoutResolvedAddress"},"PartnerCheckoutResolvedCompany":{"properties":{"legal_name":{"type":"string","title":"Legal Name","description":"Resolved legal company name."},"abn":{"type":"string","title":"Abn","description":"Normalized ABN for AU signups."},"ird_number":{"type":"string","title":"Ird Number","description":"Normalized employer IRD number for NZ signups."},"country_code":{"type":"string","title":"Country Code","description":"Inferred ISO country code from ABN vs IRD."},"currency_code":{"type":"string","title":"Currency Code","description":"Inferred currency for the country."}},"additionalProperties":false,"type":"object","required":["legal_name","country_code","currency_code"],"title":"PartnerCheckoutResolvedCompany"},"PartnerCheckoutResolvedCustomer":{"properties":{"first_name":{"type":"string","title":"First Name","description":"Resolved customer first name that will be used or was created."},"last_name":{"type":"string","title":"Last Name","description":"Resolved customer last name that will be used or was created."},"email":{"type":"string","format":"email","title":"Email","description":"Resolved customer email address after normalization."},"phone":{"type":"string","title":"Phone","description":"Resolved customer phone number."}},"additionalProperties":false,"type":"object","required":["first_name","last_name","email","phone"],"title":"PartnerCheckoutResolvedCustomer"},"PartnerCheckoutResponse":{"properties":{"mode":{"type":"string","enum":["preview","execute"],"title":"Mode","description":"`preview` for dry-run responses, `execute` for committed order creation."},"validated":{"type":"boolean","title":"Validated","description":"True when validation completed successfully."},"dry_run":{"type":"boolean","title":"Dry Run","description":"Echoes the request mode."},"scope_used":{"type":"string","title":"Scope Used","description":"Partner checkout scope accepted for this request."},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Non-fatal validation or pricing notes the integration should surface or log."},"customer":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutResolvedCustomer"}],"title":"Customer","description":"Resolved customer payload."},"company":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutResolvedCompany"}],"title":"Company","description":"Resolved company payload."},"billing_address":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutResolvedAddress"}],"title":"Billing Address","description":"Resolved billing address, country, and zone information."},"order_lines":{"items":{"$ref":"#/components/schemas/PartnerCheckoutLineItem"},"type":"array","title":"Order Lines","description":"Final line items used for pricing and, on execute, order creation."},"totals":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutTotals"}],"title":"Totals","description":"Final totals for the checkout request."},"supplier":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutSupplier"}],"title":"Supplier","description":"Supplier (Intellitron / Lightning Payroll) details for partner-issued tax invoices."},"customer_id":{"type":"integer","title":"Customer Id","description":"Created customer ID on execute. Null on preview."},"address_id":{"type":"integer","title":"Address Id","description":"Created address ID on execute. Null on preview."},"order_id":{"type":"integer","title":"Order Id","description":"Created order ID on execute. Null on preview."},"subscription_id":{"type":"integer","title":"Subscription Id","description":"Created subscription ID on execute. Null on preview."},"order_status_id":{"type":"integer","title":"Order Status Id","description":"Final order status after execute. Typically null on preview."},"emails_sent":{"type":"boolean","title":"Emails Sent","description":"True when all checkout emails queued successfully. Order creation can still succeed when false.","default":false},"idempotency_replayed":{"type":"boolean","title":"Idempotency Replayed","description":"True when a previous execute response was returned because the same Idempotency-Key and payload were reused.","default":false},"subscription_end_date":{"type":"string","format":"date","title":"Subscription End Date","description":"Aligned subscription expiry date when the partner requested term alignment. Null when the request used the default full-term subscription."},"prorata_factor":{"type":"number","title":"Prorata Factor","description":"Pricing prorata multiplier applied to the base subscription and recurring add-ons when subscription_end_date is set. 0 means the aligned window was non-positive after the trial-month deduction and prorated lines were charged $0. Null when no term alignment was requested."}},"additionalProperties":false,"type":"object","required":["mode","validated","dry_run","scope_used","customer","company","billing_address","order_lines","totals","supplier"],"title":"PartnerCheckoutResponse"},"PartnerCheckoutSupplier":{"properties":{"name":{"type":"string","title":"Name","description":"Supplier legal name as it should appear on partner-issued invoices."},"abn":{"type":"string","title":"Abn","description":"Supplier ABN (Australian Business Number)."},"address":{"type":"string","title":"Address","description":"Supplier address as a single multi-line string."},"email":{"type":"string","title":"Email","description":"Supplier contact email."},"phone":{"type":"string","title":"Phone","description":"Supplier contact phone."}},"additionalProperties":false,"type":"object","required":["name","abn","address","email","phone"],"title":"PartnerCheckoutSupplier"},"PartnerCheckoutTotals":{"properties":{"subtotal_ex_tax":{"type":"number","title":"Subtotal Ex Tax","description":"Subtotal across all lines before tax and before promo discount."},"tax":{"type":"number","title":"Tax","description":"Total tax across all lines before promo discount."},"total_inc_tax":{"type":"number","title":"Total Inc Tax","description":"Total including tax before promo discount."},"promo_discount":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutPromoDiscount"}],"title":"Promo Discount","description":"Active welcome-offer promo details, if any."},"total_after_promo_inc_tax":{"type":"number","title":"Total After Promo Inc Tax","description":"Final total including tax after promo discount. Null when no promo applies."},"currency_code":{"type":"string","title":"Currency Code","description":"Currency code for the priced order, derived from the inferred country.","example":"AUD"},"tax_rate":{"type":"number","title":"Tax Rate","description":"Effective tax rate applied at the country level."}},"additionalProperties":false,"type":"object","required":["subtotal_ex_tax","tax","total_inc_tax","currency_code","tax_rate"],"title":"PartnerCheckoutTotals"},"PartnerCheckoutUpgradeCreditBreakdown":{"properties":{"base_credit_inc_tax":{"type":"number","title":"Base Credit Inc Tax","description":"Inc-tax credit derived from the existing base subscription's remaining value."},"add_ons_credit_inc_tax":{"type":"number","title":"Add Ons Credit Inc Tax","description":"Inc-tax credit derived from the existing eligible add-ons' remaining value."},"total_credit_inc_tax":{"type":"number","title":"Total Credit Inc Tax","description":"Sum of base + add-ons credit, before being applied to the upgrade order."},"days_remaining":{"type":"integer","title":"Days Remaining","description":"Days remaining used in the credit math (`today.diff(expiry).days + 2`, matching PHP `get_subscription_discount_days_left`)."},"billing_cycle_days":{"type":"integer","title":"Billing Cycle Days","description":"Billing cycle length in days used to compute the per-day credit rate."}},"additionalProperties":false,"type":"object","required":["base_credit_inc_tax","add_ons_credit_inc_tax","total_credit_inc_tax","days_remaining","billing_cycle_days"],"title":"PartnerCheckoutUpgradeCreditBreakdown"},"PartnerCheckoutUpgradeOrder":{"properties":{"mode":{"type":"string","enum":["base","addon","both"],"title":"Mode","description":"Upgrade mode mirroring payroll_web's store.tpl checkout UI:\n- `addon`: leave the existing base subscription and its add-ons untouched; bolt on one or more new add-ons priced prorata to the existing subscription's remaining term.\n- `base`: replace the existing base subscription with a new one. The remaining value of the existing base + existing add-ons is applied as an `upgrade_credit` discount line. Existing add-ons are NOT carried over to the new subscription unless re-listed in `add_on_product_ids`.\n- `both`: same as `base`, but the partner also chooses the final add-on set for the new subscription.","example":"base"},"new_product_id":{"type":"integer","exclusiveMinimum":0.0,"title":"New Product Id","description":"Subscription product ID for the new base subscription. Required for `base` and `both` modes. Must be omitted (or null) for `addon` mode.","example":243},"add_on_product_ids":{"items":{"type":"integer"},"type":"array","maxItems":50,"title":"Add On Product Ids","description":"Add-on product IDs.\n- `addon` mode: the NEW add-ons to bolt onto the existing subscription. At least one required.\n- `base`/`both` mode: the FULL final add-on list for the new subscription. Existing add-ons that aren't re-listed will not be carried over to the new sub (their remaining value still contributes to the upgrade credit).","example":[300]},"extra_company_qty":{"type":"integer","maximum":1000.0,"minimum":0.0,"title":"Extra Company Qty","description":"Extra company slots to add to the new subscription. Valid for `base` and `both` modes only. Must be omitted (or zero) for `addon` mode.","example":2},"per_employee_qty":{"type":"integer","maximum":50000.0,"minimum":1.0,"title":"Per Employee Qty","description":"Per-employee quantity for per-employee subscription products. Required when the new product is a per-employee SKU. Must meet the partner's minimum. Valid for `base` and `both` modes only.","example":25},"subscription_end_date":{"type":"string","format":"date","title":"Subscription End Date","description":"Optional aligned subscription expiry date for the NEW subscription (base/both modes only). Same semantics as the signup endpoint: must be strictly after today and within +365 days (annual) or +30 days (monthly). Not supported in `addon` mode (add-ons are always priced to the existing subscription's expiry).","example":"2026-08-21"},"client_reference":{"type":"string","maxLength":255,"title":"Client Reference","description":"Your internal reference for this upgrade order.","example":"crm-upgrade-12345"},"metadata":{"type":"object","title":"Metadata","description":"Arbitrary key-value data stored in the order comment for auditability.","example":{"source":"partner-crm","sales_rep":"jsmith"}}},"additionalProperties":false,"type":"object","required":["mode"],"title":"PartnerCheckoutUpgradeOrder"},"PartnerCheckoutUpgradePreviousSubscription":{"properties":{"subscription_id":{"type":"integer","title":"Subscription Id","description":"The subscription that was the target of this upgrade."},"product_id":{"type":"integer","title":"Product Id","description":"The base product ID of the previous subscription."},"product_model":{"type":"string","title":"Product Model","description":"The base product model code of the previous subscription."},"expiry":{"type":"string","format":"date","title":"Expiry","description":"Expiry date of the previous subscription at the time of the upgrade."},"days_remaining_at_upgrade":{"type":"integer","title":"Days Remaining At Upgrade","description":"Days remaining on the previous subscription at the time of the upgrade. Mirrors the PHP `interval.days + 2` calculation used for credit math (base/both modes), or `ceil(seconds/86400)` for addon-mode prorata."},"billing_cycle":{"type":"string","enum":["annual","monthly","other"],"title":"Billing Cycle","description":"Billing cycle of the previous subscription's base product."},"original_base_value_inc_tax":{"type":"number","title":"Original Base Value Inc Tax","description":"Original inc-tax line total of the base subscription. Used as the denominator for the prorata credit."},"original_add_ons_value_inc_tax":{"type":"number","title":"Original Add Ons Value Inc Tax","description":"Sum of original inc-tax line totals of the existing eligible add-ons. Used for the credit denominator."}},"additionalProperties":false,"type":"object","required":["subscription_id"],"title":"PartnerCheckoutUpgradePreviousSubscription"},"PartnerCheckoutUpgradeRequest":{"properties":{"dry_run":{"type":"boolean","title":"Dry Run","description":"`true` validates and prices only. `false` creates records."},"subscription_id":{"type":"integer","exclusiveMinimum":0.0,"title":"Subscription Id","description":"The Lightning Payroll subscription_id to upgrade. The calling partner must have originally onboarded this subscription (i.e. the source order's `other_customer_id` must equal the partner's customer_id). Look up candidate subscription_ids via GET /api/partner-checkout/orders or the order-detail endpoint.","example":98321},"order":{"$ref":"#/components/schemas/PartnerCheckoutUpgradeOrder"}},"additionalProperties":false,"type":"object","required":["dry_run","subscription_id","order"],"title":"PartnerCheckoutUpgradeRequest","examples":[{"summary":"AU base upgrade dry-run","value":{"dry_run":true,"subscription_id":98321,"order":{"mode":"base","new_product_id":243,"client_reference":"crm-upgrade-12345"}}},{"summary":"Add-on-only execute (HR+ on an existing annual sub)","value":{"dry_run":false,"subscription_id":98321,"order":{"mode":"addon","add_on_product_ids":[301],"client_reference":"crm-upgrade-12346"}}},{"summary":"Both upgrade with new base + new add-on set","value":{"dry_run":true,"subscription_id":98321,"order":{"mode":"both","new_product_id":243,"add_on_product_ids":[300,301],"extra_company_qty":2}}}]},"PartnerCheckoutUpgradeResponse":{"properties":{"mode":{"type":"string","enum":["preview","execute"],"title":"Mode","description":"`preview` for dry-run responses, `execute` for committed order creation."},"upgrade_mode":{"type":"string","enum":["base","addon","both"],"title":"Upgrade Mode","description":"Echoes the request `order.mode`."},"validated":{"type":"boolean","title":"Validated","description":"True when validation completed successfully."},"dry_run":{"type":"boolean","title":"Dry Run","description":"Echoes the request mode."},"scope_used":{"type":"string","title":"Scope Used","description":"Partner checkout scope accepted for this request."},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Non-fatal validation or pricing notes the integration should surface or log."},"customer":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutResolvedCustomer"}],"title":"Customer","description":"Resolved (existing) customer payload looked up from the target subscription."},"company":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutResolvedCompany"}],"title":"Company","description":"Resolved (existing) company payload looked up from the target subscription."},"billing_address":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutResolvedAddress"}],"title":"Billing Address","description":"Resolved billing address from the existing customer's stored address."},"previous_subscription":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutUpgradePreviousSubscription"}],"title":"Previous Subscription","description":"Summary of the subscription that was upgraded."},"upgrade_credit":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutUpgradeCreditBreakdown"}],"title":"Upgrade Credit","description":"Credit breakdown applied to the upgrade order. Null for `addon` mode (no credit applies since the base subscription and its add-ons remain in force)."},"order_lines":{"items":{"$ref":"#/components/schemas/PartnerCheckoutLineItem"},"type":"array","title":"Order Lines","description":"Final line items used for pricing and, on execute, order creation. For addon mode, only prorated add-on lines. For base/both, the new subscription line + new add-on lines + an `upgrade_credit` negative line."},"totals":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutTotals"}],"title":"Totals","description":"Final totals for the upgrade request. Promo discounts are NEVER applied on upgrades (mirrors PHP behavior)."},"supplier":{"allOf":[{"$ref":"#/components/schemas/PartnerCheckoutSupplier"}],"title":"Supplier","description":"Supplier (Intellitron / Lightning Payroll) details for partner-issued tax invoices."},"order_id":{"type":"integer","title":"Order Id","description":"Created order ID on execute. Null on preview."},"new_subscription_id":{"type":"integer","title":"New Subscription Id","description":"ID of the newly created subscription for `base`/`both` mode. Null for `addon` mode (no new subscription row is created — only new subscription_add_on rows pointing at the existing sub)."},"new_subscription_expiry":{"type":"string","format":"date","title":"New Subscription Expiry","description":"Expiry date of the new subscription for base/both mode, or the unchanged existing expiry for addon mode."},"order_status_id":{"type":"integer","title":"Order Status Id","description":"Final order status after execute. Typically null on preview."},"emails_sent":{"type":"boolean","title":"Emails Sent","description":"True when all upgrade emails queued successfully. Order creation can still succeed when false.","default":false},"idempotency_replayed":{"type":"boolean","title":"Idempotency Replayed","description":"True when a previous execute response was returned because the same Idempotency-Key and payload were reused.","default":false},"subscription_end_date":{"type":"string","format":"date","title":"Subscription End Date","description":"Aligned subscription expiry date when term alignment was requested (base/both modes only). Null when the request used the default full-term subscription or for addon mode."},"prorata_factor":{"type":"number","title":"Prorata Factor","description":"Pricing prorata multiplier applied to the new base + recurring add-ons when subscription_end_date is set. Null for addon mode and for base/both without term alignment."}},"additionalProperties":false,"type":"object","required":["mode","upgrade_mode","validated","dry_run","scope_used","customer","company","billing_address","previous_subscription","order_lines","totals","supplier"],"title":"PartnerCheckoutUpgradeResponse"},"PartnerCheckoutZoneItem":{"properties":{"zone_id":{"type":"integer","title":"Zone Id","description":"Internal zone ID."},"code":{"type":"string","title":"Code","description":"Zone code to send as `billing_address.zone_code`."},"name":{"type":"string","title":"Name","description":"Human-readable zone or state name."}},"additionalProperties":false,"type":"object","required":["zone_id","code","name"],"title":"PartnerCheckoutZoneItem"},"PartnerCheckoutZonesResponse":{"properties":{"countries":{"items":{"$ref":"#/components/schemas/PartnerCheckoutCountryItem"},"type":"array","title":"Countries","description":"Supported countries and valid zone codes for partner checkout billing addresses."}},"additionalProperties":false,"type":"object","required":["countries"],"title":"PartnerCheckoutZonesResponse"},"Pay":{"properties":{"id":{"type":"integer","title":"Id","description":"The unique identifier of the pay.","example":2001},"employee_id":{"type":"integer","title":"Employee Id","description":"The internal unique database identifier of the employee.","example":1234},"employee_number":{"type":"string","title":"Employee Number","description":"The user-controlled unique employee payroll number/code.","example":"EMP001"},"pay_run_id":{"type":"integer","title":"Pay Run Id","description":"The unique identifier of the pay run associated with this pay.","example":1001},"processed_date":{"type":"string","format":"date","title":"Processed Date","description":"The date when the pay was processed.","example":"2023-01-31"},"pay_run_end_date":{"type":"string","format":"date","title":"Pay Run End Date","description":"The end date of the pay run period.","example":"2023-01-31"},"employee_format_name_shorter":{"type":"string","title":"Employee Format Name Shorter","description":"The formatted short name of the employee (e.g., 'J. Doe').","example":"J. Doe"},"employee_last_name":{"type":"string","title":"Employee Last Name","description":"The last name of the employee.","example":"Doe"},"employee_first_name":{"type":"string","title":"Employee First Name","description":"The first name of the employee.","example":"John"},"employee_email_address":{"type":"string","title":"Employee Email Address","description":"The email address of the employee.","example":"john.doe@example.com"},"status":{"type":"string","title":"Status","description":"The status of the pay (e.g., 'processed', 'pending').","example":"processed"},"gross":{"type":"number","title":"Gross","description":"The gross amount of the pay.","example":"5000.00"},"tax":{"type":"number","title":"Tax","description":"The tax amount deducted from the pay.","example":"1000.00"},"net":{"type":"number","title":"Net","description":"The net amount of the pay after deductions.","example":"4000.00"},"super":{"type":"number","title":"Super","description":"The superannuation amount associated with the pay.","example":"500.00"},"total_workers_compensation":{"type":"number","title":"Total Workers Compensation","description":"The total workers' compensation amount.","example":"200.00"},"resc_super_amount":{"type":"number","title":"Resc Super Amount","description":"The Reportable Employer Super Contributions (RESC) amount.","example":"150.00"},"compulsory_super_amount":{"type":"number","title":"Compulsory Super Amount","description":"The compulsory superannuation amount.","example":"350.00"},"nz_student_loan":{"type":"number","title":"Nz Student Loan","description":"NZ student loan amount for the pay. NZ only.","example":"45.00"},"period_student_loan_cir":{"type":"number","title":"Period Student Loan Cir","description":"NZ student loan CIR amount for the pay. NZ only.","example":"0.00"},"period_student_loan_bor":{"type":"number","title":"Period Student Loan Bor","description":"NZ student loan BOR amount for the pay. NZ only.","example":"0.00"},"format_name":{"type":"string","title":"Format Name","description":"The formatted full name of the employee (e.g., 'John Doe').","example":"John Doe"},"is_complete":{"type":"boolean","title":"Is Complete","description":"Indicates whether the pay process is complete.","example":true},"stp_status":{"type":"string","title":"Stp Status","description":"The Single Touch Payroll (STP) status.","example":"submitted"},"stp_service_action":{"type":"string","title":"Stp Service Action","description":"The STP service action taken.","example":"lodged"},"stp_timestamp":{"type":"string","format":"date","title":"Stp Timestamp","description":"The timestamp when the STP action was performed.","example":"2023-01-31"},"kiwisaver_employee_amount":{"type":"number","title":"Kiwisaver Employee Amount","description":"Employee KiwiSaver deduction for the pay. NZ only.","example":"75.00"},"kiwisaver_employer_amount":{"type":"number","title":"Kiwisaver Employer Amount","description":"Employer KiwiSaver contribution for the pay. NZ only.","example":"75.00"},"kiwisaver_esct_amount":{"type":"number","title":"Kiwisaver Esct Amount","description":"Employer KiwiSaver ESCT amount for the pay. NZ only.","example":"7.50"},"kiwisaver_paye_gross_uplift":{"type":"number","title":"Kiwisaver Paye Gross Uplift","description":"PAYE gross-up used for KiwiSaver calculations. NZ only.","example":"0.00"},"kiwisaver_employee_rate":{"type":"number","title":"Kiwisaver Employee Rate","description":"Employee KiwiSaver rate used for the pay. NZ only.","example":"0.03"},"kiwisaver_employer_rate":{"type":"number","title":"Kiwisaver Employer Rate","description":"Employer KiwiSaver rate used for the pay. NZ only.","example":"0.03"},"total_kiwi_saver":{"type":"number","title":"Total Kiwi Saver","description":"Combined employee and employer KiwiSaver amount for the pay. NZ only.","example":"150.00"},"tax_plus_student_loan":{"type":"number","title":"Tax Plus Student Loan","description":"Combined PAYE tax and NZ student loan amount for the pay. NZ only.","example":"1045.00"},"hours":{"items":{"$ref":"#/components/schemas/HoursOut"},"type":"array","title":"Hours","description":"A list of pay hours associated with this pay, including description, rate, units, overtime status, and value.","example":[{"id":1,"description":"Ordinary Time","rate":"30.00","units":"hours","is_overtime":false,"value":"37.5","pay_amount":"1125.00"},{"id":2,"description":"Saturday Overtime","rate":"45.00","units":"hours","is_overtime":true,"value":"5.0","pay_amount":"225.00"}]},"leave":{"items":{"$ref":"#/components/schemas/LeaveOut"},"type":"array","title":"Leave","description":"A list of leave hours associated with this pay, including description, leave type, rate, value, and optional leave loading amount. Leave types can include: HOLIDAY, SICK, LONG SERVICE, PAID PARENTAL, EMPLOYER FUNDED PAID PARENTAL, WORKERS COMP, COMPASSIONATE, ANCILLARY, PAID PUBLIC HOLIDAY, UNPAID, OTHER.","example":[{"id":10,"name":"Annual Leave","leave_type":"HOLIDAY","rate":"38.00","hours":"7.6","leave_loading_amount":"3.80","amount":"288.80"}]},"leave_balance_rows":{"items":{"$ref":"#/components/schemas/LeaveBalanceRow"},"type":"array","title":"Leave Balance Rows","description":"A list of leave balance rows associated with this pay, showing the employee's leave balances.","example":[{"leave_type":"annual","name":"Annual Leave","hours":"120.00"},{"leave_type":"sick","name":"Personal Leave","hours":"80.00"}]},"allowances":{"items":{"$ref":"#/components/schemas/PayAllowance"},"type":"array","title":"Allowances","description":"A list of allowances included in this pay, each with a description and amount.","example":[{"description":"Tool Allowance","amount":"50.00","is_taxable":true,"is_itemised":false,"is_included_in_super_calculations":true,"allowance_category":"TD"}]},"deductions":{"items":{"$ref":"#/components/schemas/PayDeduction"},"type":"array","title":"Deductions","description":"A list of deductions applied to this pay, each with a description and amount.","example":[{"description":"Union Fees","amount":"25.00","is_included_in_super_calculations":false}]},"bonuses":{"items":{"$ref":"#/components/schemas/PayBonus"},"type":"array","title":"Bonuses","description":"A list of bonuses included in this pay, each with a description and amount.","example":[{"description":"Performance Bonus","amount":"500.00","start_date":"2023-01-01","end_date":"2023-01-31","is_included_in_super_calculations":true,"is_directors_fees":false,"is_return_to_work":false,"tax_method":"NORMAL_EARNINGS"}]},"pay_sacrifices":{"items":{"$ref":"#/components/schemas/PaySacrifice"},"type":"array","title":"Pay Sacrifices","description":"A list of salary sacrifices associated with this pay, each with an amount.","example":[{"amount":"150.00","description":"Car Salary Sacrifice","is_included_in_super_calculations":true,"is_super":true}]},"pay_department":{"type":"string","maxLength":32,"minLength":0,"title":"Pay Department","description":"Single department name applied to this pay and all of its items.","example":"Engineering"},"back_payments":{"items":{"$ref":"#/components/schemas/BackPayments"},"type":"array","title":"Back Payments","description":"A list of back payments associated with this pay.","example":[{"description":"Back Pay Adjustment","amount":"200.00","stp_category":"ordinary_time_earnings","tax_method":"NORMAL_EARNINGS","start_date":"2023-01-01","end_date":"2023-01-31"}]}},"type":"object","required":["status","hours","leave","leave_balance_rows","allowances","deductions"],"title":"Pay"},"PayAllowance":{"properties":{"description":{"type":"string","maxLength":60,"minLength":1,"title":"Description","description":"A brief description of the allowance.\nRequired when creating or matching an allowance.","example":"Tool Allowance"},"amount":{"type":"number","title":"Amount","description":"The dollar amount for the allowance.\nRequired when creating a new allowance (or if no allowance matches the description). May be omitted when reusing an existing allowance matched by description.","example":"50.00"},"allowance_category":{"type":"string","title":"Allowance Category","description":"Required allowance category code (e.g. 'TD' for Tools). Only codes are accepted. Codes are required when creating a new allowance; you may omit this when reusing an existing allowance that already has a code. Codes: AD, CD, KN, LD, MD, OD, QN, RD, TD. (Labels for reference: Cents per KM, Award Transport, Laundry, Overtime Meals, Domestic & Overseas Travel/Accommodation, Tools, Tasks, Qualifications/Certificates, Other)","example":"TD"},"is_taxable":{"type":"boolean","title":"Is Taxable","description":"Whether the allowance is taxable.\n- Defaults to True when creating a new employee allowance.\n","example":true},"is_itemised":{"type":"boolean","title":"Is Itemised","description":"Whether the allowance is itemised on the pay.\n- Defaults to False when creating a new employee allowance.\n","example":false},"is_included_in_super_calculations":{"type":"boolean","title":"Is Included In Super Calculations","description":"Whether this allowance is included in superannuation calculations.\n- Defaults to True when creating a new employee allowance.\n","example":true}},"additionalProperties":false,"type":"object","required":["description"],"title":"PayAllowance"},"PayBonus":{"properties":{"amount":{"type":"number","title":"Amount","description":"The dollar amount for the bonus.\nRequired when creating a new bonus (or if no bonus matches the description). May be omitted when reusing an existing bonus matched by description.","example":"100.00"},"description":{"type":"string","maxLength":60,"minLength":1,"title":"Description","description":"A brief description of the bonus.\nRequired when creating or matching a bonus.","example":"Performance Bonus"},"start_date":{"type":"string","format":"date","title":"Start Date","description":"The start date for the bonus period. Required when tax_method uses a specific date range.","example":"2023-01-01"},"end_date":{"type":"string","format":"date","title":"End Date","description":"The end date for the bonus period. Required when tax_method uses a specific date range.","example":"2023-01-31"},"is_included_in_super_calculations":{"type":"boolean","title":"Is Included In Super Calculations","description":"Whether this bonus is included in superannuation calculations.\n- Defaults to True when creating a new employee bonus.\n","example":true},"is_directors_fees":{"type":"boolean","title":"Is Directors Fees","description":"Indicates if the bonus is for director's fees.","example":false},"is_return_to_work":{"type":"boolean","title":"Is Return To Work","description":"Indicates if the bonus is a return to work bonus.","example":false},"is_nz_ess":{"type":"boolean","title":"Is Nz Ess","description":"Whether this bonus is an NZ employee share scheme amount. NZ only.","example":false},"is_nz_ess_cash_settled":{"type":"boolean","title":"Is Nz Ess Cash Settled","description":"Whether the NZ ESS amount is cash settled. NZ only.","example":false},"withhold_paye":{"type":"boolean","title":"Withhold Paye","description":"Whether PAYE should be withheld for this NZ bonus. NZ only.","example":true},"tax_as_nz_extra_pay":{"type":"boolean","title":"Tax As Nz Extra Pay","description":"Whether to tax this bonus as NZ extra pay. NZ only.","example":false},"is_nz_discretionary":{"type":"boolean","title":"Is Nz Discretionary","description":"Whether this NZ bonus is discretionary and excluded from holiday pay gross earnings. NZ only.","example":false},"tax_method":{"type":"string","title":"Tax Method","description":"The tax calculation method for the bonus. Provide the *code* (e.g. 'NORMAL_EARNINGS'); docs display the readable labels. Allowed codes with labels: NORMAL_EARNINGS = As normal earnings; SPREAD_OVER_SPECIFIC_RANGE = Use date range; SPREAD_OVER_FINANCIAL_YEAR = Over this financial year; METHOD_A_WHOLE_YEAR = Method A (Whole Year); METHOD_A_SPECIFIC_RANGE = Method A (Use Date Range); METHOD_B1 = Method B(i)(Use Date Range); METHOD_B2 = Method B(ii)(Whole Year).","example":"NORMAL_EARNINGS"}},"additionalProperties":false,"type":"object","required":["description"],"title":"PayBonus"},"PayCreate":{"properties":{"employee_id":{"type":"integer","title":"Employee Id","description":"The internal Lightning Payroll (LP) unique ID for the employee. Use this if `identifier_type=employee_id`.","example":1234},"employee_number":{"type":"string","maxLength":32,"minLength":0,"title":"Employee Number","description":"The external user-controlled employee number. Required only if `identifier_type=employee_number`. Must be unique across ALL companies.","example":"EMP001"},"hours":{"items":{"$ref":"#/components/schemas/PayHours"},"type":"array","title":"Hours","description":"Optional list of pay hour items (may be empty), including description, rate, multiplier, or pay-rate mapping keys (`rate_reference` / `rate_description`), units, overtime status, and value.","example":[{"description":"Ordinary Time","rate":"30.00","units":"hours","is_overtime":false,"value":"37.5"},{"description":"Saturday Overtime","multiplier":"1.5","units":"hours","is_overtime":true,"value":"5.0"},{"description":"Ordinary Time","rate_reference":"system:ordinary_time","units":"hours","value":"7.6"}]},"leave":{"items":{"$ref":"#/components/schemas/Leave"},"type":"array","title":"Leave","description":"Optional list of leave items (may be empty), including description, leave type, rate/multiplier, value, date, and optional leave loading amount. `rate` is optional; when omitted the employee's pay_rate_per_hour is used.","example":[{"description":"Annual Leave","leave_type":"HOLIDAY","multiplier":"1.0","value":"7.6","leave_loading_amount":"3.80"}]},"pay_department":{"type":"string","maxLength":32,"minLength":0,"title":"Pay Department","description":"Department/Cost-centre name or code to be applied to all items in this entire pay. ","example":"Engineering"},"allowances":{"items":{"$ref":"#/components/schemas/PayAllowance"},"type":"array","title":"Allowances","description":"A list of allowances to be included in the pay.\n\nUsage rules:\n- IDs are not accepted; providing an `id` will raise a 400 Bad Request because it's a forbidden field. Match allowances by `description` instead.\n- The API will attempt to find an existing allowance for the employee with the same `description`.\n  - If a match is found, that allowance will be reused and creation-only required fields can be omitted (e.g. `amount`, `allowance_category`—existing values are reused).\n  - If no match is found, a NEW allowance will be created for this employee. In this case, `description`, `amount` and `allowance_category` (code) are REQUIRED.\n    • `allowance_category` must be one of the codes: AD, CD, KN, LD, MD, OD, QN, RD, TD (labels for reference: Cents per KM, Award Transport, Laundry, Overtime Meals, Domestic & Overseas Travel/Accommodation, Tools, Tasks, Qualifications/Certificates, Other). Only codes are accepted for new allowances.     • `is_taxable` defaults to True if not supplied.\n    • `is_itemised` defaults to False if not supplied.\n    • `is_included_in_super_calculations` defaults to True if not supplied.","example":[{"description":"Tool Allowance","amount":"50.00","allowance_category":"TD"},{"description":"Car Allowance","amount":"200.00","is_taxable":true,"is_itemised":true,"is_included_in_super_calculations":false,"allowance_category":"RD"}]},"deductions":{"items":{"$ref":"#/components/schemas/PayDeduction"},"type":"array","title":"Deductions","description":"A list of deductions to be included in the pay.\n\nUsage rules:\n- IDs are not accepted; providing an `id` will raise a 400 Bad Request because it's a forbidden field. Match deductions by `description` instead.\n- The API will attempt to find an existing deduction for the employee with the same `description`.\n  - If a match is found, that deduction will be reused and creation-only required fields can be omitted (e.g. `amount`, `classification`—existing values are reused).\n  - If no match is found, a NEW deduction will be created for this employee. In this case, `description`, `amount`, and `classification` (code) are REQUIRED.\n    • `classification` must be one of: CHARITY, CHILD_SUPPORT_DEDUCTION, CHILD_SUPPORT_GARNISHEE, NORMAL, UNION_FEES. Only codes are accepted for new deductions.\n    • `is_included_in_super_calculations` defaults to True if not supplied.","example":[{"description":"Union Fees","amount":"25.00","classification":"UNION_FEES"},{"description":"Health Insurance","amount":"100.00","classification":"NORMAL","is_included_in_super_calculations":false}]},"bonuses":{"items":{"$ref":"#/components/schemas/PayBonus"},"type":"array","title":"Bonuses","description":"A list of bonuses to be included in the pay.\n\nUsage rules:\n- IDs are not accepted; providing an `id` will raise a 400 Bad Request because it's a forbidden field. Match bonuses by `description` instead.\n- The API will attempt to find an existing bonus for the employee with the same `description`.\n  - If a match is found, that bonus will be reused and creation-only required fields can be omitted (e.g. `amount`, `tax_method`, and any range dates—existing values are reused).\n  - If no match is found, a NEW bonus will be created for this employee. In this case, `description`, `amount`, and `tax_method` are REQUIRED.\n    • `tax_method` must be one of: NORMAL_EARNINGS = As normal earnings; SPREAD_OVER_SPECIFIC_RANGE = Use date range; SPREAD_OVER_FINANCIAL_YEAR = Over this financial year; METHOD_A_WHOLE_YEAR = Method A (Whole Year); METHOD_A_SPECIFIC_RANGE = Method A (Use Date Range); METHOD_B1 = Method B(i)(Use Date Range); METHOD_B2 = Method B(ii)(Whole Year) (send the *code*, docs show the labels). Defaults to 'NORMAL_EARNINGS' if not supplied.\n    • If `tax_method` is a date-range method, `start_date` and `end_date` are REQUIRED.\n    • `is_included_in_super_calculations` defaults to True if not supplied.\n    • `is_directors_fees` defaults to False if not supplied.\n    • `is_return_to_work` defaults to False if not supplied.","example":[{"description":"Performance Bonus","amount":"500.00","tax_method":"NORMAL_EARNINGS"},{"description":"Director's Fee","amount":"1000.00","tax_method":"SPREAD_OVER_SPECIFIC_RANGE","start_date":"2023-01-01","end_date":"2023-01-31","is_included_in_super_calculations":false,"is_directors_fees":true,"is_return_to_work":false}]},"pay_sacrifices":{"items":{"$ref":"#/components/schemas/PaySacrifice"},"type":"array","title":"Pay Sacrifices","description":"A list of pay sacrifices to be included in the pay.\n\nUsage rules:\n- IDs are not accepted; providing an `id` will raise a 400 Bad Request because it's a forbidden field. Match pay sacrifices by `description` instead.\n- The API will attempt to find an existing pay sacrifice for the employee with the same `description`.\n  - If a match is found, that pay sacrifice will be reused and creation-only required fields can be omitted (e.g. `amount`—existing values are reused).\n  - If no match is found, a NEW pay sacrifice will be created for this employee. In this case,    `description` and `amount` are REQUIRED.\n    • `is_included_in_super_calculations` defaults to True if not supplied.\n    • `is_super` defaults to True if not supplied.","example":[{"description":"Laptop Salary Sacrifice"},{"description":"Car Salary Sacrifice","amount":"300.00","is_included_in_super_calculations":false,"is_super":true}]},"back_payments":{"items":{"$ref":"#/components/schemas/BackPayments"},"type":"array","title":"Back Payments","description":"A list of back payments to be included in the pay.\n\nUsage rules:\n- IDs are not accepted; providing an `id` will raise a 400 Bad Request because it's a forbidden field. Match back payments by `description` and `amount` instead.\n- The API will attempt to find an existing back payment for the employee with the same `description` and `amount`.\n  - If a match is found, that back payment will be reused.\n  - If no match is found, a NEW back payment will be created for this employee. In this case, `description`, `amount`, and `stp_category` (code, underscored) are REQUIRED.\n    • `stp_category` must be one of: BONUS_COMMISSION_NON_DIRECTOR_S_FEES, DIRECTOR_S_FEES, GROSS, ITEMISED_ALLOWANCESAD, ITEMISED_ALLOWANCESCD, ITEMISED_ALLOWANCESKN, ITEMISED_ALLOWANCESLD, ITEMISED_ALLOWANCESMD, ITEMISED_ALLOWANCESOD, ITEMISED_ALLOWANCESQN, ITEMISED_ALLOWANCESRD, ITEMISED_ALLOWANCESTD, LEAVEA, LEAVEC, LEAVEO, LEAVEP, LEAVEU, LEAVEW, OVERTIME, UNCLASSIFIED. Only codes are accepted for new back payments.\n    • `tax_method`, `start_date`, and `end_date` are optional.","example":[{"description":"Back Pay Adjustment","amount":"200.00","stp_category":"GROSS","tax_method":"NORMAL_EARNINGS","start_date":"2023-01-01","end_date":"2023-01-31"}]}},"type":"object","title":"PayCreate"},"PayDeduction":{"properties":{"description":{"type":"string","maxLength":60,"minLength":1,"title":"Description","description":"A brief description of the deduction.\nRequired when creating or matching a deduction.","example":"Union Fees"},"amount":{"type":"number","title":"Amount","description":"The dollar amount for the deduction.\nRequired when creating a new deduction (or if no deduction matches the description). May be omitted when reusing an existing deduction matched by description.","example":"25.00"},"classification":{"type":"string","title":"Classification","description":"Deduction classification code (use underscores). Codes are required when creating a new deduction; you may omit when reusing an existing deduction. Codes: CHARITY, CHILD_SUPPORT_DEDUCTION, CHILD_SUPPORT_GARNISHEE, NORMAL, UNION_FEES.","example":"UNION_FEES"},"is_included_in_super_calculations":{"type":"boolean","title":"Is Included In Super Calculations","description":"Whether this deduction affects superannuation calculations.\n- Defaults to True when creating a new deduction.\n","example":false}},"additionalProperties":false,"type":"object","required":["description"],"title":"PayDeduction"},"PayHours":{"properties":{"description":{"type":"string","maxLength":60,"minLength":1,"title":"Description","description":"A brief description of the pay hours.","example":"Regular Hours, KMs, Overtime, Saturday, etc."},"rate":{"type":"number","title":"Rate","description":"The dollar amount per unit for the pay hours row, such as hourly rate, per kilometre rate, etc. Provide either `rate` or `multiplier`.","example":"30.00"},"multiplier":{"type":"number","title":"Multiplier","description":"Alternative to `rate`. Multiplies the employee's pay_rate_per_hour (e.g., 1.5 for time-and-a-half, 2.0 for double time).","example":"1.5"},"rate_reference":{"type":"string","title":"Rate Reference","description":"Optional stable pay-rate reference from `GET /api/employees/{employee_id}/pay-rates` (for example `system:ordinary_time`, `employee:42`, `company:73`). Use as an alternative to sending a raw `rate`.","example":"company:73"},"rate_description":{"type":"string","maxLength":60,"minLength":0,"title":"Rate Description","description":"Optional pay-rate description to resolve a rate by description for this employee. Use when you do not send `rate`. If multiple rates share the same description, the API will return a validation error and require `rate_reference`.","example":"Ordinary Time"},"units":{"type":"string","maxLength":32,"minLength":0,"title":"Units","description":"The type of units for the pay hours row, such as hours, kilometres, buckets, etc.","example":"hours"},"is_overtime":{"type":"boolean","title":"Is Overtime","description":"Indicates whether the hours are overtime hours, which affects super guarantee calculations.","default":false,"example":false},"value":{"type":"number","title":"Value","description":"The number of units for the pay hours row, such as hours worked, kilometres driven, etc.","example":"37.5"}},"type":"object","required":["description","units","value"],"title":"PayHours"},"PayHoursBase":{"properties":{"description":{"type":"string","maxLength":60,"minLength":1,"title":"Description","example":"Ordinary Time"},"rate":{"type":"number","title":"Rate","description":"The dollar amount per unit for this hours row. Provide either `rate` or `multiplier`.","example":"30.00"},"multiplier":{"type":"number","title":"Multiplier","description":"Alternative to `rate`. Multiplies the employee's pay_rate_per_hour (e.g., 1.5 for time-and-a-half, 2.0 for double time).","example":"1.5"},"rate_reference":{"type":"string","title":"Rate Reference","description":"Optional stable pay-rate reference from `GET /api/employees/{employee_id}/pay-rates` (for example `system:ordinary_time`, `employee:42`, `company:73`). Use as an alternative to sending a raw `rate`.","example":"employee:42"},"rate_description":{"type":"string","maxLength":60,"minLength":0,"title":"Rate Description","description":"Optional pay-rate description to resolve a rate by description for this employee. Use when you do not send `rate`. If multiple rates share the same description, the API will return a validation error and require `rate_reference`.","example":"Ordinary Time"},"units":{"type":"string","maxLength":32,"minLength":0,"title":"Units","example":"hours"},"is_overtime":{"type":"boolean","title":"Is Overtime","default":false,"example":false},"value":{"type":"number","title":"Value","example":"37.5"}},"type":"object","required":["description","units","value"],"title":"PayHoursBase"},"PayHoursUpdate":{"properties":{"description":{"type":"string","maxLength":60,"minLength":1,"title":"Description","example":"Ordinary Time"},"rate":{"type":"number","title":"Rate","description":"The dollar amount per unit for this hours row. Provide either `rate` or `multiplier`.","example":"30.00"},"multiplier":{"type":"number","title":"Multiplier","description":"Alternative to `rate`. Multiplies the employee's pay_rate_per_hour (e.g., 1.5 for time-and-a-half, 2.0 for double time).","example":"1.5"},"rate_reference":{"type":"string","title":"Rate Reference","description":"Optional stable pay-rate reference from `GET /api/employees/{employee_id}/pay-rates` (for example `system:ordinary_time`, `employee:42`, `company:73`). Use as an alternative to sending a raw `rate`.","example":"employee:42"},"rate_description":{"type":"string","maxLength":60,"minLength":0,"title":"Rate Description","description":"Optional pay-rate description to resolve a rate by description for this employee. Use when you do not send `rate`. If multiple rates share the same description, the API will return a validation error and require `rate_reference`.","example":"Ordinary Time"},"units":{"type":"string","maxLength":32,"minLength":0,"title":"Units","example":"hours"},"is_overtime":{"type":"boolean","title":"Is Overtime","default":false,"example":false},"value":{"type":"number","title":"Value","example":"37.5"},"id":{"type":"integer","title":"Id"}},"type":"object","required":["description","units","value","id"],"title":"PayHoursUpdate"},"PayRunPays":{"properties":{"pay_run_id":{"type":"integer","title":"Pay Run Id","description":"The unique identifier of the pay run.","example":1001},"pay_run_end_date":{"type":"string","format":"date","title":"Pay Run End Date","description":"The end date of the pay run period.","example":"2023-01-31"},"pay_period":{"type":"string","title":"Pay Period","description":"The pay period frequency associated with the pay run (WEEKLY, FORTNIGHTLY, MONTHLY).","example":"WEEKLY"},"pays":{"items":{"$ref":"#/components/schemas/Pay"},"type":"array","minItems":0,"title":"Pays","description":"A list of basic pay information associated with the pay run."}},"type":"object","required":["pay_run_id","pay_run_end_date","pay_period","pays"],"title":"PayRunPays"},"PaySacrifice":{"properties":{"amount":{"type":"number","title":"Amount","description":"The dollar amount for the pay sacrifice.\nRequired when creating a new pay sacrifice (or if no pay sacrifice matches the description). May be omitted when reusing an existing pay sacrifice matched by description.","example":"150.00"},"description":{"type":"string","maxLength":60,"minLength":0,"title":"Description","description":"A brief description of the pay sacrifice.\nRequired when creating or matching a pay sacrifice.","example":"Salary Sacrifice for Car"},"is_included_in_super_calculations":{"type":"boolean","title":"Is Included In Super Calculations","description":"Whether this pay sacrifice is included in superannuation calculations.\n- Defaults to True when creating a new employee pay sacrifice.\n","example":true},"is_super":{"type":"boolean","title":"Is Super","description":"Indicates if the pay sacrifice is for superannuation.","example":true}},"additionalProperties":false,"type":"object","required":["description"],"title":"PaySacrifice"},"PayUpdate":{"properties":{"hours":{"items":{"anyOf":[{"$ref":"#/components/schemas/PayHoursUpdate"},{"$ref":"#/components/schemas/PayHoursBase"}]},"type":"array","title":"Hours"},"leave":{"items":{"anyOf":[{"$ref":"#/components/schemas/LeaveUpdate"},{"$ref":"#/components/schemas/LeaveBase"}]},"type":"array","title":"Leave"},"leave_balance_rows":{"items":{"$ref":"#/components/schemas/LeaveBalanceRow"},"type":"array","title":"Leave Balance Rows"}},"type":"object","required":["hours","leave","leave_balance_rows"],"title":"PayUpdate"},"RequiredOwnedAddOn":{"properties":{"add_on_key":{"type":"string","title":"Add On Key","description":"Branding add-on key owned by the reseller."},"add_on_label":{"type":"string","title":"Add On Label","description":"Human-readable add-on label."},"customer_has_required_add_on":{"type":"boolean","title":"Customer Has Required Add On","description":"Whether the matched existing customer already has this branded add-on active."}},"additionalProperties":false,"type":"object","required":["add_on_key","add_on_label","customer_has_required_add_on"],"title":"RequiredOwnedAddOn"},"TokenResponse":{"properties":{"access_token":{"type":"string","title":"Access Token","description":"JWT access token, signed with our system key","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…"},"token_type":{"type":"string","enum":["Bearer"],"title":"Token Type","description":"Always **Bearer** for Lightning Payroll APIs","example":"Bearer"},"expires_in":{"type":"integer","title":"Expires In","description":"Lifetime of the `access_token` in **seconds** (currently: 1800 = 30 minutes)","example":1800},"refresh_token":{"type":"string","title":"Refresh Token","description":"New opaque refresh token string (store this securely – it is shown only once)","example":"v5G3sbpZBqC4mfA5fEUvVxv8povwU9Dg82kUn4qB6-M"},"refresh_expires_in":{"type":"integer","title":"Refresh Expires In","description":"Lifetime of the `refresh_token` in **seconds** (default: 2 592 000 = 30 days)","example":2592000}},"type":"object","required":["access_token","token_type","expires_in","refresh_token","refresh_expires_in"],"title":"TokenResponse","description":"Standard OAuth 2.0 token payload returned by this endpoint."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"login"}}},"HTTPBearer":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"Address"},{"name":"Admin"},{"name":"API Health"},{"name":"Authentication"},{"name":"Company"},{"name":"Employee"},{"name":"FAQs"},{"name":"MCP"},{"name":"Pay Runs"},{"name":"Pays"},{"name":"Public"},{"name":"Single Touch"},{"name":"Upsell"}]}