Create an employee

curl --request POST \
  --url https://sandbox.nmbr.co/services/payroll/employees \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "employee_number": "001",
  "first_name": "Marley",
  "last_name": "Prosacco",
  "personal_email": "marley.prosacco@personal.test",
  "work_email": "mprosacco@work.test",
  "address_line_1": "Angelina Ridge",
  "city": "Toronto",
  "administrative_area": "ON",
  "country_code": "CA",
  "postal_code": "M1M1M1",
  "sin": "196710156",
  "date_of_birth": "1985-01-20"
}
'

import requests

url = "https://sandbox.nmbr.co/services/payroll/employees"

payload = {
    "employee_number": "001",
    "first_name": "Marley",
    "last_name": "Prosacco",
    "personal_email": "marley.prosacco@personal.test",
    "work_email": "mprosacco@work.test",
    "address_line_1": "Angelina Ridge",
    "city": "Toronto",
    "administrative_area": "ON",
    "country_code": "CA",
    "postal_code": "M1M1M1",
    "sin": "196710156",
    "date_of_birth": "1985-01-20"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    employee_number: '001',
    first_name: 'Marley',
    last_name: 'Prosacco',
    personal_email: 'marley.prosacco@personal.test',
    work_email: 'mprosacco@work.test',
    address_line_1: 'Angelina Ridge',
    city: 'Toronto',
    administrative_area: 'ON',
    country_code: 'CA',
    postal_code: 'M1M1M1',
    sin: '196710156',
    date_of_birth: '1985-01-20'
  })
};

fetch('https://sandbox.nmbr.co/services/payroll/employees', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.nmbr.co/services/payroll/employees",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'employee_number' => '001',
    'first_name' => 'Marley',
    'last_name' => 'Prosacco',
    'personal_email' => 'marley.prosacco@personal.test',
    'work_email' => 'mprosacco@work.test',
    'address_line_1' => 'Angelina Ridge',
    'city' => 'Toronto',
    'administrative_area' => 'ON',
    'country_code' => 'CA',
    'postal_code' => 'M1M1M1',
    'sin' => '196710156',
    'date_of_birth' => '1985-01-20'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.nmbr.co/services/payroll/employees"

	payload := strings.NewReader("{\n  \"employee_number\": \"001\",\n  \"first_name\": \"Marley\",\n  \"last_name\": \"Prosacco\",\n  \"personal_email\": \"marley.prosacco@personal.test\",\n  \"work_email\": \"mprosacco@work.test\",\n  \"address_line_1\": \"Angelina Ridge\",\n  \"city\": \"Toronto\",\n  \"administrative_area\": \"ON\",\n  \"country_code\": \"CA\",\n  \"postal_code\": \"M1M1M1\",\n  \"sin\": \"196710156\",\n  \"date_of_birth\": \"1985-01-20\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox.nmbr.co/services/payroll/employees")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"employee_number\": \"001\",\n  \"first_name\": \"Marley\",\n  \"last_name\": \"Prosacco\",\n  \"personal_email\": \"marley.prosacco@personal.test\",\n  \"work_email\": \"mprosacco@work.test\",\n  \"address_line_1\": \"Angelina Ridge\",\n  \"city\": \"Toronto\",\n  \"administrative_area\": \"ON\",\n  \"country_code\": \"CA\",\n  \"postal_code\": \"M1M1M1\",\n  \"sin\": \"196710156\",\n  \"date_of_birth\": \"1985-01-20\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.nmbr.co/services/payroll/employees")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"employee_number\": \"001\",\n  \"first_name\": \"Marley\",\n  \"last_name\": \"Prosacco\",\n  \"personal_email\": \"marley.prosacco@personal.test\",\n  \"work_email\": \"mprosacco@work.test\",\n  \"address_line_1\": \"Angelina Ridge\",\n  \"city\": \"Toronto\",\n  \"administrative_area\": \"ON\",\n  \"country_code\": \"CA\",\n  \"postal_code\": \"M1M1M1\",\n  \"sin\": \"196710156\",\n  \"date_of_birth\": \"1985-01-20\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<id>",
  "object": "employee",
  "data": {
    "company": {
      "id": "<id>",
      "object": "company",
      "links": {
        "self": "/companies/<id>"
      }
    },
    "employee_number": "001",
    "first_name": "Marley",
    "last_name": "Prosacco",
    "middle_initial": null,
    "personal_email": "marley.prosacco@personal.test",
    "work_email": "mprosacco@work.test",
    "address_line_1": "Angelina Ridge",
    "address_line_2": null,
    "city": "Toronto",
    "administrative_area": "ON",
    "province_code": "ON",
    "country_code": "CA",
    "postal_code": "M1M1M1",
    "sin": "196710156",
    "sin_last_3": "156",
    "date_of_birth": "1985-01-20",
    "warnings": {
      "object": "list",
      "data": [
        {
          "object": "warning",
          "data": {
            "namespace": "onboarding",
            "type": "bank_account_doesnt_exists"
          }
        }
      ]
    },
    "external_ref": null,
    "preferred_locale": null,
    "archived_at": null,
    "created_at": "2026-01-01T00:00:00.000000Z",
    "updated_at": "2026-01-01T00:00:00.000000Z"
  },
  "links": {
    "self": "/employees/<id>"
  }
}

