Pulling data

This article covers how to link a company and pull data using the Codat API. Unlike the previous articles, it is intended to give more guidance on platform best practice rather than give a detailed step-by-step process.

User onboarding

Use the following process to onboard users to the Codat API. You can either onboard users:

  • When they first create an account with your service.
  • At the first point you wish to create a connection to their accounting data.

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.

📘

Company name

The name of the company doesn't have to be unique. It's just there to help you identify the company in the portal.

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.

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.

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.

📘

Redirect parameter settings

For more information on setting your Redirect Parameter, please refer to your onboarding docs.

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

Retrieve Codat companyId from storage

The id that you persisted in Create a Codat company will let you interact with the relevant Codat entity for your user.

Check data freshness

Use the GET /companies/{companyId}/dataStatus endpoint to check the last time each data type was synchronised.

When you’re pulling data for the first time, this endpoint can confirm when the sync is successful.

Response for a successful first sync

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

Response for an unsuccessful first sync

{
  "suppliers": {
    "dataType": "suppliers”
    "currentStatus": "FetchError",
    "latestSyncId": "31632c48-23dc-4cb1-b3ff-0829343c8e85",
  },
  ...
}

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.

📘

You can configure a sync schedule in the Codat portal to keep each data type at an acceptable freshness. For more information, please refer to your onboarding docs or contact [email protected].

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:

  • pageSize – the size of page you wish to retrieve
  • page – which page number you wish to retrieve
  • orderBy – the property you wish to order the response by
  • query – any filter you wish to perform on the returned data (see Querying for details)

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.

Retrieve Codat companyId from storage

The companyId that was returned in Create a Codat company should be re-used for the link flow.

❗️

Re-linking and usage costs

Creating a new company may cause additional data to be pulled from the platform and is likely to incur additional usage costs.

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.

{
  "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": []
}

Redirect the user to complete the link flow

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.

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.

📘

For more information on setting your Redirect Parameter, please refer to your onboarding docs.

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.


Did this page help you?