openapi: 3.1.0
servers:
- description: Production
url: 'https://api.codat.io'
info:
title: Assess API
version: '1.0'
contact:
email: support@codat.io
url: 'https://www.codat.io/contact/'
name: Codat
summary: Codat's financial insights API
description: |-
> ### New to Codat?
>
> Our Assess API reference is relevant only to our existing clients.
> Please reach out to your Codat contact so that we can find the right product for you.
Check that you have enabled the [data types required by Assess](https://docs.codat.io/assess/get-started#prerequisites) for all of its features to work.
## Endpoints
| Endpoints | Description |
| :- |:- |
| Reports | Enriched reports and analyses of financial data. |
| Excel reports | Downloadable reports. |
| Data integrity | Match mutable accounting data with immutable banking data to increase confidence in financial data. |
[Read more...](https://www.docs.codat.io/assess/)
[See our OpenAPI spec](https://github.com/codatio/oas)
termsOfService: 'https://www.codat.io/legals/'
security:
- auth_header: []
x-speakeasy-retries:
strategy: backoff
backoff:
initialInterval: 500
maxInterval: 60000
maxElapsedTime: 3600000
exponent: 1.5
statusCodes:
- 408
- 429
- 5XX
retryConnectionErrors: true
x-codat-docs-path: codat-api
tags:
- name: Reports
description: Enriched reports and analyses of financial data.
- name: Excel reports
description: Downloadable reports.
- name: Data integrity
description: Match mutable accounting data with immutable banking data to increase confidence in financial data.
paths:
'/data/companies/{companyId}/assess/dataTypes/{dataType}/dataIntegrity/status':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/dataIntegrityDataType'
get:
summary: Get data integrity status
tags:
- Data integrity
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'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-data-integrity-status
x-speakeasy-name-override: status
description: Gets match status for a given company and datatype.
'/data/companies/{companyId}/assess/dataTypes/{dataType}/dataIntegrity/summaries':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/dataIntegrityDataType'
get:
summary: Get data integrity summary
tags:
- Data integrity
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Summaries'
'400':
$ref: '#/components/responses/Malformed-Query'
'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-data-integrity-summaries
x-speakeasy-name-override: summary
description: 'Gets match summary for a given company and datatype, optionally restricted by a Codat query string.'
parameters:
- $ref: '#/components/parameters/query'
'/data/companies/{companyId}/assess/dataTypes/{dataType}/dataIntegrity/details':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/dataIntegrityDataType'
get:
summary: List data type data integrity
tags:
- Data integrity
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Details'
examples: {}
'400':
$ref: '#/components/responses/Malformed-Query'
'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-data-type-data-integrity-details
x-speakeasy-name-override: details
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
description: 'Gets record-by-record match results for a given company and datatype, optionally restricted by a Codat query string.'
'/companies/{companyId}/reports/enhancedProfitAndLoss/accounts':
parameters:
- $ref: '#/components/parameters/companyId'
get:
summary: Get enhanced profit and loss accounts
description: |-
The Enhanced Profit and Loss Accounts endpoint returns a list of categorized accounts that appear on a company’s Profit and Loss. It also includes a balance per the financial statement date.
Codat suggests a category for each account automatically, but you can [change it](/docs/assess-categorizing-accounts-ecommerce-lending) to a more suitable one.
tags:
- Reports
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EnhancedReport'
example:
reportInfo:
currency: GBP
reportName: EnhancedProfitAndLossAccounts
companyName: Biscuits
generatedDate: '2023-03-24T16:40:59.0847354Z'
reportItems:
- date: '2022-08-31T00:00:00'
balance: 830.93
accountId: 04f7111b-55d4-4efc-b329-1bd5c791933a
accountName: Repairs & Maintenance
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 12000
accountId: 7f6a0e92-65be-4333-9a0a-d981b03bedd1
accountName: Wages
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: CostOfSales
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 28937.71
accountId: 7403e960-5b72-42ff-abf4-c870ad8910bd
accountName: Purchases
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: CostOfSales
confidence: 99.99
- levelName: Inventory
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 582.4
accountId: e8a0a24e-2dab-46b1-bfe1-6e92551c04e8
accountName: Purchase Discounts
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: CostOfSales
confidence: 99.99
- levelName: Inventory
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 350.44
accountId: cbf82e0d-87a7-464d-b567-9274ea94a1c0
accountName: Charitable and Political Donations
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: NonOperating
confidence: 99.99
- levelName: Donations
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 535.81
accountId: 78785fd7-f197-4c34-aa17-6e76b9255d34
accountName: Interest Paid (operating)
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: NonOperating
confidence: 99.99
- levelName: Interest
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 633.05
accountId: fb3210ef-edeb-48af-bb49-b85d40c1e6bb
accountName: Corporation Tax
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: NonOperating
confidence: 99.99
- levelName: Taxes
confidence: 99.99
- levelName: CorporationTaxes
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 782.61
accountId: f3aa84fe-5c31-4107-b207-7e0419f636d7
accountName: Bank Fees
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: Operating
confidence: 99.99
- levelName: BankCharges
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 8000
accountId: 9cbe5fe4-ca60-4792-8bf1-de01fb7010aa
accountName: Rent
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: Operating
confidence: 99.99
- levelName: Leases
confidence: 99.99
- levelName: BuildingRentLease
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 1090.68
accountId: 138a8eb3-5c08-4e59-a3bc-892119694447
accountName: Motor Vehicle Expenses
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: Operating
confidence: 99.99
- levelName: Leases
confidence: 99.99
- levelName: EquipmentRentLease
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 26307.02
accountId: 868591ad-f9c2-4956-a5ec-c32c1d48c6f3
accountName: Advertising & Marketing
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: Operating
confidence: 99.99
- levelName: Marketing
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 1128.85
accountId: 1734ff00-2a17-45b4-8db6-2dc2e832c460
accountName: 'Postage, Freight & Courier'
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: Operating
confidence: 99.99
- levelName: Marketing
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 40
accountId: 7d8d0322-f452-47de-a8e8-54b0130e6f38
accountName: Subscriptions
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: Operating
confidence: 99.99
- levelName: Marketing
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 5.72
accountId: 4378ddba-36b4-4b35-9970-bd972b20d137
accountName: Amortization
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: Operating
confidence: 99.99
- levelName: NonCash
confidence: 99.99
- levelName: Amortization
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 1539.18
accountId: 940c8a59-3348-4a0b-a1b1-781d9f29cc8b
accountName: Depreciation Expense
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: Operating
confidence: 99.99
- levelName: NonCash
confidence: 99.99
- levelName: Depreciation
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 1416.05
accountId: e7ac3baa-cfbe-40c1-a172-83d22e84435b
accountName: Entertainment-100% business
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: Operating
confidence: 99.99
- levelName: Personnel
confidence: 99.99
- levelName: EmployeeBenefits
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 1465.61
accountId: b5e801e8-8dbc-4390-ac99-3b0fff54a89f
accountName: General Expenses
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: Operating
confidence: 99.99
- levelName: SalesGeneralAdministrative
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 7347.35
accountId: 5360066d-1474-49f6-a7a5-c66d5f6032ba
accountName: 'Light, Power, Heating'
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: Operating
confidence: 99.99
- levelName: SalesGeneralAdministrative
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 1027.25
accountId: 7aa7988a-ff61-4cb8-bef3-15395355d108
accountName: Printing & Stationery
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: Operating
confidence: 99.99
- levelName: SalesGeneralAdministrative
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 45
accountId: 043b6bcb-dfe6-4c97-9b4c-f9b300fe3f03
accountName: Telephone & Internet
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: Operating
confidence: 99.99
- levelName: SalesGeneralAdministrative
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 0
accountId: eef78ed1-dfed-447c-bdba-3a49fb2c044b
accountName: Audit & Accountancy fees
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: Operating
confidence: 99.99
- levelName: SalesGeneralAdministrative
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 130
accountId: c16f5c35-8283-47da-9d09-5fecb183b0cb
accountName: Cleaning
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: Operating
confidence: 99.99
- levelName: SalesGeneralAdministrative
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 860.02
accountId: df62060b-41cc-4bf2-9de7-c7e537b5663a
accountName: Travel - National
accountCategory:
status: Suggested
levels:
- levelName: Expense
confidence: 99.99
- levelName: Operating
confidence: 99.99
- levelName: Travel
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 850.22
accountId: 68794a8f-b22d-4520-b97b-025b7cb10f94
accountName: Other Revenue
accountCategory:
status: Suggested
levels:
- levelName: Income
confidence: 99.99
- levelName: Revenue
confidence: 99.99
- levelName: Online
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 138457.98
accountId: 72df89d2-512b-4455-af51-a6b563733842
accountName: Sales
accountCategory:
status: Suggested
levels:
- levelName: Income
confidence: 99.99
- levelName: Revenue
confidence: 99.99
- levelName: Wholesale
confidence: 99.99
'400':
$ref: '#/components/responses/Bad-Request'
'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-accounts-for-enhanced-profit-and-loss
parameters:
- $ref: '#/components/parameters/reportDate'
- $ref: '#/components/parameters/numberOfPeriods'
'/companies/{companyId}/reports/enhancedBalanceSheet/accounts':
parameters:
- $ref: '#/components/parameters/companyId'
get:
summary: Get enhanced balance sheet accounts
description: |-
The Enhanced Balance Sheet Accounts endpoint returns a list of categorized accounts that appear on a company’s Balance Sheet along with a balance per financial statement date.
Codat suggests a category for each account automatically, but you can [change it](/docs/assess-categorizing-accounts-ecommerce-lending) to a more suitable one.
tags:
- Reports
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EnhancedReport'
example:
reportInfo:
currency: GBP
reportName: EnhancedBalanceSheetAccounts
companyName: Biscuits
generatedDate: '2023-03-24T16:42:09.2973105Z'
reportItems:
- date: '2022-08-31T00:00:00'
balance: 12973.03
accountId: 22de1660-d745-4809-a363-16b134607e66
accountName: Prepayments
accountCategory:
status: Suggested
levels:
- levelName: Asset
confidence: 99.99
- levelName: Current
confidence: 99.99
- levelName: AccruedDeferredAssets
confidence: 99.99
- levelName: PrepaidExpenses
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 316065.92
accountId: dbcaf288-2b39-4b95-8ab3-42202ab15918
accountName: Business Current Account
accountCategory:
status: Suggested
levels:
- levelName: Asset
confidence: 99.99
- levelName: Current
confidence: 99.99
- levelName: Bank
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 65945.07
accountId: e5d7612c-1671-47b4-b733-5db48363fcd0
accountName: Inventory
accountCategory:
status: Suggested
levels:
- levelName: Asset
confidence: 99.99
- levelName: Current
confidence: 99.99
- levelName: Inventory
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 71937.95
accountId: 1b6266d1-1e44-46c5-8eb5-a8f98e03124e
accountName: Accounts Receivable
accountCategory:
status: Suggested
levels:
- levelName: Asset
confidence: 99.99
- levelName: Current
confidence: 99.99
- levelName: Receivables
confidence: 99.99
- levelName: AccountsReceivables
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 2180148.56
accountId: 724ca578-8b5d-4bdb-ad45-e3820eee9de9
accountName: Office Equipment
accountCategory:
status: Suggested
levels:
- levelName: Asset
confidence: 99.99
- levelName: NonCurrent
confidence: 99.99
- levelName: AccumulatedDepreciationDepletionAmortization
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 1804674.9
accountId: be3eb911-034b-42de-95db-0d58ac978b7f
accountName: Computer Equipment
accountCategory:
status: Suggested
levels:
- levelName: Asset
confidence: 99.99
- levelName: NonCurrent
confidence: 99.99
- levelName: AccumulatedDepreciationDepletionAmortization
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 3417424.16
accountId: 39225d6f-3722-4508-ac3f-a2f6ec96ad31
accountName: Retained Earnings
accountCategory:
status: Suggested
levels:
- levelName: Equity
confidence: 99.99
- levelName: RetainedEarnings
confidence: 99.99
- levelName: CapitalIncomeReserve
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 44252.52
accountId: 78828dd9-6008-4662-b43c-e9d87907fd2b
accountName: Current Year Earnings
accountCategory:
status: Suggested
levels:
- levelName: Equity
confidence: 99.99
- levelName: ShareCapital
confidence: 99.99
- levelName: CommonStock
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 75835.64
accountId: 53bf27a7-7497-4c61-9887-dfaad5c6d80a
accountName: Accounts Payable
accountCategory:
status: Suggested
levels:
- levelName: Liability
confidence: 99.99
- levelName: Current
confidence: 99.99
- levelName: AccountsPayable
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 208264.65
accountId: e2530acd-91c8-48f8-a35f-935dbd7432e2
accountName: Accruals
accountCategory:
status: Suggested
levels:
- levelName: Liability
confidence: 99.99
- levelName: Current
confidence: 99.99
- levelName: AccruedLiabilities
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 0
accountId: d19852a2-e292-4eb9-a909-9dadb95c0e76
accountName: Rounding
accountCategory:
status: Suggested
levels:
- levelName: Liability
confidence: 99.99
- levelName: Current
confidence: 99.99
- levelName: Bank
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 25184.57
accountId: 62060aae-e5a6-4db5-a3bb-6abec6d47959
accountName: Credit Card Control Account
accountCategory:
status: Suggested
levels:
- levelName: Liability
confidence: 99.99
- levelName: Current
confidence: 99.99
- levelName: Debt
confidence: 99.99
- levelName: CreditCards
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 9650.58
accountId: 9be6382f-6b33-402d-b448-0db1dbf67a98
accountName: Historical Adjustment
accountCategory:
status: Suggested
levels:
- levelName: Liability
confidence: 99.99
- levelName: Current
confidence: 99.99
- levelName: Debt
confidence: 99.99
- levelName: LoansPayable
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 2022.41
accountId: 8636effc-50fb-45ba-8b2b-18336fa29b6b
accountName: John Smith
accountCategory:
status: Suggested
levels:
- levelName: Liability
confidence: 99.99
- levelName: Current
confidence: 99.99
- levelName: Debt
confidence: 99.99
- levelName: LoansPayable
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 29034.75
accountId: 3a872b81-d1af-4d31-9bfa-a37280b8f68c
accountName: VAT
accountCategory:
status: Confirmed
levels:
- levelName: Liability
confidence: 99.99
- levelName: Current
confidence: 99.99
- levelName: Personnel
confidence: 99.99
- levelName: PensionPayable
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 1076.55
accountId: 3b58f7ff-fa16-453a-9931-f020816d76e7
accountName: Interest Payables
accountCategory:
status: Confirmed
levels:
- levelName: Liability
confidence: 99.99
- levelName: Current
confidence: 99.99
- levelName: Personnel
confidence: 99.99
- levelName: PensionPayable
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 0
accountId: 8852a857-aa9d-4706-839f-638e9d6b5a66
accountName: Unpaid Expense Claims
accountCategory:
status: Suggested
levels:
- levelName: Liability
confidence: 99.99
- levelName: NonCurrent
confidence: 99.99
- date: '2022-08-31T00:00:00'
balance: 638999.6
accountId: 55008233-40e7-41ac-84af-2255fa028c2e
accountName: Loan
accountCategory:
status: Suggested
levels:
- levelName: Liability
confidence: 99.99
- levelName: NonCurrent
confidence: 99.99
'400':
$ref: '#/components/responses/Bad-Request'
'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-accounts-for-enhanced-balance-sheet
parameters:
- $ref: '#/components/parameters/reportDate'
- $ref: '#/components/parameters/numberOfPeriods'
'/companies/{companyId}/reports/enhancedCashFlow/transactions':
parameters:
- $ref: '#/components/parameters/companyId'
get:
summary: Get enhanced cash flow report
description: |-
> **Categorization engine**
>
> The categorization engine uses machine learning and has been fully trained against Plaid and TrueLayer banking data sources. It is not fully trained against the Basiq banking data source.
The Enhanced Cash Flow Transactions endpoint provides a fully categorized list of banking transactions for a company. Accounts and transaction data are obtained from the company's banking data sources.
tags:
- Reports
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EnhancedCashFlowTransactions'
example:
reportInfo:
pageNumber: 1
pageSize: 10
totalResults: 2194
reportName: Cash flow transactions report
companyName: test
generatedDate: '2023-03-24T16:44:17.5302732Z'
dataSources:
- accounts:
- sourceRef:
sourceType: Banking
platformName: Banking Sandbox
accountProvider: Lloyds Bank
accountName: Business Savings Account
accountType: Debit
currency: GBP
currentBalance: 0
- sourceRef:
sourceType: Banking
platformName: Banking Sandbox
accountProvider: Lloyds Bank
accountName: Banking - Business Credit Card
accountType: Credit
currency: GBP
currentBalance: 0
- sourceRef:
sourceType: Banking
platformName: Banking Sandbox
accountProvider: Lloyds Bank
accountName: Business Undeposited Funds
accountType: Debit
currency: GBP
currentBalance: 0
- sourceRef:
sourceType: Banking
platformName: Banking Sandbox
accountProvider: Lloyds Bank
accountName: Business Current Account
accountType: Debit
currency: GBP
currentBalance: 0
reportItems:
- transactions:
- sourceRef:
sourceType: Banking
accountRef:
id: 4f78a6b0-e9bb-40f2-82fd-f3a2daa1fd0a
name: Business Current Account
id: ab5e07a0-5578-4d91-8421-2dc72713b74f
date: '2022-11-08T00:00:00'
description: Payment m86SDGpQr3
amount: -6905.44
currency: GBP
transactionCategory:
confidence: 52.53
levels:
- Expense
- Operating
confidences:
- 56
- 52.53
platformName: Shopify
counterpartyNames:
- Shopify
modifiedDate: '2022-11-08T12:00:00'
- sourceRef:
sourceType: Banking
accountRef:
id: 4f78a6b0-e9bb-40f2-82fd-f3a2daa1fd0a
name: Business Current Account
id: 9846bbed-46d3-472c-a848-1ce8ebea7213
date: '2022-11-08T00:00:00'
description: Payment from customer a5c68c7b-6825-46de-bf63-6ad23ef506a4
amount: 4332.84
currency: GBP
transactionCategory:
confidence: 88
levels:
- Expense
confidences:
- 88
platformName: Amazon
counterpartyNames:
- Amazon
- Amazon Marketplace
modifiedDate: '2022-11-08T12:00:00'
- sourceRef:
sourceType: Banking
accountRef:
id: 809b9470-c9fa-4257-bc9f-06a1dc7b0cbc
name: Business Undeposited Funds
id: 94b213fb-d742-435e-90f1-bfe723a076d5
date: '2022-11-08T00:00:00'
description: Payment from customer a5c68c7b-6825-46de-bf63-6ad23ef506a4
amount: 4034.3
currency: GBP
transactionCategory:
confidence: 61.08
levels:
- Income
- Revenue
confidences:
- 65
- 61.08
platformName: Shopify
counterpartyNames: []
modifiedDate: '2022-11-08T12:00:00'
- sourceRef:
sourceType: Banking
accountRef:
id: 4f78a6b0-e9bb-40f2-82fd-f3a2daa1fd0a
name: Business Current Account
id: cfceb7ff-eaa2-45b6-aca7-fa0e0b439161
date: '2022-11-08T00:00:00'
description: Payment to supplier 78792d13-90a0-4ea2-8e07-81c3c893997e
amount: -313.76
currency: GBP
transactionCategory:
confidence: 40.98
levels:
- Expense
- CostOfSales
confidences:
- 40.98
- 99.9
platformName: Amazon
counterpartyNames: []
modifiedDate: '2022-11-08T12:00:00'
- sourceRef:
sourceType: Banking
accountRef:
id: 809b9470-c9fa-4257-bc9f-06a1dc7b0cbc
name: Business Undeposited Funds
id: ba814f14-0fe3-41d0-9308-57f40642ac75
date: '2022-11-08T00:00:00'
description: Payment to supplier 46d2e1fb-b4e9-469c-814a-21ff8105a26e
amount: -614.4
currency: GBP
transactionCategory:
confidence: 55.84
levels:
- Income
- Revenue
confidences:
- 55.84
- 75.5
platformName: Zettle
counterpartyNames: []
modifiedDate: '2022-11-08T12:00:00'
- sourceRef:
sourceType: Banking
accountRef:
id: 4f78a6b0-e9bb-40f2-82fd-f3a2daa1fd0a
name: Business Current Account
id: e67cc30e-fd5c-4eea-8365-ec40dfdd3ef6
date: '2022-11-08T00:00:00'
description: Payment from customer a5c68c7b-6825-46de-bf63-6ad23ef506a4
amount: 5199.62
currency: GBP
transactionCategory:
confidence: 57.85
levels:
- Expense
confidences:
- 57.85
platformName: Amazon
counterpartyNames: []
modifiedDate: '2022-11-08T12:00:00'
- sourceRef:
sourceType: Banking
accountRef:
id: 4f78a6b0-e9bb-40f2-82fd-f3a2daa1fd0a
name: Business Current Account
id: e0f08a0b-3575-4dde-98c4-3c854028d2d2
date: '2022-11-08T00:00:00'
description: Payment to supplier 18ac18dc-945b-4083-9013-e8a100b999fa
amount: -21420.94
currency: GBP
transactionCategory:
confidence: 70.58
levels:
- Expense
- Operating
confidences:
- 70.58
- 100
platformName: Amazon
counterpartyNames: []
modifiedDate: '2022-11-08T12:00:00'
- sourceRef:
sourceType: Banking
accountRef:
id: 809b9470-c9fa-4257-bc9f-06a1dc7b0cbc
name: Business Undeposited Funds
id: 4b70d379-8284-4f44-bb37-c7935df950cc
date: '2022-11-08T00:00:00'
description: Payment to supplier 630a3f16-5f01-4986-ae6b-82333ec49449
amount: -30924.22
currency: GBP
transactionCategory:
confidence: 48.26
levels:
- Income
confidences:
- 48.26
platformName: DoorDash
counterpartyNames: []
modifiedDate: '2022-11-08T12:00:00'
- sourceRef:
sourceType: Banking
accountRef:
id: 809b9470-c9fa-4257-bc9f-06a1dc7b0cbc
name: Business Undeposited Funds
id: 76b73373-9345-472e-8edf-5be849d797fe
date: '2022-11-08T00:00:00'
description: Payment to supplier bQATU4eSb9
amount: -568.78
currency: GBP
transactionCategory:
confidence: 65.21
levels:
- Income
- Revenue
confidences:
- 65.21
- 100
platformName: Uber
counterpartyNames:
- Uber
modifiedDate: '2022-11-08T12:00:00'
- sourceRef:
sourceType: Banking
accountRef:
id: 809b9470-c9fa-4257-bc9f-06a1dc7b0cbc
name: Business Undeposited Funds
id: ee92fd6f-e0f7-4391-85fd-4b50921b973f
date: '2022-11-08T00:00:00'
description: Payment to supplier 9c37eb21-579a-4886-8296-3a853076b7bd
amount: -13050.79
currency: GBP
transactionCategory:
confidence: 92.33
levels:
- Income
- Revenue
confidences:
- 92.33
- 92.33
platformName: DoorDash
counterpartyNames:
- DoorDash
modifiedDate: '2022-11-08T12:00:00'
'400':
$ref: '#/components/responses/Malformed-Query'
'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-enhanced-cash-flow-transactions
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
'/companies/{companyId}/reports/enhancedInvoices':
parameters:
- $ref: '#/components/parameters/companyId'
get:
summary: Get enhanced invoices report
tags:
- Reports
responses:
'200':
description: OK
content:
application/json:
x-speakeasy-usage-example: true
schema:
$ref: '#/components/schemas/EnhancedInvoicesReport'
example:
reportInfo:
pageNumber: 1
pageSize: 10
totalResults: 101
reportName: Invoices report
companyName: Small Sandbox
generatedDate: '2023-05-10T10:50:23.9437977Z'
reportItems:
- id: 15221fa4-e91a-4f64-a2bb-caeab4db85a4
invoiceNumber: UDs5KlfE
customerRef:
id: ee4d0eee-063d-4c9f-8226-2c9a6a816249
customerName: Serena Keeling
issueDate: '2021-04-06T09:44:00'
dueDate: '2021-04-06T09:44:00'
status: Paid
currency: GBP
totalAmount: 7044.83
amountDue: 0
paidOnDate: '2021-04-06T09:44:00'
modifiedDate: '2022-04-11T13:49:37Z'
sourceModifiedDate: '2022-02-27T18:28:00'
payments: []
- id: 58aea1cb-5b31-4eed-ba16-489dfa67a831
invoiceNumber: 1IU1PMoT
customerRef:
id: 81e9c0df-3e5e-4180-b20c-c8e58100cdf3
customerName: Quinton Kovacek
issueDate: '2021-04-06T09:44:00'
dueDate: '2021-04-06T09:44:00'
status: Paid
currency: GBP
totalAmount: 3567.59
amountDue: 0
paidOnDate: '2021-04-06T09:44:00'
modifiedDate: '2022-04-11T13:49:37Z'
sourceModifiedDate: '2021-06-23T22:47:00'
payments: []
- id: 9ecd07bc-9cab-4516-bad0-a0cd565cdbaf
invoiceNumber: eEIWyPN4
customerRef:
id: c7326084-cd56-48e6-bcfa-be8919e024e1
customerName: Antwon Dach
issueDate: '2021-04-08T01:27:00'
dueDate: '2021-04-18T01:27:00'
status: Paid
currency: GBP
totalAmount: 153233.36
amountDue: 0
paidOnDate: '2021-04-10T12:31:00'
modifiedDate: '2022-08-01T09:44:59Z'
sourceModifiedDate: '2021-11-11T12:10:00'
payments:
- id: 0878e8be-6746-4347-80ba-5491328c8411
date: '2021-04-10T12:31:00'
paymentType: payments
amount: 153233.36
currency: GBP
currencyRate: 1
- id: 7cea078a-5c9a-4788-ae72-9bb60c5cc184
invoiceNumber: BXb8mYQW
customerRef:
id: 44e8516d-bcb0-459f-9e5d-7beaa56d57d0
customerName: Dolores Rath
issueDate: '2021-04-16T17:30:00'
dueDate: '2021-04-23T17:30:00'
status: Paid
currency: GBP
totalAmount: 12657.69
amountDue: 0
paidOnDate: '2021-04-23T17:30:00'
modifiedDate: '2022-04-11T13:49:37Z'
sourceModifiedDate: '2021-12-08T11:32:00'
payments:
- id: 17b42934-13f6-4738-a506-2e253b1a606f
date: '2021-04-23T17:30:00'
paymentType: payments
amount: 12657.69
currency: GBP
currencyRate: 1
- id: aa4503d7-fe01-49fe-ba42-259b421ac640
invoiceNumber: wdjwiL5B
customerRef:
id: 5cbaf1af-4f02-4206-85ab-c525bd9b4f99
customerName: Bryana Douglas
issueDate: '2021-04-20T06:46:00'
dueDate: '2021-04-27T06:46:00'
status: PartiallyPaid
currency: GBP
totalAmount: 12935.39
amountDue: 381.09
modifiedDate: '2022-04-11T13:49:37Z'
sourceModifiedDate: '2022-03-11T20:03:00'
payments:
- id: 1c03986b-9b6c-4220-bde6-4e3eba6cef9f
date: '2021-04-23T14:59:00'
paymentType: payments
amount: 12554.3
currency: GBP
currencyRate: 1
- id: d8a0e26e-4ec8-4fb5-887d-8b7531e3bedf
invoiceNumber: cTjJcu8x
customerRef:
id: 6f5290e5-70aa-4d0c-816e-9d2312cf217f
customerName: Brady Wilderman
issueDate: '2021-04-23T09:32:00'
dueDate: '2021-05-03T09:32:00'
status: Paid
currency: GBP
totalAmount: 21526.72
amountDue: 0
paidOnDate: '2021-05-03T09:32:00'
modifiedDate: '2022-04-11T13:49:37Z'
sourceModifiedDate: '2021-03-12T22:37:00'
payments:
- id: 93c9c11b-3ec0-4314-85f6-0751763e752a
date: '2021-05-03T09:32:00'
paymentType: payments
amount: 21506.72
currency: GBP
currencyRate: 1
- id: 06890e67-35fb-4276-9857-95db40cfd15d
invoiceNumber: htXJuUDb
customerRef:
id: 44e8516d-bcb0-459f-9e5d-7beaa56d57d0
customerName: Dolores Rath
issueDate: '2021-05-01T23:23:00'
dueDate: '2021-05-11T23:23:00'
status: PartiallyPaid
currency: GBP
totalAmount: 7151.41
amountDue: 1225.06
modifiedDate: '2022-08-01T09:44:59Z'
sourceModifiedDate: '2022-02-24T23:02:00'
payments:
- id: 82865077-0857-46db-b9a1-6d21da43b6aa
date: '2021-05-04T17:57:00'
paymentType: payments
amount: 5926.35
currency: GBP
currencyRate: 1
- id: 160e8b51-1fa0-46b9-98fe-1ff5399ce99b
invoiceNumber: 9wegEXpG
customerRef:
id: 44e8516d-bcb0-459f-9e5d-7beaa56d57d0
customerName: Dolores Rath
issueDate: '2021-05-18T08:53:00'
dueDate: '2021-05-25T08:53:00'
status: PartiallyPaid
currency: GBP
totalAmount: 22522.34
amountDue: 14408.54
modifiedDate: '2022-04-11T13:49:37Z'
sourceModifiedDate: '2022-01-13T07:52:00'
payments:
- id: 75bd7205-bc12-4517-9964-aae159fdfaee
date: '2021-05-23T04:04:00'
paymentType: payments
amount: 8113.8
currency: GBP
currencyRate: 1
- id: 5a934955-561d-436a-a564-fd624a79f54c
invoiceNumber: l7YwGxG7
customerRef:
id: cc96af36-e2f5-49f7-bf40-271503f45071
customerName: Ignacio Moore
issueDate: '2021-05-25T19:51:00'
dueDate: '2021-06-04T19:51:00'
status: Paid
currency: GBP
totalAmount: 11047.08
amountDue: 0
paidOnDate: '2021-05-28T07:31:00'
modifiedDate: '2022-04-11T13:49:37Z'
sourceModifiedDate: '2021-08-06T05:50:00'
payments:
- id: 608fd022-f7d0-44a9-90c4-bebe0573f206
date: '2021-05-28T07:31:00'
paymentType: payments
amount: 11047.08
currency: GBP
currencyRate: 1
- id: 17690788-2936-46b5-ba46-ba6a36a87483
invoiceNumber: ntH1cRYz
customerRef:
id: e1ecc8f2-8a63-4fe9-97c9-c87fd90ca0a6
customerName: Freida Ebert
issueDate: '2021-05-27T19:07:00'
dueDate: '2021-06-03T19:07:00'
status: PartiallyPaid
currency: GBP
totalAmount: 7191.32
amountDue: 5036.83
modifiedDate: '2022-04-11T13:49:37Z'
sourceModifiedDate: '2021-03-27T08:54:00'
payments:
- id: a343b2a0-d327-41b0-993e-7b6b92fde425
date: '2021-06-03T19:07:00'
paymentType: payments
amount: 2154.49
currency: GBP
currencyRate: 1
'400':
$ref: '#/components/responses/Malformed-Query'
'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-enhanced-invoices-report
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
description: Gets a list of invoices linked to the corresponding banking transaction
'/data/companies/{companyId}/connections/{connectionId}/assess/commerceMetrics/revenue':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: Get commerce revenue metrics
tags:
- Reports
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Report'
example:
- reportInfo:
name: revenue
displayName: Revenue
dimensions:
- index: 0
displayName: Period
type: datespan
items:
- index: 0
displayName: Period 0
start: '2022-01-01'
end: '2022-12-31'
- index: 1
displayName: Revenue metrics
type: string
items:
- index: 0
value: Revenue
- index: 1
value: Revenue growth
measures:
- displayName: Value
units: GBP
index: 0
type: currency
- displayName: Percentage change vs. previous period
units: '%'
index: 1
type: percentage
reportData:
- dimension: 0
dimensionDisplayName: Period
item: 0
itemDisplayName: Period 0
components:
- dimension: 1
dimensionDisplayName: Revenue metrics
item: 0
itemDisplayName: Revenue
measures:
- index: 0
measureDisplayName: Value
value: 2392.48
- dimension: 1
dimensionDisplayName: Revenue metrics
item: 1
itemDisplayName: Revenue growth
measures:
- index: 1
measureDisplayName: Percentage change vs. previous period
value: 276.65
'400':
$ref: '#/components/responses/Bad-Request'
'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-commerce-revenue-metrics
x-speakeasy-name-override: get-commerce-revenue-metrics
description: 'Get the revenue and revenue growth for a specific company connection, over one or more periods of time.'
parameters:
- $ref: '#/components/parameters/reportDate'
- $ref: '#/components/parameters/periodLength'
- $ref: '#/components/parameters/numberOfPeriodsRequired'
- $ref: '#/components/parameters/periodUnit'
- $ref: '#/components/parameters/includeDisplayNames'
'/data/companies/{companyId}/connections/{connectionId}/assess/commerceMetrics/orders':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: Get orders report
tags:
- Reports
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Report'
example:
- reportInfo:
name: orders
displayName: Orders
dimensions:
- index: 0
displayName: Period
type: datespan
items:
- index: 0
displayName: Period 0
start: '2022-01-01'
end: '2022-12-31'
- index: 1
displayName: Order metrics
type: string
items:
- index: 0
value: Number of orders
- index: 1
value: Total value
- index: 2
value: Average order value
measures:
- displayName: Count
index: 0
type: int
- displayName: Value
units: GBP
index: 1
type: currency
reportData:
- dimension: 0
dimensionDisplayName: Period
item: 0
itemDisplayName: Period 0
components:
- dimension: 1
dimensionDisplayName: Order metrics
item: 0
itemDisplayName: Number of orders
measures:
- index: 0
measureDisplayName: Count
value: 94
- dimension: 1
dimensionDisplayName: Order metrics
item: 1
itemDisplayName: Total value
measures:
- index: 1
measureDisplayName: Value
value: 3315.18
- dimension: 1
dimensionDisplayName: Order metrics
item: 2
itemDisplayName: Average order value
measures:
- index: 1
measureDisplayName: Value
value: 35.27
'400':
$ref: '#/components/responses/Bad-Request'
'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-commerce-orders-metrics
x-speakeasy-name-override: get-commerce-orders-metrics
description: 'Gets the order information for a specific company connection, over one or more periods of time.'
parameters:
- $ref: '#/components/parameters/reportDate'
- $ref: '#/components/parameters/periodLength'
- $ref: '#/components/parameters/numberOfPeriodsRequired'
- $ref: '#/components/parameters/periodUnit'
- $ref: '#/components/parameters/includeDisplayNames'
'/data/companies/{companyId}/connections/{connectionId}/assess/commerceMetrics/refunds':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: Get refunds report
tags:
- Reports
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Report'
example:
- reportInfo:
name: refunds
displayName: Refunds
dimensions:
- index: 0
displayName: Period
type: datespan
items:
- index: 0
displayName: Period 0
start: '2022-01-01'
end: '2022-12-31'
- index: 1
displayName: Refund metrics
type: string
items:
- index: 0
value: Number of refunds
- index: 1
value: Value of refunds
- index: 2
value: Refund rate
measures:
- displayName: Count
index: 0
type: int
- displayName: Value
units: GBP
index: 1
type: currency
- displayName: Percentage
units: '%'
index: 2
type: percentage
reportData:
- dimension: 0
dimensionDisplayName: Period
item: 0
itemDisplayName: Period 0
components:
- dimension: 1
dimensionDisplayName: Refund metrics
item: 0
itemDisplayName: Number of refunds
measures:
- index: 0
measureDisplayName: Count
value: 39
- dimension: 1
dimensionDisplayName: Refund metrics
item: 1
itemDisplayName: Value of refunds
measures:
- index: 1
measureDisplayName: Value
value: 642.82
- dimension: 1
dimensionDisplayName: Refund metrics
item: 2
itemDisplayName: Refund rate
measures:
- index: 2
measureDisplayName: Percentage
value: 0.41
'400':
$ref: '#/components/responses/Bad-Request'
'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-commerce-refunds-metrics
x-speakeasy-name-override: get-commerce-refunds-metrics
description: 'Gets the refunds information for a specific company connection, over one or more periods of time.'
parameters:
- $ref: '#/components/parameters/reportDate'
- $ref: '#/components/parameters/periodLength'
- $ref: '#/components/parameters/numberOfPeriodsRequired'
- $ref: '#/components/parameters/periodUnit'
- $ref: '#/components/parameters/includeDisplayNames'
'/data/companies/{companyId}/connections/{connectionId}/assess/commerceMetrics/customerRetention':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: Get customer retention metrics
tags:
- Reports
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Report'
example:
- reportInfo:
name: customer_retention
displayName: Customer Retention
dimensions:
- index: 0
displayName: Period
type: datespan
items:
- index: 0
displayName: Period 0
start: '2022-01-01'
end: '2022-12-31'
- index: 1
displayName: Customer retention metrics
type: string
items:
- index: 0
value: Existing customers
- index: 1
value: New customers
- index: 2
value: Total customers
- index: 3
value: Retention rate
- index: 4
value: Repeat rate
measures:
- displayName: Count
index: 0
type: int
- displayName: Percentage
index: 1
type: percentage
reportData:
- dimension: 0
dimensionDisplayName: Period
item: 0
itemDisplayName: Period 0
components:
- dimension: 1
dimensionDisplayName: Customer retention metrics
item: 0
itemDisplayName: Existing customers
measures:
- index: 0
measureDisplayName: Count
value: 13
- dimension: 1
dimensionDisplayName: Customer retention metrics
item: 1
itemDisplayName: New customers
measures:
- index: 0
measureDisplayName: Count
value: 47
- dimension: 1
dimensionDisplayName: Customer retention metrics
item: 2
itemDisplayName: Total customers
measures:
- index: 0
measureDisplayName: Count
value: 60
- dimension: 1
dimensionDisplayName: Customer retention metrics
item: 3
itemDisplayName: Retention rate
measures:
- index: 1
measureDisplayName: Percentage
value: 0
- dimension: 1
dimensionDisplayName: Customer retention metrics
item: 4
itemDisplayName: Repeat rate
measures:
- index: 1
measureDisplayName: Percentage
value: 21.67
'400':
$ref: '#/components/responses/Bad-Request'
'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-commerce-customer-retention-metrics
x-speakeasy-name-override: get-commerce-customer-retention-metrics
description: 'Gets the customer retention metrics for a specific company connection, over one or more periods of time.'
parameters:
- $ref: '#/components/parameters/reportDate'
- $ref: '#/components/parameters/periodLength'
- $ref: '#/components/parameters/numberOfPeriodsRequired'
- $ref: '#/components/parameters/periodUnit'
- $ref: '#/components/parameters/includeDisplayNames'
'/data/companies/{companyId}/connections/{connectionId}/assess/commerceMetrics/lifetimeValue':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: Get lifetime value metric
tags:
- Reports
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Report'
example:
- reportInfo:
name: lifetime_value
displayName: Lifetime Value
dimensions:
- index: 0
displayName: Period
type: datespan
items:
- index: 0
displayName: Period 0
start: '2022-01-01'
end: '2022-12-31'
- index: 1
displayName: Lifetime value metrics
type: string
items:
- index: 0
value: Lifetime value
measures:
- displayName: Value
units: GBP
index: 0
type: currency
reportData:
- dimension: 0
dimensionDisplayName: Period
item: 0
itemDisplayName: Period 0
components:
- dimension: 1
dimensionDisplayName: Lifetime value metrics
item: 0
itemDisplayName: Lifetime value
measures:
- index: 0
measureDisplayName: Value
value: 3782.07
'400':
$ref: '#/components/responses/Bad-Request'
'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-commerce-lifetime-value-metrics
x-speakeasy-name-override: get-commerce-lifetime-value-metrics
description: 'Gets the lifetime value metric for a specific company connection, over one or more periods of time.'
parameters:
- $ref: '#/components/parameters/reportDate'
- $ref: '#/components/parameters/periodLength'
- $ref: '#/components/parameters/numberOfPeriodsRequired'
- $ref: '#/components/parameters/periodUnit'
- $ref: '#/components/parameters/includeDisplayNames'
'/data/companies/{companyId}/connections/{connectionId}/assess/subscriptions/process':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: Generate key subscription revenue metrics
tags:
- Reports
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Report'
'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: request-recurring-revenue-metrics
description: Requests production of key subscription revenue metrics.
'/data/companies/{companyId}/connections/{connectionId}/assess/subscriptions/mrr':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: Get key subscription revenue metrics
tags:
- Reports
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Report'
'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-recurring-revenue-metrics
x-speakeasy-name-override: get-recurring-revenue-metrics
description: Gets key metrics for subscription revenue.
'/data/companies/{companyId}/connections/{connectionId}/assess/accountingMetrics/marketing':
parameters:
- $ref: '#/components/parameters/companyId'
- $ref: '#/components/parameters/connectionId'
get:
summary: Get marketing metrics report
tags:
- Excel reports
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Report'
example:
- reportInfo: null
name: marketing_metrics
displayName: Marketing metrics
dimensions:
- index: 0
displayName: Period
type: datespan
items:
- index: 0
displayName: Period 0
start: '2022-01-01'
end: '2022-12-31'
- index: 1
displayName: Marketing metrics
type: string
items:
- index: 0
value: Marketing to revenue
- index: 1
value: Marketing to expense
measures:
- displayName: Percentage
units: '%'
index: 0
type: percentage
- displayName: Percentage change vs previous period
units: '%'
index: 1
type: percentage
reportData:
- dimension: 0
dimensionDisplayName: Period
item: 0
itemDisplayName: Period 0
components:
- dimension: 1
dimensionDisplayName: Marketing metrics
item: 0
itemDisplayName: Marketing to revenue
measures:
- index: 0
measureDisplayName: Percentage
value: 564.17
- index: 1
measureDisplayName: Percentage change vs previous period
value: 8.33
- dimension: 1
dimensionDisplayName: Marketing metrics
item: 1
itemDisplayName: Marketing to expense
measures:
- index: 0
measureDisplayName: Percentage
value: 27.63
- index: 1
measureDisplayName: Percentage change vs previous period
value: 0.12
'400':
$ref: '#/components/responses/Bad-Request'
'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-accounting-marketing-metrics
x-speakeasy-name-override: get-accounting-marketing-metrics
description: |-
Get the marketing metrics from an accounting source for a given company.
Request an Excel report for download.
parameters:
- $ref: '#/components/parameters/reportDate'
- $ref: '#/components/parameters/periodLength'
- $ref: '#/components/parameters/numberOfPeriodsRequired'
- $ref: '#/components/parameters/periodUnit'
- $ref: '#/components/parameters/includeDisplayNames'
- schema:
type: boolean
in: query
name: showInputValues
description: 'If set to true, then the system includes the input values within the response.'
'/data/companies/{companyId}/assess/excel':
parameters:
- $ref: '#/components/parameters/companyId'
post:
summary: Generate Excel report
tags:
- Excel reports
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ExcelStatus'
'400':
$ref: '#/components/responses/Bad-Request'
'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-excel-report
description: Generate an Excel report which can subsequently be downloaded.
parameters:
- $ref: '#/components/parameters/excelReportType'
get:
summary: Get Excel report status
tags:
- Excel reports
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ExcelStatus'
'400':
$ref: '#/components/responses/Malformed-Query'
'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-excel-report-generation-status
description: Returns the status of the latest report requested.
parameters:
- $ref: '#/components/parameters/excelReportType'
'/data/companies/{companyId}/assess/excel/download':
parameters:
- $ref: '#/components/parameters/companyId'
get:
summary: Download Excel report
tags:
- Excel reports
responses:
'200':
description: OK
content:
application/octet-stream:
schema:
type: object
'400':
$ref: '#/components/responses/Bad-Request'
'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-excel-report
description: Download the previously generated Excel report to a local drive.
parameters:
- $ref: '#/components/parameters/excelReportType'
'/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/codat-api#/operations/refresh-company-data) recently before calling the endpoint.
tags:
- Reports
responses:
'202':
description: Accepted
'400':
$ref: '#/components/responses/Bad-Request'
'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/codat-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/codat-api#/operations/refresh-company-data) recently before calling the endpoint.
tags:
- Reports
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LoanTransactions'
'400':
$ref: '#/components/responses/Bad-Request'
'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/codat-api#/operations/refresh-company-data) recently before calling the endpoint.
tags:
- Reports
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/codat-api#/schemas/LoanSummary) for each valid data connection.
Make sure you have [synced a company](https://docs.codat.io/codat-api#/operations/refresh-company-data) recently before calling the endpoint.
tags:
- Reports
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
webhooks:
Account categories updated:
post:
requestBody:
description: Triggered anytime that Codat updates the suggested fields or a user updates the confirmed fields.
content:
application/json:
schema:
$ref: '#/components/schemas/AccountCategoriesUpdatedWebhook'
responses:
'200':
description: Return a 200 status to indicate that the webhook was received successfully.
components:
schemas:
AccountCategoriesUpdatedWebhook:
title: Account categories updated webhook
description: Webhook request body for the "Account categories updated" event.
x-internal: true
type: object
properties:
ClientId:
title: Client ID
type: string
format: uuid
description: Unique identifier for your client in Codat.
ClientName:
type: string
description: Name of your client in Codat.
CompanyId:
$ref: '#/components/parameters/companyId/schema'
DataConnectionId:
$ref: '#/components/parameters/connectionId/schema'
RuleId:
type: string
format: uuid
description: Unique identifier for the rule.
deprecated: true
RuleType:
type: string
x-stoplight:
id: 34d52a089f08a
description: The type of rule.
AlertId:
type: string
format: uuid
description: Unique identifier of the webhook event.
Message:
type: string
description: A human-readable message about the webhook.
Data:
$ref: '#/components/schemas/AccountCategoriesUpdatedWebhook/definitions/AccountCategoriesUpdatedWebhookData'
definitions:
AccountCategoriesUpdatedWebhookData:
type: object
title: Account categories updated webhook data
properties:
modifiedDate:
description: The date on which the company's account categories were last modified in Codat.
title: Date
type: string
example: '2022-10-23'
examples:
- ClientId: bae71d36-ff47-420a-b4a6-f8c9ddf41140
ClientName: Bank of Dave
CompanyId: 8a210b68-6988-11ed-a1eb-0242ac120002
DataConnectionId: 2e9d2c44-f675-40ba-8049-353bfcb5e171
RuleId: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
RuleType: Account Categories Updated
AlertId: a9367074-b5c3-42c4-9be4-be129f43577e
Message: Account categories updated for company f1c35bdc-1546-41b9-baf4-3f31135af968.
Data:
modifiedDate: '2019-08-24T14:15:22Z'
Currency:
title: Currency
x-internal: true
type: string
description: |-
The currency data type in Codat is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, e.g. _GBP_.
## Unknown currencies
In line with the ISO 4217 specification, the code _XXX_ is used when the data source does not return a currency for a transaction.
There are only a very small number of edge cases where this currency code is returned by the Codat system.
format: ISO4217
examples:
- GBP
- USD
- EUR
CurrencyRate:
title: Currency rate
type: number
format: decimal
nullable: true
description: |-
Rate to convert the total amount of the payment into the base currency for the company at the time of the payment.
Currency rates in Codat are implemented as the multiple of foreign currency units to each base currency unit.
It is not possible to perform the currency conversion with two or more non-base currencies participating in the transaction. For example, if a company's base currency is USD, and it has a bill issued in EUR, then the bill payment must happen in USD or EUR.
Where the currency rate is provided by the underlying accounting software, it will be available from Codat with the same precision (up to a maximum of 9 decimal places).
For accounting software which do not provide an explicit currency rate, it is calculated as `baseCurrency / foreignCurrency` and will be returned to 9 decimal places.
## Examples with base currency of GBP
| Foreign Currency | Foreign Amount | Currency Rate | Base Currency Amount (GBP) |
| :--------------- | :------------- | :------------ | :------------------------- |
| **USD** | $20 | 0.781 | £15.62 |
| **EUR** | €20 | 0.885 | £17.70 |
| **RUB** | ₽20 | 0.011 | £0.22 |
## Examples with base currency of USD
| Foreign Currency | Foreign Amount | Currency Rate | Base Currency Amount (USD) |
| :--------------- | :------------- | :------------ | :------------------------- |
| **GBP** | £20 | 1.277 | $25.54 |
| **EUR** | €20 | 1.134 | $22.68 |
| **RUB** | ₽20 | 0.015 | $0.30 |
### Integration-specific details
| Integration | Scenario | System behavior |
|-------------------|-------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| QuickBooks Online | Transaction currency differs from base currency | If currency rate value is left `null`, a rate of 1 will be used by QBO by default. To override this, specify a currencyRate in the request body. |
DataIntegrityDetails:
title: Data integrity detail
type: object
properties:
id:
type: string
description: ID GUID of the transaction.
type:
type: string
description: The data type of the record.
connectionId:
type: string
format: uuid
description: ID GUID representing the connection of the accounting or banking platform.
readOnly: true
date:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment/properties/date'
description: The date of the transaction.
description:
type: string
description: The transaction description.
amount:
type: number
format: decimal
description: The transaction value.
currency:
$ref: '#/components/schemas/Currency'
description: The currency of the transaction.
matches:
type: array
items:
$ref: '#/components/schemas/DataIntegrityDetails/definitions/dataIntegrityMatch'
definitions:
dataIntegrityMatch:
type: object
properties:
id:
type: string
description: ID GUID of the transaction.
type:
type: string
description: 'The data type which the data type in the URL has been matched against. For example, if you''ve matched accountTransactions and banking-transactions, and you call this endpoint with accountTransactions in the URL, this property would be banking-transactions.'
connectionId:
type: string
description: ID GUID representing the connection of the accounting or banking platform.
format: uuid
date:
type: string
description: The date of the transaction.
description:
type: string
description: The transaction description.
amount:
type: string
description: The transaction value.
currency:
$ref: '#/components/schemas/Currency'
description: The currency of the transaction.
DataIntegrityStatus:
title: Data integrity status
type: object
allOf:
- $ref: '#/components/schemas/DataIntegritySummary/definitions/dataIntegrityType'
- type: object
properties:
statusInfo:
$ref: '#/components/schemas/DataIntegrityStatus/definitions/dataIntegrityStatusInfo'
connectionIds:
$ref: '#/components/schemas/DataIntegrityStatus/definitions/dataIntegrityConnectionId'
amounts:
$ref: '#/components/schemas/DataIntegrityStatus/definitions/dataIntegrityAmounts'
dates:
$ref: '#/components/schemas/DataIntegrityStatus/definitions/dataIntegrityDates'
definitions:
dataIntegrityStatusInfo:
type: object
properties:
lastMatched:
type: string
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment/properties/date'
description: The date the matching algorithm last ran against the company’s data type specified.
readOnly: true
currentStatus:
$ref: '#/components/schemas/DataIntegrityStatus/definitions/integrityStatus'
statusMessage:
type: string
description: Detailed explanation supporting the status value.
dataIntegrityConnectionId:
type: object
properties:
source:
type: array
description: An array of strings. The connection IDs for the type specified in the url.
items:
type: string
target:
type: array
description: An array of strings. The connection IDs for the type being matched to.
items:
type: string
dataIntegrityAmounts:
type: object
description: 'Only returned for transactions. For accounts, there is nothing returned.'
properties:
min:
type: number
format: decimal
description: Lowest value of transaction set.
max:
type: number
format: decimal
description: Highest value of transaction set.
currency:
$ref: '#/components/schemas/Currency'
dataIntegrityDates:
type: object
description: 'Only returned for transactions. For accounts, there is nothing returned.'
properties:
minDate:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment/properties/date'
description: Earliest date of transaction set.
readOnly: true
maxDate:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment/properties/date'
description: Latest date of transaction set.
readOnly: true
minOverlappingDate:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment/properties/date'
description: Earliest date where transactions exist in both accounting and banking platforms.
readOnly: true
maxOverlappingDate:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment/properties/date'
description: Latest date where transactions exist in both account and banking platforms.
readOnly: true
integrityStatus:
type: string
enum:
- Unknown
- DoesNotExist
- Error
- Complete
description: The current status of the most recently run matching algorithm.
examples:
- type: string
statusInfo:
lastMatched: '2021-10-24T14:15:22Z'
currentStatus: Unknown
statusMessage: string
connectionIds:
source:
- d5a8d1b2-b38a-4e44-8641-548ad43be6bb
- da8c9f39-8af9-4a98-964b-f1e207942837
target:
- 3d7ce25a-c107-44bc-8e0c-36c10bdd14e0
- a5300eac-01fa-4a77-b5b0-ea0b86a3be69
amounts:
min: 130
max: 2450
currency: GBP
dates:
minDate: '2021-09-17T12:09:33.441Z'
maxDate: '2021-12-16T12:12:53.441Z'
minOverlappingDate: '2021-09-30T12:09:13.441Z'
maxOverlappingDate: '2021-11-27T12:19:33.441Z'
DataIntegritySummary:
title: Data integrity summary
type: object
allOf:
- $ref: '#/components/schemas/DataIntegritySummary/definitions/dataIntegrityType'
- type: object
properties:
byAmount:
$ref: '#/components/schemas/DataIntegritySummary/definitions/dataIntegrityByAmount'
byCount:
$ref: '#/components/schemas/DataIntegritySummary/definitions/dataIntegrityByCount'
definitions:
dataIntegrityType:
type: object
properties:
type:
type: string
description: 'The data type which the data type in the URL has been matched against. For example, if you''ve matched accountTransactions and banking-transactions, and you call this endpoint with accountTransactions in the URL, this property would be banking-transactions.'
dataIntegrityByAmount:
title: Data integrity by amount
type: object
properties:
matchPercentage:
type: number
format: decimal
description: The percentage of the absolute value of transactions of the type specified in the route which have a match.
unmatched:
type: number
format: decimal
description: The sum of the absolute value of transactions of the type specified in the route which don't have a match.
matched:
type: number
format: decimal
description: The sum of the absolute value of transactions of the type specified in the route which have a match.
total:
type: number
format: decimal
description: The total of unmatched and matched.
currency:
$ref: '#/components/schemas/Currency'
dataIntegrityByCount:
title: Data integrity by count
type: object
properties:
matchPercentage:
type: number
format: decimal
description: The percentage of records of the type specified in the route which have a match.
unmatched:
type: number
format: decimal
description: The number of records of the type specified in the route which don't have a match.
matched:
type: number
format: decimal
description: The number of records of the type specified in the route which do have a match.
total:
type: number
format: decimal
description: The total of unmatched and matched.
Details:
title: Data integrity details
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/DataIntegrityDetails'
- $ref: '#/components/schemas/PagingInfo'
EnhancedCashFlowTransactions:
title: Enhanced cash flow transactions
description: |-
> **Categorization engine**
>
> The categorization engine uses machine learning and has been fully trained against Plaid and TrueLayer banking data sources. It is not fully trained against the Basiq banking data source.
The Enhanced Cash Flow Transactions endpoint provides a fully categorized list of banking transactions for a company. Accounts and transaction data are obtained from the company's banking data sources.
type: object
properties:
reportInfo:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/reportInfo'
dataSources:
type: array
items:
$ref: '#/components/schemas/EnhancedCashFlowTransactions/definitions/dataSource'
reportItems:
type: array
items:
$ref: '#/components/schemas/EnhancedCashFlowTransactions/definitions/enhancedCashFlowItem'
definitions:
dataSource:
type: object
properties:
accounts:
description: 'An array containing bank account data for each connected banking data source that have the following data types enabled: `banking-accounts`, `banking-transactions`.'
type: array
items:
$ref: '#/components/schemas/EnhancedCashFlowTransactions/definitions/accounts'
accounts:
title: Accounts
type: object
properties:
sourceRef:
title: Report source reference
description: A source reference containing the `sourceType` object "Banking".
type: object
properties:
sourceType:
description: The data source type.
type: string
examples:
- Example:
value:
sourceRef:
sourceType: Banking
platformName:
description: 'Name of the banking data source, e.g. "Plaid".'
type: string
accountProvider:
description: The bank or other financial institution providing the account.
type: string
accountName:
description: The name of the account according to the provider.
type: string
accountType:
description: 'The type of banking account, e.g. credit or debit.'
type: string
currency:
$ref: '#/components/schemas/Currency'
description: The currency code for the bank account.
currentBalance:
description: The balance of the bank account.
type: number
format: decimal
enhancedCashFlowItem:
type: object
properties:
transactions:
description: An array of transaction data.
type: array
items:
title: Cash flow transaction
type: object
properties:
id:
description: The unique identifier of the bank transaction.
type: string
date:
description: The date the bank transaction was posted.
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment/properties/date'
description:
description: The description of the bank transaction.
type: string
amount:
description: The bank transaction amount.
type: number
format: decimal
currency:
$ref: '#/components/schemas/Currency'
description: The currency code for bank transaction.
transactionCategory:
description: Contains an array of category levels.
$ref: '#/components/schemas/EnhancedCashFlowTransactions/definitions/enhancedCashFlowItem/properties/transactions/items/definitions/transactionCategory'
platformName:
description: Returns the payment processor responsible for the transaction.
type: string
counterpartyNames:
description: An array of counterparty names involved in the transaction.
type: array
items:
type: string
sourceRef:
$ref: '#/components/schemas/EnhancedCashFlowTransactions/definitions/accounts/properties/sourceRef'
accountRef:
$ref: '#/components/schemas/EnhancedCashFlowTransactions/definitions/enhancedCashFlowItem/properties/transactions/items/definitions/accountRef'
modifiedDate:
description: The date the bank transaction was last modified.
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment/properties/date'
definitions:
accountRef:
title: Account reference
description: An account reference containing the account id and name.
type: object
properties:
id:
description: The id of the account.
type: string
name:
description: The name of the account.
type: string
examples:
- Example:
value:
accountRef:
id: 4f78a6b0-e9bb-40f2-82fd-f3a2daa1fd0a
name: Business Current Account
transactionCategory:
title: Transaction category
type: object
properties:
confidence:
description: Returns the aggregate confidence of the suggested category for the transaction. The value is between 0 and 100.
type: number
format: decimal
confidences:
description: An ordered array of category level confidences where each element is the confidence of the corresponding item in the `levels` array.
type: array
items:
type: number
format: decimal
levels:
description: The suggested category is an ordered array of category levels where each element (or level) is a subcategory of the previous element (or level).
type: array
items:
type: string
examples:
- Example:
value:
transactionCategory:
confidence: 92.7
levels:
- Asset
- Current
- Bank
- BankTransfers
- ShareholderTransfers
confidences:
- 92.7
- 95
- 96
- 97.5
- 100
examples:
- reportInfo:
pageNumber: 1
pageSize: 100
totalResults: 2401
reportName: Cash Flow transactions report
companyName: Example Company
generatedDate: '2023-01-25T22:36:05.125Z'
dataSources:
- accounts:
- sourceRef:
sourceType: Banking
id: 4f78a6b0-e9bb-40f2-82fd-f3a2daa1fd0a
platformName: Plaid
accountProvider: Bank of Sandbox
accountName: Business Current Account
accountType: Debit
currency: USD
currentBalance: 1000
identifiers:
- type: Debit
subType: Current
number: 12345678
bankCode: 123456
iban: US123456789
bic: US123456789
maskedAccountNumber: 1234
- sourceRef:
sourceType: Banking
id: 12345678-1234-1234-1234-123456789012
platformName: Plaid
accountProvider: Bank of Sandbox
accountName: Business Saving Account
accountType: Debit
currency: USD
currentBalance: 5321
identifiers:
- type: Debit
subType: Saving
number: 87654321
bankCode: 654321
iban: US987654321
bic: US987654321
maskedAccountNumber: 4321
reportItems:
- transactions:
- sourceRef:
sourceType: Banking
- accountRef:
id: 4f78a6b0-e9bb-40f2-82fd-f3a2daa1fd0a
name: Business Current Account
id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
date: '2023-01-25'
description: Payment to supplier
amount: 100
currency: USD
transactionCategory:
confidence: 92.7
levels:
- Asset
- Current
- Bank
confidences:
- 92.7
- 95
- 96
platformName: Plaid
counterpartyNames:
- Counterparty
modifiedDate: '2023-01-25T22:36:05.125Z'
- sourceRef:
sourceType: Banking
- accountRef:
id: 12345678-1234-1234-1234-123456789012
name: Business Saving Account
id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
date: '2023-01-25'
description: Payment to supplier
amount: 100
currency: USD
transactionCategory: null
confidence: 92.7
levels:
- Expense
- Operating
confidences:
- 92.7
- 95
platformName: Plaid
counterpartyNames: []
modifiedDate: '2023-01-25T22:36:05.125Z'
EnhancedInvoicesReport:
title: Enhanced invoices report
description: The enhanced invoices report takes the key elements of the Invoices report verifying those marked as paid in the accounting software have actually been paid by matching with the bank statement.
type: object
properties:
reportInfo:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/reportInfo'
reportItems:
type: array
items:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/enhancedInvoiceReportItem'
definitions:
lendingCustomerRef:
type: object
properties:
id:
minLength: 1
type: string
description: '`id` from the Customers data type.'
customerName:
type: string
nullable: true
description: '`customerName` from the Customer data type.'
payment:
title: Enhanced invoice payment item
type: object
properties:
id:
type: string
description: 'ID of the invoice, which may be a GUID but it may be something else depending on the accounting software.'
date:
title: Date time
type: string
examples:
- 2022-10-23T00:00:00.000Z
- 2022-10-23T00:00:00.000Z
description: |-
In Codat's data model, dates and times are represented using the ISO 8601 standard. Date and time fields are formatted as strings; for example:
```
2020-10-08T22:40:50Z
2021-01-01T00:00:00
```
When syncing data that contains `DateTime` fields from Codat, make sure you support the following cases when reading time information:
- Coordinated Universal Time (UTC): `2021-11-15T06:00:00Z`
- Unqualified local time: `2021-11-15T01:00:00`
- UTC time offsets: `2021-11-15T01:00:00-05:00`
> Time zones
>
> Not all dates from Codat will contain information about time zones.
> Where it is not available from the underlying platform, Codat will return these as times local to the business whose data has been synced.
paymentType:
type: string
description: The type of payment.
amount:
type: number
format: decimal
description: Payment amount.
currency:
$ref: '#/components/schemas/Currency'
currencyRate:
$ref: '#/components/schemas/CurrencyRate'
bankingTransactionRefs:
type: array
items:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/bankingTransactionRef'
bankingTransactionRef:
title: Banking transaction reference
type: object
properties:
id:
type: string
description: Unique identifier for the bank transaction.
dataConnectionId:
type: string
description: Unique identifier of the bank transaction's connection.
accountId:
type: string
description: Unique identifier of the bank transaction's account.
accountName:
type: string
description: Name given to account.
date:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment/properties/date'
description:
type: string
description: Description given to bank transaction.
amount:
type: number
description: Bank transaction amount.
format: decimal
invoiceStatus:
type: string
enum:
- Unknown
- Draft
- Submitted
- PartiallyPaid
- Paid
- Void
description: |-
Current state of the invoice:
- `Draft` - Invoice hasn't been submitted to the supplier. It may be in a pending state or is scheduled for future submission, for example by email.
- `Submitted` - Invoice is no longer a draft. It has been processed and, or, sent to the customer. In this state, it will impact the ledger. It also has no payments made against it (amountDue == totalAmount).
- `PartiallyPaid` - The balance paid against the invoice is positive, but less than the total invoice amount (0 < amountDue < totalAmount).
- `Paid` - Invoice is paid in full. This includes if the invoice has been credited or overpaid (amountDue == 0).
- `Void` - An invoice can become Void when it's deleted, refunded, written off, or cancelled. A voided invoice may still be PartiallyPaid, and so all outstanding amounts on voided invoices are removed from the accounts receivable account.
enhancedInvoiceReportItem:
title: Enhanced invoice report item
type: object
allOf:
- type: object
properties:
id:
type: string
description: 'ID of the invoice, which may be a GUID but it may be something else depending on the accounting software.'
invoiceNumber:
type: string
description: Invoice number.
customerRef:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/lendingCustomerRef'
issueDate:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment/properties/date'
dueDate:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment/properties/date'
status:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/invoiceStatus'
currency:
$ref: '#/components/schemas/Currency'
totalAmount:
type: number
format: decimal
description: Invoice's total amount.
amountDue:
type: number
format: decimal
description: Invoice's total amount due.
payments:
type: array
items:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment'
paidOnDate:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment/properties/date'
- title: Modified dates
x-internal: true
allOf:
- title: ModifiedDate
x-internal: true
type: object
properties:
modifiedDate:
allOf:
- $ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment/properties/date'
- description: |-
The date when the record was last fetched from the data source and updated in Codat’s data cache.
Use it to identify and retrieve records that have changed since your last fetch. For example, filtering `modifiedDate` to today will provide new records updated in Codat today.
This date is populated for all data types except for attachments, balance sheets, company information, and profit & loss reports ([read more](https://docs.codat.io/using-the-api/modified-dates#modified-date)).
In Codat's data model, dates and times are represented using the ISO 8601 standard.
- title: Source Modified Date
x-internal: true
type: object
nullable: true
properties:
sourceModifiedDate:
allOf:
- $ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment/properties/date'
- description: |-
The date when a record was last modified in the source platform, usually by the business or a business process. For example, when payments are made against an invoice.
It is not populated ([read more](https://docs.codat.io/using-the-api/modified-dates#source-modified-date)) when:
- Pulling attachments
- The integration platform does not provide modification dates for a data type
- A record has been deleted from the source platform and Codat doesn't have a record of when the deletion occurred
- A record has been voided. For certain platforms that soft delete records, `isDeleted` metadata is used to identify void records
In Codat's data model, dates and times are represented using the ISO 8601 standard.
reportInfo:
title: Report information
type: object
description: 'Report additional information, which is specific to Lending API reports.'
properties:
pageNumber:
type: integer
description: The number of the page queried.
pageSize:
type: integer
description: The number of transactions returned per page.
totalResults:
type: integer
description: The total number of transactions available for a company for the period specified in the query string.
reportName:
type: string
description: Name of the report.
companyName:
type: string
description: The name of the company being queried.
generatedDate:
type: string
description: Date the report was generated.
examples:
- Example 1:
value:
pageNumber: 0
pageSize: 0
totalResults: 0
reportName: string
companyName: string
generatedDate: '2023-01-26T07:36:40.487Z'
EnhancedReport:
title: Enhanced report
type: object
properties:
reportInfo:
$ref: '#/components/schemas/EnhancedReport/definitions/enhancedReportInfo'
reportItems:
type: array
description: An array of report items.
items:
title: Report item
type: object
properties:
date:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment/properties/date'
description: Last date of the period.
balance:
type: number
format: decimal
description: Balance of the account as reported on the profit and loss or Balance sheet.
accountName:
type: string
description: Name of the account.
accountId:
type: string
description: The unique account ID.
accountCategory:
$ref: '#/components/schemas/EnhancedReport/definitions/enhancedReportAccountCategory'
definitions:
enhancedReportAccountCategory:
title: Account category
descrciption: 'An object containing the suggested or confirmed account categories, up to five levels.'
type: object
properties:
status:
type: string
description: 'Returns a status of "Suggested" or "Confirmed". If an account has a confirmed category, it will replace any suggested category returned.'
levels:
type: array
items:
$ref: '#/components/schemas/EnhancedReport/definitions/accountCategoryLevel'
accountCategoryLevel:
title: Account category level
description: An object containing an ordered list of account category levels.
type: object
properties:
levelName:
type: string
description: Account category name.
confidence:
type: number
format: decimal
description: Confidence level of the category. This will only be populated where `status` is `Suggested`.
enhancedReportInfo:
type: object
properties:
currency:
$ref: '#/components/schemas/Currency'
description: Currency of the P&L/Balance sheet.
reportName:
type: string
description: The name of the report.
companyName:
type: string
description: Name of the company queried.
generatedDate:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment/properties/date'
description: Returns the YYYY-MM-DD datetime of report generation.
examples:
- reportInfo:
reportName: EnhancedProfitAndLossAccounts
companyName: ABC LTD
generatedDate: '2022-01-01'
reportItems:
- date: '2022-01-01'
balance: 70
accountName: Sales UK
accountId: 13931cbf-ea06-4d6e-9538-a8457fa66011
accountCategory:
status: Suggested
levels:
- levelName: Income
confidence: 0.95
- levelName: Revenue
confidence: 0.9
- date: '2022-01-01'
balance: 30
accountName: Sales US
accountId: 13931cbf-ea06-4d6e-9538-a8457fa66011
accountCategory:
lastUpdated: '2022-01-02'
status: Suggested
levels:
- levelName: Income
confidence: 0.95
- levelName: Revenue
confidence: 0.9
- date: '2022-01-01'
balance: 70
accountName: Amazon
accountId: 13931cbf-ea06-4d6e-9538-a8457fa66011
accountCategory:
lastUpdated: '2022-01-02'
status: Suggested
levels:
- levelName: Income
confidence: 0.95
- levelName: Revenue
confidence: 0.95
- levelName: Online
confidence: 0.8
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.
ExcelStatus:
type: object
title: Excel status
properties:
lastGenerated:
$ref: '#/components/schemas/EnhancedInvoicesReport/definitions/payment/properties/date'
description: The date and time of when the generation of the most recent report was initiated.
inProgress:
type: boolean
description: 'When true, the request was successful and the report is being generated. If false, the request was unsuccessful and the report is not being generated.'
queued:
type: string
description: The date and time of when a successful request was queued for the most recent report.
success:
type: boolean
description: True if the requested report was successfully queued and false if the requested report was not able to be queued.
errorMessage:
type: string
description: Error details in case the report generation request was unsuccessful.
lastInvocationId:
type: string
description: A unique ID generated for this request.
reportType:
$ref: '#/components/schemas/ExcelStatus/definitions/excelReportTypes'
fileSize:
type: integer
nullable: true
description: The file size in Bytes is populated upon successful generation of the report.
definitions:
excelReportTypes:
type: string
enum:
- audit
- enhancedFinancials
- enhancedInvoices
- enhancedCashFlow
description: The type of the report requested in the query string.
examples:
Example 1:
value:
lastGenerated: '2023-01-25T22:36:05.125Z'
inProgress: true
queued: '2023-01-25T22:36:05.125Z'
success: true
errorMessage: string
lastInvocationId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
reportType: string
fileSize: 0
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/EnhancedInvoicesReport/definitions/payment/properties/date'
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/EnhancedInvoicesReport/definitions/payment/properties/date'
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'
errors:
type: array
description: 'If there are no errors, an empty array is returned.'
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/EnhancedInvoicesReport/definitions/payment/properties/date'
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/EnhancedInvoicesReport/definitions/payment/properties/date'
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
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'
Report:
title: Commerce report
description: |-
## Structure
Assess reports follow a consistent structure. Reports contain four sections of information:
### 1. Report definition
Information such as:
1. The report info (e.g. enhanced_profit_and_loss).
2. The display name of the report (e.g. Enhanced Profit and Loss).
### 2. Dimension info
Information about the dimension contained in the reports such as:
1. The type of dimension (e.g. datetime, recordRef).
2. The display name of the dimension (e.g. Period, Category type, Category sub type).
3. The details about each item within the dimension (e.g. displayName:"Jan 2022", start:"...", end:"...", id:"...", name:"...").
### 3. Measure info
Information about the measures contained in the report such as:
1. The display name of the measure (e.g. value of account, percentage change).
2. The type of the measure (e.g. currency, percentage).
3. The unit of the measure (e.g. %, GBP).
### 4. The data for the report
When the *includeDisplayName* parameter is set to *true*, it shows the *dimensionDisplayName* and *itemDisplayName* to make the data human-readable. The default setting for *includeDisplayName* is *false*.
## Displaying the report
Reports can be rendered as follows (ordering is implicit rather than explicit):
![A table showing an example of how a report can be rendered](https://files.readme.io/1fa20ca-Report1.png)
# Data model
## Dimensions
type: object
properties:
reportInfo:
type: object
additionalProperties:
type: string
dimensions:
type: array
items:
$ref: '#/components/schemas/Report/definitions/commerceReportDimension'
measures:
type: array
items:
$ref: '#/components/schemas/Report/definitions/commerceReportMeasure'
reportData:
type: array
items:
$ref: '#/components/schemas/Report/definitions/commerceReportComponent'
errors:
type: array
items:
$ref: '#/components/schemas/Report/definitions/commerceReportError'
definitions:
commerceReportMeasure:
title: Measure
type: object
properties:
displayName:
description: The measure's display name.
type: string
units:
type: string
description: The measure's units e.g. percentage (%).
index:
type: integer
description: The measure's index.
type:
type: string
description: The measure's type.
commerceReportError:
title: Error
type: object
properties:
message:
type: string
description: Message returned by error.
type:
type: string
description: The type of error.
details:
description: Additional details on the error.
type: object
additionalProperties:
type: array
items:
type: string
commerceReportDimension:
title: Dimension
type: object
properties:
index:
type: integer
description: The dimension's index.
displayName:
type: string
description: The dimension's display name.
type:
type: string
description: The dimension's type.
items:
type: array
items:
type: object
properties:
index:
type: integer
description: The dimension's items index.
commerceReportComponent:
title: Report component
type: object
properties:
dimension:
type: integer
description: The component's dimension.
dimensionDisplayName:
type: string
description: The component's display name.
item:
type: integer
description: The component's item number.
itemDisplayName:
type: string
description: The component's item display name.
measures:
type: array
items:
$ref: '#/components/schemas/Report/definitions/reportComponentMeasure'
components:
type: array
items:
$ref: '#/components/schemas/Report/definitions/commerceReportComponent'
reportComponentMeasure:
type: object
title: Report component measure
properties:
index:
type: integer
description: The measure's index.
measureDisplayName:
type: string
description: The measure's display name.
value:
type: number
format: decimal
description: The measure's value.
x-examples:
Example 1:
reportInfo:
additionalProp1: string
additionalProp2: string
additionalProp3: string
dimensions:
- index: 0
displayName: string
type: string
items:
- index: 0
measures:
- displayName: string
units: string
index: 0
type: string
reportData:
- dimension: 0
dimensionDisplayName: string
item: 0
itemDisplayName: string
measures:
- index: 0
measureDisplayName: string
components:
- string
errors:
- message: string
type: DatesOutOfRange
details:
additionalProp1:
- string
additionalProp2:
- string
additionalProp3:
- string
Status:
title: Data integrity statuses
x-internal: true
type: object
properties:
metadata:
type: array
items:
$ref: '#/components/schemas/DataIntegrityStatus'
Summaries:
title: Data integrity summaries
x-internal: true
type: object
properties:
summaries:
type: array
items:
$ref: '#/components/schemas/DataIntegritySummary'
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.
connectionId:
name: connectionId
in: path
required: true
schema:
type: string
format: uuid
example: 2e9d2c44-f675-40ba-8049-353bfcb5e171
description: Unique identifier for a company's data connection.
description: Unique identifier for a connection.
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).'
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).'
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).'
dataIntegrityDataType:
name: dataType
in: path
required: true
schema:
type: string
enum:
- banking-accounts
- banking-transactions
- bankAccounts
- accountTransactions
example: banking-accounts
description: A key for a Codat data type.
reportDate:
name: reportDate
in: query
required: true
schema:
type: string
example: 29-09-2020
description: 'The date in which the report is created up to. Users must specify a specific date, however the response will be provided for the full month.'
periodLength:
name: periodLength
in: query
required: true
schema:
type: integer
description: The number of months per period. E.g. 2 = 2 months per period.
numberOfPeriodsRequired:
name: numberOfPeriods
in: query
required: true
schema:
type: integer
description: The number of periods to return. There will be no pagination as a query parameter.
numberOfPeriods:
name: numberOfPeriods
in: query
required: false
schema:
type: integer
description: 'The number of periods to return. If not provided, 12 periods will be used as the default value.'
periodUnit:
name: periodUnit
in: query
required: true
schema:
type: string
enum:
- Day
- Week
- Month
- Year
description: The period unit of time returned.
includeDisplayNames:
name: includeDisplayNames
in: query
schema:
type: boolean
description: Shows the dimensionDisplayName and itemDisplayName in measures to make the report data human-readable.
excelReportType:
name: reportType
in: query
schema:
type: string
enum:
- assess
- audit
- enhancedFinancials
- enhancedInvoices
- enhancedCashFlow
description: The type of report you want to generate and download.
required: true
responses:
Bad-Request:
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
Malformed-Query:
description: Your `query` parameter was not correctly formed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Malformed query:
value:
statusCode: 400
service: ClientsApi
error: Error parsing query - Malformed query.
correlationId: bc997528a9d7abb9161ef45f05d38599
canBeRetried: Unknown
detailedErrorCode: 0
Unresolved property:
value:
statusCode: 400
service: PullApi
error: Error parsing query - Could not resolve property isCompleted on Dataset
correlationId: 98457fb9956b7f9b4b2fd4f6e23bb5c8
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
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
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
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
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
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
securitySchemes:
auth_header:
name: Authorization
description: 'The word "Basic" followed by a space and your API key. [API keys](https://docs.codat.io/accounting-api#/schemas/apiKeys) 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/codat-api#/api-keys/api-keys-list), 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)