Create a business entity

curl --request POST \
  --url https://sandbox.nmbr.co/services/payroll/business_entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "business_number": "136549169RP9916",
  "name": "Bobs Burgers (#39616)",
  "address_line_1": "13 Fake Street",
  "city": "Toronto",
  "province_code": "ON",
  "country_code": "CA",
  "postal_code": "M1M1M1",
  "contact_name": "Jean Smith",
  "contact_email": "smith@company.com",
  "contact_area_code": "111",
  "contact_phone_number": "2223333",
  "pay_day_movement_setting": "inherit",
  "vacation_pay_formula_setting": "pay_date",
  "remitter_type": "regular",
  "external_ref": "<external_reference>",
  "preferred_locale": "en",
  "resolve_journal_entry_stat_withholdings": true,
  "tax_properties": [
    {
      "type": "ca::province_of_employment",
      "value": "ca_on",
      "effective_from": "2026-01-01",
      "effective_to": null,
      "note": null
    }
  ]
}
'

{
  "id": "<id>",
  "object": "business_entity",
  "data": {
    "business_number": "136549169RP9916",
    "name": "Bobs Burgers (#39616)",
    "legal_name": null,
    "legal_registration_number": null,
    "address_line_1": "13 Fake Street",
    "address_line_2": null,
    "city": "Toronto",
    "in_preview": false,
    "province_code": "ON",
    "country_code": "CA",
    "postal_code": "M1M1M1",
    "contact_name": "Jean Smith",
    "contact_email": "smith@company.com",
    "contact_area_code": "111",
    "contact_phone_number": "2223333",
    "contact_extension": null,
    "pay_day_movement_setting": "inherit",
    "vacation_pay_formula_setting": "pay_date",
    "remitter_type": "regular",
    "status": "onboarding",
    "company": {
      "id": "<id>",
      "object": "company",
      "links": {
        "self": "/companies/<id>"
      }
    },
    "warnings": {
      "object": "list",
      "data": [
        {
          "object": "warning",
          "data": {
            "namespace": "onboarding",
            "type": "business_legal_information_not_provided"
          }
        },
        {
          "object": "warning",
          "data": {
            "namespace": "onboarding",
            "type": "bank_account_doesnt_exists"
          }
        },
        {
          "object": "warning",
          "data": {
            "namespace": "onboarding",
            "type": "bank_account_pad_not_signed"
          }
        }
      ]
    },
    "external_ref": "<external_reference>",
    "available_tax_properties": [
      "ca::tax_id",
      "ca::qc::tax_id",
      "ca::province_of_employment",
      "ca::federal_oc_surtax_exempt",
      "ca::on::eht",
      "ca::mb::eht",
      "ca::nl::eht",
      "ca::bc::eht",
      "ca::qc::eht"
    ],
    "effective_processing_speed": "three_day",
    "processing_speed": "inherit",
    "has_bank_accounts": false,
    "has_pay_schedules": false,
    "has_payrolls": false,
    "current_tax_jurisdiction": "ca_on",
    "ca_settings": {
      "roe_submission_setting": "manual"
    },
    "accounting_settings": {
      "default_bank_accounting_code": null,
      "default_payroll_payable_accounting_code": null,
      "resolve_journal_entry_stat_withholdings": true,
      "primary_tag_group": null,
      "block_approval_on_incomplete_journal_entries": false,
      "block_approval_on_missing_export_identifiers": false
    },
    "default_bank_accounting_code": null,
    "default_payroll_payable_accounting_code": null,
    "preferred_locale": {
      "id": "<id>",
      "object": "locale",
      "data": {
        "label": "English"
      }
    },
    "hold_funding_for_verification": false,
    "resolve_journal_entry_stat_withholdings": true,
    "primary_tag_group": null,
    "created_at": "2026-01-01T00:00:00.000000Z",
    "updated_at": "2026-01-01T00:00:00.000000Z"
  },
  "links": {
    "self": "/business_entities/<id>"
  }
}

