NAV undefined
bash cs python javascript

Introduction

Welcome to the Codat API documentation.

The Codat API allows businesses to interact with financial data sources with minimal technical investment. In particular the API provides a wrapper around Codat CORE which handles authentication, standardisation and synchronisation of financial data.

The API is organised around REST and all responses are JSON.

If you have any suggestions for improving this documentation please email support@codat.io

Environments

There are two environments for the API: UAT and Production.

The two environments are completely separated which allows UAT to be used as a sandbox for testing and the credentials can be shared with all engineers at your organisation. No changes made in UAT will have any impact on Production.

The UAT environment data will be persisted indefinitely such that it can be used for ongoing integration tests.

Developers will need to obtain a separate API key for each environment. The chosen environment is defined by the base URL for the API.

Environment Base URL
UAT https://api-uat.codat.io/
Production https://api.codat.io/

Partners

Depending on your use case and technical setup you may prefer to use the Codat API via one of our partner applications or open-source API wrappers.

Screenshot of the Codat Link Site Screenshot of the Codat Link Site Screenshot of the Codat Link Site Screenshot of the Codat Link Site

Integrations

An integration is a third party financial data source (e.g. accounting software provider). Integrations can connect to financial data, via Codat, for your companies.

Creating a data connection

For a company to sync their data with Codat they first must have a data connection to one of the data platforms that Codat support. You can achieve this with the create data connection endpoint.

PUT /companies/{companyId}/platform {platformKey}

var request = new RestRequest("/companies/{companyId}/platform", Method.PUT);
request.AddUrlSegment("companyId", companyId);
request.AddHeader("Authorization", $"Basic {encodedApiKey}");
request.AddBody(JsonEncdode(platformKey));

var response = client.Execute(request);
var authorisationLink = response.DataConnections[0].LinkUrl;

After this data connection has been created the company with need to authorise it using the linkUrl. This URL links to the internal Codat authorisation sub system that will manage the differences between the various platforms.

Once this authorisation flow has been completed the user will be redirected back to the redirectUrl set on your profile.

WARNING: Multiple data connections

While supported by the API it is strongly advised that you manage the data connections that a company has closely and ensure that they only have one active connection at any given time. In some situations it may be required to have more than one data connection per company, if you think this might apply to you, please get in touch with support@codat.io to go over your use case before building.

Danger may occur when you have multiple data connections that provide data for the same data type (see below) connections may override, or worse corrupt, data from opposing connections trying to sync the same data type.

Offline Platforms

Offline platforms work slightly differently as there is no web authorisation flow or redirecting. In this situation the linkUrl will be a link to a download for a sync tool. This sync tool, once it has been run will automatically 'authorise' a company in the same way that, for example, an OAuth2 flow might.

When the tool is run by the end user they will be presented with a desktop application that will ask for a 'licence key', this licence key is the company ID provided by Codat. You will, if you are not using the Codat demo authorisation flow, need to present this to your users when they connect using an offline platform.

Sandbox Accounting Integration

The sandbox accounting integration is a demo accounting software connection. It is designed for developers to test the Codat API without needing an account with a third party accounting software provider.

The sandbox accounting integration acts as a typical accounting package, it provides a demo user authentication page and returns demo accounting data.

Supported Data Types

The table below documents the Codat supported data types for fetching data from third-party integrations.

Data type Sage 50 Quickbooks Online Xero Kashflow Freshbooks FreeAgent Sage One Exact Online Clearbooks Tide Sandbox Accounting MYOB Quickbooks Pro
balanceSheet x x x x x
bankStatements x x x x x x
bills x x x x x x x x
chartOfAccounts x x x x x x x x
creditNotes x x x x x x
company x x x x x x x x x x x x
customers x x x x x x x x x x x x
invoices x x x x x x x x x x x x
journalEntries x x x x x
payments x x x x x x x
profitAndLoss x x x x x x
suppliers x x x x x x x x x x

Portal

