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.

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 Essentials 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

Below you will find some useful "how to" guides for common functions within Codat to help you familiarise yourself with the API.

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.

Using Postman to call the API

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.

Linking, re-linking and pulling data using the Codat API

This section covers how to link a company and pull data using the API. It is intended to give more guidance on platform best-practice rather than give a detailed step-by-step taster like the previous recipes.

User onboarding

You can onboard users to the Codat API when they first create an account with your service or at the first point you wish to create a connection to their accounting data.

Step 1 - Create a Codat company

To create a company in Codat, use the POST /companies endpoint with a request body containing the name for the company, as you wish it to appear in Codat.

Request:

{
   "name": "YOUR IDENTIFIER FOR COMPANY"
}

Response:

{
  "id": "a77cbf07-ca1a-4a36-a252-957cf6097925",
  "name": "YOUR IDENTIFIER FOR COMPANY",
  "platform": "",
  "redirect": "https://link-uat.codat.io/a77cbf07-ca1a-4a36-a252-957cf6097925/link",
  "status": "PendingAuth",
  "lastSync": null,
  "dataConnections": []
}

The id property from this response should be persisted in your system as the unique Codat identifier for this company.

Step 2 - Redirect the user

Send the user to the redirect URL returned in the previous step. They will be sent to the Codat Link Site where they can select their accounting software and complete the link process.

Step 3 - Callback from Codat

Once the user has completed the link flow, the Codat platform will redirect them to the Redirect Parameter URL you have configured in the Authorisation Flow page in the Codat portal. This URL can include the Codat companyId as well as other custom query parameters.

Once your user is redirected to the page specified by the Redirect Parameter, the link process is complete and their accounting data has begun synchronising.

Pulling data

Step 1 - Retrieve Codat companyId from storage

The id that you persisted in Step 1 of User Onboarding will let you interact with the relevant Codat entity for your user.

Step 2 - Check data freshness

If the freshness of data from the platform is important for your use-case, or if you’re pulling data for the first time and need to ensure the Codat sync has completed correctly, you can use the GET /companies/{companyId}/dataStatus endpoint to check the last time each dataset was synchronised.

Response

{
  "suppliers": {
    "dataType": "suppliers",
    "lastSuccessfulSync": "2018-06-11T13:26:54.6884704Z",
    "currentStatus": "Complete",
    "latestSyncId": "31632c48-23dc-4cb1-b3ff-0829343c8e85",
    "latestSuccessfulSyncId": "31632c48-23dc-4cb1-b3ff-0829343c8e85"
  },
  ...
}

Step 3 - Queue a new data sync (Optional)

If there are datasets which are not as up-to-date as you require, you can use the POST /companies/{companyId}/data/queue/{datatype} endpoint to queue a new sync for that datatype. If all datasets need to be resynchronised, it will be faster to use the POST /companies/{companyId}/data/all endpoint to queue all the datasets.

Once you've queued the sync, you can poll the GET /companies/{companyId}/dataStatus endpoint (as described above) to monitor progress of the sync.

Step 4 - Request specific data type

Codat exposes endpoints for easily querying each of the supported data types; each of these endpoints is detailed in our Swagger documentation.

For example, when querying invoices, you can use the GET /companies/{companyId}/data/invoices endpoint, with query string parameters as below:

Re-linking a company

Occasionally a Codat company will go into a deauthorized state. This indicates that Codat’s link to the accounting software is no longer valid, and you will not be able to queue any further data syncs for that company. You will still be able to query data previously retrieved from the platform.

Companies can become deauthorized by the user revoking access within their accounting software or due to platform limitations such as Xero's limited access period for non-partner companies.

To enable you to sync new data, you will need to ask the user to complete the link flow again as detailed below.

Step 1 - Retrieve Codat companyId from storage

The companyId that was returned in Step 1 of User Onboarding should be re-used for the link flow.

Step 2 - Get the company's data from Codat API

To get the URL that the user should be redirected to, use the GET /companies/{companyId} endpoint and look for the redirect field in the response.

Example response from GET /companies/{companyId}:

{
  "id": "a77cbf07-ca1a-4a36-a252-957cf6097925",
  "name": "YOUR IDENTIFIER FOR USER HERE",
  "platform": "Sandbox",
  "redirect": "https://link-uat.codat.io/link/start/ a77cbf07-ca1a-4a36-a252-957cf6097925/80315c32-be70-4da3-8725-615555b25cc4",
  "status": "Deauthorized",
  "lastSync": "2018-05-23T14:40:21.173Z",
  "dataConnections": []
}

Send the user to the redirect URL returned in the previous step. They will be sent to the Codat Link Site where they can select their accounting software and complete the link process.

Step 4 - Callback from Codat

Once the user has completed the link flow, the Codat platform will redirect them to the Redirect Parameter URL you have configured in the Authorisation Flow page in the Codat portal. This URL can include the Codat companyId as well as other custom query parameters.

Once your user is redirected to the page specified by the Redirect Parameter, the re-authorisation process is complete and their accounting data has begun synchronising again.

Recipe requests?

If there's another recipe you think would be useful and would like to see, please get in touch with us and we can add it to our collection. Just send us an email with a description of what you're looking for.

Support

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

When making a support request, please include: