Codat · Schema

Accounting: Account

> **Language tip:** Accounts are also referred to as **chart of accounts**, **nominal accounts**, and **general ledger**. ## Overview Accounts are the categories a business uses to record accounting transactions. From the Accounts endpoints, you can retrieve a list of all accounts for a specified company. The categories for an account include: * Asset * Expense * Income * Liability * Equity. The same account may have a different category based on the integration it is used in. For example, a current account (known as checking in the US) should be categorized as `Asset.Current` for Xero, and `Asset.Bank.Checking` for QuickBooks Online. At the same time, each integration may have its own requirements to the categories. For example, a Paypal account in Xero is of the `Asset.Bank` category and therefore requires additional properties to be provided. To determine the list of allowed categories for a specific integration, you can: - Follow our [Create, update, delete data](https://docs.codat.io/using-the-api/push) guide and use the [Get create account model](https://docs.codat.io/lending-api#/operations/get-create-chartOfAccounts-model). - Refer to the integration's own documentation. > **Accounts with no category** > > If an account is pulled from the chart of accounts and its nominal code does not lie within the category layout for the company's accounts, then the **type** is `Unknown`. The **fullyQualifiedCategory** and **fullyQualifiedName** fields return `null`. > > This approach gives a true representation of the company's accounts whilst preventing distorting financials such as a company's profit and loss and balance sheet reports.

Unified_API
View JSON Schema on GitHub

JSON Schema

