> ## Documentation Index
> Fetch the complete documentation index at: https://docs.teal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an Instance

> Creates a new Instance based on the given parameters.



## OpenAPI

````yaml POST /v0/instance
openapi: 3.1.0
info:
  title: Teal API
  version: '0.1'
servers:
  - url: https://api.sandbox.teal.dev
    description: Sandbox
  - url: https://api.teal.dev
    description: Production
security: []
paths:
  /v0/instance:
    post:
      tags:
        - Instances
      summary: Create an Instance
      description: Creates a new Instance based on the given parameters.
      operationId: create_instance_v0_instance_post
      parameters:
        - name: x-teal-agent-id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: 'null'
            description: The agent id
            title: X-Teal-Agent-Id
          description: The agent id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstanceCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TealErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TealErrorResponse'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TealErrorResponse'
          description: Unprocessable Content
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TealErrorResponse'
          description: Service Unavailable
      security:
        - OAuth2PasswordBearer: []
components:
  schemas:
    InstanceCreate:
      properties:
        coa_template_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Coa Template Id
          description: |-
            The ID of the Chart of Accounts Template used 
                    to pre-populate the Instance's ledgers.
          examples:
            - CNmWM3X6AcvRdEwZKxq4bL
        custom_coa:
          anyOf:
            - $ref: '#/components/schemas/InstanceCreateCustomCoa'
            - type: 'null'
          description: A custom COA definition to be used for the created instance.
        entries_start:
          type: string
          format: date-time
          title: Entries Start
          description: |-
            The datetime in UTC time from which the API will 
                    sync an Instance's accounting data. Transactions or journal entries cannot 
                    be entered before this date.
          examples:
            - '2024-01-01T00:00:00Z'
        name:
          type: string
          title: Name
          description: The name of the business.
          examples:
            - ACME Goods Inc
        subscription:
          $ref: '#/components/schemas/SubscriptionLevel'
          description: The Instance's subscription tier.
          default: tier0
          examples:
            - tier3
        accounting_basis:
          anyOf:
            - $ref: '#/components/schemas/AccountingBasis'
            - type: 'null'
          description: 'The accounting method used: cash basis or accrual basis.'
          examples:
            - accrual
      type: object
      required:
        - entries_start
        - name
      title: InstanceCreate
    Instance:
      properties:
        id:
          type: string
          title: Id
          description: The unique ID of the object.
          examples:
            - RKtPbubK5NcbBsUmU1ktSP
        entries_start:
          type: string
          format: date-time
          title: Entries Start
          description: |-
            The datetime in UTC time from which the API will 
                    sync an Instance's accounting data. Transactions or journal entries cannot 
                    be entered before this date.
          examples:
            - '2024-01-01T00:00:00Z'
        name:
          type: string
          title: Name
          description: The name of the business.
          examples:
            - ACME Goods Inc
        subscription:
          $ref: '#/components/schemas/SubscriptionLevel'
          description: The Instance's subscription tier.
          examples:
            - tier3
        accounting_package:
          $ref: '#/components/schemas/AccountingPackage'
          description: |-
            The type of accounting package the Instance
                    uses as the source of truth for their books.
          examples:
            - platformgl
        accounting_basis:
          anyOf:
            - $ref: '#/components/schemas/AccountingBasis'
            - type: 'null'
          description: 'The accounting method used: cash basis or accrual basis.'
          examples:
            - accrual
      type: object
      required:
        - id
        - entries_start
        - name
        - subscription
        - accounting_package
      title: Instance
    TealErrorResponse:
      properties:
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: A description of the error for API developers.
        data:
          title: Data
          description: Data associated with the error.
        display_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Display Message
          description: A description of the error for end users.
        error_code:
          anyOf:
            - $ref: '#/components/schemas/TealErrorCode'
            - type: 'null'
          description: Error code associated with the error.
      type: object
      required:
        - message
      title: TealErrorResponse
    InstanceCreateCustomCoa:
      properties:
        ledgers:
          items:
            $ref: '#/components/schemas/CustomCoaLedger'
          type: array
          title: Ledgers
        required_ledgers:
          $ref: '#/components/schemas/CustomRequiredLedgers'
          default:
            uncategorized_inflow:
              name: Uncategorized Cash Inflow
              sort_code: '0'
            uncategorized_outflow:
              name: Uncategorized Cash Outflow
              sort_code: '1'
            transfers_between_accounts:
              name: Transfers Between Accounts
              sort_code: '2'
            opening_balances:
              name: Opening Balance Retained Earnings
              sort_code: '3'
            accounts_receivable:
              name: Accounts Receivable
              sort_code: '4'
            accounts_payable:
              name: Accounts Payable
              sort_code: '6'
      type: object
      required:
        - ledgers
      title: InstanceCreateCustomCoa
    SubscriptionLevel:
      type: string
      enum:
        - tier0
        - tier1
        - tier2
        - tier3
        - tier4
      title: SubscriptionLevel
    AccountingBasis:
      type: string
      enum:
        - cash
        - accrual
      title: AccountingBasis
    AccountingPackage:
      type: string
      enum:
        - platformgl
      title: AccountingPackage
    TealErrorCode:
      type: string
      enum:
        - invalid_date
        - invalid_ledger
        - missing_parameters
        - duplicate_name
        - duplicate_sort_code
        - invalid_ledger_type
        - invalid_ledger_report_cash_flow
        - deleting_required_ledger
        - repeated_tag_group
        - deleting_transaction_line
        - modifying_read_only_ledger
        - debits_credits_not_equal
        - modifying_datetime_opening_balance
        - modifying_accrual_journal_entry
        - modifying_payment_application_journal_entry
        - reconciliation_in_progress
        - reconciled_balance_does_not_match
        - journal_entry_outside_reconciliation_period
        - entries_start_date_after_transactions
        - entries_start_date_after_reconciliations
        - entries_start_date_after_journal_entries
      title: TealErrorCode
    CustomCoaLedger:
      properties:
        name:
          type: string
          maxLength: 255
          title: Name
          description: >-
            The name of the ledger.


            Teal does not enforce any other conventions or patterns on naming
            schemes; however, we recommend you use concise, descriptive names,
            especially for financial account ledgers.
          examples:
            - Pluto Checking 4242
        sort_code:
          type: string
          maxLength: 20
          pattern: ^[0-9]+$
          title: Sort Code
          description: >-
            Determines the display order in reports, ordered digit by digit,
            starting from the leftmost position. For example, `20010` will come
            before `3050`.


            Teal does not enforce any other conventions or patterns on sort
            codes. However, it is recommended to adopt a common convention such
            as starting all ledgers of the same type with the same number
            (assets start with 1, liabilities start with 2, etc.). The default
            CoA templates provided by Teal follow best practices for sort code
            numbering.


            Required if `financial_account_type` is not specified.
          examples:
            - '1400'
        sub_type:
          $ref: '#/components/schemas/LedgerSubType'
          description: >-
            Indicates similar characteristics and accounting treatment for a
            group of ledgers within a `type`.


            Required if `financial_account_type` is not specified.
          examples:
            - current_assets
        type:
          $ref: '#/components/schemas/LedgerType'
          description: >-
            Indicates the purpose and location of the funds and value recorded
            in the ledger and which report it is included in: `asset`,
            `liability` and `equity` ledgers are displayed on the balance sheet;
            `revenue` and `expenses` are displayed on the income statement.


            Required if `financial_account_type` is not specified.
          examples:
            - asset
        children:
          anyOf:
            - items:
                $ref: '#/components/schemas/CustomCoaLedger'
              type: array
            - type: 'null'
          title: Children
          description: The child ledgers
      type: object
      required:
        - name
        - sort_code
        - sub_type
        - type
      title: CustomCoaLedger
    CustomRequiredLedgers:
      properties:
        uncategorized_inflow:
          $ref: '#/components/schemas/CustomRequiredLedger'
          description: The ledger to be used for uncategorized income
          default:
            sort_code: '0'
            name: Uncategorized Cash Inflow
          examples:
            - name: Uncategorized Cash Inflow
              sort_code: '0'
        uncategorized_outflow:
          $ref: '#/components/schemas/CustomRequiredLedger'
          description: The ledger to be used for uncategorized outflow
          default:
            sort_code: '1'
            name: Uncategorized Cash Outflow
          examples:
            - name: Uncategorized Cash Outflow
              sort_code: '1'
        transfers_between_accounts:
          $ref: '#/components/schemas/CustomRequiredLedger'
          description: The ledger to be used for transfers between accounts
          default:
            sort_code: '2'
            name: Transfers Between Accounts
          examples:
            - name: Transfers Between Accounts
              sort_code: '2'
        opening_balances:
          $ref: '#/components/schemas/CustomRequiredLedger'
          description: The ledger to be used for opening balance retained earnings
          default:
            sort_code: '3'
            name: Opening Balance Retained Earnings
          examples:
            - name: Opening Balance Retained Earnings
              sort_code: '3'
        accounts_receivable:
          $ref: '#/components/schemas/CustomRequiredLedger'
          description: The ledger to be used for accounts receivable
          default:
            sort_code: '4'
            name: Accounts Receivable
          examples:
            - name: Accounts Receivable
              sort_code: '4'
        accounts_payable:
          $ref: '#/components/schemas/CustomRequiredLedger'
          description: The ledger to be used for accounts payable
          default:
            sort_code: '6'
            name: Accounts Payable
          examples:
            - name: Accounts Payable
              sort_code: '6'
      type: object
      title: CustomRequiredLedgers
    LedgerSubType:
      type: string
      enum:
        - current_assets
        - non-current_assets
        - transfers_between_accounts
        - uncategorized_assets
        - current_liabilities
        - non-current_liabilities
        - equity
        - operating_revenues
        - other_income
        - cost_of_goods_sold
        - operating_expenses
        - other_expenses
        - retained_earnings
      title: LedgerSubType
    LedgerType:
      type: string
      enum:
        - asset
        - liability
        - equity
        - revenue
        - expense
      title: LedgerType
    CustomRequiredLedger:
      properties:
        sort_code:
          type: string
          maxLength: 20
          pattern: ^[0-9]+$
          title: Sort Code
          description: >-
            Determines the display order in reports, ordered digit by digit,
            starting from the leftmost position. For example, `20010` will come
            before `3050`.


            Teal does not enforce any other conventions or patterns on sort
            codes. However, it is recommended to adopt a common convention such
            as starting all ledgers of the same type with the same number
            (assets start with 1, liabilities start with 2, etc.). The default
            CoA templates provided by Teal follow best practices for sort code
            numbering.


            Required if `financial_account_type` is not specified.
          examples:
            - '1400'
        name:
          type: string
          maxLength: 255
          title: Name
          description: >-
            The name of the ledger.


            Teal does not enforce any other conventions or patterns on naming
            schemes; however, we recommend you use concise, descriptive names,
            especially for financial account ledgers.
          examples:
            - Pluto Checking 4242
      type: object
      required:
        - sort_code
        - name
      title: CustomRequiredLedger
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      description: >-
        Bearer authentication header of the form Bearer <token>, where <token>
        is your auth token.
      flows:
        password:
          scopes: {}
          tokenUrl: https://developer.teal.dev

````