List business entities

curl --request GET \
  --url https://sandbox.nmbr.co/services/payroll/business_entities \
  --header 'Authorization: Bearer <token>'

{
  "object": "list",
  "data": [
    {
      "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": "approved",
        "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": null,
        "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>"
      }
    }
  ],
  "links": {
    "first": "/business_entities?page=1",
    "last": "/business_entities?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 15,
    "total": 1,
    "has_more": false
  }
}

GET

business_entities

curl --request GET \
  --url https://sandbox.nmbr.co/services/payroll/business_entities \
  --header 'Authorization: Bearer <token>'

{
  "object": "list",
  "data": [
    {
      "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": "approved",
        "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": null,
        "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>"
      }
    }
  ],
  "links": {
    "first": "/business_entities?page=1",
    "last": "/business_entities?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 15,
    "total": 1,
    "has_more": false
  }
}

Authorizations

Authorization

string

header

required

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

Query Parameters

expand

enum<string>[]

Available options:

accounting_settings.default_bank_accounting_code,

accounting_settings.default_payroll_payable_accounting_code,

accounting_settings.primary_tag_group,

bank_accounts,

business_presets,

company,

default_bank_accounting_code,

default_payroll_payable_accounting_code,

effective_tax_properties,

pay_schedules,

payrolls,

primary_tag_group,

tax_properties

Response

200 - application/json

object

string

read-only

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

data

object[]

Hide child attributes

data.id

string

read-only

The unique identifier of the object in Nmbr.

data.object

string

read-only

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

data.data

Default · object

Default
With company expanded
With pay_schedules expanded
With payrolls expanded
With bank_accounts expanded
With business_presets expanded
With tax_properties expanded
With effective_tax_properties expanded
With default_bank_accounting_code expanded
With default_payroll_payable_accounting_code expanded
With primary_tag_group expanded
With accounting_settings.default_bank_accounting_code expanded
With accounting_settings.default_payroll_payable_accounting_code expanded
With accounting_settings.primary_tag_group expanded

Hide child attributes

data.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.data.name

string

The business entity's operating or trade name.

Maximum string length: 255

data.data.legal_name

string | null

The business entity's registered legal name.

Maximum string length: 255

data.data.legal_registration_number

string | null

The provincial business registration number.

Maximum string length: 255

data.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.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.data.city

string | null

The city of the business entity's mailing address.

Maximum string length: 255

data.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.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.data.country_code

string | null

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

Maximum string length: 2

data.data.postal_code

string | null

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

Maximum string length: 255

data.data.contact_name

string | null

The name of the primary contact at the business entity.

Maximum string length: 255

data.data.contact_email

string | null

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

Maximum string length: 255

data.data.contact_area_code

string | null

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

Maximum string length: 255

data.data.contact_phone_number

string | null

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

Maximum string length: 255

data.data.contact_extension

string | null

The extension for the primary contact's phone number.

Maximum string length: 255

data.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.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.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.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.data.company

object

Hide child attributes

data.data.company.id

string

read-only

The unique identifier of the object in Nmbr.

data.data.company.object

string

read-only

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

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

string | null

data.data.warnings.data

object[] | null

Hide child attributes

data.data.warnings.data.object

string | null

data.data.warnings.data.data

object

Hide child attributes

data.data.warnings.data.data.namespace

string | null

data.data.warnings.data.data.type

string | null

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

string[] | null

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

data.data.effective_processing_speed

string | null

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

data.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.data.has_bank_accounts

boolean

Whether this business entity has any Bank Accounts configured.

data.data.has_pay_schedules

boolean

Whether this business entity has any Pay Schedules configured.

data.data.has_payrolls

boolean

Whether this business entity has any Payrolls.

data.data.current_tax_jurisdiction

string | null

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

data.data.ca_settings

object

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

Hide child attributes

data.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.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.data.accounting_settings.default_bank_accounting_code

any

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

data.data.accounting_settings.default_payroll_payable_accounting_code

any

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

data.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.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.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.data.default_bank_accounting_code

any

deprecated

This attribute is deprecated and will be removed.

Use accounting_settings.default_bank_accounting_code.

data.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.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.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.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.data.created_at

string<dateTime>

read-only

The date and time the object was created in Nmbr.

data.data.updated_at

string<dateTime>

read-only

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

Delete a company Create a business entity

⌘I