> ## 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.

# Historical Payrolls

> Capturing year-to-date amounts is an important step in the accuracy of your payroll

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.

```bash theme={null}
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`.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.