POST

employees

Create an employee

curl --request POST \
  --url https://sandbox.nmbr.co/services/payroll/employees \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "employee_number": "001",
  "first_name": "Marley",
  "last_name": "Prosacco",
  "personal_email": "marley.prosacco@personal.test",
  "work_email": "mprosacco@work.test",
  "address_line_1": "Angelina Ridge",
  "city": "Toronto",
  "administrative_area": "ON",
  "country_code": "CA",
  "postal_code": "M1M1M1",
  "sin": "196710156",
  "date_of_birth": "1985-01-20"
}
'

import requests

url = "https://sandbox.nmbr.co/services/payroll/employees"

payload = {
    "employee_number": "001",
    "first_name": "Marley",
    "last_name": "Prosacco",
    "personal_email": "marley.prosacco@personal.test",
    "work_email": "mprosacco@work.test",
    "address_line_1": "Angelina Ridge",
    "city": "Toronto",
    "administrative_area": "ON",
    "country_code": "CA",
    "postal_code": "M1M1M1",
    "sin": "196710156",
    "date_of_birth": "1985-01-20"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    employee_number: '001',
    first_name: 'Marley',
    last_name: 'Prosacco',
    personal_email: 'marley.prosacco@personal.test',
    work_email: 'mprosacco@work.test',
    address_line_1: 'Angelina Ridge',
    city: 'Toronto',
    administrative_area: 'ON',
    country_code: 'CA',
    postal_code: 'M1M1M1',
    sin: '196710156',
    date_of_birth: '1985-01-20'
  })
};

