> ## 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. # List form batches ## OpenAPI ````yaml /spec/openapi.json get /form_batches 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: /form_batches: get: tags: - Form Batches summary: List form batches operationId: form-batches-index parameters: - name: owner_id in: query schema: type: string required: false description: >- Filter form batches based on the owner. Accepts multiple comma-separated values. - name: owner_type in: query schema: type: string enum: - business_entity required: false description: Filter form batches based on the type of owner. - name: form_type in: query schema: anyOf: - type: string enum: - rl1 - roe - t4 - t4a - td1 - td1ab - td1bc - td1mb - td1nb - td1nl - td1ns - td1nt - td1nu - td1on - td1pe - td1sk - td1x - td1yt - tp_1015_3_v - tp_1015_r_13_v - type: array items: type: string enum: - rl1 - roe - t4 - t4a - td1 - td1ab - td1bc - td1mb - td1nb - td1nl - td1ns - td1nt - td1nu - td1on - td1pe - td1sk - td1x - td1yt - tp_1015_3_v - tp_1015_r_13_v required: false description: Filter form batches based on the form type. - name: form_stage in: query schema: anyOf: - type: string enum: - amendment - cancellation - original - type: array items: type: string enum: - amendment - cancellation - original required: false description: >- Filter form batches based on the stage (original, amendment, cancellation). - name: status in: query schema: anyOf: - type: string enum: - done - draft - processing - submitted - type: array items: type: string enum: - done - draft - processing - submitted required: false description: Filter form batches based on the status. - name: sort in: query schema: type: string enum: - effective_date required: false description: >- Sort order is specified using the format `sort=field[:direction][,field[:direction],...]` where `field` is the name of the field to sort by and `direction` is the optional sort direction (`asc` or `desc`). - name: expand in: query schema: type: array items: type: string enum: - owner required: false responses: '200': description: OK content: application/json: schema: type: object properties: object: type: string description: The type of the object in Nmbr (`"list"`). readOnly: true data: type: array items: 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 (`"form_batch"`). readOnly: true data: type: object allOf: - $ref: '#/components/schemas/FormBatch' anyOf: - type: object title: Default - type: object title: With owner expanded properties: owner: type: object properties: data: $ref: '#/components/schemas/FormBatchOwner' example: object: list data: - id: object: form_batch data: owner: id: object: business_entity links: self: /business_entities/ form_type: t4 form_stage: original effective_date: '2026-01-01' status: draft contact_name: Prof. Brody Ernser III contact_email: weber.pierre@example.net contact_area_code: '657' contact_phone_number: '3654916' contact_extension: null note: null metadata: counts: total: 0 valid: 0 invalid: 0 draft: 0 approved: 0 processing: 0 submitted: 0 done: 0 rejected: 0 flags: is_submittable: false timestamps: submitted_at: null completed_at: null identifiers: confirmation_number: null created_at: '2026-01-01T00:00:00.000000Z' updated_at: '2026-01-01T00:00:00.000000Z' links: self: /form_batches/ - id: object: form_batch data: owner: id: object: business_entity links: self: /business_entities/ form_type: t4 form_stage: amendment effective_date: '2026-01-01' status: draft contact_name: Prof. Brody Ernser III contact_email: weber.pierre@example.net contact_area_code: '657' contact_phone_number: '3654916' contact_extension: null note: null metadata: counts: total: 0 valid: 0 invalid: 0 draft: 0 approved: 0 processing: 0 submitted: 0 done: 0 rejected: 0 flags: is_submittable: false timestamps: submitted_at: null completed_at: null identifiers: confirmation_number: null created_at: '2026-01-01T00:00:00.000000Z' updated_at: '2026-01-01T00:00:00.000000Z' links: self: /form_batches/ links: first: /form_batches?page=1 last: /form_batches?page=1 prev: null next: null meta: current_page: 1 last_page: 1 per_page: 15 total: 2 has_more: false components: schemas: FormBatch: type: object title: Form Batch properties: owner: type: object description: The owner of this form batch. Currently always a Business Entity. 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 form_type: type: string description: The type of Forms in this batch (e.g. T4, RL-1). maxLength: 255 enum: - rl1 - roe - t4 - t4a - td1 - td1ab - td1bc - td1mb - td1nb - td1nl - td1ns - td1nt - td1nu - td1on - td1pe - td1sk - td1x - td1yt - tp_1015_3_v - tp_1015_r_13_v form_stage: type: string description: >- The lifecycle stage of the Forms in this batch: original, amendment, or cancellation. enum: - amendment - cancellation - original effective_date: type: string description: >- The effective date used to determine the form variant for all Forms in this batch. format: date status: type: string description: The submission status of this batch. enum: - done - draft - processing - submitted contact_name: type: string description: The name of the contact person responsible for this submission. maxLength: 255 contact_email: type: string description: The email address of the contact person. maxLength: 255 contact_area_code: type: string description: The 3-digit area code of the contact's phone number. maxLength: 255 contact_phone_number: type: string description: The 7-digit phone number of the contact. maxLength: 255 contact_extension: type: string description: The optional extension for the contact's phone number. nullable: true maxLength: 255 note: type: string description: An optional note for this form batch. nullable: true metadata: type: object description: >- Form-type-specific metadata for this batch. Structure varies by form type. nullable: true properties: counts: type: object nullable: true properties: total: type: number nullable: true format: decimal valid: type: number nullable: true format: decimal invalid: type: number nullable: true format: decimal draft: type: number nullable: true format: decimal approved: type: number nullable: true format: decimal processing: type: number nullable: true format: decimal submitted: type: number nullable: true format: decimal done: type: number nullable: true format: decimal rejected: type: number nullable: true format: decimal flags: type: object nullable: true properties: is_submittable: type: boolean timestamps: type: object nullable: true properties: submitted_at: type: string readOnly: true nullable: true format: dateTime completed_at: type: string readOnly: true nullable: true format: dateTime identifiers: type: object nullable: true properties: confirmation_number: type: string 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 FormBatchOwner: type: object oneOf: - $ref: '#/components/schemas/BusinessEntity' BusinessEntity: type: object title: Business Entity properties: business_number: type: string description: >- The Canada Revenue Agency (CRA) Business Number (BN) for this business entity, used to identify the business for payroll tax remittances. nullable: true maxLength: 255 name: type: string description: The business entity's operating or trade name. maxLength: 255 legal_name: type: string description: The business entity's registered legal name. nullable: true maxLength: 255 legal_registration_number: type: string description: The provincial business registration number. nullable: true maxLength: 255 address_line_1: type: string description: >- The first line of the business entity's mailing address. Canada Revenue Agency forms (T4, RL-1) truncate this to the length those forms allow. nullable: true maxLength: 255 address_line_2: type: string description: >- The second line of the business entity's mailing address. Canada Revenue Agency forms (T4, RL-1) truncate this to the length those forms allow. nullable: true maxLength: 255 city: type: string description: The city of the business entity's mailing address. nullable: true maxLength: 255 in_preview: type: boolean description: >- When `true`, the business entity is in preview mode. In preview mode, Payrolls can be run and approved but no real money movement occurs. administrative_area: type: string description: >- The region of the business entity's mailing address — the province, state, or county, depending on the country. For Canadian business entities this is the province. nullable: true maxLength: 255 province_code: type: string description: >- This attribute is deprecated and will be removed. A deprecated alias of `administrative_area` that mirrors its value. Use `administrative_area` instead. nullable: true deprecated: true country_code: type: string description: The country code for the business entity's mailing address. nullable: true maxLength: 2 postal_code: type: string description: The postal code for the business entity's mailing address. nullable: true maxLength: 255 contact_name: type: string description: The name of the primary contact at the business entity. nullable: true maxLength: 255 contact_email: type: string description: The email address of the primary contact at the business entity. nullable: true maxLength: 255 contact_area_code: type: string description: The area code for the primary contact's phone number. nullable: true maxLength: 255 contact_phone_number: type: string description: The primary contact's phone number, excluding area code. nullable: true maxLength: 255 contact_extension: type: string description: The extension for the primary contact's phone number. nullable: true maxLength: 255 pay_day_movement_setting: type: string description: >- The business entity-level setting for how pay dates are adjusted when they fall on a weekend or bank holiday. If set to `inherit`, the Company's setting is used. enum: - inherit - next_business_day - previous_business_day vacation_pay_formula_setting: type: string description: >- The formula used to calculate vacation pay for Employees in this business entity. enum: - pay_date - period_end - period_start remitter_type: type: string description: >- The Canada Revenue Agency (CRA) remitter type, which determines the frequency of payroll tax remittances to the CRA. nullable: true enum: - accelerated_threshold_1 - accelerated_threshold_2 - quarterly - regular status: type: string description: >- The business entity's current status. A business entity must reach `approved` status before live Payrolls can be processed. enum: - approved - onboarding - suspended company: 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 (`"company"`). readOnly: true warnings: type: object description: >- A collection of data validation warnings for this business entity. Warnings indicate incomplete or potentially incorrect data and could prevent payroll processing. nullable: true properties: object: type: string nullable: true data: type: array nullable: true items: type: object properties: object: type: string nullable: true data: type: object nullable: true properties: namespace: type: string nullable: true type: type: string 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 available_tax_properties: type: array description: >- A list of Tax Property template identifiers supported for this business entity, based on its jurisdiction. nullable: true items: type: string effective_processing_speed: type: string description: >- The resolved processing speed after applying inheritance from the Partner if `processing_speed` is `inherit`. nullable: true processing_speed: type: string description: >- The business entity-level processing speed setting. If set to `inherit`, the Partner's processing speed is used. enum: - five_day - four_day - inherit - one_day - three_day - two_day has_bank_accounts: type: boolean description: Whether this business entity has any Bank Accounts configured. has_pay_schedules: type: boolean description: Whether this business entity has any Pay Schedules configured. has_payrolls: type: boolean description: Whether this business entity has any Payrolls. current_tax_jurisdiction: type: string description: >- The current tax jurisdiction for the business entity, derived from its `ca::province_of_employment` Tax Property. nullable: true ca_settings: type: object description: >- Canada-specific settings for this business entity. Only present for business entities with a Canadian address. nullable: true properties: roe_submission_setting: type: string description: >- Indicates whether Record of Employment (ROE) submissions are managed by Nmbr (`managed`) or by the employer directly (`manual`). nullable: true accounting_settings: type: object description: >- Accounting-related settings for this business entity. New clients should read and write these through this object; the top-level `default_bank_accounting_code`, `default_payroll_payable_accounting_code`, `resolve_journal_entry_stat_withholdings`, and `primary_tag_group` fields are retained as aliases for backwards compatibility. nullable: true properties: default_bank_accounting_code: description: >- The Accounting Code used as the default bank account row when generating journal entries. default_payroll_payable_accounting_code: description: >- The Accounting Code used as the default payroll payable row when generating journal entries. resolve_journal_entry_stat_withholdings: type: boolean description: >- When `true`, statutory withholding line items (employee and employer) are split across tracking dimensions derived from their applicable source earnings. When `false`, each statutory withholding appears as a single unsplit row in journal entries. primary_tag_group: description: >- The Tag Group that drives default accounting-code resolution for line items. Setting this also flags the group as a journal entry dimension. block_approval_on_incomplete_journal_entries: type: boolean description: >- When `true`, payroll approval is blocked if any exportable journal entry row has no Accounting Code. block_approval_on_missing_export_identifiers: type: boolean description: >- When `true`, payroll approval is blocked if any exportable journal entry row has no Accounting Code OR has one that lacks the enabled integration's external identifier. default_bank_accounting_code: description: |- This attribute is deprecated and will be removed. Use `accounting_settings.default_bank_accounting_code`. deprecated: true default_payroll_payable_accounting_code: description: |- This attribute is deprecated and will be removed. Use `accounting_settings.default_payroll_payable_accounting_code`. deprecated: true preferred_locale: type: string description: >- The locale used for payroll communications sent to Employees and Contractors within this business entity. If not set, the Company's locale is used. nullable: true enum: - en - fr hold_funding_for_verification: type: boolean description: >- When `true`, funding payments will be automatically held after settlement for verification. Downstream payments (employee, CRA, RQ) will not be processed until the funding payment hold is released. resolve_journal_entry_stat_withholdings: type: boolean description: |- This attribute is deprecated and will be removed. Use `accounting_settings.resolve_journal_entry_stat_withholdings`. deprecated: true primary_tag_group: description: |- This attribute is deprecated and will be removed. Use `accounting_settings.primary_tag_group`. deprecated: true 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 ````