POST

business_entities

curl --request POST \
  --url https://sandbox.nmbr.co/services/payroll/business_entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "business_number": "136549169RP9916",
  "name": "Bobs Burgers (#39616)",
  "address_line_1": "13 Fake Street",
  "city": "Toronto",
  "province_code": "ON",
  "country_code": "CA",
  "postal_code": "M1M1M1",
  "contact_name": "Jean Smith",
  "contact_email": "smith@company.com",
  "contact_area_code": "111",
  "contact_phone_number": "2223333",
  "pay_day_movement_setting": "inherit",
  "vacation_pay_formula_setting": "pay_date",
  "remitter_type": "regular",
  "external_ref": "<external_reference>",
  "preferred_locale": "en",
  "resolve_journal_entry_stat_withholdings": true,
  "tax_properties": [
    {
      "type": "ca::province_of_employment",
      "value": "ca_on",
      "effective_from": "2026-01-01",
      "effective_to": null,
      "note": null
    }
  ]
}
'

{
  "id": "<id>",
  "object": "business_entity",
  "data": {
    "business_number": "136549169RP9916",
    "name": "Bobs Burgers (#39616)",
    "legal_name": null,
    "legal_registration_number": null,
    "address_line_1": "13 Fake Street",
    "address_line_2": null,
    "city": "Toronto",
    "in_preview": false,
    "province_code": "ON",
    "country_code": "CA",
    "postal_code": "M1M1M1",
    "contact_name": "Jean Smith",
    "contact_email": "smith@company.com",
    "contact_area_code": "111",
    "contact_phone_number": "2223333",
    "contact_extension": null,
    "pay_day_movement_setting": "inherit",
    "vacation_pay_formula_setting": "pay_date",
    "remitter_type": "regular",
    "status": "onboarding",
    "company": {
      "id": "<id>",
      "object": "company",
      "links": {
        "self": "/companies/<id>"
      }
    },
    "warnings": {
      "object": "list",
      "data": [
        {
          "object": "warning",
          "data": {
            "namespace": "onboarding",
            "type": "business_legal_information_not_provided"
          }
        },
        {
          "object": "warning",
          "data": {
            "namespace": "onboarding",
            "type": "bank_account_doesnt_exists"
          }
        },
        {
          "object": "warning",
          "data": {
            "namespace": "onboarding",
            "type": "bank_account_pad_not_signed"
          }
        }
      ]
    },
    "external_ref": "<external_reference>",
    "available_tax_properties": [
      "ca::tax_id",
      "ca::qc::tax_id",
      "ca::province_of_employment",
      "ca::federal_oc_surtax_exempt",
      "ca::on::eht",
      "ca::mb::eht",
      "ca::nl::eht",
      "ca::bc::eht",
      "ca::qc::eht"
    ],
    "effective_processing_speed": "three_day",
    "processing_speed": "inherit",
    "has_bank_accounts": false,
    "has_pay_schedules": false,
    "has_payrolls": false,
    "current_tax_jurisdiction": "ca_on",
    "ca_settings": {
      "roe_submission_setting": "manual"
    },
    "accounting_settings": {
      "default_bank_accounting_code": null,
      "default_payroll_payable_accounting_code": null,
      "resolve_journal_entry_stat_withholdings": true,
      "primary_tag_group": null,
      "block_approval_on_incomplete_journal_entries": false,
      "block_approval_on_missing_export_identifiers": false
    },
    "default_bank_accounting_code": null,
    "default_payroll_payable_accounting_code": null,
    "preferred_locale": {
      "id": "<id>",
      "object": "locale",
      "data": {
        "label": "English"
      }
    },
    "hold_funding_for_verification": false,
    "resolve_journal_entry_stat_withholdings": true,
    "primary_tag_group": null,
    "created_at": "2026-01-01T00:00:00.000000Z",
    "updated_at": "2026-01-01T00:00:00.000000Z"
  },
  "links": {
    "self": "/business_entities/<id>"
  }
}

