Skip to main content
While it’s simpler to switch payroll providers at the beginning of the fiscal year - a point where you have less historical payroll data to deal with - switching payroll providers mid-year does happen. Modern payroll services make the migration process much simpler than the manual processes required by older systems. Nmbr provides support for switching payroll providers mid-year in the form of historical payrolls. Historical payrolls are used to capture payroll data from your previous payroll provider, data such as wages paid to date, income tax collected to date, and CPP contributed to date. By capturing at least 1 historical payroll, Nmbr will have the necessary data to calculate your upcoming and future payrolls accurately.

​
Payroll Setup

Start by creating the shell for a historical payroll. 
curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/payrolls \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
          "pay_schedule_id": "axzjqzC5oOZ51h3mqmXK"
          "type": "historical",
          "period_start" : "2023-01-01",
          "period_end" : "2023-06-01"
          "pay_date": "2023-06-01"
        }'
A new historical payroll will be created, and can have Pay Stub data imported to populate the Payroll.

​
Bulk Importing Historical Pay Stubs

Nmbr supports bulk importing of historical pay stubs through a CSV file. This is useful for migrating large amounts of payroll data from a previous provider. There are two types of import templates available:
  • preset: This template includes the line items types configured through a Business Preset.
  • all_types: This template includes all possible line item types.

​
Importing through the API

Historical pay stubs can be created through the API by uploading a CSV file containing the historical pay stub data.

​
Generating the CSV Template

Generate the CSV import template by making a GET request. You must specify the template type as either preset or all_types. 
curl --request GET \
     --url https://sandbox.nmbr.co/services/payroll/payrolls/<payroll_ulid>/import?template=preset \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Accept: text/csv'
This will return a CSV file that can be filled out with the historical pay stub data.

​
Uploading the CSV File

Once the CSV file is filled out, it can be uploaded to the historical payroll using a POST request. 
curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/payrolls/<payroll_ulid>/import \
     --header 'Authorization: Bearer <access_token>' \
        --header 'accept: application/json' \
        --header 'content-type: multipart/form-data' \
        --form 'import_file=@/path/to/your/file.csv'
Upload Validation Errors
If the Accept header is set to application/json, validation errors will be returned a JSON object. If the Accept header is set to text/csv, validation errors will as a CSV that combines the original data with an additional error column. This validation CSV can be updated and re-uploaded directly. Note: a CSV will only be returned if the uploaded CSV was well-formed.

​
Importing through the Portal

Historical pay stubs can also be imported through the Nmbr Portal. Navigate to the Payroll section, select the appropriate Pay Schedule, and then select the Historical Payroll you created earlier. There will be an option to “Import Historical Pay Stubs”, which will guide you through the process of uploading a CSV file. Like with the API, you will need to choose between the preset and all_types templates.

​
Approving payrolls

Approving the historical payroll will lock in the data and give you an accurate foundation for all future payroll runs. 
curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/payrolls/01HZNX4N7DTJJ9BTV3TSZ46A85/approve \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

​
Additional Employees

A single Pay Schedule can have multiple Historical Payrolls, provided they do not contain conflicting earning periods for any individual employees. If a new Employee, or multiple Employees, are being added to an existing Pay Schedule mid-year, you may create an Historical Payroll to represent those Employees Year-To-Dates before their first regular Payroll.