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 organization with the Codat API.

If you're an Administrator or a Developer you can access your API key from the Codat Portal under Settings > Organization.

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 authorization, when using the API Explorer this is handled automatically once provided with your API key.

a. Open up Swagger, our API explorer

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.

10261026

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.

10061006

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.

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.

You can also add the platformType parameter to specify an integration platform you would like to set up for the new company. Retrieve the platform key first and then use it in your request.

Copy and paste the sample request below into the request body as shown.

{
  "name": "Platypus Properties",
  "platformType": "gbol"
}

So the request should look like this:

960960

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.

Retrieve platform keys

To identify individual accounting, commerce and banking integration platforms, Codat uses unique four-character codes. These are then used as values for the platform parameters in endpoints, such as platformType, key and platformKey.

You can use the Integrations endpoint to send a GET request and obtain the full list of platforms.

Please review the example response for Xero, an accounting integration platform. The unique four-character value for this platform is returned in the key parameter.

{
  "results": [
    {
      "name": "Xero",
      "key": "gbol",
      "logoUrl": "https://static.codat.io/public/platforms/gbol.png",
      "enabled": true,
      "sourceId": "8a156a5a-39cb-4f9d-856e-76ef9b9a9607",
      "integrationId": "0f20c943-12d0-4800-9f6c-d218f62d494c",
      "sourceType": "Accounting",
      "isOfflineConnector": false,
      "isBeta": false,
      "supportedEnvironments": "LiveAndSandbox",
      "linkedConnectionsCount": 1,
      "totalConnectionsCount": 3,
      "dataProvidedBy": "Codat",
      "datatypeFeatures": []
        }
      ]
    }

If you have a specific integration platform for which you need to retrieve a key, you can send a GET request with the platform name in the query. For additional details on querying, you can review our Querying documentation.


Did this page help you?