openapi: 3.0.3
info:
  title: Codat API
  description: >-
    Codat's business data API standardizes small-business accounting, banking,
    and commerce data behind a single integration at api.codat.io, and can write
    bills, payments, and expenses back into connected platforms. This document
    consolidates representative endpoints from Codat's Platform, Accounting,
    Banking, Commerce, Lending, Bank Feeds, Sync for Payables, Sync for Expenses,
    and Sync for Commerce products. See docs.codat.io and github.com/codatio/oas
    for the authoritative per-product specifications.
  termsOfService: https://www.codat.io/legal/
  contact:
    name: Codat Support
    url: https://www.codat.io/contact/
  version: '3.0'
servers:
  - url: https://api.codat.io
    description: Codat production
security:
  - authHeader: []
tags:
  - name: Companies
    description: Create and manage the companies (customers) you pull data for.
  - name: Connections
    description: Manage a company's connections to accounting, banking, and commerce platforms.
  - name: Manage data
    description: Queue data refreshes and inspect pull history and status.
  - name: Webhooks
    description: Manage webhook consumers for event subscriptions.
  - name: Integrations
    description: Discover supported integrations and their branding.
  - name: Accounting
    description: Standardized accounting data types.
  - name: Banking
    description: Standardized banking data types.
  - name: Commerce
    description: Standardized commerce and point-of-sale data types.
  - name: Lending
    description: Assess reports and lending metrics.
  - name: Bank Feeds
    description: Push transactions into accounting platforms as a bank feed.
  - name: Payables
    description: Sync for Payables - write bills and payments.
  - name: Expenses
    description: Sync for Expenses - reconcile card and expense transactions.
  - name: Sync for Commerce
    description: Sync commerce sales into accounting software.
