> ## Documentation Index > Fetch the complete documentation index at: https://docs.layerfi.com/llms.txt > Use this file to discover all available pages before exploring further. # Create business > Creates a new business in Layer. This endpoint is idempotent using the `external_id` field as the idempotency key, so subsequent requests with the same `external_id` will update or no-op. ## Response Status Codes * **201 Created** - A new business was successfully created * **200 OK** - An existing business was found and returned: * Archived business with matching phone number was unarchived * Non-archived business with matching external ID was found * **400 Bad Request** - Phone number matches an existing non-archived business with a different external ID The response includes `previously_imported: true` when an existing business is returned. ## Rate Limiting This endpoint has a custom rate limit policy. **Rate Limit Details:** | Environment | Limit | Refill Period | Initial Size | | ----------- | ----------- | ------------- | ------------ | | Sandbox | 10 requests | 1 second | 10 requests | | Production | 10 requests | 1 second | 10 requests | **Response Headers:** All responses include the following rate limit headers: * **X-RateLimit-Limit**: The rate limit bucket capacity * **X-RateLimit-Remaining**: The number of tokens remaining in the bucket * **X-RateLimit-Reset**: UTC timestamp (in seconds) when the bucket will be refilled For more details on rate limiting, see [Rate Limiting](/api-details/rate-limiting). ## OpenAPI ````yaml post /v1/businesses openapi: 3.0.1 info: title: API version: latest servers: [] security: - BearerAuth: [] tags: [] externalDocs: url: / paths: /v1/businesses: post: tags: [] summary: Create business description: >- Creates a new business in Layer. This endpoint is idempotent using the `external_id` field as the idempotency key, so subsequent requests with the same `external_id` will update or no-op. operationId: businesses.post parameters: - name: Content-Type in: header description: Content-Type must be set to application/json. schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/NewBusinessParams' responses: '200': description: >- An existing business was found and returned. This occurs when an archived business with matching phone number was unarchived, or a non-archived business with matching external ID was found. The response includes `previously_imported: true` when an existing business is returned. headers: {} content: application/json: schema: $ref: '#/components/schemas/ApiBusiness' '201': description: A new business was successfully created. headers: {} content: application/json: schema: $ref: '#/components/schemas/ApiBusiness' '400': description: >- Invalid business creation parameters. Common scenarios include: (1) Phone number already registered with a different external ID, (2) Invalid or missing required fields, (3) Invalid JSON structure. content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: phone_number_conflict: summary: Phone number already registered value: errors: - type: BadRequest description: >- That phone number is already registered with Layer by another business. invalid_parameters: summary: Invalid or missing required fields value: errors: - type: InvalidParameters description: >- Invalid JSON: Field 'id' is required for type with serial name 'AccountId', but it was missing at path: $.line_items[0].account_identifier. general_bad_request: summary: General validation error value: errors: - type: BadRequest description: At least one field must be provided to update. deprecated: false components: schemas: NewBusinessParams: type: object properties: external_id: type: string description: >- Unique ID of the business in your system for linking purposes. **Idempotency key**. legal_name: type: string description: Legal name of the business as it has been registered. tin: type: string nullable: true description: Tax Identification Number for the business. us_state: $ref: '#/components/schemas/USState' description: The state this business is incorporated in. country: $ref: '#/components/schemas/Country' description: >- 2 letter ISO country code representing the country this business is incorporated in. Defaults to US. entity_type: $ref: '#/components/schemas/BusinessType' description: Entity type of the business. Used to determine tax filing status. phone_number: type: string description: Phone number used for SMS based categorization. sms_enabled: type: boolean description: Whether SMS is enabled for this business. sms_categorization_start_date: type: string format: date-time description: Date when SMS categorization starts for this business. activation_at: type: string format: date-time description: >- The activation timestamp represents the time at which Layer should begin displaying accounting data. Data before this time will not be displayed to users. This field is important for businesses migrating over from other accounting platforms. Defaults to Jan 1 of the current year. internal_bank_account_ids: type: array items: $ref: '#/components/schemas/NewBusinessUnitAccountId' description: >- List of internal bank account identifiers to associate with this business. unit_ids: type: array items: $ref: '#/components/schemas/NewBusinessUnitAccountId' description: List of unit account identifiers to associate with this business. plaid_items: type: array items: $ref: '#/components/schemas/CreatePlaidItem' description: Plaid items to link to this business. plaid_processor_tokens: type: array items: $ref: '#/components/schemas/CreatePlaidProcessorToken' description: Plaid processor tokens to link to this business. skip_onboarding: type: boolean description: Whether to skip the onboarding process for this business. industry: type: string description: Industry classification for the business. naics_code: type: string nullable: true description: 6-digit NAICS code used to identify the business's industry. stripe_connect_accounts: type: array items: $ref: '#/components/schemas/StripeConnectAccountInput' description: List of Stripe Connect accounts associated with this business. default_reporting_basis: type: string nullable: true enum: - CASH - ACCRUAL description: Default accounting basis for financial reports. free_trial_ends_at: type: string format: date-time nullable: true description: The date and time when the business's free trial ends. enable_bookkeeping: type: boolean default: false description: >- When true, enrolls the created business into bookkeeping, provided that the platform is configured for bookkeeping. ApiBusiness: type: object properties: id: type: string format: uuid description: Unique identifier for the business. type: type: string description: Resource type. Value will be “Business”. example: Business external_id: type: string description: >- Unique ID of the business in your system for linking purposes. **Idempotency key**. example: test-acme-id legal_name: type: string example: ACME LLC description: Legal name of the business as it has been registered. tin: type: string nullable: true description: Tax Identification Number for the business. us_state: $ref: '#/components/schemas/USState' description: The state this business is incorporated in. country: $ref: '#/components/schemas/Country' description: >- 2 letter ISO country code representing the country this business is incorporated in. Defaults to US. entity_type: $ref: '#/components/schemas/BusinessType' description: Entity type of the business. Used to determine tax filing status. industry: type: string description: Industry classification for the business. phone_number: type: string description: Phone number used for SMS based categorization. example: '+16504651359' naics_code: type: string nullable: true description: 6-digit NAICS code used to identify the business's industry. example: '484110' sms_enabled: type: boolean description: Whether SMS is enabled for this business. sms_stopped: type: boolean description: Whether this business has responded to Layer's SMS with "STOP". sms_categorization_start_date: type: string format: date-time description: Date when SMS categorization starts for this business. activation_at: type: string format: date-time description: >- The activation timestamp represents the time at which Layer should begin displaying accounting data. Data before this time will not be displayed to users. This field is important for businesses migrating over from other accounting platforms. Defaults to Jan 1 of the current year. imported_at: type: string format: date-time description: >- Time when the business entity was created in Layer. **Eligible sort key**. updated_at: type: string format: date-time nullable: true description: >- Time when the business's information was last updated in Layer. **Eligible sort key**. archived_at: type: string format: date-time nullable: true description: Time when the business was archived, if applicable. unit_accounts: type: array items: $ref: '#/components/schemas/APIUnitAccount' description: List of unit accounts associated with this business. plaid_items: type: array items: $ref: '#/components/schemas/ApiPlaidItem' description: Plaid items linked to this account. plaid_processor_tokens: type: array items: $ref: '#/components/schemas/ApiPlaidProcessorToken' description: Plaid processor tokens linked to this account. previously_imported: type: boolean nullable: true description: >- True if an archived business with the same phone number was unarchived during creation. stripe_connect_accounts: type: array items: type: object description: List of Stripe Connect accounts associated with this business. default_reporting_basis: type: string nullable: true enum: - CASH - ACCRUAL description: Default accounting basis for financial reports. free_trial_ends_at: type: string format: date-time nullable: true description: The date and time when the business's free trial ends. ApiError: type: object description: An error object returned in API error responses. properties: type: $ref: '#/components/schemas/ApiErrorType' description: >- A fixed category for the error, helpful for categorizing and processing errors. description: type: string description: A human-readable error description. error_enum: $ref: '#/components/schemas/ApiEnumErrorType' description: >- A stable, machine-readable identifier for programmatically handling specific error conditions. Only present for 4xx client errors—not included for 5xx server errors. Use this instead of parsing the description field, as enum values remain stable across API versions. nullable: true meta: type: object description: Optional additional information about the error. nullable: true required: - type - description USState: type: string enum: - AL - AK - AZ - AR - CA - CO - CT - DE - DC - FL - GA - HI - ID - IL - IN - IA - KS - KY - LA - ME - MD - MA - MI - MN - MS - MO - MT - NE - NV - NH - NJ - NM - NY - NC - ND - OH - OK - OR - PA - PR - RI - SC - SD - TN - TX - UT - VT - VI - VA - WA - WV - WI - WY description: Which United States state the business is incorporated in. Country: type: string enum: - AF - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BA - BW - BV - BR - IO - BN - BG - BF - BI - KH - CM - CA - CV - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - CI - HR - CU - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IL - IT - JM - JP - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MK - MG - MW - MY - MV - ML - MT - ME - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RS - RW - SH - KN - LC - PM - VC - WS - SM - ST - SA - SN - SC - SL - SG - SK - SI - SB - SO - ZA - GS - ES - LK - SD - SR - SJ - SZ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - US - UM - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW description: Which country the business is incorporated in. BusinessType: type: string enum: - SOLE_PROP - C_CORP - LLC - S_CORP - PARTNERSHIP - NON_PROFIT - TRUST description: Type of the business. NewBusinessUnitAccountId: type: object properties: unit_id: type: string account_name: type: string nullable: true description: Name of the Unit account. example: My Unit account opening_balance_init_to_zero: type: boolean opening_balance_do_not_init: type: boolean CreatePlaidItem: description: >- Parameters for specifying a Plaid item when creating or updating a business. Either provide `item_id` and `access_token` to create a new item, or provide `id` to reference an existing Plaid item by its Layer ID. Referencing by `id` is only supported when updating a business, not when creating one. oneOf: - title: New Plaid item type: object description: Create a new Plaid item from an item ID and access token. required: - item_id - access_token properties: item_id: type: string description: Plaid's unique identifier for the item. access_token: type: string description: Access token for the Plaid item. sync_transactions: type: boolean default: true description: Whether to sync transactions for this item. institution_plaid_id: type: string nullable: true description: Plaid's identifier for the institution. - title: Existing Plaid item by Layer ID type: object description: >- Reference an existing Plaid item by its Layer ID. Only valid when updating a business. required: - id properties: id: type: string format: uuid description: >- The Layer ID of an existing Plaid item (the `layer_item_id` from the response). CreatePlaidProcessorToken: description: >- Parameters for specifying a Plaid processor token when creating or updating a business. Either provide `processor_token` to create a new token, or provide `id` to reference an existing processor token by its Layer ID. Referencing by `id` is only supported when updating a business, not when creating one. oneOf: - title: New Plaid processor token type: object description: Create a new Plaid processor token. required: - processor_token properties: processor_token: type: string description: >- The processor_token returned by Plaid upon generation via the [/processor/token/create](https://plaid.com/docs/api/processors/#processortokencreate) endpoint. - title: Existing processor token by Layer ID type: object description: >- Reference an existing Plaid processor token by its Layer ID. Only valid when updating a business. required: - id properties: id: type: string format: uuid description: >- The Layer ID of an existing Plaid processor token (the `layer_processor_token_id` from the response). StripeConnectAccountInput: type: object properties: stripe_id: type: string APIUnitAccount: type: object properties: id: type: string description: The Unit account’s ID. example: '111111' importedAt: type: string format: date-time description: When the Unit account was imported. ApiPlaidItem: type: object properties: layer_item_id: type: string format: uuid description: >- Layer’s unique identifier for this Plaid item. Can be used to reference this item when updating a business. example: 550e8400-e29b-41d4-a716-446655440000 accessToken: type: string example: access-sandbox-a67d0be8-abcd-1234-5678-14fc7bc65366 institution: $ref: '#/components/schemas/ApiPlaidInstitution' itemId: type: string example: V3jvONy9xbroJVaRnm6oiAqVMv5Qz3TrNyLdL syncTransactions: type: boolean ApiPlaidProcessorToken: type: object properties: layer_processor_token_id: type: string format: uuid description: >- Layer’s unique identifier for this Plaid processor token. Can be used to reference this token when updating a business. example: 550e8400-e29b-41d4-a716-446655440000 processor_token: type: string example: processor-sandbox-d8e791d1-1234-9876-a207-69acca316045 ApiErrorType: type: string enum: - ResourceArchived - AuthFailure - Plaid - Stripe - InvalidState - ResourceNotFound - InvalidParameters - JsonSerialization - Unknown - BadRequest - PaginationCursor - Conflict - LedgerOperationFailed ApiEnumErrorType: type: string description: >- Stable enum values for programmatic error handling. Only present in 4xx error responses. enum: - AccessCodeInvalid - BalanceSheetDoesNotBalance - BalanceSheetMissingAccount - BankStatementParserError - BillStateError - BulkCategorizeFailure - BulkMatchFailure - BusinessTaskAlreadyCompleted - BusinessTaskDeleted - CalendlyOAuthError - CallBookingError - CantUpdateTransactionInCustomerPayout - CantUpdateTransactionInVendorPayout - CheckPayrollConfigNotFound - CheckPayrollServiceNotFound - ClerkUserAlreadyExists - ConflictingQueryParams - CustomAccountAlreadyExists - CustomTransactionCsvParsingError - CustomTransactionUploadFailure - CustomerPayoutInputFormatError - DoesNotMatchExistingEntity - EmptyBatchRequest - ExpenseParserError - ExternalAccountBalanceReconciliationError - ExternalIdConflict - InvalidCategory - InvalidEffectiveDate - InvalidLedgerOperation - InvalidMonthlyAverageRange - InvalidMultiPartRequest - InvalidPaginationCursor - InvalidPayload - InvoiceDeleted - InvoiceNotFound - InvoiceReferenceMismatch - InvoiceStateError - ManualRateLimit - MultipleTagKeyFiltersUnsupported - NoCognitoUserFound - NoOpeningBalanceFound - NotYetReconciled - OnePasswordApiError - OnePasswordItemNotFound - OnePasswordVaultNotFound - OpenAICategorizationError - PaymentLinkInvalid - PayrollStateError - PeriodIsClosed - PeriodNotClosed - PhoneNumberAlreadyRegistered - PlaidApiError - PlaidConnectionBroken - PlaidCreateLinkTokenError - PlaidCredentialsNotConfigured - PlaidExchangePublicTokenError - PlaidGetInstitutionByIdError - PlaidGetItemError - PlaidInvalidEnvironment - PlaidItemAlreadyExists - PlaidItemNotFound - PlaidProcessorApiError - PlaidUnlinkItemError - QueryParamFormat - QueryParamMissing - QuickbooksBrokenConnection - QuickbooksConnectionAlreadyExists - QuickbooksConnectionAlreadySyncing - QuickbooksConnectionMissing - QuickbooksConnectionNotActivated - QuickbooksInvalidRequest - QuickbooksInvalidState - QuickbooksNoMatchingAccount - QuickbooksNonPostingAccountType - QuickbooksNotConfigured - QuickbooksOAuthCallbackInvalid - QuickbooksOAuthError - QuickbooksTokenExpired - ResourceArchived - ScheduleCNotConfigured - SmsNotEnabled - SpecifiedBadRequest - SpecifiedIdNotFound - SplitTransactionError - StepEvaluationBadRequest - StripeConnectAccountIdNotFound - StripeCredentialsNotConfigured - StripeGetBalanceForConnectAccountFailure - StripeRedirectOrRefreshUrlNotConfigured - TagFilterNotFound - UnexpectedQueryParam - UnitAccountsInUse - WrongAnswerType ApiPlaidInstitution: type: object properties: id: type: string deprecated: true description: Deprecated. Use `layer_id` instead. example: 550e8400-e29b-41d4-a716-446655440000 layer_id: type: string format: uuid description: Layer’s unique identifier for this Plaid institution. example: 550e8400-e29b-41d4-a716-446655440000 plaid_institution_id: type: string description: The Plaid institution’s ID within Plaid. example: ins_1 name: type: string description: The Plaid institution’s name. example: Bank of America logo: type: string nullable: true description: The Plaid institution’s logo. example: >- iVBORw0KGgoAAAANSUhEUgAAAJgAAACYCAMAAAAvHNATAAAA6lBMVEUAAAD////////////////////////////////////////////////////////////////////////////////qUmn74ubnNVD4xc398fLlJkT1qLTf4+zpRFzrYHb509rvfY7xjJuAkLTzmqfxi5vzmai/x9lBWY7v8fXtb4LjGDftboIhPXwBIWkRL3P3t8D2t8HsYHbvfo7P1ePzmqigrMeQnr3oRF1RZphhdaGQnb0xS4Wfq8dgdKHuboL609lwgqtgdaFwgqqvutCfrMevudCQnr5BWY/pQ11RZpeQnb70qLRRZ5f98fO30r7oAAAAFHRSTlMA3yDvv0AQn2DPcFCAoJAwf4+vXxXsOc8AAAYDSURBVHhe7ZwHcus4EESZo5L9h1nROfvnvDmn+19nvevvoqimQAKgRFTtvguwa7pnIEIgNFmM0DtwLV/X6V903bLcQWCPtR4ZB65v0jZ8N7B7EGUHFmhCTCvYZ+kc+8Ck1uhuqO0FUNWM6e7cVGdikhC6Z+yyWK5J4ri7kmZbJIllKyILsbo21ABZShjqTKhDJo7WEaFOnaJ73ZTrkAAV/AxNAhQomnNAO+JAKmmGTjtDl7DzmUk7xBS2c0I7ZiIWL5d2jiuiy6c94BuqxB5bQBVdqEwVXahMFV2oTA1diN52EfBpz/jtlLm0d1zhea/AGuBRLzxrDL5JvWA2tKYDDalIax5QbxwoEjAkVGOyIqajxgRDDhUxEgmbOlKxzpxQ7wxqk08KYKiRfMRSpGCIDcIsIiVLZpMkWfEyn13eZ9Il67Rg6Sq6+kJ0+o1cybpM2PN5frVG8jKVKVm3LZku31W0XQprcztvybiIqnWL5ddyT6hIUXSabnbAfF1bVMSS418nXrLVY6zyFxsPz6p1E7DUlJgVacQqTFwk65Zyl80WjX4cXW0yO61qS6/XhXMOkJH2hMmf88cBAXWDsuWXRSYc/5BESK+TTW0v7quGz09SEsEGJ6W1JZcxyTPi6smLn89qtZWeNvVhlhYxT1+OW8k6uru9vfvzzZSAItrshJiQ7DTK/5Edt/cyoEam390+8Qtqo3jd0vwE0x6Xi3wraQH8sNgmq+T8jOp4Gl3RaVZTq2oOV3G7nxhms4koC3kePchKGbMYpbFDZgvKQtK0duFC8uWC2IybIrYu6+anqr93H6ZtFi5UBfqRgD3Fzm5KWXdHNbH7UDqLyXpXp+pF2nrv098q6/y25Oii4m9ZxjeEoIfYGWz8B2HbwlVpxSnErpT2QztZaCE7/ePmzN9UDPvx0d/S4ovtsmC6AenxtldyuzlcF+Avr6worVf18sHwpCCEwrqmnJ5vdfHb2wrvp+KystVTd/waE+BpA9C13cWPpb8w1kAWe1FPK298uEyNtCG6WPL9ulGvNlx8C8sSyMJH1q/76KdbrpTo1aczcBE14zhFWWg3klT9tDaEfYKKQCHBYngPwGyhLCSKq4NMpwqfz1uE/u4InyYpa3NF0PGVcvoVs1yl5pI0QWeYspqHnK4RMj16zyrXW3QRn8QpC9GITXO5XqM5y4xTFrcwbMbNci2iduEqEoYsAWGvNprxFVVZoTHHzC0FlCUk7CN7di1mOLkyAuI5pywUhh3Kml0rVi9iuDCILJredqe/QeqhGZnPSpPmcYrgHEM+30Dq65txtmBuDGF/sIX51MjRDaQ+wwc+ji5Uj+QFMYC1ksH09wv0p7lc6azWRch8vbAh8bPEdBGQLTnCBbjaiHjB3CQpM/TYts0M+Des0xybkV0udLGZQAtlbczv25YrWvBsKhpCNmJmsFy4VnEw5twZjq9hSLQs1zwjHvhPixVJQ5aXQqHHLQKYFxxFizL0esaxLrI3VQLi5fhLXx4zRj13uXAbakzcxEm9O9lcoly4O2wSPyfQjZB6KBcHpvi/zjEBK9FmRCz2djrvhEPyP0iIQPYAAdtGsJtnvAqFrKWNxySIrj0yIkmyOhuTheSxWHkvF3U2fp3JnyNz5Lx8ncuu2DgsuvAylbcRnezEyyKRtxHHfhd9GSdS3Yg9WTIgOU5gDZLA00qE44/7wrO40+OAQwLE7Fxm3Z7tt0mWv67hdVwMAw+2SQctv+/+LKBN8jyPSR5b3cOTWDJFTugqWTJX4SPNyIB6Z6D0sXkkpJ7xtC0cKpV85lquyueMoSJGIiPqjZHSn5ip/1Ee4ikSMGSgyMhHhrR3hkp87I/4GsBozf8/FNcN9T/5V/+SBPWvlUAMv5eP/RWZZ0NHE2HQ47xn4/V8PY76Fwohzoh2xMjR5PD0ndgYatIYO+jOQyiXEkXTQ60jnE4HxwDK1Z+f6t8LaNn/mQse0VC1bhI1RDvUhMh3jj00uVWNbG0vhEOdS5Wj7Y9xy6t9e7p3eOhv1+S7Qb9XNdvBwLWs8vpo33JHXig9Rv8G+MxS+LqktYUAAAAASUVORK5CYII= securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ````