Codat Liabilities API

openapi: 3.2.0
info:
  title: Lending Liabilities API
  description: 'Our Lending solution helps you make smarter credit decisions on small businesses by enabling you to pull your customers'' latest data from accounting, banking, and commerce software they are already using. It also includes features to help providers verify the accuracy of data and process it more efficiently.


    The Lending solution is built on top of the latest accounting, commerce, and banking data, providing you with the most important data points you need to get a full picture of SMB creditworthiness and make a comprehensive assessment of your customers.


    [Explore solution](https://docs.codat.io/lending/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. |

    | Bank statements | Retrieve banking data from linked bank accounts. |

    | Sales | Retrieve standardized sales data from a linked commerce software. |

    | Financial statements | Financial data and reports from a linked accounting software. |

    | Liabilities | Debt and other liabilities. |

    | Accounts payable | Data from a linked accounting software representing money the business owes money to its suppliers. |

    | Accounts receivable | Data from a linked accounting software representing money owed to the business for sold goods or services. |

    | Transactions | Data from a linked accounting software representing transactions. |

    | Company info | View company information fetched from the source platform. |

    | Data integrity | Match mutable accounting data with immutable banking data to increase confidence in financial data. |

    | Excel reports | Download reports in Excel format. |

    | Manage data | Control how data is retrieved from an integration. |

    | File upload | Endpoints to manage uploaded files. |

    | Loan writeback | Implement the [loan writeback](https://docs.codat.io/lending/guides/loan-writeback/introduction) procedure in your lending process to maintain an accurate position of a loan during the entire lending cycle. |

    <!-- End Codat Tags Table -->'
  version: 3.0.0
  contact:
    name: Codat
    email: support@codat.io
  termsOfService: https://www.codat.io/legals/
servers:
- description: Production
  url: https://api.codat.io
security:
- auth_header: []
tags:
- name: Liabilities
  description: Debt and other liabilities.
paths:
  /companies/{companyId}/reports/liabilities/loans/transactions:
    parameters:
    - $ref: '#/components/parameters/companyId'
    - schema:
        type: string
        enum:
        - banking
        - commerce
        - accounting
      in: query
      name: sourceType
      description: Data source type.
      required: true
    post:
      summary: Generate loan transactions report
      description: 'The _Generate loan transactions_ endpoint requests the generation of the Loan Transactions report.


        Learn more about Codat''s liabilities feature [here](https://docs.codat.io/lending/features/liabilities-overview).


        Make sure you have [synced a company](https://docs.codat.io/lending-api#/operations/refresh-company-data) recently before calling the endpoint.

        '
      tags:
      - Liabilities
      responses:
        '202':
          description: Accepted
        '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'
      operationId: generate-loan-transactions
      x-speakeasy-name-override: generate-loan-transactions
    get:
      summary: List loan transactions
      description: 'The *List loan transactions* endpoint returns all [loan transactions](https://docs.codat.io/lending-api#/schemas/LoanTransactions) identified from a company''s accounting, banking, and commerce integrations.


        This detail gives analysts a better idea of the loan obligations a company may have.


        Make sure you have [synced a company](https://docs.codat.io/lending-api#/operations/refresh-company-data) recently before calling the endpoint.

        '
      tags:
      - Liabilities
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanTransactions'
        '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'
      operationId: list-loan-transactions
      x-speakeasy-name-override: list-loan-transactions
  /companies/{companyId}/reports/liabilities/loans:
    parameters:
    - $ref: '#/components/parameters/companyId'
    - schema:
        type: string
        enum:
        - banking
        - commerce
        - accounting
      in: query
      name: sourceType
      description: Data source type.
      required: true
    post:
      summary: Generate loan summaries report
      description: 'The _Generate loan summaries_ endpoint requests the generation of the Loan Summaries report.


        Learn more about Codat''s liabilities feature [here](https://docs.codat.io/lending/features/liabilities-overview).


        Make sure you have [synced a company](https://docs.codat.io/lending-api#/operations/refresh-company-data) recently before calling the endpoint.

        '
      tags:
      - Liabilities
      responses:
        '202':
          description: Accepted
        '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'
      operationId: generate-loan-summary
      x-speakeasy-name-override: generate-loan-summary
    get:
      summary: Get loan summaries
      description: 'The *Get loan summaries* endpoint returns a summary by integration type of all loans identified from a company''s accounting, banking, and commerce integrations.


        The endpoint returns a list of a company''s [loan summaries](https://docs.codat.io/lending-api#/schemas/LoanSummary) for each valid data connection.


        Make sure you have [synced a company](https://docs.codat.io/lending-api#/operations/refresh-company-data) recently before calling the endpoint.

        '
      tags:
      - Liabilities
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanSummary'
        '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'
      operationId: get-loan-summary
      x-speakeasy-name-override: get-loan-summary
components:
  schemas:
    LoanSummary:
      title: Loan summary
      type: object
      properties:
        reportInfo:
          $ref: '#/components/schemas/LoanSummary/definitions/loanSummaryReportInfo'
        reportItems:
          type: array
          description: Returns a summary of all loan activity for that integration type
          items:
            $ref: '#/components/schemas/LoanSummary/definitions/loanSummaryReportItem'
      definitions:
        loanSummaryReportInfo:
          title: Loan Summary Report Info
          type: object
          properties:
            reportName:
              type: string
              description: The name of the report.
            companyName:
              type: string
              description: Name of the company queried.
            generatedDate:
              $ref: '#/components/schemas/DateTime'
              description: Returns the YYYY-MM-DD datetime of report generation.  urns the YYYY-MM-DD datetime of report generation.
        loanRef:
          title: Loan Reference
          type: object
          properties:
            id:
              type: string
              description: The id of the object being referred to.
            dataConnectionId:
              type: string
              description: The dataConnectionId the object being referred to is associated with.
              x-stoplight:
                id: vrnhmgrfndjhh
            type:
              type: string
              description: The object type data is referring to, e.g. Account.
        loanSummaryRecordRef:
          title: Item reference
          type: object
          properties:
            id:
              type: string
              description: The id of the object being referred to.
            dataConnectionId:
              type: string
              description: The dataConnectionId the object being referred to is associated with.
            integrationType:
              $ref: '#/components/schemas/LoanSummary/definitions/loanSummaryIntegrationType'
            recordRefType:
              $ref: '#/components/schemas/LoanSummary/definitions/loanSummaryRecordRefType'
        loanSummaryReportItem:
          type: object
          properties:
            recordRef:
              $ref: '#/components/schemas/LoanSummary/definitions/loanSummaryRecordRef'
              description: Contains object that contains a summary of all loan transactions for that integration type.
            description:
              type: string
              description: The description of the object being referred to. E.g. the account.
            startDate:
              $ref: '#/components/schemas/DateTime'
              description: The date of the earliest loan transaction.
            totalDrawdowns:
              type: number
              format: decimal
              description: The total loan drawdowns.
            totalRepayments:
              type: number
              format: decimal
              description: The total loan repayments which includes capital plus any interest.
            balance:
              type: number
              format: decimal
              description: The loan outstanding balance.  This may not equal totalDrawdowns - totalRepayments due to interest which has been accrued.
            lender:
              type: string
              description: The name of lender providing the loan.
        loanSummaryIntegrationType:
          title: Integration type
          type: string
          enum:
          - Accounting
          - Banking
          - Commerce
          description: The integration type begin referred to.
        loanSummaryRecordRefType:
          title: Record reference type
          type: string
          enum:
          - accounts
          - banking-accounts
          - commerce-transactions
          description: The datatype being referred to.
      examples:
      - reportInfo:
          reportName: LoanSummaryReport
          companyName: The Coffee shop
          generatedDate: '2022-10-23T00:00:00Z'
        reportItems:
        - recordRef:
            id: string
            dataConnectionId: DE34E8E3-089F-4DF4-89E9-F7C43618FCAAA
            integrationType: Accounting
            recordRefType: accounts
          description: string
          startDate: '2021-01-01'
          totalInvestments: 100000
          totalRepayments: 83481.72
          balance: 42513.18
          lender: Barclays Bank
    LoanTransactions:
      title: Loan transactions
      type: object
      properties:
        reportInfo:
          $ref: '#/components/schemas/LoanTransactions/definitions/loanTransactionsReportInfo'
        reportItems:
          type: array
          description: Contains object of reporting properties. The loan ref will reference a different object depending on the integration type.
          items:
            $ref: '#/components/schemas/LoanTransactions/definitions/reportItems'
      definitions:
        loanTransactionsReportInfo:
          title: Loan Transactions Report Info
          type: object
          properties:
            pageNumber:
              type: integer
              description: The page number.
            pageSize:
              type: integer
              description: Queried page size.
            totalResults:
              type: integer
              description: The total number of transactions returned.
            reportName:
              type: string
              description: The name of the report.
            companyName:
              type: string
              description: Name of the company queried.
            generatedDate:
              $ref: '#/components/schemas/DateTime'
              description: Returns the YYYY-MM-DD datetime of report generation.
        loanRef:
          title: Loan Reference
          type: object
          properties:
            id:
              type: string
              description: The id of the object being referred to.
            dataConnectionId:
              type: string
              description: The dataConnectionId the object being referred to is associated with.
            type:
              type: string
              description: The object type data is referring to, e.g. Account.
        itemRef:
          title: Item reference
          type: object
          properties:
            id:
              type: string
              description: The id of the object, e.g. the Journal entry.
            dataConnectionId:
              type: string
              description: The data connection id being referenced.
            type:
              type: string
              description: The data type the loan transaction entry was extracted from.
        reportItems:
          type: object
          properties:
            loanRef:
              $ref: '#/components/schemas/LoanTransactions/definitions/loanRef'
              description: Contains object that contains all the Loan transactions for that integration type.
            itemRef:
              $ref: '#/components/schemas/LoanTransactions/definitions/itemRef'
              description: Contains object of reporting properties. The loan ref will reference a different object depending on the integration type.
            date:
              $ref: '#/components/schemas/DateTime'
              description: The date of that entry type occurred.
            amount:
              type: number
              format: decimal
              description: The loan transaction amount.
            loanTransactionType:
              description: The type of loan transaction.
              type: string
              enum:
              - Investment
              - Repayment
              - Interest
              - AccuredInterest
            lender:
              type: string
              description: The name of lender providing the loan.
      examples:
      - reportInfo:
          pageNumber: 1
          pageSize: 1000
          totalResults: 1
          reportName: AccountingLoanTransactions
          companyName: Supermarket store
          generatedDate: '2022-10-23T00:00:00Z'
        reportItems:
        - loanRef:
            id: '332'
            dataConnectionId: ecd2d6be-5194-40a1-838f-5577a4881aaa
            type: chartOfAccount
          itemRef:
            id: '755488'
            dataConnectionId: ecd2d6be-5194-40a1-838f-5577a4881aaa
            type: journalEntry
          date: '2020-08-02'
          amount: -455
          transactionType: Repayment
          lender: Barclays Bank
    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.
    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."
  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
    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
    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
    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
    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
  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.
  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: lending-api
x-codat-keep-docs-paths-local: true
x-codat-speakeasy-pagination:
  type: offsetLimit
  inputs:
  - name: page
    in: parameters
    type: page
  outputs:
    results: $.results