paths:
  /companies:
    get:
      operationId: listCompanies
      tags: [Companies]
      summary: List companies
      description: Returns a list of your companies with pagination, search, and ordering.
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/orderBy'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Companies'
    post:
      operationId: createCompany
      tags: [Companies]
      summary: Create company
      description: Creates a new company that represents one of your customers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyRequestBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
  /companies/{companyId}:
    parameters:
      - $ref: '#/components/parameters/companyId'
    get:
      operationId: getCompany
      tags: [Companies]
      summary: Get company
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
    patch:
      operationId: updateCompany
      tags: [Companies]
      summary: Update company
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyRequestBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
    delete:
      operationId: deleteCompany
      tags: [Companies]
      summary: Delete company
      description: Permanently deletes a company, its connections, and cached data.
      responses:
        '204':
          description: No Content
  /companies/{companyId}/connections:
    parameters:
      - $ref: '#/components/parameters/companyId'
    get:
      operationId: listConnections
      tags: [Connections]
      summary: List connections
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connections'
    post:
      operationId: createConnection
      tags: [Connections]
      summary: Create connection
      description: Creates a connection for the company by providing a platform key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                platformKey:
                  type: string
                  example: gbol
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
  /companies/{companyId}/connections/{connectionId}:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    get:
      operationId: getConnection
      tags: [Connections]
      summary: Get connection
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
    delete:
      operationId: deleteConnection
      tags: [Connections]
      summary: Delete connection
      responses:
        '204':
          description: No Content
    patch:
      operationId: unlinkConnection
      tags: [Connections]
      summary: Update connection
      description: Deauthorizes a connection without deleting it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum: [Unlinked]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
  /companies/{companyId}/data/all:
    parameters:
      - $ref: '#/components/parameters/companyId'
    post:
      operationId: refreshAllData
      tags: [Manage data]
      summary: Refresh all data
      description: Queues a refresh of all data types for a company.
      responses:
        '204':
          description: No Content
  /companies/{companyId}/data/queue/{dataType}:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - name: dataType
        in: path
        required: true
        schema:
          type: string
        example: invoices
    post:
      operationId: refreshDataType
      tags: [Manage data]
      summary: Refresh data type
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PullOperation'
  /companies/{companyId}/dataStatus:
    parameters:
      - $ref: '#/components/parameters/companyId'
    get:
      operationId: getDataStatus
      tags: [Manage data]
      summary: Get data status
      description: Returns the sync status for each data type of a company.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/DataStatus'
  /webhooks:
    get:
      operationId: listWebhookConsumers
      tags: [Webhooks]
      summary: List webhook consumers
      responses:
        '200':
          description: OK
    post:
      operationId: createWebhookConsumer
      tags: [Webhooks]
      summary: Create webhook consumer
      responses:
        '200':
          description: OK
  /integrations:
    get:
      operationId: listIntegrations
      tags: [Integrations]
      summary: List integrations
      description: Lists the integrations supported by your Codat instance.
      responses:
        '200':
          description: OK
  /integrations/{platformKey}:
    parameters:
      - name: platformKey
        in: path
        required: true
        schema:
          type: string
        example: gbol
    get:
      operationId: getIntegration
      tags: [Integrations]
      summary: Get integration
      responses:
        '200':
          description: OK

  /companies/{companyId}/data/accounts:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/pageSize'
    get:
      operationId: listAccounts
      tags: [Accounting]
      summary: List accounts
      description: Gets the latest chart of accounts for a company.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataList'
  /companies/{companyId}/data/accounts/{accountId}:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - name: accountId
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getAccount
      tags: [Accounting]
      summary: Get account
      responses:
        '200':
          description: OK
  /companies/{companyId}/connections/{connectionId}/data/invoices:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/pageSize'
    get:
      operationId: listInvoices
      tags: [Accounting]
      summary: List invoices
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataList'
  /companies/{companyId}/connections/{connectionId}/data/invoices/{invoiceId}:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
      - name: invoiceId
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getInvoice
      tags: [Accounting]
      summary: Get invoice
      responses:
        '200':
          description: OK
  /companies/{companyId}/connections/{connectionId}/data/bills:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/pageSize'
    get:
      operationId: listBills
      tags: [Accounting]
      summary: List bills
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataList'
  /companies/{companyId}/connections/{connectionId}/data/journalEntries:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    get:
      operationId: listJournalEntries
      tags: [Accounting]
      summary: List journal entries
      responses:
        '200':
          description: OK
  /companies/{companyId}/connections/{connectionId}/data/customers:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    get:
      operationId: listCustomers
      tags: [Accounting]
      summary: List customers
      responses:
        '200':
          description: OK
  /companies/{companyId}/connections/{connectionId}/data/suppliers:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    get:
      operationId: listSuppliers
      tags: [Accounting]
      summary: List suppliers
      responses:
        '200':
          description: OK
  /companies/{companyId}/connections/{connectionId}/data/financials/balanceSheet:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    get:
      operationId: getBalanceSheet
      tags: [Accounting]
      summary: Get balance sheet
      responses:
        '200':
          description: OK
  /companies/{companyId}/connections/{connectionId}/data/financials/profitAndLoss:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    get:
      operationId: getProfitAndLoss
      tags: [Accounting]
      summary: Get profit and loss
      responses:
        '200':
          description: OK
  /companies/{companyId}/connections/{connectionId}/data/financials/cashFlowStatement:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    get:
      operationId: getCashFlowStatement
      tags: [Accounting]
      summary: Get cash flow statement
      responses:
        '200':
          description: OK

  /companies/{companyId}/connections/{connectionId}/data/banking-accounts:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    get:
      operationId: listBankingAccounts
      tags: [Banking]
      summary: List banking accounts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataList'
  /companies/{companyId}/connections/{connectionId}/data/banking-transactions:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    get:
      operationId: listBankingTransactions
      tags: [Banking]
      summary: List banking transactions
      responses:
        '200':
          description: OK
  /companies/{companyId}/connections/{connectionId}/data/banking-transactionCategories:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    get:
      operationId: listBankingTransactionCategories
      tags: [Banking]
      summary: List banking transaction categories
      responses:
        '200':
          description: OK

  /companies/{companyId}/connections/{connectionId}/data/commerce-customers:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    get:
      operationId: listCommerceCustomers
      tags: [Commerce]
      summary: List commerce customers
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataList'
  /companies/{companyId}/connections/{connectionId}/data/commerce-orders:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    get:
      operationId: listCommerceOrders
      tags: [Commerce]
      summary: List commerce orders
      responses:
        '200':
          description: OK
  /companies/{companyId}/connections/{connectionId}/data/commerce-payments:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    get:
      operationId: listCommercePayments
      tags: [Commerce]
      summary: List commerce payments
      responses:
        '200':
          description: OK
  /companies/{companyId}/connections/{connectionId}/data/commerce-products:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    get:
      operationId: listCommerceProducts
      tags: [Commerce]
      summary: List commerce products
      responses:
        '200':
          description: OK

  /companies/{companyId}/reports/enhancedBalanceSheet/accounts:
    parameters:
      - $ref: '#/components/parameters/companyId'
    get:
      operationId: getEnhancedBalanceSheetAccounts
      tags: [Lending]
      summary: Get enhanced balance sheet accounts
      description: Assess-categorized balance sheet accounts for a company.
      responses:
        '200':
          description: OK
  /companies/{companyId}/reports/enhancedProfitAndLoss/accounts:
    parameters:
      - $ref: '#/components/parameters/companyId'
    get:
      operationId: getEnhancedProfitAndLossAccounts
      tags: [Lending]
      summary: Get enhanced profit and loss accounts
      responses:
        '200':
          description: OK
  /data/companies/{companyId}/assess/dataTypes/{dataType}/dataIntegrity/status:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - name: dataType
        in: path
        required: true
        schema:
          type: string
        example: banking-transactions
    get:
      operationId: getDataIntegrityStatus
      tags: [Lending]
      summary: Get data integrity status
      description: Returns the match status for a data type used in Assess data integrity.
      responses:
        '200':
          description: OK

  /companies/{companyId}/connections/{connectionId}/data/bankAccounts:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    get:
      operationId: listBankFeedBankAccounts
      tags: [Bank Feeds]
      summary: List bank feed bank accounts
      responses:
        '200':
          description: OK
    put:
      operationId: createBankFeedBankAccounts
      tags: [Bank Feeds]
      summary: Create bank feed bank accounts
      description: Maps source accounts to target bank accounts in the accounting platform.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: OK
  /companies/{companyId}/connections/{connectionId}/bankFeedAccounts:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    get:
      operationId: getBankFeedConfiguration
      tags: [Bank Feeds]
      summary: Get bank feed configuration
      responses:
        '200':
          description: OK

  /companies/{companyId}/connections/{connectionId}/payables/bills:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    get:
      operationId: listPayablesBills
      tags: [Payables]
      summary: List payable bills
      responses:
        '200':
          description: OK
    post:
      operationId: createPayableBill
      tags: [Payables]
      summary: Create bill
      description: Creates a bill in the accounting platform for the given company.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: OK
  /companies/{companyId}/connections/{connectionId}/payables/bills/{billId}/payment:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
      - name: billId
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: createBillPayment
      tags: [Payables]
      summary: Create bill payment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: OK
  /companies/{companyId}/connections/{connectionId}/payables/suppliers:
    parameters:
      - $ref: '#/components/parameters/companyId'
      - $ref: '#/components/parameters/connectionId'
    post:
      operationId: createPayableSupplier
      tags: [Payables]
      summary: Create supplier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: OK

  /companies/{companyId}/sync/expenses/expense-transactions:
    parameters:
      - $ref: '#/components/parameters/companyId'
    post:
      operationId: createExpenseTransactions
      tags: [Expenses]
      summary: Create expense transactions
      description: Creates an expense transaction to be reconciled into accounting software.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: OK
  /companies/{companyId}/sync/expenses/syncs/latest/status:
    parameters:
      - $ref: '#/components/parameters/companyId'
    get:
      operationId: getLatestExpenseSyncStatus
      tags: [Expenses]
      summary: Get latest sync status
      responses:
        '200':
          description: OK
  /companies/{companyId}/sync/expenses/mappingOptions:
    parameters:
      - $ref: '#/components/parameters/companyId'
    get:
      operationId: getExpenseMappingOptions
      tags: [Expenses]
      summary: Get mapping options
      description: Gets accounts, tracking categories, and tax rates for expense mapping.
      responses:
        '200':
          description: OK

  /companies/{companyId}/sync/commerce/latest:
    parameters:
      - $ref: '#/components/parameters/companyId'
    post:
      operationId: requestCommerceSync
      tags: [Sync for Commerce]
      summary: Sync latest commerce data
      description: Runs a commerce sync from the last successful sync to the specified date.
      responses:
        '200':
          description: OK
  /config/companies/{companyId}/sync/commerce:
    parameters:
      - $ref: '#/components/parameters/companyId'
    get:
      operationId: getCommerceConfig
      tags: [Sync for Commerce]
      summary: Get commerce sync configuration
      responses:
        '200':
          description: OK
    post:
      operationId: setCommerceConfig
      tags: [Sync for Commerce]
      summary: Set commerce sync configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: OK
  /meta/companies/{companyId}/sync/commerce/status:
    parameters:
      - $ref: '#/components/parameters/companyId'
    get:
      operationId: getCommerceSyncStatus
      tags: [Sync for Commerce]
      summary: Get commerce sync status
      responses:
        '200':
          description: OK
