---
title: "Create a business"
method: POST
path: "/v1/businesses"
tags: ["Businesses"]
---

# Create a business

`POST /v1/businesses`

## Request

- Base URL: `https://api.slant.app`
- URL: `https://api.slant.app/v1/businesses`
- Auth: HTTP bearer

Create a new business

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `book_id` string, required: The book ID
  - `name` string, required: Business name
  - `industry` string: Industry
  - `website_url` string: Website URL
  - `tax_id` string: Tax ID
  - `additional_info` string: Additional information
  - `custom_fields` object: Custom field values keyed by Business field_key. Null, blank strings, and empty arrays clear individual values.
  - `email_addresses` object[]: Array of email addresses
    - `email` string, email
    - `email_type` 'personal' | 'business' | 'school' | 'other' | 'inactive'
    - `is_primary` boolean
  - `phone_numbers` object[]: Array of phone numbers
    - `phone_number` string
    - `phone_type` 'mobile' | 'work' | 'home' | 'fax' | 'other'
    - `is_primary` boolean
    - `extension` string
  - `addresses` object[]: Array of addresses
    - `line1` string, required
    - `line2` string
    - `city` string
    - `state` string
    - `zip` string
    - `country_code` string
    - `address_type` 'home' | 'work' | 'mailing' | 'other'
    - `is_primary` boolean
  - `tag_ids` string[]: Array of tag IDs to associate

## Response `201`

business created

- Business
  - `custom_fields` object: Business custom field values keyed by field_key
  - `id` string, required: The business ID
  - `book_id` string, required: The book ID
  - `name` string, required: Business name
  - `industry` string, nullable: Industry
  - `website_url` string, nullable: Website URL
  - `tax_id` string, nullable: Tax ID
  - `additional_info` string, nullable: Additional information
  - `created_at` string, date-time, required: When the business was created
  - `updated_at` string, date-time, required: When the business was last updated
  - `email_addresses` Email[]: Array of email addresses
    - `email` string, email, required
    - `email_type` 'personal' | 'business' | 'school' | 'other' | 'inactive', required
    - `is_primary` boolean, required
    - `id` string: The email address ID
  - `phone_numbers` PhoneNumber[]: Array of phone numbers
    - `phone_number` string, required
    - `extension` string, nullable
    - `phone_type` 'mobile' | 'work' | 'home' | 'fax' | 'other', required
    - `is_primary` boolean, required
    - `id` string: The phone number ID
  - `addresses` Address[]: Array of addresses
    - `line1` string, nullable
    - `line2` string, nullable
    - `city` string, nullable
    - `state` string, nullable
    - `zip` string, nullable
    - `country_code` string, nullable
    - `address_type` 'home' | 'work' | 'mailing' | 'other', required
    - `is_primary` boolean, required
    - `id` string: The address ID
  - `tags` object[]: Array of tags
    - `id` string
    - `name` string

## Other responses

- `400`: Bad Request - malformed JSON, invalid filters, or missing required book context
- `401`: unauthorized - missing or invalid token
- `403`: Access denied. Policy and membership failures may have an empty body. A read-only personal token cannot perform writes.
- `422`: unprocessable entity - invalid payload
- `429`: An hourly API rate limit was exceeded. Wait Retry-After seconds before retrying.

## Changes

- **2026-11-03** `173c41bf6be9`: 1 breaking, 1 warning, 11 info
  - the request property `addresses/items/line1` became required
  - added the new `inactive` enum value to the `email_addresses/items/email_type` response property for the response status `201`
  - added the new optional request property `custom_fields`
  - added the new optional request property `phone_numbers/items/extension`
  - …9 more

[Operation history](https://skmtc.dev/slant/apis/slant-public-api-v1/changes/v1/businesses/post.md)

---

[API](https://skmtc.dev/slant/apis/slant-public-api-v1.md) - [All operations](https://skmtc.dev/slant/apis/slant-public-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/slant/apis/slant-public-api-v1/revisions/173c41bf6be9?raw)