Codat provides a web-based portal that allows our clients to utilise financial data without technical development with the Codat API. The portal is powered by the Codat API, any functionality in the portal is also available using the API directly.

The portal is not visible to users of the companies who are sharing their accounting data.

The portal can be used to:

Environment Portal URL
UAT https://portal-uat.codat.io/
Production https://portal.codat.io/

Screenshot of the Codat Portal

Link

Codat requires authorisation from the company sharing their data to establish a connection to the finanical data source. The Codat API handles the technical element of the authorisation flow, removing the need for in-house development of managing OAuth connections, token refresh etc.

Codat clients have two options for the user experience their customers will follow to authorise the sharing of their financial data:

  1. Clients can implement their own front-end user journey powered by the Codat API; or
  2. Clients can use the customisable Codat Link Site (see below) which does not require technical development

Link Site

The Codat Link Site is a front-end interface, powered by the Codat API, which guides end users through the process of linking their financial accounts. The link site removes the need for Codat clients to implement their own front-end UX for the linking process and can be included as part of an existing customer journey.

The Codat Link Site is customisable, allowing you to set your own logo, colour scheme, contact details and text. Custom variables can be set via the Codat portal.

Screenshot of the Codat Link Site

API

API Explorer

Interactive API documentation based on Swagger.

Environment Swagger URL
UAT https://api-uat.codat.io/swagger
Production https://api.codat.io/swagger

Copy and paste your API key into the top right corner to make API calls in your browser.

Authentication

Codat uses API keys to control access to the API.

It is vital this API key is kept secret and is not available in publicly accessible areas such GitHub and client-side code. Codat recommends the API key is inserted at release time and the number of people at your organisation with access to your API key is minimised.

Codat expects for the API key to be included in all API requests to the server, Base64 encoded within an 'Authorization' header.

Authorization: Basic your_encoded_api_key

Admin and Developer users can view and regenerate API keys from the Codat Portal.

Model

Companies

In the context of the Codat system, a Company refers to the entity linking their financial accounts.

Data connections

Within the Codat System a Data Connection is a link between a Company and a financial data source.

Datasets

A particular synchronisation of a data type is referred to as a Dataset.

Push

In addition to the querying of data, Codat also supports the pushing of data back to third party integrations. As with retrieving data, Codat acts as a standardisation layer when pushing data. New data is passed to the Codat API in the Codat standard format and Codat handles the mapping to the individual formats for each third party integration.

Push endpoints

POST or PUT endpoints are used to add or update data in third party systems. The format of endpoints for updating data is /companies/{companyId}/connections/{connectionId}/push/{dataType} e.g. POST suppliers

A data connection Id is required so the Codat system can identify which integration to update in the event that a single company is linked to multiple integrations with support for the same data type. The data connection Id can be retrieved from the GET /connections or GET /companies endpoints.

Push response model

When pushing data to a third-party integration via the Codat API the response will be a Codat Push reponse in the format below. A Codat PUSH response contains validation messages of two levels, warnings and information.

{
  "validation": {
    "warnings": [
      {
        "field": "string",
        "details": "string"
      }
    ],
    "information": [
      {
        "field": "string",
        "details": "string"
      }
    ]
  },
  "data": {
    //Model of new or updated object returned
  }
}

Errors

The Codat API uses the following error codes:

Error Code Meaning
400 Bad Request -- The server cannot or will not process the request due to an apparent client error
401 Unauthorized -- Your API key is wrong
403 Forbidden -- The requested endpoint is hidden for administrators only
404 Not Found -- The resource could not be found
405 Method Not Allowed -- You tried to access a method with an invalid method
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarially offline for maintanance. Please try again later.

Error response

The content of the error reponse will include a more detailed error message and a correlationId which can be used to identify a particular response to Codat support.

Example content

{
  "statusCode": 404,
  "service": "QuickbooksOnline",
  "error": "InvoicePdfNotFoundException: Invoice not found for company 360cb9b3-d9cf-4f66-b8db-8a3523fe3dc5 and ID 12345",
  "correlationId": "131f0225-5467-421a-b179-4531d6b4a942"
}

