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

Field	Type	Description
id	uuid	Unique id of the data connection
provider_name	string	Name of the associated provider
requested_data_types	array of strings	Array of requested data types
skip_permissions	bool	Whether or not to skip the display of permission list when the user access the redirect_url
redirect_url	string	Where to redirect the user to start the authorization process
return_url	string	The url on your system where the user is redirected when the authorization process is finished
status	string	Status of the data connection
connected_at	datetime	When the data connection changed to status CONNECTED
created_at	datetime	When the data connection was created
disconnected_at	datetime	When 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.