Pushing data

Supported datatypes

The table below summarises support for pushing data across the Codat data types and the accounting integrations Codat supports.

Supported 'push' data types.
Click to expand.Supported 'push' data types.
Click to expand.

Supported 'push' data types.
Click to expand.

Legend

Supports creating records (i.e. POST)
Supports updating records (i.e. PUT)
We’ve recently added support for this datatype
Available on request from provider
Not currently supported by Codat
- Not supported by underlying provider


Xero - Bank Transactions
You must have a partner app enabled for bank feeds to be able to push bank transactions to a bank account in Xero. See here for more info about Xero bank feeds requirements and configuration.

Sage 50/ QuickBooks Desktop - Customers and Suppliers
Whilst there is no direct push attachment functionality available for Sage 50 and QuickBooks Desktop, it is possible to push metadata, such as a short link URL, by using the notes field against line items when pushing an Invoice or a Bill to Sage 50.

Freshbooks - Suppliers and Bill Payments
Suppliers are not directly supported via Codat's PUSH/ Suppliers endpoint. Instead, a new supplier is created when a bill is pushed that references a supplier that doesn't already exist.
Bill payments are not directly supported via Codat's PUSH/ billPayments endpoint. Instead, a bill payment is created when a bill is pushed.

📘

Prerequisites

Before you can update a company's data using our API, you'll need the company to authorise a data connection (see our documentation on user authorisation).

Types of push

Codat supports two types of push to a company's data source: operations to create a record in a company's accounting software (POST) and operations to update an existing record (PUT).

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.

Overview

Since its inception the Codat API has enabled financial technology businesses to pull their customers' accounting data from a wide range of SME accounting software packages (both cloud and on-premise) in a standardised format. However, today's business owners demand increasing levels of inter-connectivity between the software they use day-to-day. Thus, in order to deliver the most engaging user experiences it is necessary to provide users the ability to push data back into their accounting software. This is functionality that Codat offers, and it is implemented as follows.

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 categorisation 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.

Codat does not wish to limit users to pushing to a very limited number of standard categories, so we have implemented an "options" endpoint, which allows us to expose to our clients the fields which are required to be pushed for a specific linked company, and the options which may be selected for each field.

The Options endpoint

The Options endpoint for a linked company is accessed as follows:

GET /companies/{companyId}/connections/{connectionId}/options/{dataType} and can be found in Swagger .

Below is an example response from this endpoint for the accounts dataset:

{
  "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"). The displayName 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

🚧

Pushing data not referenced by the Options endpoint

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 or TimedOut
  • 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, so that the outcome of the push can 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:

You can periodically poll the single endpoint while a push is in a Pending state to identify when it enters a Success or Failed 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.


Did this page help you?