Querying

The Codat API uses a simple, flexible query language to enable filtering of response data.

Data returned from the API can be filtered by including a URL encoded query parameter with your request.

Some example queries follow:

1. Invoices with amounts outstanding

GET /companies/{companyId}/data/invoices?query=amountDue%3e0

var request = new RestRequest("companies/{companyId}/data/invoices", Method.GET);
request.AddUrlSegment("companyId", companyId);
request.AddUrlSegment("query", "amountDue>0");
request.AddHeader("Authorization", $"Basic {encodedApiKey}");
var response = client.Execute(request);
var info = response.Data;
var query = new InvoicesQuery(companyId, 'amountDue>0')
  .run(codat.uat(apiKey));

2. GBP Invoices

GET /companies/{companyId}/data/invoices?query=currency%3dGBP

var request = new RestRequest("companies/{companyId}/data/invoices", Method.GET);
request.AddUrlSegment("companyId", companyId);
request.AddUrlSegment("query", "currency=GBP");
request.AddHeader("Authorization", $"Basic {encodedApiKey}");
var response = client.Execute(request);
var info = response.Data;
var query = new InvoicesQuery(companyId, 'currency=GBP')
  .run(codat.uat(apiKey));

3. Invoices to a particular customer

GET /companies/{companyId}/data/invoices?query=customerRef.id%3d61

var request = new RestRequest("companies/{companyId}/data/invoices", Method.GET);
request.AddUrlSegment("companyId", companyId);
request.AddUrlSegment("query", "customerRef.id=61");
request.AddHeader("Authorization", $"Basic {encodedApiKey}");
var response = client.Execute(request);
var info = response.Data;
var query = new InvoicesQuery(companyId, 'customerRef.id=61')
  .run(codat.uat(apiKey));

4. Outstanding Invoices of value less than 1000

GET /companies/{companyId}/data/invoices?query=amountDue%3e0,totalAmount%3c1000

var request = new RestRequest("companies/{companyId}/data/invoices", Method.GET);
request.AddUrlSegment("companyId", companyId);
request.AddUrlSegment("query", "amountDue>0,totalAmount<1000");
request.AddHeader("Authorization", $"Basic {encodedApiKey}");
var response = client.Execute(request);
var info = response.Data;
var query = new InvoicesQuery(companyId, 'amountDue>0,totalAmount<1000')
  .run(codat.uat(apiKey));

Paging

The Codat API uses a simple set of query parameters on data endpoints to facilitate paging through large amounts of data.

1. Request

To activate paging add 2 query parameters to your requests to a supporting dataset.

2. Response

{
    "results": [
        // This will be an array of the specified data type
    ],
    "pageNumber": 1,    // Current page number
    "pageSize": 1,      // Current max size for the page
    "totalResults": 1,  // Total size of the dataset
    "_links": {         // HAL links
        "self": "",     // Direct link to the dataset 
        "current" : "", // URL for the Current page
        "next": "",     // URL for the next page (where applicable)
        "previous": ""  // URL for the previous page (where applicable)
    }
}

You can use the totalResults and pageSize to calculate the number of pages that will be required to retrieve all of the available data.

3. Invoices example

GET /companies/{companyId}/data/invoices?page=1&pageSize=100

var request = new RestRequest("companies/{companyId}/data/invoices", Method.GET);
request.AddUrlSegment("companyId", companyId);
request.AddQueryParameter("page", 1.ToString());
request.AddQueryParameter("pageSize", 100.ToString());
request.AddHeader("Authorization", $"Basic {encodedApiKey}");
var response = client.Execute(request);
var info = response.Data;
var query = new InvoicesQuery(companyId, 
                    /* filter query */ null, 
                    /* page number  */ 1, 
                    /* page size    */ 100)
                .run(codat.uat(apiKey));

// Following of the pages directly from the HAL links is not yet supported by the client library.

Monitoring

