Creating and updating data
Understand how to push data to Codat's integrated platforms
In addition to pulling data from integrations, you can push data to create and update records in the underlying integrations using Codat's data model.
View the full details of Codat's support for pushing data for each accounting platform in the Data Coverage Explorer.
Types of push
Codat supports two types of push to a company's data source:
POST
- Create a record in a company's accounting softwarePUT
- Update an existing record
Create and update operations behave similarly, with both having an options endpoint and returning a pushOperation to allow you to monitor the state of the push.
There are some additional considerations when updating to help ensure the company's data integrity.
Step 1: Options
Before pushing data into accounting software, it is often necessary to collect some details from the user as to how they would like the data to be inserted. This includes names and amounts on transactional entities, but also factors such as categorization of entities, which is often handled differently between different accounting packages. A good example of this is specifying where on the balance sheet/profit and loss reports the user would like a newly-created nominal account to appear.
Our /options
endpoint exposes which fields are required to be pushed for a specific linked company, and the options which may be selected for each field.
GET /options
You can retrieve the options for a given data type by calling:
GET /companies/{companyId}/connections/{connectionId}/options/{dataType}
{
"type": "Object",
"displayName": "Nominal Account",
"description": "Account represented in the chart of accounts or general ledger.",
"properties": {
"nominalCode": {
"type": "String",
"displayName": "Nominal Code",
"description": "Identifier for the nominal account.",
"required": true,
"validation": {
"warnings": [{
"field": "nominalCode",
"details": "Must have a length between 1 and 7 characters."
}
]
}
},
"name": {
"type": "String",
"displayName": "Name",
"description": "Name of account as it appears in the chart of accounts or general ledger.",
"required": true
},
"fullyQualifiedCategory": {
"type": "String",
"displayName": "Fully Qualified Category",
"description": "Account type and category for nominal account.",
"options": [{
"value": "Asset.CashOnHand",
"type": "String",
"displayName": "Cash On Hand"
}, {
"value": "Asset.Checking",
"type": "String",
"displayName": "Checking"
}
],
"required": true,
}
},
"required": false,
}
This example describes the nominal account object as requiring three properties to be populated: nominalCode
, name
, and fullyQualifiedCategory
.
- The
nominalCode
property is a string, which has a validation warning that it must be between 1 and 7 characters long. - The
name
property is an unrestricted string. - The
fullyQualifiedCategory
property is an enum property, namely it accepts a string chosen from a list of options (in this case, "Asset.CashOnHand" and "Asset.Checking"). ThedisplayName
on the options can be used to display the user a more descriptive name, such as "Cash On Hand" and "Checking".
Displaying options to your user
The structure of the options endpoint is designed such that it can be easily parsed into a set of controls which can be displayed to the end user such that they can select how data is pushed into their accounting software.
For example, when rendering the "fullyQualifiedCategory" from the above example as a control on a HTML form, it can be parsed into the following:
<select name="fullyQualifiedCategory" required>
<option value="Asset.CashOnHand">Cash On Hand</option>
<option value="Asset.Checking">Checking</option>
</select>
Step 2: Pushing a record
If you attempt to push a record using fields that are not documented in the Options response for that company, the additional data may not be pushed to the platform and you may receive validation errors in response to your "push" request.
The push endpoint
The endpoint for pushing a record is as follows:
POST /companies/{companyId}/connections/{connectionId}/push/{dataType}
An example would be posting a new invoice to an accounting package for a given company.
The request body should be a JSON object which conforms to the structure of the options endpoint above. It is expected that the options endpoint is queried before performing any push operation.
For example, a valid request body for the example above would be as follows:
{
"nominalCode": "4200",
"name": "Codat Bank Account",
"fullyQualifiedCategory": "Asset.CashOnHand"
}
The response from the push endpoint is a PushOperation object, which is structured as follows:
{
"pushOperationKey": "f989ebc8-1fc6-4367-acd1-1892e97bb7b0",
"companyId": "9ac8109a-ebf9-464a-b178-fdab4970a584",
"dataConnectionId": "15b69c97-318c-46c4-bb68-6f451f365227",
"dataType": "accounts",
"status": "Pending",
"requestedOnUtc": "2018-08-15T17:22:00",
"completedOnUtc": null,
"data": {},
"validation": {}
}
Properties on the object are as follows:
- pushOperationKey: A unique identifier generated by Codat to represent this single push operation. This identifier can be used to track the status of the push, and should be persisted
- dataType: The type of data being pushed, eg invoices, customers
- status: The status of the push operation, which can be
Pending
,Failed
,Success
,TimedOut
, orUnknown
- requestedOnUtc: The datetime (in UTC) when the push was requested
- completedOnUtc: The datetime (in UTC) when the push was completed, null if Pending
- data: The object which was pushed. If the push has completed successfully, this represents the object as it appears in the platform (with any platform-generated fields populated)
- validation: A human-readable object describing validation decisions Codat has made when pushing data into the platform. If a push has failed because of validation errors, they will be detailed here.
Synchronous vs asynchronous push
The majority of platforms are implemented to push asynchronously so you will receive a Pending
push operation in response to your push request. You can use the details in this response to monitor the status of your push request.
For some platforms, pushing may be implemented synchronously and you may receive a Success
or Failed
push operation in response to your push request (in place of a Pending
push operation). However, we strongly suggest that you assume that all pushes will be processed asynchronously when integrating with Codat.
Timeouts
It is possible for an operation to be in a Pending
status indefinitely, for example if a user's on-premise software is offline. To avoid possible issues this could create for clients, Codat provides a timeout functionality for push operations in the Pending
status. If the timeoutInMinutes
property has been set on a push operation, Codat will guarantee that the operation will not be processed after that deadline. If the deadline expires, the status of the push operation will change to TimedOut
.
Step 3: Monitoring status of push
For asynchronous push operations, where the push is initially in a Pending
status, you may wish to have a process that will provide an update on a final Success
or Failed
state, or Unknown
state if the outcome of the push is unclear. This outcome can then be communicated to the user, or further actions can be taken.
Codat supports two methods of monitoring the status of push operations: polling and webhooks.
1. Polling
The Codat API provides two endpoints for monitoring push operations: one for viewing the status of all the most recent push operations, and one for viewing the status of a single push operation, identified by the PushOperationKey
returned when you requested the push.
You can:
- List all push operations (paged) for a company using
GET /companies/{companyId}/push
- Get a single push operation by ID using
GET /companies/{companyId}/push/{pushOperationKey}
.
You can periodically poll the single endpoint while a push is in a Pending
state to identify when it enters a Success
, Failed
, or Unknown
state, at which point the outcome can be communicated to the user.
The list endpoint can be used to present to the user a list of recent push requests and their statuses. This can be useful for applications which push data frequently.
2. Webhooks
A second option for monitoring push operations is to register a subscription to the "Push status changed" rule. This can be configured by following the instructions in our documentation for subscribing to rules.