Create business

POST/api/v1/businesses

Create a new business entity with optional integrations.

Operation ID: create_business·View as markdown·OpenAPI slice

Authentication

Bearer token authentication. Pass your DayZero API token in the Authorization header and the target business UUID in x-business-id.

Request body

Schema: BusinessCreateRequest

accounting_basisstring: Default accounting basis financial reports open on: 'accrual' or 'cash'. Omit for accrual.
namestringrequired: Business display name.
default_currencystring: Default currency for the business (USD, CAD, AUD, EUR, or GBP).
tax_year_end_monthinteger: Month when the tax/fiscal year ends (1-12). Default 12 = calendar year.
mailboxstring: Unique email prefix for bill forwarding. Auto-generated from the business name when omitted.
user_idstring: UUID of the user who will own this business. Optional for admin-created businesses.
coa_template_idstring: Pre-built chart of accounts template ID. Mutually exclusive with custom_coa_template.
custom_coa_templateCustomCoaTemplate: Custom chart of accounts definition. Mutually exclusive with coa_template_id.
entries_startstring: Date from which to start importing transactions (YYYY-MM-DD).
firm_idstring: Advisory firm UUID to link this business to.
stripe_account_idstring: Stripe Connect account ID.
stripe_subscription_idstring: Stripe subscription ID for billing.
stripe_customer_idstring: Stripe customer ID (e.g., cus_xxx).
subscription_itemsobject: Stripe subscription items/products linked to this business.
accounting_engine_typestring: Accounting engine: 'local' (DayZero, default), or null (inherit from firm).
trial_ends_atstring · date-time: UTC expiry of the free trial. Omit for the standard 30-day trial.
billing_statusstring: Initial billing state (trialing, active, ...). Omit for trialing.
plan_tierstring: Plan tier (free, self_directed, managed, firm_client, grandfathered).
active_addonsarray · string: Paid add-on slugs to enable from day one.

Responses

201Successful Response

Schema: SuccessEnvelope_BusinessResponse_

successboolean
messagestring
codestring
dataBusinessResponse

400Bad Request - Invalid input

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

401Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

403Forbidden - Insufficient permissions

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

409Conflict - Resource already exists or is in an incompatible state

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

422Validation Error

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

Code samples

POST/api/v1/businesses

bash

curl -X POST 'https://api.ondayzero.com/api/v1/businesses' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "coa_template_id": "standard_accrual",
  "entries_start": "2024-01-01",
  "mailbox": "acme",
  "name": "Acme Corporation",
  "user_id": "019ab37c-05e7-7000-8000-000000000001"
}'