Skip to main content
Nmbr supports generating, validating, and submitting Canadian year-end tax forms:
  • T4 / T4A → Canada Revenue Agency (CRA)
  • RL-1 → Revenu Québec
For official guidance on form requirements and box definitions, refer to:

​
Form Lifecycle

  1. draft – Generated but not yet approved
  2. approved – Validated and locked for submission
  3. processing – Submitted to Nmbr for processing
  4. submitted – Receipt confirmed by the tax authority
  5. done – Processing completed by the tax authority

​
Generating Year-End Tax Forms

Year-end tax forms can be generated by payroll administrators in: Generated forms are populated using payroll data for the selected tax year and grouped into a form batch.

​
Generating Forms via API

Using the Generate Forms endpoint, specify the form_type and tax_year. You can optionally provide:
  • form_batch_id to group generated forms into an existing batch.
  • employee_ids to generate forms for specific employees only (T4/RL-1).
  • contractor_ids to generate forms for specific contractors only (T4A).
  • province_of_employment to restrict forms to a single province (T4).
The response will include an async task which can be tracked using the Async Task endpoint. Once the task is complete, the generated forms can be retrieved using the List Forms endpoint. Forms will only be generated for employees/contractors with paid pay stubs in the given tax year.

​
Setting Box 45 on T4s

Box 45 (employer-offered dental benefits) is not set when T4s are generated. A T4 has a validation error until Box 45 has a value from 1 to 5. Set box_45_employer_offered_dental_benefits on each T4 in draft status: POST /forms/batch/upsert
An employee who worked in more than one province gets one T4 for each province. Set Box 45 on each of them.

​
Retrieving Year-End Tax Forms

Use the List Forms endpoint with the type query parameter set to t4, t4a, or rl1.

​
Validation

Validate form fields using the Form Type Validation endpoint. The list of form fields can be retrieved from the Form Type endpoint. Forms must have no validation errors before they can be approved.

​
Approving a Form

Forms in draft status can be approved once valid using the Approve Form endpoint. Approval locks the form for submission.

​
Submitting a Form Batch

Year-end forms must be submitted as part of a form batch. Use the Submit Form Batch endpoint. A batch can only be submitted when all forms in the batch are valid and approved. On submission:
  • All forms move to processing
  • T4/T4A forms are submitted to the CRA
  • RL-1 forms are submitted to Revenu Québec
When the submission is successfully received by the tax authority, forms will move to submitted status. When the tax authority completes processing, forms will move to done status. The time to complete processing can vary based on the tax authority’s workload and processing times. If any forms are rejected by the tax authority, the Nmbr team will reach out with details on the errors and next steps to resolve.

​
Confirmation Number

When a form batch moves to submitted, metadata.identifiers.confirmation_number on the form batch holds the tax authority’s confirmation number. The number confirms that the tax authority received the filing, so the batch is submitted. The batch moves to done when the tax authority finishes processing. Several form batches can have the same confirmation number, because one filing can include more than one batch. metadata.timestamps.submitted_at and metadata.timestamps.completed_at record when the batch moved to submitted and done.

​
Webhooks

Year-end forms and form batches send these webhooks:

​
Downloading PDFs

​
Individual Form PDF

PDF versions of individual forms can be retrieved using the Retrieve Form endpoint with the Accept: application/pdf header. PDFs are only available for forms with no validation errors. PDFs for valid forms that are not yet done will be watermarked with “DRAFT” to indicate they are not yet complete.

​
Batch PDF

A zip file containing all forms in a batch can be downloaded once all forms are marked done using the Download Form Batch endpoint.

​
Email

There are two emails associated with year-end tax forms:
  1. Form Batch Completion Email – Sent to the form batch contact when the batch is marked done.
  2. Form Recipient Email – Sent to employees/contractors. Can be triggered in the Nmbr Component by the payroll administrator, or in the Partner Portal.
See Configuring Email for more details.

​
Amending Forms

Once a form batch is submitted, forms cannot be edited. If changes are needed, an official amendment must be made with the tax authority. Amendments can only be performed on forms in done status. Amendments can be performed: Amending a form will create a new amendment form linked to the original form (as source_form_id). The amendment form will have its own lifecycle and must be approved and submitted to the tax authority.

​
Testing in Sandbox

Sandbox completes submitted form batches by itself. Nothing reaches the CRA or Revenu Québec, so test data is safe to use. After a form batch is submitted:
  1. About a minute later, the batch moves to submitted with a fake confirmation number. Each RL-1 also gets a fake slip number.
  2. About a minute after that, the batch moves to done. Nmbr sends the same webhooks as in production, and the PDFs are ready to download.
When the forms are done, the payroll administrator can amend them. A batch of amendments completes the same way.

​
Deadlines

The deadline for submitting year-end tax forms to the CRA and Revenu Québec is typically the last day of February following the tax year. For example, for the 2025 tax year, forms must be submitted by March 2, 2026 (since February 28 falls on a Saturday, the deadline moves to the next business day). Late or missed filings may result in penalties from the CRA or Revenu Québec. It is the responsibility of the payroll administrator to ensure forms are generated, approved, and submitted by the deadline. Nmbr recommends starting the process early to allow time for resolving any validation errors or issues with the tax authority.