codat-accountingaccount-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "#/components/schemas/AccountingAccount",
  "title": "Accounting: Account",
  "description": "\ufeff> **Language tip:** Accounts are also referred to as **chart of accounts**, **nominal accounts**, and **general ledger**.\n\n## Overview\n\nAccounts are the categories a business uses to record accounting transactions. From the Accounts endpoints, you can retrieve a list of all accounts for a specified company.\n\nThe categories for an account include:\n* Asset\n* Expense\n* Income\n* Liability\n* Equity.\n\nThe same account may have a different category based on the integration it is used in. For example, a current account (known as checking in the US) should be categorized as `Asset.Current` for Xero, and `Asset.Bank.Checking` for QuickBooks Online.\n\nAt the same time, each integration may have its own requirements to the categories. For example, a Paypal account in Xero is of the `Asset.Bank` category and therefore requires additional properties to be provided.\n\nTo determine the list of allowed categories for a specific integration, you can:\n- Follow our [Create, update, delete data](https://docs.codat.io/using-the-api/push) guide and use the [Get create account model](https://docs.codat.io/lending-api#/operations/get-create-chartOfAccounts-model).\n- Refer to the integration's own documentation.\n\n> **Accounts with no category**\n>\n> If an account is pulled from the chart of accounts and its nominal code does not lie within the category layout for the company's accounts, then the **type** is `Unknown`. The **fullyQualifiedCategory** and **fullyQualifiedName** fields return `null`.\n>\n> This approach gives a true representation of the company's accounts whilst preventing distorting financials such as a company's profit and loss and balance sheet reports.",
  "allOf": [
    {
      "properties": {
        "id": {
          "type": "string",
          "description": "Identifier for the account, unique for the company.",
          "example": "1b6266d1-1e44-46c5-8eb5-a8f98e03124e"
        }
      }
    },
    {
      "$ref": "#/components/schemas/AccountingAccount/definitions/accountPrototype"
    },
    {
      "properties": {
        "metadata": {
          "$ref": "#/components/schemas/Metadata"
        }
      }
    },
    {
      "$ref": "#/components/schemas/CommerceOrder/allOf/3"
    }
  ],
  "definitions": {
    "accountPrototype": {
      "title": "Account prototype",
      "type": "object",
      "properties": {
        "nominalCode": {
          "type": "string",
          "nullable": true,
          "description": "Reference given to each nominal account for a business. It ensures money is allocated to the correct account. This code isn't a unique identifier in the Codat system.",
          "example": "610"
        },
        "name": {
          "type": "string",
          "nullable": true,
          "description": "Name of the account.",
          "example": "Accounts Receivable"
        },
        "description": {
          "type": "string",
          "nullable": true,
          "description": "Description for the account.",
          "example": "Invoices the business has issued but has not yet collected payment on."
        },
        "fullyQualifiedCategory": {
          "type": "string",
          "nullable": true,
          "description": "Full category of the account. \r\n\r\nFor example, `Liability.Current` or `Income.Revenue`. To determine a list of possible categories for each integration, see our examples, follow our [Create, update, delete data](https://docs.codat.io/using-the-api/push) guide, or refer to the integration's own documentation.",
          "example": "Asset.Current"
        },
        "fullyQualifiedName": {
          "type": "string",
          "nullable": true,
          "description": "Full name of the account, for example:\n- `Cash On Hand`\n- `Rents Held In Trust`\n- `Fixed Asset`",
          "examples": [
            "Cash On Hand",
            "Fixed Asset"
          ]
        },
        "currency": {
          "$ref": "#/components/schemas/SourceAccount/properties/currency"
        },
        "currentBalance": {
          "type": "number",
          "format": "decimal",
          "nullable": true,
          "description": "Current balance in the account.",
          "example": 0
        },
        "type": {
          "$ref": "#/components/schemas/AccountingAccount/definitions/accountType"
        },
        "status": {
          "$ref": "#/components/schemas/AccountingAccount/definitions/accountStatus"
        },
        "isBankAccount": {
          "type": "boolean",
          "description": "Confirms whether the account is a bank account or not."
        },
        "validDatatypeLinks": {
          "type": "array",
          "nullable": true,
          "description": "The validDatatypeLinks can be used to determine whether an account can be correctly mapped to another object; for example, accounts with a `type` of `income` might only support being used on an Invoice and Direct Income. For more information, see [Valid Data Type Links](/lending-api#/schemas/ValidDataTypeLinks).",
          "items": {
            "title": "Valid data type links",
            "description": "When querying Codat's data model, some data types return `validDatatypeLinks` metadata in the JSON response. This indicates where that object can be used as a reference\u2014a _valid link_\u2014when creating or updating other data.\n\nFor example, `validDatatypeLinks` might indicate the following references:\n\n- Which tax rates are valid to use on the line item of a bill.\n- Which items can be used when creating an invoice. \n\nYou can use `validDatatypeLinks` to present your SMB customers with only valid choices when selecting objects from a list, for example.\n\n## `validDatatypeLinks` example\n\nThe following example uses the `Accounting.Accounts` data type. It shows that, on the linked integration, this account is valid as the account on a payment or bill payment; and as the account referenced on the line item of a direct income or direct cost. Because there is no valid link to Invoices or Bills, using this account on those data types will result in an error.\n\n```json validDatatypeLinks for an account\n{\n            \"id\": \"bd9e85e0-0478-433d-ae9f-0b3c4f04bfe4\",\n            \"nominalCode\": \"090\",\n            \"name\": \"Business Bank Account\",\n            #...\n            \"validDatatypeLinks\": [\n                {\n                    \"property\": \"Id\",\n                    \"links\": [\n                        \"Payment.AccountRef.Id\",\n                        \"BillPayment.AccountRef.Id\",\n                        \"DirectIncome.LineItems.AccountRef.Id\",\n                        \"DirectCost.LineItems.AccountRef.Id\"\n                    ]\n                }\n            ]\n        }\n```\n\n\n\n## Support for `validDatatypeLinks`\n\nCodat currently supports `validDatatypeLinks` for some data types on our Xero, QuickBooks Online, QuickBooks Desktop, Exact (NL), and Sage Business Cloud integrations. \n\nIf you'd like us to extend support to more data types or integrations, suggest or vote for this on our <a href=\"https://portal.productboard.com/codat/5-product-roadmap\">Product Roadmap</a>.",
            "type": "object",
            "properties": {
              "property": {
                "type": "string",
                "nullable": true,
                "description": "The property from the account that can be linked."
              },
              "links": {
                "type": "array",
                "nullable": true,
                "description": "Supported `dataTypes` that the record can be linked to.",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        },
        "supplementalData": {
          "$ref": "#/components/schemas/SupplementalData"
        }
      }
    },
    "accountRef": {
      "title": "Account reference",
      "type": "object",
      "description": "Data types that reference an account, for example bill and invoice line items, use an accountRef that includes the ID and name of the linked account.",
      "properties": {
        "id": {
          "type": "string",
          "description": "'id' from the Accounts data type."
        },
        "name": {
          "type": "string",
          "description": "'name' from the Accounts data type."
        }
      }
    },
    "accountType": {
      "title": "Account type",
      "enum": [
        "Unknown",
        "Asset",
        "Expense",
        "Income",
        "Liability",
        "Equity"
      ],
      "type": "string",
      "description": "Type of account",
      "example": "Asset"
    },
    "accountStatus": {
      "title": "Account status",
      "enum": [
        "Unknown",
        "Active",
        "Archived",
        "Pending"
      ],
      "type": "string",
      "description": "Status of the account",
      "example": "Active"
    }
  },
  "type": "object"
}