---
title: "Create an employee"
method: POST
path: "/employees"
tags: ["Employees"]
---

# Create an employee

`POST /employees`

## Request body

- object
  - `employee_number` string, nullable — An optional identifier for the employee within the partner's system, such as a badge number or HR system ID. Distinct from `id` and `external_ref`.
  - `first_name` string, required — The employee's first name.
  - `last_name` string, required — The employee's last name.
  - `middle_initial` string, nullable — The employee's middle initial.
  - `personal_email` string — The employee's personal email address, used as the primary address for payroll communications such as Pay Stub emails.
  - `work_email` string — The employee's work email address. Used for payroll communications if `personal_email` is not set.
  - `address_line_1` string, nullable — The first line of the employee's mailing address. Canada Revenue Agency forms (T4, RL-1) truncate this to the length those forms allow.
  - `address_line_2` string, nullable — The second line of the employee's mailing address. Canada Revenue Agency forms (T4, RL-1) truncate this to the length those forms allow.
  - `city` string, nullable — The city of the employee's mailing address.
  - `administrative_area` string, nullable — The region of the employee's mailing address — the province, state, or county, depending on the country. For Canadian employees this is the Province of Residence (POR), not the Province of Employment (POE) or Province of Work (POW). POE and POW are configured via the Work Assignment's Tax Properties.
  - `province_code` string, nullable — This attribute is deprecated and will be removed. A deprecated alias of `administrative_area` that mirrors its value. Use `administrative_area` instead. In Canada, must be an uppercase 2-letter province code: `AB`, `BC`, `MB`, `NB`, `NL`, `NS`, `NT`, `NU`, `ON`, `PE`, `QC`, `SK`, `YT`
  - `country_code` 'CA' | 'GB' — The country code for the employee's mailing address.
  - `postal_code` string, nullable — The postal code for the employee's mailing address.
  - `sin` string — The employee's Social Insurance Number (SIN), used for tax reporting.
  - `date_of_birth` string, date — The employee's date of birth.
  - `external_ref` string
  - `preferred_locale` 'en' | 'fr' — The locale used for payroll communications sent to this employee, such as Pay Stub emails. If not set, the Business Entity's locale is used.
  - `archived_at` string, date — The date the employee was archived. Archiving an employee also archives all Work Assignments that are not already archived. Archived employees do not appear in active listings.

## Response `201`

Created

- object
  - `id` string — The unique identifier of the object in Nmbr.
  - `object` string — The type of the object in Nmbr (`"employee"`).
  - `data` Employee
    - `company` object
      - `id` string — The unique identifier of the object in Nmbr.
      - `object` string — The type of the object in Nmbr (`"company"`).
    - `employee_number` string, nullable — An optional identifier for the employee within the partner's system, such as a badge number or HR system ID. Distinct from `id` and `external_ref`.
    - `first_name` string — The employee's first name.
    - `last_name` string — The employee's last name.
    - `middle_initial` string, nullable — The employee's middle initial.
    - `personal_email` string, nullable — The employee's personal email address, used as the primary address for payroll communications such as Pay Stub emails.
    - `work_email` string, nullable — The employee's work email address. Used for payroll communications if `personal_email` is not set.
    - `address_line_1` string, nullable — The first line of the employee's mailing address. Canada Revenue Agency forms (T4, RL-1) truncate this to the length those forms allow.
    - `address_line_2` string, nullable — The second line of the employee's mailing address. Canada Revenue Agency forms (T4, RL-1) truncate this to the length those forms allow.
    - `city` string, nullable — The city of the employee's mailing address.
    - `administrative_area` string, nullable — The region of the employee's mailing address — the province, state, or county, depending on the country. For Canadian employees this is the Province of Residence (POR), not the Province of Employment (POE) or Province of Work (POW). POE and POW are configured via the Work Assignment's Tax Properties.
    - `province_code` string, nullable — This attribute is deprecated and will be removed. A deprecated alias of `administrative_area` that mirrors its value. Use `administrative_area` instead.
    - `country_code` 'CA' | 'GB', nullable — The country code for the employee's mailing address.
    - `postal_code` string, nullable — The postal code for the employee's mailing address.
    - `sin` string, nullable — This attribute is deprecated and will be removed. The employee's Social Insurance Number (SIN), used for tax reporting. If you only need the last 3 digits for display purposes, use `sin_last_3` instead. If you need the complete SIN, use the `/employees/:id/reveal` endpoint instead. Note the `/reveal` endpoint can only reveal one employee at a time and is rate-limited for security reasons.
    - `sin_last_3` string, nullable — The last 3 digits of the employee's Social Insurance Number (SIN). `null` if no SIN has been provided.
    - `date_of_birth` string, date, nullable — The employee's date of birth.
    - `warnings` object, nullable — A collection of data validation warnings for this employee. Warnings indicate incomplete or potentially incorrect data and could prevent payroll processing.
      - `object` string, nullable
      - `data` object[], nullable
        - `object` string, nullable
        - `data` object, nullable
          - `namespace` string, nullable
          - `type` string, nullable
    - `external_ref` string, nullable — A reference to the object in an external system, e.g. the primary key of the object in your application's database. Nmbr doesn't use, validate, parse, or require this value to be unique - it simply stores it for your reference.
    - `preferred_locale` 'en' | 'fr', nullable — The locale used for payroll communications sent to this employee, such as Pay Stub emails. If not set, the Business Entity's locale is used.
    - `archived_at` string, dateTime, nullable — The date the employee was archived. Archiving an employee also archives all Work Assignments that are not already archived. Archived employees do not appear in active listings.
    - `created_at` string, dateTime — The date and time the object was created in Nmbr.
    - `updated_at` string, dateTime — The date and time the object was last updated in Nmbr.

---

[API](https://skmtc.net/nmbr/apis/nmbr-api.md) · [All operations](https://skmtc.net/nmbr/apis/nmbr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nmbr/nmbr-api/versions/01cd9c45a923/schema)