Supplemental data
Customize data types with additional properties not included in Codat's out-of-the box data models
What is supplemental data?
Codat's supported data types include standardized properties. Some data sourcesData source An external platform (such as QuickBooks, Xero, or a bank) that Codat integrates with to pull or push financial data. (e.g. Xero) may contain properties not common across other sources, and so are not covered by our out-of-the-box data model. You can use supplemental data to extend our data types to fetch or create such properties alongside our standard ones.
Supplemental data supports reading data via GET or creating data through POST request methods. Codat does not support updating data using supplemental data.
Consider our Xero integration. Xero's Contact schema maps to Codat's supplier data type. Some of its properties (like TaxNumber) are mapped, whereas others (like BankAccountDetails) are not. If you configure supplemental data for this Xero property, suppliers data from Xero could additionally include BankAccountDetails.

Common uses
Integration-specific properties not included in our standard data models may still provide you with additional benefits, enriching the data relevant for your use case. For example, you can enhance our invoices data type with an invoice URL, a Xero-specific field that directs the user to a source document for an invoice hosted outside of Xero. For QBO, the invoices data type can be supplemented with SalesTermRef, providing you with sales terms associated with an invoice.
We have compiled a list of properties commonly used by our customers to enrich our standard data types. You can review these in detail to see how you can use supplemental data to your advantage.
Are you looking to fetch additional data types using endpoints that are not included in Codat's standardized data model? You might need to use custom data instead.
Supported integrations
We are rapidly expanding coverage across integrations and data types according to client demand. We currently cover the following integrations and data types:
Configure supplemental data
You'll need to specify what supplemental data should be passed in the response for each integration and data type pair you require. To do so, use the Configure supplemental data endpoint.
PUT /integrations/{platformKey}/datatypes/{datatype}/supplementalDataConfig
You can use the same endpoint with an empty supplementalDataConfig object to reset the supplemental data configuration at any time.
Within the request body, PlatformEndpoint and PlatformPropertyName parameter values must match the integration's requirements exactly, including casing. Ensure you are familiar with the source data structure as Codat does not validate the supplemental data values against the integration provider.
{
"supplementalDataConfig": {
"{ClientObjectName}": {
"dataSource": "/{PlatformEndpoint}",
"pullData": {
"{ClientDefinedName}": "{PlatformPropertyName}",
"{ClientDefinedName2}": "{PlatformPropertyName2}"
},
"pushData": {
"{ClientDefinedName}": "{PlatformPropertyName}",
"{ClientDefinedName2}": "{PlatformPropertyName2}"
}
}
}
}
You can use dot notation to retrieve nested properties from within the supplemental data object. For example, maintain the following configuration to retrieve the supplier's Name value from Xero's BrandingTheme object with two properties, BrandingThemeID and Name, along with their BankAccountDetails.
{
"supplementalDataConfig": {
"yourKeyNameForXeroSuppliers": {
"dataSource": "/Contacts",
"pullData": {
"SupplierBankAccount": "BankAccountDetails",
"BrandingThemeName": "BrandingTheme.Name"
}
}
}
}
Once set, you can retrieve an existing supplemental data configuration by using the Get supplemental data configuration endpoint:
GET /integrations/{platformKey}/datatypes/{datatype}/supplementalDataConfig
Platform endpoint mapping
Review the table below for platform schemas we use in our data types, which are available for you to fetch or create supplemental data. Refer to to the platform's individual documentation (for example, Xero or QBO) for further details of their schemas and property coverage.