First API call

This article explains how to make your first call to the API, from the comfort of your browser, using the Codat API Explorer. Complete the following steps in order. Don't worry no coding is required!

Find your API key

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

If you're 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 [email protected]

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

Set up the 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.codat.io/swagger/index.html

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.

Retrieve a full list of your 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.

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.

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:

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.


Did this page help you?