Activate a sync for a consumer

Activating a sync links one of your end-users to a sync Chift built for you. This page shows each step, from an empty consumer to the Chift-hosted page where your end-user connects their software. New to the model? Read Building with Syncs first.

Prerequisites

An API key, and a bearer token you create from it. See Authenticate with Chift API.
A sync built with Chift, identified by a syncid. Chift builds the sync and its flows with you. Find the syncid with Get syncs.
At least one active connector for the software your end-user connects. See Activate a connector. You cannot connect a connector you have not activated.

What your end-user connects

A sync connects two Unified APIs. Usually, one side is your own software. This side is the same for every end-user, so your end-user does not choose it. Your end-user chooses only the other side: their own software, such as their accounting software.

Example. Your product is an e-commerce software. The sync fetches invoices from your software. It books them into the end-user’s accounting software. The e-commerce side is always your software. Your end-user chooses only their accounting software.

You can also pre-authenticate your software’s side. Then your end-user connects only their own software. You arrange this with Chift when Chift builds the sync. If you do not pre-authenticate your side, your end-user also authenticates your software during the setup. See the expose models for options such as the pre-OAuth2 sync.

Two ways to present the choice

You can present the connector choice in two ways. Both ways run the same flow. They differ in one point only: who shows your end-user the connectors for their software. It is a trade-off between a native experience and the amount you build. Embedded connector-picker — you show the connector choice inside your own product. You pass the chosen connector as integrationids. The Chift-hosted sync page then opens with the connector pre-selected. This gives the most on-brand experience, but you build and maintain that screen.

Connector choice shown inside your own product — Embedded connector-picker: your end-user chooses their software inside your product.

Chift connector-picker — Chift hosts the picker on the sync page. You build nothing. Omit integrationids. Your end-user then chooses their software on the Chift-hosted page.

Connector picker on the Chift-hosted page — Chift connector-picker: your end-user chooses their software on a Chift-hosted page.

Both paths end the same way. You send a link to the Chift-hosted sync page. There, your end-user also confirms the mappings the flow needs.

The flow

Create the consumer

Create one consumer per end-user. Store the returned consumerid on your end-user record. Reuse it for every sync and connection that end-user makes.

curl -X POST https://api.chift.eu/consumers \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your end-user'\''s company name",
    "internal_reference": "your-internal-end-user-id",
    "email": "contact@your-end-user.example",
    "redirect_url": "https://yourapp.example/syncs/callback"
  }'

Field	Required	Notes
`name`	Yes	Shown in your Chift platform and used in automated emails.
`email`	No	Used for activation reminders and emails.
`internal_reference`	No	Your own ID for this end-user. Makes reconciliation easier later.
`redirect_url`	No	Where Chift sends the end-user after activation. You can also set one default for the account. See Activation links & redirects.

Already have a consumerid for this end-user? Skip this step.

API reference: Create new consumer ↗

Fetch the connectors (embedded connector-picker only)

Skip this step if you use the Chift connector-picker.

curl "https://api.chift.eu/integrations?status=active" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

status=active returns only the connectors you have activated. Each entry includes integrationid (an integer), name, api, and logo fields. Filter on api to show only the connectors for the software your end-user chooses, such as accounting.API reference: Get list of integrations ↗

Present the connector-picker

Choose the option that matches your setup (see Two ways to present the choice):Embedded connector-picker — render the list from the previous step in your own UI. Let your end-user choose the connector for their software. Pass the chosen integrationids in the next step.Chift connector-picker — you build nothing here. Skip this step. Omit integrationids in the next step. Your end-user chooses their software on the Chift-hosted page after you send the link.

Create the sync activation link

Create the link for this consumer with a POST. Pass the syncid of the sync Chift built for you.

curl -X POST https://api.chift.eu/consumers/{consumerid}/syncs \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "syncid": "your-sync-id",
    "integrationids": ["42"]
  }'

Field	Required	Notes
`syncid`	Yes	The sync Chift built for you.
`integrationids`	No	Array of `integrationid` values for the software your end-user chooses. Pass at most one per Unified API. Chift then shows only these connectors. Omit it to let your end-user choose on the Chift connector-picker.
`country`	No	ISO 3166-1 alpha-2 code. Filters the connector list by country. Chift ignores it when you set `integrationids`.
`link_metadata`	No	Free-form object. Chift stores it and returns it in the sync status.

The call returns one field, url.

Your end-user chooses only the connector for their own software. Your own software is usually the only active connector of its type on your account, so Chift selects it automatically and you do not pass it. integrationids accepts at most one id per Unified API. Two ids for the same Unified API return HTTP 400. An id that is not part of the sync also returns HTTP 400.

API reference: Retrieve the url of a sync for a specific consumer ↗

Send your end-user to the activation link

Redirect your end-user to the returned url, or email it to them.

A token secures the link. The token expires 30 minutes after you create it. Create the link just before your end-user opens it. If the token expires, call the endpoint again to create a new link.

Your end-user opens the Chift-hosted sync page. There, your end-user connects their software and confirms the mappings the flow needs. If you set integrationids, the connector is pre-selected. If you do not, your end-user first chooses their software on the Chift connector-picker (see Two ways to present the choice).

Confirm the setup

When your end-user finishes, read the sync status for the consumer. Confirm the status is active.

curl "https://api.chift.eu/consumers/{consumerid}/syncs/{syncid}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

status returns active once the consumer completes the setup. Otherwise it returns inactive. When the status is inactive, status_details explains why.Do not rely on the redirect alone. An end-user who abandons the flow never triggers it. See Monitor sync executions to monitor the sync over time.API reference: Get sync information for one consumer ↗

Next steps

Activation links & redirects

The sync activation link, connector pre-selection, and the redirect.

Monitor sync executions

Confirm setup, list executions, and trigger a run.

Error codes

Every code the endpoints above can return.

Getting started

Unified API

Syncs

Core docs & concepts

Datalayer

API's guides

Activate a sync for a consumer

Prerequisites

What your end-user connects

Two ways to present the choice

The flow

Next steps

Activation links & redirects

Monitor sync executions

Error codes

​Prerequisites

​What your end-user connects

​Two ways to present the choice

​The flow

​Next steps

Activation links & redirects

Monitor sync executions

Error codes

Prerequisites

What your end-user connects

Two ways to present the choice

The flow

Next steps