Request fields

Who this is for: Integrators building JSON bodies for POST /v1/deductions, batch pay runs, or year projection.

When you finish: You know which T4127 (Payroll Deductions Formulas) inputs are required, their defaults, and when to send each optional field.

A claim code is the TD1 box value that maps to federal and provincial personal amounts. Proration applies when Option 1 splits mid-year provincial rates (see effective-dates.md).

Money is always a quoted decimal string in dollars and cents (for example "1000.00"; "1000" and "1000.5" are read the same way as "1000.00" and "1000.50"). JSON numbers are rejected (HTTP 400 invalid_request naming the field). An amount with more than 2 decimal places (for example "1000.505") is refused with HTTP 400 invalid_request naming the field. Every money field is zero or more: a negative amount (for example "-50.00") is refused with HTTP 400 invalid_request whose message names the field, on POST /v1/deductions, on each item of a batch and on the year projection (-0.00 reads as zero). An amount may have at most 15 digits before the decimal point; a larger one is refused with HTTP 400 invalid_request naming the field. A year projection (POST /v1/deductions/year) also keeps running totals, so there gross_pay, pensionable_earnings, insurable_earnings, taxable_benefits and additional_tax_requested times the number of pay periods must stay within 15 digits too (HTTP 400 otherwise). The year projection takes only some of the fields below; see year-projection.md.

Six fields most callers need

Claim codes and claim amounts

Send both claim codes, or the total claim amounts from the TD1 forms as federal_tc / provincial_tcp instead. A code and an amount for the same side in one request are refused (HTTP 400 invalid_request, ambiguous claim), so exactly one row below sets TC (federal) and TCP (provincial):

Codes 2 to 10 use the printed amount at every income; the income phase-out applies to code 1 and to no code. The CRA prints the July 2026 Newfoundland and Labrador table for Option 1 only (its basic amount, $15,000.00, is prorated; Option 2 uses $13,094.00), so from 2026-07-01 an NL provincial_claim_code from 2 to 10 with calculation_option option2 is refused with HTTP 400 invalid_request naming the field: send provincial_tcp instead. The response's breakdown.TC and breakdown.TCP show the amounts used. The tables are the CRA's CSV files archived in data/sources/ with their SHA-256 and pinned in the engine by SHA-512; the 2027 preview reuses the July 2026 tables.

Identity and dates

Income

Claims and personal amounts

Deductions from pay

Year-to-date (YTD)

Bonus and lump sums

Option 2 and commission

Unknown property names yield unknown_field (HTTP 400). The API strips no extra keys silently, on any route. In a batch, every field goes on each item: the envelope takes only requests, and a field next to it (for example federal_claim_code or as_of) is refused. A documented field the engine does not read (prior_province, date_of_birth, cpp_election_after_65, commission_income, commission_expenses, ytd_qpp, ytd_qpp2 and ytd_qpip) is refused by name whenever it is sent with a value; null is read as not sent. A value of the wrong type or outside the values its field takes (for example pay_period 3, a claim code 11, cpp_months 256), and a required field left out, are HTTP 400 invalid_request naming the field.

See api-reference.md for routes and errors.md for rejection behavior.

Last reviewed: 2026-10-24
Engine: 0.1.0