Categorization of accounts

Reference document for the Account Categorization endpoints

🚧

This categorization of accounts via only applies to our classic Enhanced Financials. For our revised categorization aimed at eCommerce lenders, explore Enhanced Financials for eCommerce lenders.

The Categorization of accounts API consists of the following endpoints:

API endpoints for categorization of accounts

Account categories have three sub-categories:

  • Account type — the highest level classification of an account, e.g. Asset, Liability, etc.
  • Account subtype — category often used for traditional financial ratios, e.g. Current assets, Current liabilities, etc.
  • Account detail — individual accounts, e.g. Cash, Inventory, Depreciation, etc.

List all available categories

The endpoint is available in Swagger under Assess. It contains the original category suggested by Codat suggested and the category that was confirmed by you or your customer confirmed.

  • A list of all the Codat standard categories can be found under:

GET /data/assess/accounts/categories

[
  {
    "type": "Asset",
    "subtype": "Current",
    "subtypeDisplayName": "Current assets",
    "detailType": "Cash",
    "detailTypeDisplayName": "Cash",
    "detailTypeDescription": "Use 'Cash' for cash in the bank or held on premise. This should include overdrawn accounts."
  },
  {
    "type": "Income",
    "subtype": "Operating",
    "subtypeDisplayName": "Operating",
    "detailType": "GeneralServices",
    "detailTypeDisplayName": "General services",
    "detailTypeDescription": "Use 'General services' for income generated from services the company performs or usage fees charged."
  }
  ...
]

Get the category for a specific account

The endpoint is available in Swagger under Assess.

The suggested and confirmed categories for a specific account can be obtained from the following endpoint:

GET /data/companies/{companyId}/connections/{connectionId}/assess/accounts/categories

{
      "accountRef": {
        "id": "367f8daa-1464-4152-bf4e-21548696f916",
        "name": "Purchases"
      },
      "suggested": {
        "type": "Expense",
        "subtype": "CostOfSales",
        "detailType": "Labour"
      },
      "confirmed": {
        "type": "Expense",
        "subtype": "Operating",
        "detailType": "AmortisationDepreciation"
      }
    },

List all accounts with their categories

The endpoint is available in Swagger under Assess.

GET /data/companies/{companyId}/connections/{connectionId}/assess/accounts/categories

Data model

FieldTypeDescription
accountRefSee AccountRefAn object containing account reference data.
suggestedSee SuggestedAn object containing suggested category data.
confirmedSee ConfirmedAn object containing confirmed category data.

AccountRef

FieldTypeDescription
idstringThe account Id.
namestringThe name of the account.

Suggested

Field

Type

Description

type

string

The suggested account type.

subtype

string

The suggested account subtype.

detailType

string

The suggested account detail type.

modifiedDate

See Date

YYYY-MM-DDT00:00:00Z

The date the category was suggested for the account.

Confirmed

Field

Type

Description

type

string

The confirmed account type.

subtype

string

The confirmed account subtype.

detailType

string

The confirmed account detail type.

modifiedDate

See Date

YYYY-MM-DDT00:00:00Z

The date the account category was confirmed.

{
  "results": [
    {
      "accountRef": {
        "id": "043b6bcb-dfe6-4c97-9b4c-f9b300fe3f03",
        "name": "Telephone & Internet"
      },
      "suggested": {
        "type": "Expense",
        "subtype": "Operating",
        "detailType": "GeneralAdministrative",
        "modifiedDate": "2021-12-08T12:21:29"
      },
      "confirmed": {
        "type": "Expense",
        "subtype": "Operating",
        "detailType": "SubscriptionFees",
        "modifiedDate": "2022-03-02T09:41:06"
      }
    }

Update categories for a company

The categories for all or a batch of accounts in a specific connection can be updated in Swagger under Assess.
Note that this does not update the end accounting platform’s account, and only updates the categories saved against the company within Assess.

The endpoint is available in Swagger under Assess.

PATCH /data/companies/{companyId}/connections/{connectionId}/assess/accounts/categories

In the update request body, provide:

  • type (classification of the account, e.g. Asset, Liability, Income, Expense)
  • subType (e.g. Current asset)
  • detailType (e.g. Cash equivalents).

You can provide a partial list of accounts you wish to update, or pass the whole object as null if you wish to remove the confirmed category for an account.

{
  "categories": [
    {
      "accountRef": {
        "id": "string"
      },
      "confirmed": {
        "type": "string",
        "subtype": "string",
        "detailType": "string"
        "modifiedDate": "2022-03-01T16:58:15.907Z"
      }
    }
  ]

Update the category for a specific account

The confirmed category for an account can be updated or removed.

The endpoint is available in Swagger under Assess.

PATCH /data/companies/{companyId}/connections/{connectionId}/assess/accounts/{accountId}/categories

Note: Even if you are updating 2 accounts out of 100, you should still provide the categories on the other 98 accounts to prevent replacing those that were previously confirmed.


Read next