Codat Financial summary API

openapi: 3.1.0
info:
  title: Bank Feeds Account mapping Financial summary API
  version: 3.0.0
  contact:
    email: support@codat.io
    name: Codat
  description: 'Bank Feeds solution enables your SMB users to set up bank feeds from accounts in your application to supported accounting software.


    A bank feed is a connection between a source bank account in your application and a target bank account in a supported accounting software.


    [Explore solution](https://docs.codat.io/bank-feeds-api/overview) | [See OpenAPI spec](https://github.com/codatio/oas)


    ---

    <!-- Start Codat Tags Table -->

    ## Endpoints


    | Endpoints | Description |

    | :- |:- |

    | Companies | Create and manage your SMB users'' companies. |

    | Connections | Create new and manage existing data connections for a company. |

    | Source accounts | Provide and manage lists of source bank accounts. |

    | Account mapping | Extra functionality for building an account management UI. |

    | Company information | Get detailed information about a company from the underlying platform. |

    | Transactions | Create new bank account transactions for a company''s connections, and see previous operations. |

    <!-- End Codat Tags Table -->'
  termsOfService: https://www.codat.io/legals/
servers:
- description: Production
  url: https://api.codat.io
security:
- auth_header: []
tags:
- name: Financial summary
  description: View financial summary information for a company, including credit model reports and accounting score.
paths:
  /companies/{companyId}/reports/creditModel/{reportId}/excel:
    parameters:
    - $ref: '#/components/parameters/companyId'
    - $ref: '#/components/parameters/reportId'
    - $ref: '#/components/parameters/maxAge'
    get:
      tags:
      - Financial summary
      summary: Download credit model Excel
      description: "> **Available as beta release**\n>\n> This endpoint is part of a beta release. Please contact your account manager if you want to enable it.\n\nUse the *Download Credit Model Excel* endpoint to download the credit model Excel file. \n\nBefore using it, you must call the [Generate report](https://docs.codat.io/lending-api#/operations/generate-report) endpoint of type `creditModel`."
      operationId: download-credit-model-excel
      x-speakeasy-name-override: download-credit-model-excel
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/Payment-Required'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/Not-Found'
        '429':
          $ref: '#/components/responses/Too-Many-Requests'
        '500':
          $ref: '#/components/responses/Internal-Server-Error'
        '503':
          $ref: '#/components/responses/Service-Unavailable'
  /companies/{companyId}/reports/creditModel/{reportId}/financialSummary:
    parameters:
    - $ref: '#/components/parameters/companyId'
    - $ref: '#/components/parameters/reportId'
    get:
      tags:
      - Financial summary
      summary: Get financial summary insights
      description: '> **Available as beta release**

        >

        > This endpoint is part of a beta release. Please contact your account manager if you want to enable it.


        Financial summary insights provide high-level indicators about the accuracy and completeness of a business’s financial data. These insights include:

        - Closed Books Indicator – An estimate of the most recent accounting period officially closed by a business

        - Accounting Score – An evaluation of the quality and completeness of a business’s bookkeeping


        Before accessing this endpoint, you must call the [Generate report](https://docs.codat.io/lending-api#/operations/generate-report) endpoint of type `creditModel`.


        > Please note that missing elements might be disabled for the account. Please contact account manager for more details.'
      operationId: get-financial-summary
      x-speakeasy-name-override: get-financial-summary
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialSummary'
              example:
                booksClosedDate:
                  date: '2025-05-31T00:00:00Z'
                  reason:
                  - One or more accounts show a deviation from expected movements for March 2025
                  - One of the marketing accounts haven't been booked for February 2025
                  - One of the inventory accounts haven't been booked for March 2025
                accountingScore:
                  score: 90
                  reason:
                  - Balance sheet is unbalanced.
                  - Negative Tangible Assets on Balance Sheet
                  - Negative Accounts Receivable on Balance Sheet
        '204':
          description: No content
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/Payment-Required'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/Not-Found'
        '429':
          $ref: '#/components/responses/Too-Many-Requests'
        '500':
          $ref: '#/components/responses/Internal-Server-Error'
        '503':
          $ref: '#/components/responses/Service-Unavailable'
components:
  responses:
    BadRequest:
      description: The request made is not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Malformed query:
              value:
                statusCode: 400
                service: PublicApi
                error: Error processing request - not valid.
                correlationId: bc997528a9d7abb9161ef45f05d38599
                canBeRetried: Unknown
                detailedErrorCode: 0
    Payment-Required:
      description: 'An account limit has been exceeded. The type of limit is described in the error property:


        - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request.

        - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan.

        - Your Free account is older than 365 days and has expired. Contact support@codat.io.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Conflict:
              value:
                statusCode: 429
                service: PublicApi
                error: You have exceeded the 50-company limit that applies to a Free plan. We recommend that you delete any companies you no longer need and retry the request.
                correlationId: bc997528a9d7abb9161ef45f05d38599
                canBeRetried: Unknown
                detailedErrorCode: 0
    Forbidden:
      description: You are using an outdated API key or a key not associated with that resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Conflict:
              value:
                statusCode: 403
                service: PublicApi
                error: You are using an outdated API key or a key not associated with that resource.
                correlationId: bc997528a9d7abb9161ef45f05d38599
                canBeRetried: Unknown
                detailedErrorCode: 0
    Too-Many-Requests:
      description: Too many requests were made in a given amount of time. Wait a short period and then try again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Conflict:
              value:
                statusCode: 429
                service: PublicApi
                error: You have made too many requests in a given amount of time; please retry later.
                correlationId: bc997528a9d7abb9161ef45f05d38599
                canBeRetried: Unknown
                detailedErrorCode: 0
    Unauthorized:
      description: Your API request was not properly authorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Unauthorized:
              value:
                statusCode: 401
                service: PublicApi
                error: Unauthorized
                correlationId: 7eb40d6b415d7bcd99ce658268284056
                canBeRetried: Unknown
                detailedErrorCode: 0
    Not-Found:
      description: 'One or more of the resources you referenced could not be found.

        This might be because your company or data connection id is wrong, or was already deleted.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Data connection not found:
              value:
                statusCode: 404
                service: PublicApi
                error: Data connection a22dd66b-564a-4832-9b37-7b3ce4aeb7de not found
                correlationId: 8fa2b5f4794970a4ee73758f612e8df0
                canBeRetried: Unknown
                detailedErrorCode: 0
            Company not found:
              value:
                statusCode: 404
                service: ClientsApi
                error: No company was found with ID 846ed55c-974b-4392-a1f1-87b6fdbf3c5e
                correlationId: 0a40c2f31fc8f992fb88b0853e4166f3
                canBeRetried: Unknown
                detailedErrorCode: 0
            No data available:
              value:
                statusCode: 404
                service: PublicApi
                error: No data available for accounts for ID e5889b459f544926ac5b8e6756df2s
                correlationId: 0a40c2f31fc8f992fb88b0853e4166f3
                canBeRetried: Unknown
                detailedErrorCode: 0
    Internal-Server-Error:
      description: There is a problem with our server. Please try again later.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Conflict:
              value:
                statusCode: 500
                service: PublicApi
                error: There is a problem with our server. Please try again later.
                correlationId: bc997528a9d7abb9161ef45f05d38599
                canBeRetried: Unknown
                detailedErrorCode: 0
    Service-Unavailable:
      description: The Codat API is temporarily offline for maintenance. Please try again later.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Conflict:
              value:
                statusCode: 500
                service: PublicApi
                error: The Codat API is temporarily offline for maintenance. Please try again later.
                correlationId: bc997528a9d7abb9161ef45f05d38599
                canBeRetried: Unknown
                detailedErrorCode: 0
  parameters:
    companyId:
      name: companyId
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 8a210b68-6988-11ed-a1eb-0242ac120002
        description: Unique identifier for your SMB in Codat.
      description: Unique identifier for a company.
    reportId:
      name: reportId
      description: Unique identifier for a report, use either the Id of the report or `latest` for the most recently generate report.
      in: path
      required: true
      schema:
        oneOf:
        - type: string
          title: ID
          format: uuid
          example: 8a210b68-6988-11ed-a1eb-0242ac120002
        - type: string
          title: Latest
          enum:
          - latest
    maxAge:
      description: The maximum age of report to fetch.
      name: maxAge
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/DateTime'
  schemas:
    DateTime:
      title: Date time
      type: string
      examples:
      - '2022-10-23T00:00:00Z'
      - '2022-10-23'
      description: "In Codat's data model, dates and times are represented using the <a class=\"external\" href=\"https://en.wikipedia.org/wiki/ISO_8601\" target=\"_blank\">ISO 8601 standard</a>. Date and time fields are formatted as strings; for example:\n\n```\n2020-10-08T22:40:50Z\n2021-01-01T00:00:00\n```\n\n\n\nWhen syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information:\n\n- Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z`\n- Unqualified local time: `2021-11-15T01:00:00`\n- UTC time offsets: `2021-11-15T01:00:00-05:00`\n\n> Time zones\n> \n> Not all dates from Codat will contain information about time zones.  \n> Where it is not available from the underlying platform, Codat will return these as times local to the business whose data has been synced."
    ErrorMessage:
      title: Error message
      type: object
      x-internal: true
      properties:
        statusCode:
          type: integer
          description: The HTTP status code returned by the error.
        service:
          type: string
          description: Codat's service the returned the error.
        error:
          type: string
          description: A brief description of the error.
        correlationId:
          type: string
          description: Unique identifier used to propagate to all downstream services and determine the source of the error.
        validation:
          $ref: '#/components/schemas/ErrorMessage/definitions/errorValidation'
        canBeRetried:
          type: string
          description: '`True` if the error occurred transiently and can be retried.'
        detailedErrorCode:
          type: integer
          description: Machine readable error code used to automate processes based on the code returned.
      definitions:
        errorValidation:
          title: Validation error
          type: object
          nullable: true
          description: A human-readable object describing validation decisions Codat has made. If an operation has failed because of validation errors, they will be detailed here.
          properties:
            errors:
              type: array
              nullable: true
              items:
                $ref: '#/components/schemas/ErrorMessage/definitions/errorValidationItem'
            warnings:
              type: array
              nullable: true
              items:
                $ref: '#/components/schemas/ErrorMessage/definitions/errorValidationItem'
        errorValidationItem:
          title: Validation error item
          type: object
          properties:
            itemId:
              type: string
              nullable: true
              description: Unique identifier for a validation item.
            message:
              type: string
              nullable: true
              description: A message outlining validation item's issue.
            validatorName:
              type: string
              nullable: true
              description: Name of validator.
    FinancialSummary:
      title: Closed Books Indicator
      type: object
      properties:
        booksClosedDate:
          type: object
          description: The date time in UTC the books closed.
          properties:
            date:
              type: string
              format: date-time
              description: The date time in UTC the books closed.
              example: '2025-05-31T00:00:00Z'
            reason:
              type: array
              description: List of reasons explaining the books closed date.
              items:
                type: string
              example:
              - One or more accounts show a deviation from expected movements for March 2025
              - One of the marketing accounts haven't been booked for February 2025
              - One of the inventory accounts haven't been booked for March 2025
        accountingScore:
          type: object
          description: A score based on data completeness, accuracy, consistency, and presentation of data and the reasons for the score.
          properties:
            score:
              type: number
              format: decimal
              description: The accounting score value.
              example: 90
            reason:
              type: array
              description: List of reasons explaining the accounting score.
              items:
                type: string
              example:
              - Balance sheet is unbalanced.
              - Negative Tangible Assets on Balance Sheet
              - Negative Accounts Receivable on Balance Sheet
  securitySchemes:
    auth_header:
      name: Authorization
      description: The word "Basic" followed by a space and your API key. [API keys](https://docs.codat.io/platform-api#/schemas/ApiKeyDetails) are tokens used to control access to the API. You can get an API key via [the Codat Portal](https://app.codat.io/developers/api-keys), via [the API](https://docs.codat.io/platform-api#/operations/list-api-keys), or [read more](https://docs.codat.io/using-the-api/authentication) about authentication at Codat.
      type: apiKey
      in: header
      x-speakeasy-example: Basic BASE_64_ENCODED(API_KEY)
x-speakeasy-retries:
  strategy: backoff
  backoff:
    initialInterval: 500
    maxInterval: 60000
    maxElapsedTime: 3600000
    exponent: 1.5
  statusCodes:
  - 408
  - 429
  - 5XX
  retryConnectionErrors: true
x-speakeasy-name-override:
- operationId: ^list-.*?
  methodNameOverride: list
- operationId: ^list-.*?-attachments
  methodNameOverride: list-attachments
- operationId: ^get-.*?
  methodNameOverride: get
- operationId: ^get-create-.*?-model
  methodNameOverride: get-create-model
- operationId: ^get-create-update.*?-model
  methodNameOverride: get-create-update-model
- operationId: ^get-.*?-attachment
  methodNameOverride: get-attachment
- operationId: ^update-.*?
  methodNameOverride: update
- operationId: ^create-.*?
  methodNameOverride: create
- operationId: ^delete-.*?
  methodNameOverride: delete
- operationId: ^delete-.*?-attachment
  methodNameOverride: delete-attachment
- operationId: ^download-.*?-attachment
  methodNameOverride: download-attachment
- operationId: ^upload-.*?-attachment
  methodNameOverride: upload-attachment
x-codat-docs-path: bank-feeds-api
x-codat-keep-docs-paths-local: true
x-codat-speakeasy-pagination:
  type: offsetLimit
  inputs:
  - name: page
    in: parameters
    type: page
  outputs:
    results: $.results