Skip to main content
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.

​
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: Request
Response (truncated)

​
Generating ROEs

Generate ROEs with the 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
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 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

​
Tracking generation

Follow the work in one of two ways: poll the Retrieve an async task endpoint, or listen for the async_task_completed webhook, which fires when the task finishes, whether it succeeded or failed. The task starts as processing and moves to completed once every ROE is created. A failed run moves to error instead and removes any ROEs it had already created, leaving completed_at as null. Fetch the task on every webhook and check status before you act on the results. Request
Response
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 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 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 endpoint, under the fields key. Request
Response

​
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.
Build your integration against sandbox. When you’re ready to go live, including collecting your clients’ Letters of Agreement, let us know so we can enable ROE SAT on your production account.

​
Letters of Agreement

Service Canada requires the employer’s written permission before Nmbr can file their ROEs. That permission is a Letter of Agreement (LOA): a letter the employer signs naming Nmbr as the service provider that issues their ROEs. An LOA covers one CRA payroll account number (BN15). ROEs whose Block 5 matches a covered account are filed with Service Canada when you submit them.
Without an 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.
Putting an LOA in place takes two steps: the employer signs the letter, then you record the agreement.

​
Getting the letter

Generate the letter for the employer to sign with the Generate a blank ROE SAT agreement letter endpoint. The response is a PDF, and nothing is saved. Request
The letter is filled in from the business entity. Override any of it:
  • business_number (optional): the BN15 to print on the letter. Defaults to the business entity’s business number.
  • business_legal_name (optional): the employer’s legal name to print on the letter. Defaults to the business entity’s legal name.
  • locale (optional): en or fr. Defaults to the business entity’s language.

​
Recording the agreement

Once the employer has agreed, record it with the Create an ROE SAT agreement endpoint. Send the details from the signed letter. Request
Response
business_entity_id, business_number, signer_name, signer_title, and signed_on are required. business_legal_name and locale default to the business entity’s values. Every agreement keeps a copy of the letter, so it can be produced for Service Canada on request. To store the employer’s own signed copy, send the request as multipart/form-data with a letter file (PDF, up to 10 MB). When you don’t send one, Nmbr generates a copy recording the acceptance and attaches that instead. letter_was_uploaded tells you which one an agreement holds. Retrieve either copy with the Download an ROE SAT agreement letter endpoint. The copy is attached moments after the agreement is created, so a download immediately afterwards can return a letter_not_ready error. Retry it. A business number can have only one agreement in effect at a time. Recording a second one for a number already covered returns an already_covered error.

​
Checking coverage

List the agreements on file with the List ROE SAT agreements endpoint, filtered by business_entity_id or business_number. Read a single one with Retrieve an ROE SAT agreement. Request
An agreement is in effect while revoked_at is null.

​
Revoking an agreement

An employer can withdraw their permission at any time. Revoke the agreement as soon as they do with the Revoke an ROE SAT agreement endpoint: Nmbr must not file for an employer who has withdrawn. Request
Revoking stops future filing. ROEs already sent to Service Canada are unaffected. Revoking an agreement that is already revoked returns an already_revoked error. To restore filing for a business number, record a new agreement covering it.

​
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.
Follow the lifecycle by polling the form, or listen for the form_completed webhook, which fires when an ROE reaches done. 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 endpoint. Request
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. 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)

The employee copy is available for ROEs Nmbr filed through ROE SAT. Once one reaches done, retrieve the copy with the Retrieve a form endpoint and an Accept: application/pdf header. The PDF renders in the employee’s preferred language.