For the full rules, including what each block means, see Service Canada’s ROE guide for employers.
ROEs are forms
An ROE is a form. Read the Forms guide for how form types describe their fields, and how to create, read, update, and validate a form. This page covers what’s specific to ROEs. Retrieve the definition with the Retrieve a form type endpoint and build your editing UI from it. The fields carry the ROE-specific details, such as the separation codes on Block 16: RequestGenerating ROEs
Generate ROEs with the Generate forms endpoint. Send aroes array, where each entry describes one ROE: the employee, the work assignments it covers, and its date window. One request can generate many ROEs.
Request
employee_id(required): the employee the ROE is for.work_assignment_ids(required): the work assignments the ROE covers. They must belong to the same employee and the same business entity.first_day_worked(required): Block 10. The first day the employee worked and earned insurable pay. If they had an earlier ROE, this is the first day worked since that ROE, not their hire date. FormatYYYY-MM-DD.last_day_for_which_paid(required): Block 11. The last day the employee was paid insurable earnings for. Usually their last day of work, but paid vacation or sick days at the end of employment push it later. Must be on or afterfirst_day_worked. FormatYYYY-MM-DD.separation_code(optional): Block 16, the reason for issuing the ROE. For example,A00for shortage of work or end of contract,E00for a quit. See Service Canada’s ROE guide for the full list.expected_recall_code(optional): Block 14. One ofY(returning),N(not returning), orU(unknown).expected_recall_date(optional): Block 14. FormatYYYY-MM-DD.
first_day_worked and last_day_for_which_paid bound the ROE. The pay periods, insurable earnings and hours, and the final pay period ending date are all derived from the payrolls between them.
effective_date (optional, format YYYY-MM-DD) applies to every ROE in the request and sets which ROE version the forms use. It defaults to today.
Generation runs in the background, so the endpoint returns an async task instead of the forms themselves.
Response
Tracking generation
Follow the work in one of two ways: poll the Retrieve an async task endpoint, or listen for theasync_task_completed webhook, which fires when the task finishes. The task starts as processing and moves to completed once every ROE is created.
Request
results is a generated ROE. The forms are created as drafts with their fields already populated from the employee’s payroll data. Retrieve a form with the Retrieve a form endpoint to read or edit it before validation.
If a single ROE fails to generate, its entry carries an error key while the others succeed. The task still completes.
Insurable earnings by pay period
An ROE breaks insurable earnings down by pay period: each period haspp{n}_insurable_earnings, pp{n}_insurable_hours, and pp{n}_period_end_date fields, which the generator fills from payroll data. Periods run newest to oldest: pp1 is the final pay period, and its ending date is Block 12. The Block 15A and 15B totals are derived from the per-period values, so you don’t set them.
Validation
Validate an ROE’s fields with the Validate a form endpoint before submission. Send the form’seffective_date and the fields you want to check. The full list of fields you can validate comes from the Retrieve a form type endpoint, under the fields key.
Request
Submission
Submit an ROE with the Submit a form endpoint. The ROE must be valid to submit: a form with outstanding errors is refused. Nmbr files submitted ROEs with Service Canada through ROE SAT (Secure Automated Transfer), Service Canada’s electronic filing channel for payroll service providers.Letters of Agreement
Filing on an employer’s behalf requires their permission: a Letter of Agreement (LOA) signed by the employer, authorizing Nmbr to issue their ROEs. Once the employer’s LOA is on file, their ROEs are managed: submission hands them to Nmbr to file.Without a signed LOA, submission marks the ROE
done but nothing is sent to Service Canada. The XML export (the Retrieve a form endpoint with an Accept: application/xml header) produces the file to upload in ROE Web.The lifecycle
A managed ROE moves through these statuses:draft: editable and validatable.processing: queued for transmission to Service Canada. No longer editable.submitted: transmitted to Service Canada, response pending.done: accepted and filed. The employee copy becomes available.
Serial numbers
You never set serial numbers. Block 1 (the ROE’s own serial) and Block 2 (the serial of the ROE it amends) are read-only, and values sent for them are ignored. Nmbr assigns Block 1 when a managed ROE is submitted, and fills Block 2 when you amend.Amending a filed ROE
A filed ROE can’t be edited or cancelled, only amended. Service Canada expects an amendment when the original needs to be changed, corrected, or updated (for example, extra separation money is paid after filing), when the original was issued in error, or when Service Canada requests one. Amend adone ROE with the Amend a form endpoint.
Request
done and points to the amendment through its superseding_form field; the amendment points back through source_form.
An amendment is a complete replacement, not a diff. Service Canada swaps out the original wholesale, so every field is filed again, not just the ones that changed.
Only ROEs Nmbr filed for you can be amended this way. An ROE filed manually must be corrected in ROE Web, and trying to amend one returns a not_amendable error.
The employee copy (PDF)
Once a managed ROE reachesdone, retrieve the employee’s copy with the Retrieve a form endpoint and an Accept: application/pdf header. The PDF renders in the employee’s preferred language.