components:
  securitySchemes:
    authHeader:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Codat expects your API key Base64-encoded and sent in the Authorization
        header using the Basic scheme, for example:
        `Authorization: Basic YOUR_BASE64_ENCODED_API_KEY`.
  parameters:
    companyId:
      name: companyId
      in: path
      required: true
      description: Unique identifier for a company.
      schema:
        type: string
        format: uuid
    connectionId:
      name: connectionId
      in: path
      required: true
      description: Unique identifier for a connection.
      schema:
        type: string
        format: uuid
    page:
      name: page
      in: query
      description: Page number (1-indexed).
      schema:
        type: integer
        default: 1
    pageSize:
      name: pageSize
      in: query
      description: Number of records per page.
      schema:
        type: integer
        default: 100
    query:
      name: query
      in: query
      description: Codat query language expression to filter results.
      schema:
        type: string
    orderBy:
      name: orderBy
      in: query
      description: Field to order results by.
      schema:
        type: string
  schemas:
    Companies:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Company'
        pageNumber:
          type: integer
        pageSize:
          type: integer
        totalResults:
          type: integer
    Company:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        platform:
          type: string
        redirect:
          type: string
        created:
          type: string
          format: date-time
        tags:
          type: object
          additionalProperties:
            type: string
    CompanyRequestBody:
      type: object
      required: [name]
      properties:
        name:
          type: string
          example: Acme Roofing
        description:
          type: string
        tags:
          type: object
          additionalProperties:
            type: string
    Connections:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Connection'
    Connection:
      type: object
      properties:
        id:
          type: string
          format: uuid
        integrationId:
          type: string
        sourceId:
          type: string
        sourceType:
          type: string
          enum: [Accounting, Banking, BankFeed, Commerce, Expense, Other, Unknown]
        platformName:
          type: string
        linkUrl:
          type: string
        status:
          type: string
          enum: [PendingAuth, Linked, Unlinked, Deauthorized]
        created:
          type: string
          format: date-time
    PullOperation:
      type: object
      properties:
        id:
          type: string
          format: uuid
        companyId:
          type: string
          format: uuid
        dataType:
          type: string
        status:
          type: string
          enum: [Initial, Queued, Fetching, MapQueued, Mapping, Complete, FetchError, MapError, InternalError, PermissionsError, RateLimitError, PrerequisiteNotMet, Cancelled]
        requested:
          type: string
          format: date-time
    DataStatus:
      type: object
      properties:
        dataType:
          type: string
        status:
          type: string
        lastSuccessfulSync:
          type: string
          format: date-time
        currentStatus:
          type: string
        latestSyncId:
          type: string
    DataList:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
        pageNumber:
          type: integer
        pageSize:
          type: integer
        totalResults:
          type: integer