Skip to main content
The Nmbr API supports generating ROEs and submitting them to Service Canada.
To learn more about ROEs including when you should issue an ROE and the meaning of each field, please visit Service Canada - Record of Employment.

​
Generating an ROE

An ROE is a tax form. It can be generated using the form store endpoint. You must provide the owner_id (the employee’s Id) and the type of roe in the body of the request. 
# POST /services/payroll/forms/
{
  "owner_id": "emp_123",
  "type": "roe"
}
This will generate an ROE for the employee, but without any fields completed.

​
Populating an ROE

ROEs are populated based on an employee’s record of earnings over a given period of time. The Nmbr API provides population data.

​
Generating Population Data

Retrieve population data using the form type populate endpoint. You must provide the employee_id, work_assignment_ids, first_day_worked, and last_day_for_which_paid. 
# POST /services/payroll/form_types/roe/populate
{
  "employee_id": "emp_123",
  "work_assignment_ids": ["wrk_123"],
  "first_day_worked": "2025-01-15",
  "last_day_for_which_paid": "2025-04-01"
}
The response will contain the populated fields. 
{
  "object": "form_population_result",
  "data": {
    "fields": {
      "block_10_first_day_worked": "2025-01-01",
      "block_11_last_day_for_which_paid": "2025-01-31",
      "block_8_social_insurance_number": "196710156",
      "employee_first_name": "Marley",
      "employee_last_name": "Prosacco",
      "block_5_cra_payroll_account_number": "148030647RP9916",
      "block_6_pay_period_type": "M",
      "block_12_final_pay_period_ending_date": "2025-01-31",
      "block_15_total_insurable_hours": "0",
      "pp1_insurable_earnings": 456.0,
      "pp2_insurable_earnings": 612.0,
      "pp3_insurable_earnings": 284.0
    }
  },
  "links": {
    "self": null
  }
}

​
Persisting Population Data

Population data is not automatically persisted to a form. To persist the population result, update the form using the form update endpoint. 
# PUT /services/payroll/forms/form_123
{
  "block_10_first_day_worked": "2025-01-01",
  "block_11_last_day_for_which_paid": "2025-01-31",
  "block_8_social_insurance_number": "196710156",
  "employee_first_name": "Marley",
  "employee_last_name": "Prosacco",
  "block_5_cra_payroll_account_number": "148030647RP9916",
  "block_6_pay_period_type": "M",
  "block_12_final_pay_period_ending_date": "2025-01-31",
  "block_15_total_insurable_hours": "0",
  "pp1_insurable_earnings": 456.0,
  "pp2_insurable_earnings": 612.0,
  "pp3_insurable_earnings": 213.15
}

​
Population Strategies

When populating form, the work assignments’ pay schedules dictate the number of pay periods to be used. For a single work assignment, the work assignment’s pay schedule is used. If multiple work assignments are provided and the pay schedules are in sync (ex: semi-monthly and standard monthly), the longer of the pay schedules frequencies is used. This ensures no proration is done. If multiple work assignments are provided and the pay schedules are not in sync (ex: semi-monthly and weekly), weekly averaging is used.

​
Validation

Validate the fields of an ROE using the form type validate endpoint. The fields that can be sent to the validation endpoint can be retrieved from the Retrieve form type endpoint for ROE found at services/payroll/form_types/roe under the fields key. 
# POST /services/payroll/form_types/roe/validate
{
  "block_10_first_day_worked": "2025-01-01",
  "block_11_last_day_for_which_paid": "2025-01-31",
  "block_8_social_insurance_number": "196710156",
  "employee_first_name": "Marley",
  "employee_last_name": "Prosacco",
  "block_5_cra_payroll_account_number": "148030647RP9916",
  "block_6_pay_period_type": "M",
  "block_12_final_pay_period_ending_date": "2025-01-31",
  "block_15_total_insurable_hours": "0",
  "pp1_insurable_earnings": 0.0,
  "pp2_insurable_earnings": 612.0,
  "pp3_insurable_earnings": 213.15
}
The response will contain any validation errors. 
{
  "data": {
    "errors": {
      "pp1_insurable_earnings": ["pp1_insurable_earnings cannot be 0"]
    }
  }
}

​
Submission

An ROE can be submitted using the form submit endpoint.

​
Manual Submission

  • By default, the submission endpoint assumes manual submission. The form’s status is changed to done. The form is not submitted to Service Canada, but the XML version of the form can be exported.

​
Managed Submission

  • ROEs can automatically be submitted to Service Canada using managed submissions. Managed submission are enabled per business entity. In the Nmbr Portal, create a Business Entity ROE Authorization for the Business Entity that should have managed submissions. Once the authorization is complete, ROEs generated for the Business Entity will be managed. When submitted, a managed ROE’s status is changed from draft to processing until it is verified with Service Canada. Once verified, the form’s status is changed to done.

​
Exporting the XML

Retrieve the XML using the form show endpoint with Content-Type: application/xml.