Authorizations

Authorization

string

header

required

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

Body

application/json

name

string

required

The business entity's operating or trade name.

Maximum string length: 255

business_number

string

The Canada Revenue Agency (CRA) Business Number (BN) for this business entity, used to identify the business for payroll tax remittances.

legal_name

string

The business entity's registered legal name.

Maximum string length: 255

legal_registration_number

string

The provincial business registration number.

Maximum string length: 255

address_line_1

string

The first line of the business entity's mailing address. This character limit (30) is set by government reporting requirements, not application-level validation.

Maximum string length: 30

address_line_2

string

The second line of the business entity's mailing address. This character limit (30) is set by government reporting requirements, not application-level validation.

Maximum string length: 30

city

string

The city of the business entity's mailing address.

Maximum string length: 28

province_code

string | null

The province code for the business entity's mailing address.

A province must be provided when creating a business entity in Canada.

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

string

The country code for the business entity's mailing address.

Must be an uppercase 2-letter country code (ISO 3166-1 alpha-2, e.g., CA).

postal_code

string

The postal code for the business entity's mailing address.

Maximum string length: 10

contact_name

string

The name of the primary contact at the business entity.

Maximum string length: 255

contact_email

string

The email address of the primary contact at the business entity.

contact_area_code

string | null

The area code for the primary contact's phone number.

contact_phone_number

string | null

The primary contact's phone number, excluding area code.

contact_extension

string

The extension for the primary contact's phone number.

Maximum string length: 5

pay_day_movement_setting

enum<string>

The business entity-level setting for how pay dates are adjusted when they fall on a weekend or bank holiday. If set to inherit, the Company's setting is used.

Available options:

inherit,

next_business_day,

previous_business_day

vacation_pay_formula_setting

enum<string>

The formula used to calculate vacation pay for Employees in this business entity.

Available options:

pay_date,

period_end,

period_start

remitter_type

enum<string>

The Canada Revenue Agency (CRA) remitter type, which determines the frequency of payroll tax remittances to the CRA.

Available options:

accelerated_threshold_1,

accelerated_threshold_2,

quarterly,

regular

in_preview

boolean

When true, the business entity is in preview mode. In preview mode, Payrolls can be run and approved but no real money movement occurs.

external_ref

string

Maximum string length: 255

preferred_locale

enum<string>

The locale used for payroll communications sent to Employees and Contractors within this business entity. If not set, the Company's locale is used.

Available options:

en,

fr

hold_funding_for_verification

boolean

resolve_journal_entry_stat_withholdings

boolean

accounting_settings

object

Hide child attributes

accounting_settings.resolve_journal_entry_stat_withholdings

boolean

accounting_settings.block_approval_on_incomplete_journal_entries

boolean

accounting_settings.block_approval_on_missing_export_identifiers

boolean

tax_properties

object[]

Hide child attributes

tax_properties.type

enum<string>

Available options:

ca::ab::claim_amount,

ca::ab::total_income_less_than_total_claim_amount,

ca::ab::workers_compensation_class,

ca::bc::claim_amount,

ca::bc::eht,

ca::bc::total_income_less_than_total_claim_amount,

ca::bc::workers_compensation_class,

ca::cpp_exempt,

ca::ei_exempt,

ca::ei_premium_reduction,

ca::federal::additional_tax,

ca::federal::annual_deduction_at_source,

ca::federal::claim_amount,

ca::federal::commission_expenses,

ca::federal::commission_total_income,

ca::federal::total_income_less_than_total_claim_amount,

ca::federal_oc_surtax_exempt,

ca::first_nation_exemptions,

ca::mb::claim_amount,

ca::mb::eht,

ca::mb::total_income_less_than_total_claim_amount,

ca::mb::workers_compensation_class,

ca::nb::claim_amount,

ca::nb::total_income_less_than_total_claim_amount,

ca::nb::workers_compensation_class,

ca::nl::claim_amount,

ca::nl::eht,

