> ## 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 forms ## OpenAPI ````yaml /spec/openapi.json get /forms 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: /forms: get: tags: - Forms summary: List forms operationId: forms-index parameters: - name: owner_id in: query schema: type: string required: false description: Filter forms based on the owner. - name: work_assignment_id in: query schema: type: string required: false description: Filter forms based on the Work Assignment. - name: employee_id in: query schema: type: string required: false description: >- Filter forms owned by the Employee or the Employee's Work Assignments. - name: form_batch_id in: query schema: type: string required: false description: Filter forms by Form Batch. - name: 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 forms based on the type of form. - name: status in: query schema: anyOf: - type: string enum: - approved - done - draft - processing - rejected - submitted - type: array items: type: string enum: - approved - done - draft - processing - rejected - submitted required: false description: Filter forms based on the status of form. - name: owner_type in: query schema: type: string enum: - contractor - employee - work_assignment required: false description: Filter forms based on the type of the form's owner. - name: owner_name in: query schema: type: string required: false description: Filter forms based on the owner's name. - name: created_at in: query schema: type: object required: false description: >- Only return forms with a `created_at` date matching the filter. Date filters support two formats: Exact Date Match: Provide a well-formatted date in `YYYY-MM-DD` format for an exact match. Example: `created_at=2024-01-01` Use an array-like syntax to specify a range with one or more comparison operators: - `gt` (greater than) - `gte` (greater than or equal to) - `lte` (less than or equal to) - `lt` (less than) Example: `created_at[gte]=2024-01-01&created_at[lt]=2024-12-31` - name: fields in: query schema: type: array items: type: object required: false description: >- Filter forms by field content. An array of objects with `field` (required) and `value` (optional) keys. Providing only `field` returns forms that have any value for that field; providing both returns forms where that field matches the given value. - name: fields.* in: query schema: type: string required: false - name: fields.*.field in: query schema: type: string required: true - name: fields.*.value in: query schema: type: string required: false - 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: - form_batch - 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"`). readOnly: true data: type: object allOf: - $ref: '#/components/schemas/Form' anyOf: - type: object title: Default - type: object title: With owner expanded properties: owner: type: object properties: data: $ref: '#/components/schemas/FormOwner' - type: object title: With form_batch expanded properties: form_batch: type: object properties: data: $ref: '#/components/schemas/FormBatch' example: object: list data: - id: object: form data: owner: id: object: employee links: self: /employees/ form_batch: null stage: original note: null type: roe effective_date: '2026-01-01' version_year: '2026' version_month: january validation_error_count: 19 status: draft is_editable: true metadata: flags: is_editable: true is_submittable: false is_amendable: false is_xml_exportable: true details: submission_setting: manual business_entity_name: null roe_format: standard submission_setting: manual business_entity_name: null block_1_serial_number: null block_2_serial_number_of_amended_or_replaced: null block_3_employer_payroll_reference_number: null block_5_cra_payroll_account_number: null block_6_pay_period_type: null block_8_social_insurance_number: null employee_first_name: null employee_initial: null employee_last_name: null employee_address_line_1: null employee_address_line_2: null employee_address_line_3: null employee_postal_code: null contact_first_name: null contact_last_name: null contact_area_code: null contact_phone_number: null contact_phone_number_extension: null block_10_first_day_worked: null block_11_last_day_for_which_paid: null block_12_final_pay_period_ending_date: null block_16_separation_code: null block_14_expected_recall_code: null block_14_expected_recall_date: null block_18_comments: null block_15_total_insurable_hours: null pp1_insurable_earnings: null pp2_insurable_earnings: null pp3_insurable_earnings: null pp4_insurable_earnings: null pp5_insurable_earnings: null pp6_insurable_earnings: null pp7_insurable_earnings: null pp8_insurable_earnings: null pp9_insurable_earnings: null pp10_insurable_earnings: null pp11_insurable_earnings: null pp12_insurable_earnings: null pp13_insurable_earnings: null pp14_insurable_earnings: null pp15_insurable_earnings: null pp16_insurable_earnings: null pp17_insurable_earnings: null pp18_insurable_earnings: null pp19_insurable_earnings: null pp20_insurable_earnings: null pp21_insurable_earnings: null pp22_insurable_earnings: null pp23_insurable_earnings: null pp24_insurable_earnings: null pp25_insurable_earnings: null pp26_insurable_earnings: null pp27_insurable_earnings: null pp28_insurable_earnings: null pp29_insurable_earnings: null pp30_insurable_earnings: null pp31_insurable_earnings: null pp32_insurable_earnings: null pp33_insurable_earnings: null pp34_insurable_earnings: null pp35_insurable_earnings: null pp36_insurable_earnings: null pp37_insurable_earnings: null pp38_insurable_earnings: null pp39_insurable_earnings: null pp40_insurable_earnings: null pp41_insurable_earnings: null pp42_insurable_earnings: null pp43_insurable_earnings: null pp44_insurable_earnings: null pp45_insurable_earnings: null pp46_insurable_earnings: null pp47_insurable_earnings: null pp48_insurable_earnings: null pp49_insurable_earnings: null pp50_insurable_earnings: null pp51_insurable_earnings: null pp52_insurable_earnings: null pp53_insurable_earnings: null vacation_pay_code: null vacation_pay_start_date: null vacation_pay_end_date: null vacation_pay_amount: null statutory_holiday_pay_for_date_1: null statutory_holiday_pay_for_amount_1: null statutory_holiday_pay_for_date_2: null statutory_holiday_pay_for_amount_2: null statutory_holiday_pay_for_date_3: null statutory_holiday_pay_for_amount_3: null statutory_holiday_pay_for_date_4: null statutory_holiday_pay_for_amount_4: null statutory_holiday_pay_for_date_5: null statutory_holiday_pay_for_amount_5: null statutory_holiday_pay_for_date_6: null statutory_holiday_pay_for_amount_6: null statutory_holiday_pay_for_date_7: null statutory_holiday_pay_for_amount_7: null statutory_holiday_pay_for_date_8: null statutory_holiday_pay_for_amount_8: null statutory_holiday_pay_for_date_9: null statutory_holiday_pay_for_amount_9: null statutory_holiday_pay_for_date_10: null statutory_holiday_pay_for_amount_10: null other_monies_code_1: null other_monies_start_date_1: null other_monies_end_date_1: null other_monies_amount_1: null other_monies_code_2: null other_monies_start_date_2: null other_monies_end_date_2: null other_monies_amount_2: null other_monies_code_3: null other_monies_start_date_3: null other_monies_end_date_3: null other_monies_amount_3: null special_payments_code_1: null special_payments_start_date_1: null special_payments_end_date_1: null special_payments_amount_1: null special_payments_period_1: null special_payments_code_2: null special_payments_start_date_2: null special_payments_end_date_2: null special_payments_amount_2: null special_payments_period_2: null special_payments_code_3: null special_payments_start_date_3: null special_payments_end_date_3: null special_payments_amount_3: null special_payments_period_3: null special_payments_code_4: null special_payments_start_date_4: null special_payments_end_date_4: null special_payments_amount_4: null special_payments_period_4: null created_at: '2026-01-01T00:00:00.000000Z' updated_at: '2026-01-01T00:00:00.000000Z' links: self: /forms/ - id: object: form data: owner: id: object: work_assignment links: self: /work_assignments/ form_batch: null stage: original note: null type: td1 effective_date: '2026-01-01' version_year: '2026' version_month: january validation_error_count: 0 is_editable: true line_1_basic_personal_amount: null line_2_infirm_children_caregiver_amount: null line_3_age_amount: null line_4_pension_income_amount: null line_5_tuition: null line_6_disability_amount: null line_7_spouse_or_common_law_partner_amount: null line_8_eligible_dependent_amount: null line_9_infirm_dependent_caregiver_amount: null line_10_dependent_caregiver_amount: null line_11_spouse_or_common_law_transfer_amount: null line_12_dependent_transfer_amount: null line_13_total_claim_amount: null more_than_one_employer_or_payer: null total_income_less_than_total_claim_amount: null ninety_percent_world_income_taxable_income: null prescribed_zone_deduction: null additional_tax_deduction: null created_at: '2026-01-01T00:00:00.000000Z' updated_at: '2026-01-01T00:00:00.000000Z' links: self: /forms/ links: first: /forms?page=1 last: /forms?page=1 prev: null next: null meta: current_page: 1 last_page: 1 per_page: 15 total: 2 has_more: false components: schemas: Form: type: object title: Form properties: owner: type: object description: >- The owner of this form. Can be a Work Assignment, Employee, or Contractor. 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 (`"work_assignment"`). readOnly: true form_batch: description: The Form Batch this form belongs to, if any. stage: type: string description: >- The lifecycle stage of this form: original, amendment, or cancellation. enum: - amendment - cancellation - original note: type: string description: An optional note for this form. nullable: true type: type: string description: The type of form (e.g. T4, ROE, 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 effective_date: type: string description: >- The effective date used to determine the form variant (e.g. the T4 tax year). format: date version_year: type: string description: >- The form variant's version year. New versions are typically released in January. Note: the version year may differ from the tax year. For example, income earned in the 2025 tax year is typically reported on a 2026 version of the T4. nullable: true version_month: type: string description: >- The month component of the form variant, for forms with monthly variants. `null` for annual forms. nullable: true validation_error_count: type: number description: >- The number of validation errors currently present in the form's fields. nullable: true format: decimal is_editable: type: boolean description: |- Whether the form can be edited. Whether the form can currently be modified. line_1_basic_personal_amount: {} line_2_infirm_children_caregiver_amount: {} line_3_age_amount: {} line_4_pension_income_amount: {} line_5_tuition: {} line_6_disability_amount: {} line_7_spouse_or_common_law_partner_amount: {} line_8_eligible_dependent_amount: {} line_9_infirm_dependent_caregiver_amount: {} line_10_dependent_caregiver_amount: {} line_11_spouse_or_common_law_transfer_amount: {} line_12_dependent_transfer_amount: {} line_13_total_claim_amount: {} more_than_one_employer_or_payer: {} total_income_less_than_total_claim_amount: {} ninety_percent_world_income_taxable_income: {} prescribed_zone_deduction: {} additional_tax_deduction: {} 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 FormOwner: type: object oneOf: - $ref: '#/components/schemas/Employee' - $ref: '#/components/schemas/Contractor' - $ref: '#/components/schemas/WorkAssignment' 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 Employee: type: object title: Employee properties: 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 employee_number: type: string description: >- An optional identifier for the employee within the partner's system, such as a badge number or HR system ID. Distinct from `id` and `external_ref`. nullable: true maxLength: 40 first_name: type: string description: The employee's first name. maxLength: 50 last_name: type: string description: The employee's last name. maxLength: 50 middle_initial: type: string description: The employee's middle initial. nullable: true maxLength: 1 personal_email: type: string description: >- The employee's personal email address, used as the primary address for payroll communications such as Pay Stub emails. nullable: true maxLength: 255 work_email: type: string description: >- The employee's work email address. Used for payroll communications if `personal_email` is not set. nullable: true maxLength: 255 address_line_1: type: string description: >- The first line of the employee'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 employee'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 employee's mailing address. nullable: true maxLength: 255 administrative_area: type: string description: >- The region of the employee's mailing address — the province, state, or county, depending on the country. For Canadian employees this is the Province of Residence (POR), not the Province of Employment (POE) or Province of Work (POW). POE and POW are configured via the Work Assignment's Tax Properties. 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 employee's mailing address. nullable: true maxLength: 2 enum: - CA - GB postal_code: type: string description: The postal code for the employee's mailing address. nullable: true maxLength: 10 sin: type: string description: >- This attribute is deprecated and will be removed. The employee's Social Insurance Number (SIN), used for tax reporting. If you only need the last 3 digits for display purposes, use `sin_last_3` instead. If you need the complete SIN, use the `/employees/:id/reveal` endpoint instead. Note the `/reveal` endpoint can only reveal one employee at a time and is rate-limited for security reasons. nullable: true deprecated: true sin_last_3: type: string description: >- The last 3 digits of the employee's Social Insurance Number (SIN). `null` if no SIN has been provided. nullable: true date_of_birth: type: string description: The employee's date of birth. nullable: true format: date warnings: type: object description: >- A collection of data validation warnings for this employee. 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 preferred_locale: type: string description: >- The locale used for payroll communications sent to this employee, such as Pay Stub emails. If not set, the Business Entity's locale is used. nullable: true enum: - en - fr archived_at: type: string description: >- The date the employee was archived. Archiving an employee also archives all Work Assignments that are not already archived. Archived employees do not appear in active listings. readOnly: true nullable: true format: dateTime 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 Contractor: type: object title: Contractor properties: business_name: type: string description: >- The contractor's business or corporation name. `null` for individual contractors. nullable: true maxLength: 255 first_name: type: string description: The contractor's first name. `null` for corporation contractors. nullable: true maxLength: 50 last_name: type: string description: The contractor's last name. `null` for corporation contractors. nullable: true maxLength: 50 middle_initial: type: string description: The contractor's middle initial. `null` for corporation contractors. nullable: true maxLength: 1 email: type: string description: The contractor's email address, used for payroll communications. nullable: true maxLength: 255 business_number: type: string description: >- The contractor's 15-character (BN15) Canada Revenue Agency (CRA) program account number, consisting of a 9-digit Business Number (BN), a 2-letter program identifier, and a 4-digit reference number. `null` for individual contractors. nullable: true maxLength: 15 sin_last_3: description: >- The last 3 digits of the contractor's Social Insurance Number (SIN). `null` if no SIN has been provided. 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 preferred_locale: type: string description: >- The locale used for payroll communications sent to this contractor, such as Pay Stub emails. If not set, the Business Entity's locale is used. nullable: true enum: - en - fr archived_at: type: string description: >- The date the contractor was archived. Archiving a contractor also archives all Work Assignments that are not already archived. Archived contractors do not appear in active listings. readOnly: true nullable: true format: dateTime 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 WorkAssignment: type: object title: Work Assignment properties: title: type: string description: >- An optional label for this work assignment, used to distinguish between multiple work assignments for the same Employee or Contractor. nullable: true maxLength: 255 title_translations: type: object description: Optional translations for the `title` property. allOf: - $ref: '#/components/schemas/Translations' nullable: true title_translated: type: string description: >- The translation of the `title` property for the request locale. Computed using the values in `title` and `title_translations` and the value of the request's `Accept-Language` header. readOnly: true employee: 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 (`"employee"`). 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 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 current_tax_jurisdiction: type: string description: >- The current Province of Employment (POE) for the work assignment, derived from the `ca::province_of_employment` Tax Property on the work assignment or, if none is set, from the Business Entity. nullable: true is_primary: type: boolean description: >- When `true`, the standard tax reductions are applied to this work assignment's Pay Stubs. Only one work assignment per Employee per Business Entity may be primary. If none is explicitly set to primary, the earliest work assignment is treated as primary. accrued_vacation_pay: type: number description: This attribute is deprecated and will be removed. deprecated: true format: decimal paid_vacation_pay: type: number description: This attribute is deprecated and will be removed. deprecated: true format: decimal first_non_draft_period_start: type: string description: >- The start of the first pay period for which this work assignment has a non-draft Payroll. `null` if the work assignment has never appeared on an approved or paid Payroll. nullable: true format: date last_non_draft_period_end: type: string description: >- The end of the most recent pay period for which this work assignment has a non-draft Payroll. `null` if the work assignment has never appeared on an approved or paid Payroll. nullable: true format: date available_tax_properties: type: array description: >- A list of Tax Property template identifiers supported for this work assignment, based on its jurisdiction. nullable: true items: type: string 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 archived_at: type: string description: >- The date the work assignment was archived. Archiving ends the work assignment's participation in future Payrolls. The archive date must not fall before any active Pay Rate's effective period. readOnly: true nullable: true format: dateTime 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 Translations: type: object nullable: true properties: en: type: string maxLength: 255 fr: type: string maxLength: 255 securitySchemes: CompanyToken: type: http scheme: bearer ````