fetch('https://sandbox.nmbr.co/services/payroll/employees', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.nmbr.co/services/payroll/employees",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'employee_number' => '001',
    'first_name' => 'Marley',
    'last_name' => 'Prosacco',
    'personal_email' => 'marley.prosacco@personal.test',
    'work_email' => 'mprosacco@work.test',
    'address_line_1' => 'Angelina Ridge',
    'city' => 'Toronto',
    'administrative_area' => 'ON',
    'country_code' => 'CA',
    'postal_code' => 'M1M1M1',
    'sin' => '196710156',
    'date_of_birth' => '1985-01-20'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.nmbr.co/services/payroll/employees"

	payload := strings.NewReader("{\n  \"employee_number\": \"001\",\n  \"first_name\": \"Marley\",\n  \"last_name\": \"Prosacco\",\n  \"personal_email\": \"marley.prosacco@personal.test\",\n  \"work_email\": \"mprosacco@work.test\",\n  \"address_line_1\": \"Angelina Ridge\",\n  \"city\": \"Toronto\",\n  \"administrative_area\": \"ON\",\n  \"country_code\": \"CA\",\n  \"postal_code\": \"M1M1M1\",\n  \"sin\": \"196710156\",\n  \"date_of_birth\": \"1985-01-20\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox.nmbr.co/services/payroll/employees")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"employee_number\": \"001\",\n  \"first_name\": \"Marley\",\n  \"last_name\": \"Prosacco\",\n  \"personal_email\": \"marley.prosacco@personal.test\",\n  \"work_email\": \"mprosacco@work.test\",\n  \"address_line_1\": \"Angelina Ridge\",\n  \"city\": \"Toronto\",\n  \"administrative_area\": \"ON\",\n  \"country_code\": \"CA\",\n  \"postal_code\": \"M1M1M1\",\n  \"sin\": \"196710156\",\n  \"date_of_birth\": \"1985-01-20\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.nmbr.co/services/payroll/employees")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"employee_number\": \"001\",\n  \"first_name\": \"Marley\",\n  \"last_name\": \"Prosacco\",\n  \"personal_email\": \"marley.prosacco@personal.test\",\n  \"work_email\": \"mprosacco@work.test\",\n  \"address_line_1\": \"Angelina Ridge\",\n  \"city\": \"Toronto\",\n  \"administrative_area\": \"ON\",\n  \"country_code\": \"CA\",\n  \"postal_code\": \"M1M1M1\",\n  \"sin\": \"196710156\",\n  \"date_of_birth\": \"1985-01-20\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<id>",
  "object": "employee",
  "data": {
    "company": {
      "id": "<id>",
      "object": "company",
      "links": {
        "self": "/companies/<id>"
      }
    },
    "employee_number": "001",
    "first_name": "Marley",
    "last_name": "Prosacco",
    "middle_initial": null,
    "personal_email": "marley.prosacco@personal.test",
    "work_email": "mprosacco@work.test",
    "address_line_1": "Angelina Ridge",
    "address_line_2": null,
    "city": "Toronto",
    "administrative_area": "ON",
    "province_code": "ON",
    "country_code": "CA",
    "postal_code": "M1M1M1",
    "sin": "196710156",
    "sin_last_3": "156",
    "date_of_birth": "1985-01-20",
    "warnings": {
      "object": "list",
      "data": [
        {
          "object": "warning",
          "data": {
            "namespace": "onboarding",
            "type": "bank_account_doesnt_exists"
          }
        }
      ]
    },
    "external_ref": null,
    "preferred_locale": null,
    "archived_at": null,
    "created_at": "2026-01-01T00:00:00.000000Z",
    "updated_at": "2026-01-01T00:00:00.000000Z"
  },
  "links": {
    "self": "/employees/<id>"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

first_name

string

required

The employee's first name.

Maximum string length: 50

last_name

string

required

The employee's last name.

Maximum string length: 50

employee_number

string | null

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.

Maximum string length: 40

middle_initial

string | null

The employee's middle initial.

Maximum string length: 1

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 | null

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 | null

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 | null

The city of the employee's mailing address.

administrative_area

string | null

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.

Maximum string length: 255

province_code

string | null

deprecated

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

enum<string>

The country code for the employee's mailing address.

Available options:

CA,

GB

postal_code

string | null

The postal code for the employee's mailing address.

Maximum string length: 10

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

Maximum string length: 255

preferred_locale

enum<string>

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.

Available options:

en,

fr

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 - application/json

Created

string

read-only

The unique identifier of the object in Nmbr.

object

string

read-only

The type of the object in Nmbr ("employee").

data

Employee · object

Hide child attributes

data.company

object

Hide child attributes

data.company.id

string

read-only

The unique identifier of the object in Nmbr.

data.company.object

string

read-only

The type of the object in Nmbr ("company").

data.employee_number

string | null

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.

Maximum string length: 40

data.first_name

string

The employee's first name.

Maximum string length: 50

data.last_name

string

The employee's last name.

Maximum string length: 50

data.middle_initial

string | null

The employee's middle initial.

Maximum string length: 1

data.personal_email

string | null

The employee's personal email address, used as the primary address for payroll communications such as Pay Stub emails.

Maximum string length: 255

data.work_email

string | null

The employee's work email address. Used for payroll communications if personal_email is not set.

Maximum string length: 255

data.address_line_1

string | null

The first line of the employee's mailing address. Canada Revenue Agency forms (T4, RL-1) truncate this to the length those forms allow.

Maximum string length: 255

data.address_line_2

string | null

The second line of the employee's mailing address. Canada Revenue Agency forms (T4, RL-1) truncate this to the length those forms allow.

Maximum string length: 255

data.city

string | null

The city of the employee's mailing address.

Maximum string length: 255

data.administrative_area

string | null

Maximum string length: 255

data.province_code

string | null

deprecated

This attribute is deprecated and will be removed.

A deprecated alias of administrative_area that mirrors its value. Use administrative_area instead.

data.country_code

enum<string> | null

The country code for the employee's mailing address.

Available options:

CA,

GB

Maximum string length: 2

data.postal_code

string | null

The postal code for the employee's mailing address.

Maximum string length: 10

data.sin

string | null

deprecated

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.

data.sin_last_3

string | null

The last 3 digits of the employee's Social Insurance Number (SIN). null if no SIN has been provided.

data.date_of_birth

string<date> | null

The employee's date of birth.

data.warnings

object | null

A collection of data validation warnings for this employee. Warnings indicate incomplete or potentially incorrect data and could prevent payroll processing.

Hide child attributes

data.warnings.object

string | null

data.warnings.data

object[] | null

Hide child attributes

data.warnings.data.object

string | null

data.warnings.data.data

object | null

Hide child attributes

data.warnings.data.data.namespace

string | null

data.warnings.data.data.type

string | null

data.external_ref

string | null

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.

Maximum string length: 255

data.preferred_locale

enum<string> | null

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.

Available options:

en,

fr

data.archived_at

string<dateTime> | null

read-only

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.

data.created_at

string<dateTime>

read-only

The date and time the object was created in Nmbr.

data.updated_at

string<dateTime>

read-only

The date and time the object was last updated in Nmbr.

List employees Retrieve an employee

⌘I

Overview

Bulk & Batch Operations

Partner

Companies

Employees

Contractors

Payrolls

Line Items

Banking

Reporting

Forms

Vacation Pay

Lookups

Calculations

Miscellaneous

Create an employee

Authorizations

Body

Response