Step 2: Connect

Connect is the second most important step of the process and it involves:

  • Adding a company
  • Linking the company to the Sandbox
  • Synchronising company financial data

Add a company

CompaniesCompanies - Businesses (typically SMEs) whose financial data are being connected to via the Codat Portal. As a user of the Codat Portal, companies are your customers. in Codat are your customers.

  1. On Codat's Swagger page, select Companies > POST /companies, and then Try it out.
  2. Provide some information about the company you wish to create, for example, the name of the new company. For testing purposes, you may use the sample request below and paste it into the Request body.
  3. Execute the request to the Codat API. You will get a Response Code of 200 and the Response Body will contain details of the new company, including the redirect you will need in the next step.
{
 "name": "Recipe test company"
}
{
  "id": "2432c867-9983-48c1-b42f-bb3efabfe4e1",
  "name": "Recipe test company",
  "platform": "",
  "redirect": "https://link-uat.codat.io/13ef4c46-aa33-4661-96c5-d47e90b4bd62/link",
  "status": "PendingAuth",
  "dataConnections": [],
  "created": "2021-02-21T17:03:36.1526072Z",
  "createdByUserName": "Magdalena Wk"
}

📘

Codat API offers many other company options

Link the company to the Sandbox

With a new company created, you can now link it to the Codat Sandbox environment. The Sandbox is a replica of the Portal production environment, supporting all of the same API endpoints. The Sandbox contains dummy accounting data generated especially for the purpose of your testing.

  1. Copy the redirect URL returned in the previous step in the Response Body.
  2. Send the redirect URL to your customer. They will need to paste the link into their browser. Next, they will be prompted to go to the Codat Link Site where they can connect to the Sandbox and complete the linking process.

Once the company authorises the connection, its status under GET /companies/{companyId} changes to: linked.

{
  "id": "2432c867-9983-48c1-b42f-bb3efabfe4e1",
  "name": "Recipe test company",
  "platform": "Sandbox",
  "redirect": "https://link-uat.codat.io/2432c867-9983-48c1-b42f-bb3efabfe4e1/link",
  "status": "Linked",
  "lastSync": "2021-03-01T12:35:19.7095473Z",
  "dataConnections": [
    {
      "id": "ea014f81-d3b4-4d99-a4fe-fd48f226b719",
      "integrationId": "9e0cc03b-3868-4543-98c0-568f0f1b12a3",
      "sourceId": "aff0f057-255f-42c4-8d4a-ae23b43e1615",
      "platformName": "Sandbox",
      "linkUrl": "https://link-uat.codat.io/link/start/2432c867-9983-48c1-b42f-bb3efabfe4e1/ea014f81-d3b4-4d99-a4fe-fd48f226b719",
      "status": "Linked",
      "lastSync": "2021-03-01T12:35:19.7095468Z",
      "created": "2021-03-01T12:34:53Z",
      "sourceType": "Accounting"
    }
  ],
  "created": "2021-03-01T12:34:24Z"
}
Link Site - your customer's view when connecting to the Codat PortalLink Site - your customer's view when connecting to the Codat Portal

Link Site - your customer's view when connecting to the Codat Portal

Synchronise company data

Before you can see the data of the linked company in the Codat Portal, they need to be synchronised. In simple terms, synchronisation (also known as "sync") is needed to maintain consistency between the data on the Codat Portal and the data provided by the integration your company has linked to the Portal. When your customer authorises connection to their company data, Codat automatically obtains their datasets.

Note: You can configure which data types are synchronised during the first link under Codat Portal sync settings.

The data set is queued for synchronisation when you make a request to POST /companies/{companyId}/data/all. You can find your company ID in the Codat Portal on the Companies tab or in the GET /companies endpoint.

When Fetch on first link is turned off in the Codat Portal sync settings for a data type, you can still synchronise individual data type making a request to POST /companies/{companyId}/data/queue/{dataType}.

Sample requestSample request

Sample request

{
  "id": "dec486c0-082b-4164-bc38-91fadad4c8a4",
  "companyId": "73f61a39-0d2b-4a9e-ab43-36495202f781",
  "connectionId": "6a582306-aab4-40f5-9a2c-03574ff8b9b7",
  "dataType": "bills",
  "status": "Initial",
  "requested": "2021-02-21T17:05:40.5730806Z",
  "progress": 10,
  "isCompleted": false,
  "isErrored": false
}

Did this page help you?