> ## 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 custom account

> Creates a custom account for a business. Custom accounts offer platforms direct control over bank account data and should be used for accounts operated directly by the platform.

## Rate Limiting

This endpoint has a custom rate limit policy.

**Rate Limit Details:**

| Environment | Limit       | Refill Period | Initial Size |
| ----------- | ----------- | ------------- | ------------ |
| Sandbox     | 5 requests  | 1 second      | 10 requests  |
| Production  | 20 requests | 1 second      | 40 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/{businessId}/custom-accounts/
openapi: 3.0.1
info:
  title: API
  version: latest
servers: []
security:
  - BearerAuth: []
tags: []
externalDocs:
  url: /
paths:
  /v1/businesses/{businessId}/custom-accounts/:
    post:
      tags: []
      summary: Create custom account
      description: >-
        Creates a custom account for a business. Custom accounts offer platforms
        direct control over bank account data and should be used for accounts
        operated directly by the platform.
      operationId: business.custom-accounts.post
      parameters:
        - name: businessId
          in: path
          description: The UUID of the business to create custom account for.
          required: true
          schema:
            type: string
        - 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/NewCustomAccountParams'
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiCustomAccount'
        '404':
          description: >-
            Business id is not found. This indicates the business id is invalid
            or the business has been archived.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Custom account already exists for the business.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: >-
            Account creation failure, which should only occur if bank account
            support is not enabled for your platform. Reach out to Layer support
            for assistance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      deprecated: false
components:
  schemas:
    NewCustomAccountParams:
      type: object
      properties:
        external_id:
          type: string
          description: >-
            Unique ID of the custom account in an external system for linking
            and idempotency.
          example: ww9wwLgkrbU3jkg3J4J7ckBR3zKQV6sLPQevK
        mask:
          type: string
          description: Last 4 digits of the custom account number.
          example: '4321'
        account_name:
          type: string
          description: Name of the custom account.
          example: My custom account
        institution_name:
          type: string
          description: Name of the institution for the custom account.
          example: My custom account institution
        account_type:
          type: string
          enum:
            - DEPOSITORY
            - CREDIT
            - LOAN
          nullable: true
          description: The type of the custom account.
          example: DEPOSITORY
        account_subtype:
          type: string
          enum:
            - CHECKING
            - SAVINGS
            - CREDIT CARD
            - LOAN
          nullable: true
          description: The subtype of the custom account.
          example: checking
    ApiCustomAccount:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique ID for the custom account.
        external_id:
          type: string
          description: >-
            Unique ID of the custom account in an external system for linking
            and idempotency.
          example: ww9wwLgkrbU3jkg3J4J7ckBR3zKQV6sLPQevK
        mask:
          type: string
          nullable: true
          description: Last 4 digits of the custom account number.
          example: '4321'
        account_name:
          type: string
          description: Name of the account.
          example: My custom account
        institution_name:
          type: string
          description: Name of the institution for the custom account.
          example: My custom account institution
        account_type:
          type: string
          enum:
            - DEPOSITORY
            - CREDIT
            - LOAN
          nullable: true
          description: The type of the custom account.
          example: DEPOSITORY
        account_subtype:
          type: string
          enum:
            - CHECKING
            - SAVINGS
            - CREDIT CARD
            - LOAN
          nullable: true
          description: The subtype of the custom account.
          example: checking
        created_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of when the custom account was created.
        updated_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of when the custom account was last created.
        archived_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of when the custom account was archived.
        ledger_account_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            The ID of the [ledger
            account](https://docs.layerfi.com/api-reference/ledger/chart#ledger-account-object)
            associated with the custom account.
    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
    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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````