> ## 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. # Record of Employment (ROE) > Generate, validate, and submit ROEs to Service Canada The Nmbr API generates ROEs, validates them, and submits them to Service Canada. A Record of Employment (ROE) is the form an employer issues when an employee quits, is laid off, or takes an unpaid leave. If pay stops, for any reason, an ROE is due. Service Canada uses it to work out the employee's Employment Insurance (EI) benefits: whether they qualify, how much, and for how long. > For the full rules, including what each block means, see [Service Canada's ROE guide for employers](https://www.canada.ca/en/employment-social-development/programs/ei/ei-list/reports/roe-guide.html). ## ROEs are forms An ROE is a form. Read the [Forms guide](/guides/payroll-fundamentals/forms) 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](/api-reference/form-types/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: **Request** ```json theme={null} # GET /services/payroll/form_types/roe ``` **Response (truncated)** ```json theme={null} { "id": "roe", "object": "form_type", "data": { "type": "roe", "label": "Record of Employment", "version_year": 2026, "version_month": "august", "groups": { "employment_dates": "Employment Dates & Final Pay Period", "reason_recall_contact": "Reason, Recall & Contact" }, "fields": [ { "key": "block_16_separation_code", "label": "Separation Code (Block 16)", "type": "select", "required": true, "readonly": false, "group": "reason_recall_contact", "options": { "A00": "(A00) Shortage Of Work Or End Of Contract", "E00": "(E00) Quit", "M00": "(M00) Dismissal" } } ] } } ``` ## Generating ROEs Generate ROEs with the [Generate forms](/api-reference/form-types/generate-forms) endpoint. Send a `roes` 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** ```json theme={null} # POST /services/payroll/form_types/roe/generate { "roes": [ { "employee_id": "emp_01H7M9X2QV4N", "work_assignment_ids": ["wrkas_01HX3F7T8B2D"], "first_day_worked": "2026-01-06", "last_day_for_which_paid": "2026-07-31", "separation_code": "A00", "expected_recall_code": "N" } ] } ``` Each ROE accepts: * `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. Format `YYYY-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 after `first_day_worked`. Format `YYYY-MM-DD`. * `separation_code` (optional): Block 16, the reason for issuing the ROE. For example, `A00` for shortage of work or end of contract, `E00` for a quit. See [Service Canada's ROE guide](https://www.canada.ca/en/employment-social-development/programs/ei/ei-list/reports/roe-guide.html) for the full list. * `expected_recall_code` (optional): Block 14. One of `Y` (returning), `N` (not returning), or `U` (unknown). * `expected_recall_date` (optional): Block 14. Format `YYYY-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** ```json theme={null} { "id": "task_01HZ9R4M6K0P", "object": "async_task", "data": { "type": "form_generation", "status": "processing", "completed_at": null, "results": [] } } ``` ### Tracking generation Follow the work in one of two ways: poll the [Retrieve an async task](/api-reference/async-tasks/retrieve-an-async-task) endpoint, or listen for the `async_task_completed` [webhook](/api/overview/webhook-structure), which fires when the task finishes. The task starts as `processing` and moves to `completed` once every ROE is created. **Request** ```json theme={null} # GET /services/payroll/async_tasks/task_01HZ9R4M6K0P ``` **Response** ```json theme={null} { "id": "task_01HZ9R4M6K0P", "object": "async_task", "data": { "type": "form_generation", "status": "completed", "completed_at": "2026-08-07T18:42:11Z", "results": [ { "id": "form_01HZ9RBC72W8", "object": "form", "status": "draft" } ] } } ``` Each entry in `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](/api-reference/forms/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 has `pp{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](/api-reference/form-types/validate-a-form) endpoint before submission. Send the form's `effective_date` and the fields you want to check. The full list of fields you can validate comes from the [Retrieve a form type](/api-reference/form-types/retrieve-a-form-type) endpoint, under the `fields` key. **Request** ```json theme={null} # POST /services/payroll/form_types/roe/validate { "effective_date": "2026-08-07", "block_10_first_day_worked": "2026-01-06", "block_11_last_day_for_which_paid": "2026-07-31", "block_16_separation_code": "A00", "pp1_insurable_earnings": 0.0, "pp2_insurable_earnings": 1840.0, "pp3_insurable_earnings": 1840.0 } ``` **Response** ```json theme={null} { "data": { "errors": { "pp1_insurable_earnings": ["pp1_insurable_earnings cannot be 0"] } } } ``` ## Submission Submit an ROE with the [Submit a form](/api-reference/forms/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](/api-reference/forms/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](#the-employee-copy-pdf) becomes available. Poll the form to follow it through the lifecycle. A managed ROE cannot be exported as XML, because Nmbr handles the filing. ### 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 a `done` ROE with the [Amend a form](/api-reference/forms/amend-a-form) endpoint. **Request** ```json theme={null} # POST /services/payroll/forms/form_01HZ9RBC72W8/amend ``` The response is a new draft ROE that starts as a copy of the original, ready to edit. Block 2 carries the serial number of the ROE it replaces, and the amendment takes a fresh Block 1 serial when you submit it. It then moves through the same lifecycle as any managed ROE. The original stays `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 reaches `done`, retrieve the employee's copy with the [Retrieve a form](/api-reference/forms/retrieve-a-form) endpoint and an `Accept: application/pdf` header. The PDF renders in the employee's preferred language.