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.
The ROE fields in the API follow Service Canada’s ROE SAT format. For what each block means, see Service Canada’s ROE guide for employers. That guide describes the paper and ROE Web form, so a few blocks look different in the API. See Differences from the ROE guide.

​
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. The options on the form type’s block_16_separation_code field list every code with its label.
  • 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.

​
Differences from the ROE guide

The API uses the ROE SAT format. Where it differs from Service Canada’s ROE guide for employers:
  • Block 15C: each pay period has insurable earnings, insurable hours, and an end date. The ROE guide shows earnings only.
  • Blocks 15A and 15B: Nmbr calculates the totals from the pay periods. You don’t enter them.
  • Block 1: Nmbr assigns the serial number when it files the ROE. You don’t enter it.
  • Codes in Blocks 16, 17C, and 19: the ROE guide gives each reason as a letter or a description. The API uses the full codes, which you can read from each field’s options. Service Canada lists them in Appendix D. A Block 16 code’s first letter matches the letter in the ROE guide, so E02 is a kind of quit (E).
For the full SAT rules, see Service Canada’s ROE SAT 4.0 user guide.

​
Historical payrolls on an ROE

A historical payroll is left off an ROE unless you set first_day_worked back to cover its period, and that period matches one of the employee’s pay periods exactly. A historical payroll covering more than one pay period never matches. Note: an ROE reports the insurable hours on the pay stubs. A historical payroll needs hours on its pay stubs for Service Canada to receive 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
Errors mirror the checks Service Canada applies when it receives an ROE, so a form with no errors is one Service Canada accepts. Advisories cover the checks Service Canada flags but does not reject, such as an unusual run of pay periods with no insurable earnings. Show them to the user, but they do not stop submission.

​
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. Filing starts as soon as a Letter of Agreement covers the employer’s payroll account number.

​
Submission settings

What submission does depends on the ROE’s submission_setting, which you can read in the form’s metadata.
  • automatic: a Letter of Agreement covers the ROE’s payroll account number. Submission files the ROE with Service Canada, and it moves through the lifecycle below. The employee copy is available once it is done.
  • manual: no agreement covers the account. Submission marks the ROE done and nothing is sent to Service Canada. Export the XML with the Retrieve a form endpoint and an Accept: application/xml header. The employer uploads that file in ROE Web.
Recording an agreement changes the drafts it covers to automatic. An ROE that is already done keeps the setting it was filed with.

​
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. 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. Nothing is recorded until you create the agreement. 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

An automatic 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. An automatic ROE cannot be exported as XML. See Downloading an ROE.

​
Serial numbers

Block 1 (the ROE’s serial number) 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 an automatic ROE is submitted, and fills Block 2 when you amend one. A manual ROE gets its serial from ROE Web, so Block 1 stays empty in the API.

​
Follow-up from Service Canada

Service Canada may contact the employer about a filed ROE, but only after the employee files a claim for Employment Insurance (EI) benefits. Even then, Service Canada calls only when it needs more information to decide the claim. It aims to decide a claim within 28 days of the employee filing it, so a call usually comes in that time, but it can come later. Service Canada calls the contact person in Block 16 (the contact_* fields). If the call shows a mistake on the ROE, Service Canada may ask the employer to amend it.

​
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 automatic ROE. The original stays done and points to the amendment through its superseding_form field; the amendment points back through source_form. Only automatic ROEs can be amended this way. The employer corrects a manual ROE in ROE Web. Amending one through the API returns a not_amendable error.

​
The employee copy (PDF)

The employee copy is available for automatic ROEs. 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.

​
Downloading an ROE

Which file you can download depends on the ROE’s submission_setting: Check is_xml_exportable and is_pdf_exportable in the form’s metadata before you request a file. A request for a file that is not available returns 406 Not Acceptable. An automatic ROE has no XML because Nmbr files it for the employer. If the employer also uploaded the XML to ROE Web, Service Canada would receive the same ROE twice and flag it, which delays the employee’s claim. A manual ROE has no PDF because Service Canada only authorizes an employee copy for ROEs filed through ROE SAT. For a manual ROE, the employee gets their copy from their My Service Canada Account, and the employer sees the ROEs they filed in ROE Web.