ca::nl::total_income_less_than_total_claim_amount,

ca::nl::workers_compensation_class,

ca::ns::claim_amount,

ca::ns::total_income_less_than_total_claim_amount,

ca::ns::workers_compensation_class,

ca::nt::claim_amount,

ca::nt::territorial_payroll_tax,

ca::nt::total_income_less_than_total_claim_amount,

ca::nt::workers_compensation_class,

ca::nu::claim_amount,

ca::nu::territorial_payroll_tax,

ca::nu::total_income_less_than_total_claim_amount,

ca::nu::workers_compensation_class,

ca::on::claim_amount,

ca::on::dependent_children_credit,

ca::on::eht,

ca::on::impaired_dependants_credit,

ca::on::total_income_less_than_total_claim_amount,

ca::on::workers_compensation_class,

ca::pe::claim_amount,

ca::pe::total_income_less_than_total_claim_amount,

ca::pe::workers_compensation_class,

ca::province_of_employment,

ca::province_of_work,

ca::qc::additional_tax,

ca::qc::claim_amount,

ca::qc::commission_percentage_taxed,

ca::qc::eht,

ca::qc::qpip_exempt,

ca::qc::qpp_exempt,

ca::qc::tax_id,

ca::qc::total_income_less_than_total_claim_amount,

ca::qc::workers_compensation_class,

ca::sk::claim_amount,

ca::sk::total_income_less_than_total_claim_amount,

ca::sk::workers_compensation_class,

ca::statutory_holiday_pay,

ca::tax_id,

ca::yt::claim_amount,

ca::yt::total_income_less_than_total_claim_amount,

ca::yt::workers_compensation_class

tax_properties.value

string

tax_properties.effective_from

string<date>

tax_properties.effective_to

string<date>

tax_properties.note

string | null

tax_properties.owner_id

string

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 ("business_entity").

data

Business Entity · object

Hide child attributes

data.business_number

string | null

The Canada Revenue Agency (CRA) Business Number (BN) for this business entity, used to identify the business for payroll tax remittances.

Maximum string length: 255

data.name

string

The business entity's operating or trade name.

Maximum string length: 255

data.legal_name

string | null

The business entity's registered legal name.

Maximum string length: 255

data.legal_registration_number

string | null

The provincial business registration number.

Maximum string length: 255

data.address_line_1

string | null

The first line of the business entity's mailing address. This character limit (30) is set by government reporting requirements, not application-level validation.

Maximum string length: 255

data.address_line_2

string | null

The second line of the business entity's mailing address. This character limit (30) is set by government reporting requirements, not application-level validation.

Maximum string length: 30

data.city

string | null

The city of the business entity's mailing address.

Maximum string length: 255

data.in_preview

boolean

When true, the business entity is in preview mode. In preview mode, Payrolls can be run and approved but no real money movement occurs.

data.province_code

enum<string> | null

The province code for the business entity's mailing address.

Available options:

AB,

BC,

FEDERAL,

MB,

NB,

NL,

NS,

NT,

NU,

OC,

ON,

PE,

QC,

SK,

YT

Maximum string length: 3

data.country_code

string | null

The country code for the business entity's mailing address.

Maximum string length: 2

data.postal_code

string | null

The postal code for the business entity's mailing address.

Maximum string length: 255

data.contact_name

string | null

The name of the primary contact at the business entity.

Maximum string length: 255

data.contact_email

string | null

The email address of the primary contact at the business entity.

Maximum string length: 255

data.contact_area_code

string | null

The area code for the primary contact's phone number.

Maximum string length: 255

data.contact_phone_number

string | null

The primary contact's phone number, excluding area code.

Maximum string length: 255

data.contact_extension

string | null

The extension for the primary contact's phone number.

Maximum string length: 255

data.pay_day_movement_setting

enum<string>

The business entity-level setting for how pay dates are adjusted when they fall on a weekend or bank holiday. If set to inherit, the Company's setting is used.

Available options:

inherit,

next_business_day,

previous_business_day

