Skip to main content

Data Connections

A data connection represents a user's connection to a provider. It allows you to synchronize the user's data from that provider. A user can have multiple data connections to the same provider (except for providers marked as unique).

Data connection status

  • AUTH_REQUIRED: When the data connection is first created and the provider requires authorization of the user. You have to redirect the user to redirect_url
  • CONNECTING: When the user has first accessed the redirect_url
  • CONNECTED: When the data connection if ready for synchronization. The user has given its authorization or no authorization is needed.
  • AUTH_ERROR: When an authorization error occurred during a synchronization. You have to redirect the user to redirect_url to re-authorize the connection
  • DISCONNECTED: When you manually revoked your access to the data connection

Create a data connection

Use POST /api/v6/users/{userId}/data-connections to create a data connection. You have to specify:

  • The provider_name
  • The list of data types you want to be able to access from that connection (requested_data_types)
  • Whether you want to show the permission list to the user. If not you have to do it yourself. (skip_permissions)

The list of requested data types must be supported by the provider.

Delete a data connection

Use DELETE /api/v6/users/{userId}/data-connections/{dataConnectionId} to delete a data connection.

:::notice caution When you delete a data connection, all the data coming from it will be deleted as well. :::

Edit a data connection status

Use PATCH /api/v6/users/{userId}/data-connections/{dataConnectionId} to edit the data connection. You have to specify:

  • The status the data connection will have. If the provided value is DISCONNECTED it will disconnect the data connection. If the value is AUTH_REQUIRED it will reconnect the data connection or ask for authentication if required.
  • The requested_data_types The list of data types you want to be updated.

Caution, you can change the status to:

  • DISCONNECTED only if the current status is CONNECTED or AUTH_ERROR.
  • AUTH_REQUIRED only if the current status is DISCONNECTED or AUTH_ERROR.

You can update the requested_data_types only if the current status is DISCONNECTED or AUTH_ERROR.

Data connection object

FieldTypeDescription
iduuidUnique id of the data connection
provider_namestringName of the associated provider
requested_data_typesarray of stringsArray of requested data types
skip_permissionsboolWhether or not to skip the display of permission list when the user access the redirect_url
redirect_urlstringWhere to redirect the user to start the authorization process
return_urlstringThe url on your system where the user is redirected when the authorization process is finished
statusstringStatus of the data connection
connected_atdatetimeWhen the data connection changed to status CONNECTED
created_atdatetimeWhen the data connection was created
disconnected_atdatetimeWhen the data connection was disconnected (either AUTH_ERROR or DISCONNECTED)

If the return_url is provided, you will be redirected to this URL with the status:

  • status=success if the connection was successful.
  • status=abort if the user canceled the connection.