Skip to main content
A TD1, formally the Canada Revenue Agency (CRA) Personal Tax Credits Return, is the form an employer collects from an employee to figure out how much income tax to withhold from each pay. The amounts an employee claims on it lower the tax deducted from their pay, so the employer sends the right amount to the CRA. TD1s are not filed with the CRA, and the employee doesn’t use them for their own return. They exist so the employer can calculate withholding and record the employee’s TD1 code. Employees complete a federal TD1 and the TD1 for their province. Both are collected when the employee starts a job and at the beginning of each calendar year, and again whenever they:
  • Want to increase the tax deducted from their pay.
  • Want to claim additional deductions.
  • Have a significant life change, such as going back to school or taking on a dependent.
If an employee doesn’t submit their TD1s, the employer withholds tax using the CRA’s default (basic personal) amount for the year. An employee with two jobs may claim their tax credits on only one job’s TD1.

​
TD1 forms in the Nmbr API

TD1s are forms. Read the Forms guide for how to list form types, read their fields, create a form, and update it. This page covers what’s specific to TD1s. Nmbr provides every federal and provincial TD1 as its own form type:
  • td1: the federal TD1.
  • td1on, td1ab, td1bc, and so on: one form type per province and territory.
  • td1x: Statement of Commission Income and Expenses, for commission employees.
  • tp_1015_3_v: the Québec Source Deductions Return, Québec’s equivalent of the TD1.
A few things set TD1s apart from other forms:
  • Their owner is a work assignment. A TD1 attaches to one work assignment, not to the employee as a whole, so an employee with two jobs can claim different amounts on each. Use a wrkas_ ID as the owner_id when you create one.
  • They’re records, not filings. TD1s aren’t submitted to a government agency, generated from payroll data, or exported. You create one, set the claim amounts, and Nmbr uses them in withholding calculations.
Retrieve a TD1’s fields from the Retrieve a form type endpoint before you build against it. The claim amounts are currency fields keyed by line, such as line_1_basic_personal_amount.

​
Creating a TD1

Create a TD1 with the Create a form endpoint. Send the type, the work assignment as owner_id, and any claim amounts. Request
The response is the full form, with any unset lines returned as null. Update it later with the Update a form endpoint, sending only the lines you want to change.