data.vacation_pay_formula_setting

enum<string>

The formula used to calculate vacation pay for Employees in this business entity.

Available options:

pay_date,

period_end,

period_start

data.remitter_type

enum<string> | null

The Canada Revenue Agency (CRA) remitter type, which determines the frequency of payroll tax remittances to the CRA.

Available options:

accelerated_threshold_1,

accelerated_threshold_2,

quarterly,

regular

data.status

enum<string>

The business entity's current status. A business entity must reach approved status before live Payrolls can be processed.

Available options:

approved,

onboarding,

suspended

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

object

A collection of data validation warnings for this business entity. 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

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

string[] | null

A list of Tax Property template identifiers supported for this business entity, based on its jurisdiction.

data.effective_processing_speed

string | null

The resolved processing speed after applying inheritance from the Partner if processing_speed is inherit.

data.processing_speed

enum<string>

The business entity-level processing speed setting. If set to inherit, the Partner's processing speed is used.

Available options:

five_day,

four_day,

inherit,

one_day,

three_day,

two_day

data.has_bank_accounts

boolean

Whether this business entity has any Bank Accounts configured.

data.has_pay_schedules

boolean

Whether this business entity has any Pay Schedules configured.

data.has_payrolls

boolean

Whether this business entity has any Payrolls.

data.current_tax_jurisdiction

string | null

The current tax jurisdiction for the business entity, derived from its ca::province_of_employment Tax Property.

data.ca_settings

object

Canada-specific settings for this business entity. Only present for business entities with a Canadian address.

Hide child attributes

data.ca_settings.roe_submission_setting

string | null

Indicates whether Record of Employment (ROE) submissions are managed by Nmbr (managed) or by the employer directly (manual).

data.accounting_settings

object

Accounting-related settings for this business entity. New clients should read and write these through this object; the top-level default_bank_accounting_code, default_payroll_payable_accounting_code, resolve_journal_entry_stat_withholdings, and primary_tag_group fields are retained as aliases for backwards compatibility.

Hide child attributes

data.accounting_settings.default_bank_accounting_code

any

The Accounting Code used as the default bank account row when generating journal entries.

data.accounting_settings.default_payroll_payable_accounting_code

any

The Accounting Code used as the default payroll payable row when generating journal entries.

data.accounting_settings.resolve_journal_entry_stat_withholdings

boolean

When true, statutory withholding line items (employee and employer) are split across tracking dimensions derived from their applicable source earnings. When false, each statutory withholding appears as a single unsplit row in journal entries.

The Tag Group that drives default accounting-code resolution for line items. Setting this also flags the group as a journal entry dimension.

data.accounting_settings.block_approval_on_incomplete_journal_entries

boolean

When true, payroll approval is blocked if any exportable journal entry row has no Accounting Code.

data.accounting_settings.block_approval_on_missing_export_identifiers

boolean

When true, payroll approval is blocked if any exportable journal entry row has no Accounting Code OR has one that lacks the enabled integration's external identifier.

data.default_bank_accounting_code

any

deprecated

This attribute is deprecated and will be removed.

Use accounting_settings.default_bank_accounting_code.

data.default_payroll_payable_accounting_code

any

deprecated

This attribute is deprecated and will be removed.

Use accounting_settings.default_payroll_payable_accounting_code.

data.preferred_locale

enum<string> | null

The locale used for payroll communications sent to Employees and Contractors within this business entity. If not set, the Company's locale is used.

Available options:

en,

fr

data.hold_funding_for_verification

boolean

When true, funding payments will be automatically held after settlement for verification. Downstream payments (employee, CRA, RQ) will not be processed until the funding payment hold is released.

data.resolve_journal_entry_stat_withholdings

boolean

deprecated

This attribute is deprecated and will be removed.

Use accounting_settings.resolve_journal_entry_stat_withholdings.

This attribute is deprecated and will be removed.

Use accounting_settings.primary_tag_group.

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 business entities Retrieve a business entity

⌘I