Codat provides functionality to monitor changes in Companies financial data, via the Codat API, using Rules and Alerts.

Rules

Rules can be created to match on particular transactional events occurring (e.g. new customer added) or to identify trends over time (e.g. 10% drop in sales this quarter).

Alerts

Alerts are triggered when a Rule matches. An alert trigger can notify in three ways:

Notification Method Description
Portal Alerts on screen in the Codat portal
Email Alerts received via email to the address(es) registered for the Rule
Webhook A callback to a URL registered for the Rule

Recipes

How-To guides for the most common functions.

Your first call to the API using API Explorer

This guide will focus on making your first call to the API, from the comfort of your browser, using the Codat API Explorer.

Step 1 - You need an API key

Your API key is the secret token which authenticates your organisation with the Codat API.

If you are an Administrator or a Developer you can access your API key from the Codat portal (https://portal-uat.codat.io) under Account > Profile

If you do not have a portal login please contact your administrator on the Codat system who can create one for you. If you would like to sign up for a separate test Codat account please email support@codat.io.

You will need to copy your API key for step 2 below.

Step 2 - Set up API Explorer

When making calls to the API you must provide the correct authorisation, when using the API Explorer this is handled automatically once provided with your API key.

a. Open up the API explorer - https://api-uat.codat.io/swagger

b. Enter your API key into the box in the top-right corner

c. Click explore

The page will then appear to refresh, you are now ready for the next step.

Step 3 - Get all companies

The simplest first call to the API is to get a list of Companies you have added to the Codat system.

a. Click the word Companies, a drop-down list of available options (endpoints) for companies will then appear.

List of endpoints in Swagger for Companies section

b. Click the first endpoint in the list, GET /companies. This endpoint will fetch (GET) a list of the companies you have set up on the Codat system.

c. Click the "Try it out!" button to execute the request to the Codat API.

d. If all successful you should see a Response Code of 200 and a list of companies, in JSON format, in the Response Body.

Successful swagger response

If you haven't added any companies yet you can either do so via the Codat portal - Companies > Add Company - or via the API using the extension step below.

Extension - Add a company via API

a. Heading back to the drop-down list of endpoints under Company from step 3, select POST /companies

b. This time we will need to provide some information about the company we wish to create, the minimum amount of information is the name of the new company. Copy and paste the JSON below into the args parameter field as shown.

{
   "name" : "Recipe test company"
}

So the request should look like:

POST new company args

c. Click the "Try it out!" button to execute the request to the Codat API.

d. If all successful you should see a Response Code of 200 and the Response Body will contain details of the new company.

Now repeat step 3 above and you should see your new company in the list of companies returned by the GET /companies endpoint.

Your first call to the API using Postman

This guide will focus on making the same call to the API as above but using Postman rather than the API explorer.

Step 1 - Open up Postman

Postman is a HTTP client for testing web services, if you don't have Postman installed you can download it here.

Open up a new request in Postman, in the windows application this is done via the "New" button in the top left of the screen.

Step 2 - Set up request

We will be making a request to the API to fetch (GET) a list of Companies you have added to the Codat system.

a. The type of request should be set to GET

b. The request URL should be set to https://api-uat.codat.io/companies

Step 3 - Add authorization header

Codat expects for the API key to be included in all API requests to the server, Base64 encoded within an 'Authorization' header, you can read more in the Authentication section.

a. Take your API key and Base 64 encode it. If you don't know how to do this locally, for UAT only you can use an online tool to .

b. Add a new Header with Key equal to Authorization (note the US spelling) and value equal to the word Basic plus a space and your Base 64 encoded API key from the previous step.

Your request should now look similar to below:

Postman request

Step 4 - Execute request

Execute the request to the Codat API by clicking "Send".

If successful the response will be a JSON object containing a list of the companies you have added to the Codat system.

Is there another recipe you would like to see?

Let us know if there is another recipe you think would be useful for developers and we will add it to our collection.

Support

All support queries should be sent to support@codat.io.

When making a support request, please include: