Codat Manage reports API

openapi: 3.1.0
info:
  title: Bank Feeds Account mapping Manage reports 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: Manage reports
  description: Generate and review generated reports for a company.
paths:
  /companies/{companyId}/reports/{reportType}:
    parameters:
    - $ref: '#/components/parameters/companyId'
    - $ref: '#/components/parameters/reportType'
    post:
      tags:
      - Manage reports
      summary: Generate report
      description: 'Use the *Generate report* endpoint to initiate the generation of a report specified by the `reportType` parameter.


        This action triggers the system to refresh and pull the necessary data from the company''s data sources to ensure the report contains the most up-to-date information.'
      operationId: generate-report
      x-speakeasy-name-override: generate-report
      responses:
        '202':
          description: Accepted (pending)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportOperation'
              examples:
                Report:
                  $ref: '#/components/examples/SingleReportExample'
        '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'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/Too-Many-Requests'
        '500':
          $ref: '#/components/responses/Internal-Server-Error'
        '503':
          $ref: '#/components/responses/Service-Unavailable'
  /companies/{companyId}/reports/{reportType}/{reportId}/status:
    parameters:
    - $ref: '#/components/parameters/companyId'
    - $ref: '#/components/parameters/reportType'
    - $ref: '#/components/parameters/reportId'
    - $ref: '#/components/parameters/maxAge'
    get:
      tags:
      - Manage reports
      summary: Get report status
      description: 'Use the *Get report status* endpoint to return the metadata about report generation, such as its current status, date of request, and date of generation.


        You can either provide the ID of a report or use `latest` as the ID value to get the most recent generated *reportName* report for the company.


        '
      operationId: get-report-status
      x-speakeasy-name-override: get-report-status
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportOperation'
              examples:
                Report:
                  $ref: '#/components/examples/SingleReportExample'
        '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:
    parameters:
    - $ref: '#/components/parameters/companyId'
    - $ref: '#/components/parameters/page'
    - $ref: '#/components/parameters/pageSize'
    - $ref: '#/components/parameters/query'
    - $ref: '#/components/parameters/orderBy'
    get:
      tags:
      - Manage reports
      summary: List reports
      description: Use the *List reports* endpoint to return details (such as generation's current status, date of request, and date of generation) about all reports generated for a company. The query parameter can be used to filter the results.
      operationId: list-reports
      x-speakeasy-name-override: list-reports
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportOperation/definitions/reports'
              example:
                pageNumber: 1
                pageSize: 4
                totalResults: 15
                _links:
                  self:
                    href: /companies/0f591937-4ea9-48c4-847a-fe65fb24bb41/reports
                  current:
                    href: /companies/0f591937-4ea9-48c4-847a-fe65fb24bb41/reports?page=1&pageSize=4
                  next:
                    href: /companies/0f591937-4ea9-48c4-847a-fe65fb24bb41/reports?page=2&pageSize=4
                results:
                - id: c0d52c82-777f-4309-81a0-d935aea0562b
                  status: InProgress
                  type: categorizedBankStatement
                  requested: '2024-10-15T07:00:00Z'
                  updated: '2024-10-15T15:31:45Z'
                - id: 79ef0451-edbd-4108-82ff-0b991444f1ec
                  status: Complete
                  type: categorizedBankStatement
                  requested: '2024-09-10T05:50:00Z'
                  updated: '2024-09-11T14:37:12Z'
                - id: ae125b45-ed37-4bb4-bb4a-d55383fd56b2
                  status: Complete
                  type: categorizedBankStatement
                  requested: '2024-09-06T07:47:10Z'
                  updated: '2024-09-20T14:42:15Z'
                - id: ebfaf90c-31fe-407f-a016-bc2b3e60894a
                  status: Error
                  type: categorizedBankStatement
                  requested: '2024-07-15T04:45:14Z'
                  updated: '2024-07-15T17:41:45Z'
                  errorMessage: Failed to generate the report because....
        '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:
  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."
    ReportOperation:
      title: Report
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the report
          example: 52c0f26b-051a-43ff-b02a-258eec67f5ef
        status:
          type: string
          enum:
          - InProgress
          - Complete
          - Error
          description: The status of the report generation.
        type:
          type: string
          enum:
          - categorizedBankStatement
          - creditModel
          - spendAnalysis
          description: The name of the generated report.
        requestedDate:
          description: The date and time on which the report was requested.
          $ref: '#/components/schemas/DateTime'
        updatedDate:
          description: The date and time on which the report was last updated.
          $ref: '#/components/schemas/DateTime'
        errorMessage:
          type: string
          nullable: true
          description: A short message describing any errors that occurred while generating the report.
      description: Information about report generation.
      definitions:
        reports:
          title: Reports
          allOf:
          - type: object
            properties:
              results:
                type: array
                items:
                  $ref: '#/components/schemas/ReportOperation'
                minLength: 0
                maxLength: 2000
          - $ref: '#/components/schemas/PagingInfo'
    PagingInfo:
      type: object
      title: Pagination information
      x-internal: true
      properties:
        pageNumber:
          type: integer
          description: Current page number.
        pageSize:
          type: integer
          description: Number of items to return in results array.
          maximum: 2000
        totalResults:
          type: integer
          description: Total number of items.
        _links:
          $ref: '#/components/schemas/PagingInfo/definitions/links'
      definitions:
        links:
          title: Hal Links
          type: object
          required:
          - self
          - current
          properties:
            self:
              $ref: '#/components/schemas/PagingInfo/definitions/halRef'
            current:
              $ref: '#/components/schemas/PagingInfo/definitions/halRef'
            next:
              $ref: '#/components/schemas/PagingInfo/definitions/halRef'
            previous:
              $ref: '#/components/schemas/PagingInfo/definitions/halRef'
          examples:
          - self:
              href: /companies
            current:
              href: /companies?page=1&pageSize=10
        halRef:
          title: Hypertext reference
          type: object
          properties:
            href:
              type: string
              format: uri-reference
              description: Uri hypertext reference.
      required:
      - pageNumber
      - pageSize
      - totalResults
      - _links
      examples:
      - pageNumber: 1
        pageSize: 10
        totalResults: 1
        _links:
          self:
            href: /companies/{id}/data/{dataType}
          current:
            href: /companies/{id}/data/{dataType}?page=1&pageSize=10
    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.
  responses:
    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
    Conflict:
      description: The data type's dataset has not been requested or is still syncing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Conflict:
              value:
                statusCode: 409
                service: PublicApi
                error: The data set has not been requested.
                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
    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
    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
    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
    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
    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:
    orderBy:
      name: orderBy
      in: query
      required: false
      schema:
        type: string
        example: -modifiedDate
      description: Field to order results by. [Read more](https://docs.codat.io/using-the-api/ordering-results).
    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
    pageSize:
      name: pageSize
      in: query
      schema:
        type: integer
        format: int32
        default: 100
        example: 100
        minimum: 1
        maximum: 5000
      description: Number of records to return in a page. [Read more](https://docs.codat.io/using-the-api/paging).
    query:
      name: query
      in: query
      required: false
      schema:
        type: string
      example: id=e3334455-1aed-4e71-ab43-6bccf12092ee
      description: Codat query string. [Read more](https://docs.codat.io/using-the-api/querying).
    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.
    maxAge:
      description: The maximum age of report to fetch.
      name: maxAge
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/DateTime'
    reportType:
      name: reportType
      description: The type of the report
      in: path
      required: true
      schema:
        type: string
        enum:
        - categorizedBankStatement
        - creditModel
    page:
      name: page
      in: query
      schema:
        type: integer
        format: int32
        minimum: 1
        example: 1
        default: 1
      description: Page number. [Read more](https://docs.codat.io/using-the-api/paging).
  examples:
    SingleReportExample:
      value:
        id: 6e9bae88-72c9-45ae-abe8-41fbf2871458
        status: InProgress
        type: categorizedBankStatement
        requestedDate: '2024-09-27T04:43:41Z'
        updatedDate: '2024-10-01T14:41:46Z'
  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