Getting started for developers

📘

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, you can sign up here.

To get started with Codat's API, follow these 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.

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)

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. 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 now link it to the Codat sandbox environment.

1. Copy the redirect URL returned in the response body of the previous step. Send the redirect URL to your customer.

2. The customer needs to paste the Link URL into their browser. They will be prompted to go to Link, where they can connect to the Sandbox and complete the linking process.

Once the company authorizes the connection, its status under the View a single company endpoint changes to linked.

Synchronize company data

When your customer authorizes connection to their company data, Codat automatically obtains their datasets.

Now, you need to synchronize the data of the linked company in the Codat Portal to maintain data consistency.

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.