> ## 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. # Create a business entity ## OpenAPI ````yaml /spec/openapi.json post /business_entities openapi: 3.0.0 info: title: Nmbr API description: API to interact with Nmbr Payroll version: 1.0.0 servers: - url: https://sandbox.nmbr.co/services/payroll security: - CompanyToken: [] tags: - name: Accounting Codes - name: Accounting Code Rules - name: Adjustments - name: Allowances - name: Allowance Line Items - name: Allowance Types - name: Async Tasks - name: Bank Accounts - name: Business Entities - name: Business Entity Verifications - name: Business Entity ROE Authorizations - name: Business Presets - name: Calculations - name: Companies - name: Contractors - name: Deductions - name: Deduction Line Items - name: Deduction Types - name: Earnings - name: Earning Line Items - name: Earning Types - name: Effective Tax Properties - name: Employees - name: Employee Benefits - name: Employee Benefit Line Items - name: Employee Benefit Types - name: Employer Benefits - name: Employer Benefit Line Items - name: Employer Benefit Types - name: Employer Statutory Withholding Line Items - name: Employer Statutory Withholding Types - name: Forms - name: Form Batches - name: Form Types - name: Holidays - name: Integrations - name: Journal Entries - name: Overtime Rates - name: Partners - name: Pay Rates - name: Pay Schedules - name: Pay Splits - name: Pay Stubs - name: Payments - name: Payrolls - name: Reimbursements - name: Reimbursement Line Items - name: Reimbursement Types - name: Remittance Accounts - name: Remittance Account Enrollments - name: Reports - name: Statutory Withholding Line Items - name: Statutory Withholding Types - name: Tags - name: Tag Groups - name: Tax Properties - name: Tax Property Templates - name: Tokens - name: Usage Records - name: Usage Summaries - name: Vacation Pay - name: Vacation Pay Settings - name: Webhooks - name: Work Assignments paths: /business_entities: post: tags: - Business Entities summary: Create a business entity operationId: business-entities-store requestBody: content: application/json: schema: allOf: - type: object properties: business_number: type: string description: >- The Canada Revenue Agency (CRA) Business Number (BN) for this business entity, used to identify the business for payroll tax remittances. name: type: string description: The business entity's operating or trade name. maxLength: 255 legal_name: type: string description: The business entity's registered legal name. maxLength: 255 legal_registration_number: type: string description: The provincial business registration number. maxLength: 255 address_line_1: type: string description: >- The first line of the business entity's mailing address. Canada Revenue Agency forms (T4, RL-1) truncate this to the length those forms allow. nullable: true address_line_2: type: string description: >- The second line of the business entity's mailing address. Canada Revenue Agency forms (T4, RL-1) truncate this to the length those forms allow. nullable: true city: type: string description: The city of the business entity's mailing address. nullable: true administrative_area: type: string description: >- The region of the business entity's mailing address — the province, state, or county, depending on the country. For Canadian business entities this is the province. For a Canadian business entity, provide the province (e.g. ON). nullable: true maxLength: 255 province_code: type: string description: >- 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` nullable: true deprecated: true country_code: type: string description: >- 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: type: string description: >- The postal code for the business entity's mailing address. nullable: true maxLength: 10 contact_name: type: string description: The name of the primary contact at the business entity. maxLength: 255 contact_email: type: string description: >- The email address of the primary contact at the business entity. contact_area_code: type: string description: The area code for the primary contact's phone number. nullable: true contact_phone_number: type: string description: The primary contact's phone number, excluding area code. nullable: true contact_extension: type: string description: The extension for the primary contact's phone number. maxLength: 5 pay_day_movement_setting: type: string description: >- 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. enum: - inherit - next_business_day - previous_business_day vacation_pay_formula_setting: type: string description: >- The formula used to calculate vacation pay for Employees in this business entity. enum: - pay_date - period_end - period_start remitter_type: type: string description: >- The Canada Revenue Agency (CRA) remitter type, which determines the frequency of payroll tax remittances to the CRA. enum: - accelerated_threshold_1 - accelerated_threshold_2 - quarterly - regular in_preview: type: boolean description: >- 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: type: string maxLength: 255 preferred_locale: type: string description: >- The locale used for payroll communications sent to Employees and Contractors within this business entity. If not set, the Company's locale is used. enum: - en - fr hold_funding_for_verification: type: boolean resolve_journal_entry_stat_withholdings: type: boolean accounting_settings: type: object properties: resolve_journal_entry_stat_withholdings: type: boolean block_approval_on_incomplete_journal_entries: type: boolean block_approval_on_missing_export_identifiers: type: boolean tax_properties: type: array items: type: object properties: type: type: string enum: - 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::income_tax_rate - >- 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::provincial::income_tax_rate - ca::qc::additional_tax - ca::qc::claim_amount - ca::qc::commission_percentage_taxed - ca::qc::eht - ca::qc::income_tax_rate - 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 value: type: string effective_from: type: string format: date effective_to: type: string format: date note: type: string nullable: true owner_id: type: string - type: object required: - name example: business_number: 136549169RP9916 name: Bobs Burgers (#39616) address_line_1: 13 Fake Street city: Toronto administrative_area: '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: 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 responses: '201': description: Created content: application/json: schema: type: object properties: id: type: string description: The unique identifier of the object in Nmbr. readOnly: true object: type: string description: The type of the object in Nmbr (`"business_entity"`). readOnly: true data: $ref: '#/components/schemas/BusinessEntity' example: 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 administrative_area: 'ON' 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: object: company links: self: /companies/ 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: 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: 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/ components: schemas: BusinessEntity: type: object title: Business Entity properties: business_number: type: string description: >- The Canada Revenue Agency (CRA) Business Number (BN) for this business entity, used to identify the business for payroll tax remittances. nullable: true maxLength: 255 name: type: string description: The business entity's operating or trade name. maxLength: 255 legal_name: type: string description: The business entity's registered legal name. nullable: true maxLength: 255 legal_registration_number: type: string description: The provincial business registration number. nullable: true maxLength: 255 address_line_1: type: string description: >- The first line of the business entity's mailing address. Canada Revenue Agency forms (T4, RL-1) truncate this to the length those forms allow. nullable: true maxLength: 255 address_line_2: type: string description: >- The second line of the business entity's mailing address. Canada Revenue Agency forms (T4, RL-1) truncate this to the length those forms allow. nullable: true maxLength: 255 city: type: string description: The city of the business entity's mailing address. nullable: true maxLength: 255 in_preview: type: boolean description: >- When `true`, the business entity is in preview mode. In preview mode, Payrolls can be run and approved but no real money movement occurs. administrative_area: type: string description: >- The region of the business entity's mailing address — the province, state, or county, depending on the country. For Canadian business entities this is the province. nullable: true maxLength: 255 province_code: type: string description: >- This attribute is deprecated and will be removed. A deprecated alias of `administrative_area` that mirrors its value. Use `administrative_area` instead. nullable: true deprecated: true country_code: type: string description: The country code for the business entity's mailing address. nullable: true maxLength: 2 postal_code: type: string description: The postal code for the business entity's mailing address. nullable: true maxLength: 255 contact_name: type: string description: The name of the primary contact at the business entity. nullable: true maxLength: 255 contact_email: type: string description: The email address of the primary contact at the business entity. nullable: true maxLength: 255 contact_area_code: type: string description: The area code for the primary contact's phone number. nullable: true maxLength: 255 contact_phone_number: type: string description: The primary contact's phone number, excluding area code. nullable: true maxLength: 255 contact_extension: type: string description: The extension for the primary contact's phone number. nullable: true maxLength: 255 pay_day_movement_setting: type: string description: >- 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. enum: - inherit - next_business_day - previous_business_day vacation_pay_formula_setting: type: string description: >- The formula used to calculate vacation pay for Employees in this business entity. enum: - pay_date - period_end - period_start remitter_type: type: string description: >- The Canada Revenue Agency (CRA) remitter type, which determines the frequency of payroll tax remittances to the CRA. nullable: true enum: - accelerated_threshold_1 - accelerated_threshold_2 - quarterly - regular status: type: string description: >- The business entity's current status. A business entity must reach `approved` status before live Payrolls can be processed. enum: - approved - onboarding - suspended company: type: object properties: id: type: string description: The unique identifier of the object in Nmbr. readOnly: true object: type: string description: The type of the object in Nmbr (`"company"`). readOnly: true warnings: type: object description: >- A collection of data validation warnings for this business entity. Warnings indicate incomplete or potentially incorrect data and could prevent payroll processing. nullable: true properties: object: type: string nullable: true data: type: array nullable: true items: type: object properties: object: type: string nullable: true data: type: object nullable: true properties: namespace: type: string nullable: true type: type: string nullable: true external_ref: type: string description: >- 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. nullable: true maxLength: 255 available_tax_properties: type: array description: >- A list of Tax Property template identifiers supported for this business entity, based on its jurisdiction. nullable: true items: type: string effective_processing_speed: type: string description: >- The resolved processing speed after applying inheritance from the Partner if `processing_speed` is `inherit`. nullable: true processing_speed: type: string description: >- The business entity-level processing speed setting. If set to `inherit`, the Partner's processing speed is used. enum: - five_day - four_day - inherit - one_day - three_day - two_day has_bank_accounts: type: boolean description: Whether this business entity has any Bank Accounts configured. has_pay_schedules: type: boolean description: Whether this business entity has any Pay Schedules configured. has_payrolls: type: boolean description: Whether this business entity has any Payrolls. current_tax_jurisdiction: type: string description: >- The current tax jurisdiction for the business entity, derived from its `ca::province_of_employment` Tax Property. nullable: true ca_settings: type: object description: >- Canada-specific settings for this business entity. Only present for business entities with a Canadian address. nullable: true properties: roe_submission_setting: type: string description: >- Indicates whether Record of Employment (ROE) submissions are managed by Nmbr (`managed`) or by the employer directly (`manual`). nullable: true accounting_settings: type: object description: >- 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. nullable: true properties: default_bank_accounting_code: description: >- The Accounting Code used as the default bank account row when generating journal entries. default_payroll_payable_accounting_code: description: >- The Accounting Code used as the default payroll payable row when generating journal entries. resolve_journal_entry_stat_withholdings: type: boolean description: >- 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. primary_tag_group: description: >- The Tag Group that drives default accounting-code resolution for line items. Setting this also flags the group as a journal entry dimension. block_approval_on_incomplete_journal_entries: type: boolean description: >- When `true`, payroll approval is blocked if any exportable journal entry row has no Accounting Code. block_approval_on_missing_export_identifiers: type: boolean description: >- 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. default_bank_accounting_code: description: |- This attribute is deprecated and will be removed. Use `accounting_settings.default_bank_accounting_code`. deprecated: true default_payroll_payable_accounting_code: description: |- This attribute is deprecated and will be removed. Use `accounting_settings.default_payroll_payable_accounting_code`. deprecated: true preferred_locale: type: string description: >- The locale used for payroll communications sent to Employees and Contractors within this business entity. If not set, the Company's locale is used. nullable: true enum: - en - fr hold_funding_for_verification: type: boolean description: >- 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. resolve_journal_entry_stat_withholdings: type: boolean description: |- This attribute is deprecated and will be removed. Use `accounting_settings.resolve_journal_entry_stat_withholdings`. deprecated: true primary_tag_group: description: |- This attribute is deprecated and will be removed. Use `accounting_settings.primary_tag_group`. deprecated: true created_at: type: string description: The date and time the object was created in Nmbr. readOnly: true format: dateTime updated_at: type: string description: The date and time the object was last updated in Nmbr. readOnly: true format: dateTime securitySchemes: CompanyToken: type: http scheme: bearer ````