> ## Documentation Index > Fetch the complete documentation index at: https://docs.nmbr.co/llms.txt > Use this file to discover all available pages before exploring further. # Create a payroll ## OpenAPI ````yaml /spec/openapi.json post /payrolls openapi: 3.0.0 info: title: Nmbr API description: API to interact with Nmbr Payroll version: 1.0.0 servers: - url: https://sandbox.nmbr.co/services/payroll security: - CompanyToken: [] tags: - name: Accounting Codes - name: Accounting Code Rules - name: Adjustments - name: Allowances - name: Allowance Line Items - name: Allowance Types - name: Async Tasks - name: Bank Accounts - name: Business Entities - name: Business Entity Verifications - name: Business Entity ROE Authorizations - name: Business Presets - name: Calculations - name: Companies - name: Contractors - name: Deductions - name: Deduction Line Items - name: Deduction Types - name: Earnings - name: Earning Line Items - name: Earning Types - name: Effective Tax Properties - name: Employees - name: Employee Benefits - name: Employee Benefit Line Items - name: Employee Benefit Types - name: Employer Benefits - name: Employer Benefit Line Items - name: Employer Benefit Types - name: Employer Statutory Withholding Line Items - name: Employer Statutory Withholding Types - name: Forms - name: Form Batches - name: Form Types - name: Holidays - name: Integrations - name: Journal Entries - name: Overtime Rates - name: Partners - name: Pay Rates - name: Pay Schedules - name: Pay Splits - name: Pay Stubs - name: Payments - name: Payrolls - name: Reimbursements - name: Reimbursement Line Items - name: Reimbursement Types - name: Remittance Accounts - name: Remittance Account Enrollments - name: Reports - name: Statutory Withholding Line Items - name: Statutory Withholding Types - name: Tags - name: Tag Groups - name: Tax Properties - name: Tax Property Templates - name: Tokens - name: Usage Records - name: Usage Summaries - name: Vacation Pay - name: Vacation Pay Settings - name: Webhooks - name: Work Assignments paths: /payrolls: post: tags: - Payrolls summary: Create a payroll operationId: payrolls-store requestBody: content: application/json: schema: allOf: - type: object properties: pay_schedule_id: type: string source_payroll_id: type: string description: >- The ID of the source regular payroll for `off_cycle` payrolls. Only allowed when creating a Payroll of type `off_cycle`. The source payroll must be a regular payroll on the same pay-schedule. type: type: string description: >- The type of payroll. `regular` payrolls are generated automatically on the Pay Schedule. `off_cycle` Payrolls are created manually against a source regular payroll. `historical` and `correction` payrolls are used to record or correct prior periods. enum: - correction - historical - off_cycle - regular note: type: string description: An optional note on the payroll, visible to the partner. nullable: true period_start: type: string description: >- The start date of the pay period. When creating a payroll of type `historical` or `correction`, a `period_start` date is required. A `period_start` date is prohibited on a `off_cycle` payroll. format: date period_end: type: string description: >- The end date of the pay period. When creating a payroll of type `historical` or `correction`, a `period_end` date is required. A `period_end` date is prohibited on a `off_cycle` payroll. format: date custom_pay_frequency: type: string description: >- For payrolls on a custom-frequency Pay Schedule, the pay frequency for this specific pay period. Only allowed when creating a regular payroll on a custom frequency pay schedule where frequency is defined per payroll. enum: - bi-weekly - monthly - semi-monthly - weekly pay_date: type: string description: The date on which Employees and Contractors are paid. format: date original_pay_date: type: string description: >- For payrolls on a custom-frequency Pay Schedule, the originally scheduled pay date before any movement for weekends or bank holidays. Used for year-to-date calculations and tax year assignment. Only allowed when creating a regular payroll on a custom frequency pay schedule. format: date external_ref: type: string maxLength: 255 - type: object required: - pay_schedule_id - type example: pay_schedule_id: source_payroll_id: type: off_cycle pay_date: '2026-01-08' responses: '201': description: Created content: application/json: schema: type: object properties: id: type: string description: The unique identifier of the object in Nmbr. readOnly: true object: type: string description: The type of the object in Nmbr (`"payroll"`). readOnly: true data: $ref: '#/components/schemas/Payroll' example: id: object: payroll data: business_entity: id: object: business_entity links: self: /business_entities/ pay_schedule: id: object: pay_schedule links: self: /pay_schedules/ type: off_cycle period_number: 1 period_label: 1 A period_start: '2026-01-01' period_end: '2026-01-31' pay_date: '2026-01-08' original_pay_date: null debit_date: '2026-01-05' approval_due_at: '2026-01-05T21:30:00.000000Z' regular_periods_count: 12 is_impacted_by_weekend_or_holiday: false is_blocked_by_draft: false note: null employee_summary: gross: null subtractions: null reimbursements: null net: null contractor_summary: gross: null reimbursements: null net: null company_summary: taxes_and_contributions: null benefits: null total: null liability: null cash_requirement: null status: draft approved_at: null is_stale: false stale_since: null source_payroll: id: object: payroll links: self: /payrolls/ warnings: object: list data: [] external_ref: null created_at: '2026-01-01T00:00:00.000000Z' updated_at: '2026-01-01T00:00:00.000000Z' links: self: /payrolls/ components: schemas: Payroll: type: object title: Payroll properties: business_entity: type: object properties: id: type: string description: The unique identifier of the object in Nmbr. readOnly: true object: type: string description: The type of the object in Nmbr (`"business_entity"`). readOnly: true pay_schedule: type: object properties: id: type: string description: The unique identifier of the object in Nmbr. readOnly: true object: type: string description: The type of the object in Nmbr (`"pay_schedule"`). readOnly: true type: type: string description: >- The type of payroll. `regular` payrolls are generated automatically on the Pay Schedule. `off_cycle` Payrolls are created manually against a source regular payroll. `historical` and `correction` payrolls are used to record or correct prior periods. enum: - correction - historical - off_cycle - regular period_number: type: integer description: >- The sequential number of this pay period within the calendar year of its `pay_date`, counting only regular payrolls. `null` for off-cycle, historical, and correction payrolls. nullable: true period_label: type: string description: A human-readable label for this pay period. nullable: true period_start: type: string description: The start date of the pay period. format: date period_end: type: string description: The end date of the pay period. format: date pay_date: type: string description: The date on which Employees and Contractors are paid. format: date original_pay_date: type: string description: >- For payrolls on a custom-frequency Pay Schedule, the originally scheduled pay date before any movement for weekends or bank holidays. Used for year-to-date calculations and tax year assignment. nullable: true format: date debit_date: type: string description: >- The expected date the company's account will be debited the `cash_requirement` amount. nullable: true approval_due_at: type: string description: >- The date and time, in UTC, by which the payroll must be approved to be processed on time. readOnly: true nullable: true format: dateTime regular_periods_count: type: integer description: >- The total number of regular pay periods in this Pay Schedule whose `pay_date` falls in the same calendar year as this payroll's `pay_date`. Used for year-to-date calculations. nullable: true is_impacted_by_weekend_or_holiday: type: boolean description: >- Whether `pay_date` or `approval_due_at` has been moved to avoid falling on a weekend or bank holiday. is_blocked_by_draft: type: boolean description: >- Whether this payroll is blocked from being approved because an earlier payroll on the same Pay Schedule is still in draft status. note: type: string description: An optional note on the payroll, visible to the partner. nullable: true employee_summary: type: object description: A summary of pay across all Employees in this payroll. nullable: true properties: gross: description: The sum of all earnings and allowances. subtractions: description: The total of all deductions, taxes, and benefit contributions. reimbursements: description: The total of non-taxable reimbursements. net: description: The Employee net pay; when negative, a warning is included. contractor_summary: type: object description: A summary of pay across all Contractors in this payroll. nullable: true properties: gross: description: The sum of all earnings. reimbursements: description: The total of non-taxable reimbursements. net: description: The Contractor net pay. company_summary: type: object description: A summary of the company's obligations in this payroll. nullable: true properties: taxes_and_contributions: description: The employer share of statutory remittances (CPP and EI). benefits: description: The total of employer benefit contributions. total: description: The company's total obligations. liability: type: number description: >- The total amount owed by the company for this payroll, including Employee and Contractor net pay, employer tax contributions, and employer benefit contributions. nullable: true format: decimal cash_requirement: type: number description: >- The total amount that will be debited from the company's account when this payroll is approved. nullable: true format: decimal status: type: string description: The current status of the payroll. enum: - approved - draft - failed - paid - partially_paid - processing approved_at: type: string description: The date on which the payroll was approved. nullable: true format: date is_stale: type: boolean description: >- Whether the payroll's tax calculations are out of date. When `true`, `stale_since` indicates when the payroll became stale. stale_since: type: string description: >- The timestamp at which the payroll's tax calculations became stale and need to be recalculated. `null` if the payroll is up to date. readOnly: true nullable: true format: dateTime source_payroll: {} warnings: type: object description: >- A collection of data validation warnings for this payroll. Warnings indicate incomplete or potentially incorrect data and could prevent payroll processing. nullable: true properties: object: type: string nullable: true data: type: object nullable: true external_ref: type: string description: >- A reference to the object in an external system, e.g. the primary key of the object in your application's database. Nmbr doesn't use, validate, parse, or require this value to be unique - it simply stores it for your reference. nullable: true maxLength: 255 created_at: type: string description: The date and time the object was created in Nmbr. readOnly: true format: dateTime updated_at: type: string description: The date and time the object was last updated in Nmbr. readOnly: true format: dateTime securitySchemes: CompanyToken: type: http scheme: bearer ````