Guide for developers

We'll take you from making your first API call through to exploring company data in three steps:

1. Authenticate with Codat's API and make your first request.
2. Connect to your SMB customers' company data.
3. Explore the data shared by the company.

📘

Codat account required

You'll need a Codat account and its API key for this tutorial. If you haven't signed up for an account yet, see how to create one here.

Step 1: Authenticate

Codat uses API keys to control access to the API. You can get your API key and corresponding authorization header by following our guide.

When you've found your API key and authorization header, make your first API call using our API reference, or in code.

Make your first API call using our API reference

1. View our API reference and select Companies in the left navigation.

   This displays the endpoints available for interacting with Companies. By default, the All companies endpoint is selected, which lists all of your created companies.

2. Add your authorization header to the Authentication section on the right-hand side of the page.

3. Edit the query parameters for the API request, if needed. Parameters page and pageSize are set automatically.

4. To execute the API request, click Try it! in the code sample on the right-hand side of the page.

The API response is returned in the Response section beneath the code sample, alongside a 200 code if it was successful.

Make your first API call in code

1. Create a new REST client using <https://api.codat.io> as the base URL.
2. Add your Authorization header.
3. Create a GET request for the /companies endpoint.
4. Execute the request.

// Using RestSharp;

var baseUrl = "https://api.codat.io";
var authHeaderValue = "Basic ABCDEF1234567890";

// Create a RestClient using the Codat API's base URL
var codatApiClient = new RestClient(baseUrl);

// Add your authorization header
codatApiClient.AddDefaultHeader("Authorization", authHeaderValue);

// Create a GET request
var getCompaniesRequest = new RestRequest("companies", Method.GET);
getCompaniesRequest.AddQueryParameter("page", "1");

// Execute the request
var getCompaniesResponse = codatApiClient.Execute(getCompaniesRequest);

import requests

baseUrl = 'https://api.codat.io/'
authHeaderValue = 'Basic ABCDEF1234567890=='

getCompaniesUrl = baseUrl + 'companies?page=1&pageSize=100'
requestHeaders = {'Authorization' : authHeaderValue}

getCompaniesResponse = requests.get(getCompaniesUrl, headers=requestHeaders)

Step 2: Connect

You can easily connect your SMB customers' financial accounts with our auth flow. To try it out, create a new company, link it to our sandbox, and synchronize the company's financial data.

Companies in Codat represent your customers.

📘

Codat sandbox

The Sandbox integration supports all available API endpoints. It contains a complete set of synthetic accounting, commerce, and banking data generated specifically for testing.

Add a new company

1. Head to our API reference, navigate to Companies and select the Create company endpoint.

2. Enter a name for the company in the name parameter.

   You can also add the platformType parameter to specify an integration platform for the new company in advance. Retrieve the platform key to use it in your request, or pick up accounting platform keys here and commerce platform keys here. Alternatively, the platformType parameter will be picked up when your customer selects a platform in the Link flow.

3. Now, click the Try it button and review the response. The response body contains details of the new company, including the redirect URL you will need next.

You can also explore other Companies endpoints in the API reference used to update, delete and modify existing companies.

Link the company to the Sandbox

With a new company created, you can link to our Sandbox and browse some sandbox data using our Link feature.

1. Copy the redirect URL returned in the response body of the previous step. This URL is what you would typically send to your customer to complete the linking process.

2. Paste the Link URL into your browser and follow the Link auth flow and select the Sandbox integration. You don't need to enter any credentials.

Once you have completed linking the connection, you can see that the company's status under the View a single company endpoint changes to linked.

Synchronize company data

When the company was linked in the previous step, Codat then pulled the data for it from the Sandbox. This happens automatically on linking, though you can disable this setting). If you want to pull data for that company again, you can trigger this via our API:

1. Find your companyId, the required request parameter, in the Codat Portal on the Companies tab or via the View all companies endpoint.

2. To queue a data set for synchronization, make a request to the Pull new data snapshot endpoint.

📘

Data type synchronization

You can configure which data types are synchronized during the first link under Codat Portal data type settings.

You can synchronize individual data types by making a request to the Pull new data snapshot for a data type endpoint.

Step 3: Explore

Now you can access and view your customers' financial data and gain immediate insight into their finances.

Check data freshness

Use the Get datatype status endpoint to check the last time a data type was synchronized.

The date and time of the last successful sync will be returned in the response under the lastSuccessfulSync parameter.

Access synchronized data

Codat provides various endpoints for you to query each of the supported data types easily.

For example, when querying invoices, use the All invoices endpoint. You can perform filtering on the response data using querying.

Push data

You can create a record in a company's accounting software (POST) or update an existing record (PUT) using Codat's Push data endpoints.

For example, you can post a new invoice to a company's accounting platform by using the Create invoice endpoint.

Remember to provide the required parameters in addition to the invoice detail in the request body. Use the All connections endpoint to get your connectionId. To view the required body parameters for a data type, use the Get POST push options endpoint.