> ## 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. # Retrieve a form > Endpoint to fetch a Form. The following example is for a 2026 TD1, but the response fields will differ depending on the specific Form instance requested. ## OpenAPI ````yaml /spec/openapi.json get /forms/{form} 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/{form}: get: tags: - Forms summary: Retrieve a form description: >- Endpoint to fetch a Form. The following example is for a 2026 TD1, but the response fields will differ depending on the specific Form instance requested. operationId: forms-show parameters: - name: form in: path schema: type: string required: true - 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: 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: 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/ 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 ````