Data connections

A data connection represents a company's connection to a data source and allows you to synchronize data (pull and/or push) with that source.

A company can have multiple data connections depending on the type of data source it is connecting to. For example, a single company can link to:

Any combination of accounting, banking, and commerce data connections is allowed.

Before you can use a data connection to pull or push data, the company must grant you access to their business data by linking the connection.

Data connection status

Data connections can have one of the statuses described in the following table.

Status

Definition

Linked

The connection is linked to a data source; you can use it to pull and push a company's consented data to and from the underlying provider's platform.

PendingAuth

The company hasn't authorized access to their financial platform (the data source). The SMB customer selected the platform in Link but did not complete the authorization flow.

Deauthorized

The connection was linked but is no longer able to access data from the underlying provider's platform.

You can access any data that was already pulled or pushed using this data connection. However, you can't perform any new pulls or pushes until the connection is re-linked.

A data connection usually becomes Deauthorized if the company revoked your access or an expiry time was reached.

Unlinked

The data connection was previously linked but you asked for your access to be revoked (see Disconnect a data connection to revoke your access to a data source).

Similar to Deauthorized, you can still access any data that was already pulled or pushed using the data connection, but can't perform any new pulls or pushes unless the connection is re-linked.

Linked data connection example

{
    "id": "00000000-0000-0000-0000-000000000000",
    "integrationId": "18cb53c4-3807-4a5a-8da9-303053a40002",
    "sourceId": "58e1d32f-a092-438a-bffb-3bf6af9ba8ec",
    "platformName": "Sage 50 (UK)",
    "linkUrl": "https://link.codat.io/companies/00000000-0000-0000-0000-000000000000/connections/00000000-0000-0000-0000-000000000000/start",
    "status": "Linked",
    "lastSync": "2022-01-01T12:00:00.0000000Z",
    "created": "2021-01-01T12:00:00Z",
    "sourceType": "Accounting"
}

Disconnect a data connection to revoke your access to a data source

You can disconnect a data connection using the PATCH /connectionId endpoint. This revokes your access to synchronize data with the linked company and sets the data connection's status to Unlinked.

To disconnect a data connection, you'll need to provide:

  • The companyId of the linked company as a path parameter.
  • The connectionId of the data connection to disconnect as a path parameter.
  • A status of Unlinked in the request body.

When a connection is set to Unlinked, you can continue to access any data that was already pulled or pushed to the data source, but you can't perform any new pulls or pushes (unless the connection is re-linked).

📘

Only Linked data connections can be unlinked.

Example: Disconnect a data connection

PATCH /companies/COMPANY_ID/connections/CONNECTION_ID

Request body:

{
  "status": "Unlinked"
}

Sample response to Unlinked request

{
  "id": "69c25cc8-e1cd-4b63-b43d-75da021df35d",
  "integrationId": "43b64770-a953-46d6-ab30-46c21094a276",
  "sourceId": "9a96f326-226a-4e0f-923a-6758fdba40cc",
  "platformName": "Stripe",
  "linkUrl": "https://link.codat.io/link/start/c9219b93-4eff-4806-99d8-ed3337b6ded2/69c25cc8-e1cd-4b63-b43d-75da021df35d",
  "status": "Unlinked",
  "lastSync": "2021-02-11T12:12:13.1988465Z",
  "created": "2021-02-11T12:04:53Z",
  "sourceType": "Commerce"
}

Delete a data connection

To delete a data connection, send a request to the DELETE /connectionId endpoint and provide the companyId and connectionId as path parameters.

DELETE /companies/COMPANY_ID/connections/CONNECTION_ID

When you delete a data connection:

  • You can't make any data pulls or pushes against the underlying data provider.
  • The data connection isn't returned by GET /connections or GET / companies.

Did this page help you?