> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chift.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/developer-guides/syncs/overview) first.

## Prerequisites

1. **An API key**, and a bearer token you create from it. See [Authenticate with Chift API](/developer-guides/chift-authentication).
2. **A sync built with Chift**, identified by a `syncid`. Chift builds the sync and its flows with you. Find the `syncid` with [Get syncs](/api-reference/endpoints/syncs/get-syncs).
3. **At least one active connector** for the software your end-user connects. See [Activate a connector](/back-office/getting-started/activate-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.

<Info>
  **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.
</Info>

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](/syncs/expose-overview) for options such as the [pre-OAuth2 sync](/syncs/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.

<Frame caption="Embedded connector-picker: your end-user chooses their software inside your product.">
  <img src="https://mintcdn.com/chift/vSJ6kANJcydTHQ9s/images/embedded-connector-picker.png?fit=max&auto=format&n=vSJ6kANJcydTHQ9s&q=85&s=ddcd5a05417492b44004cc4dd5727aba" alt="Connector choice shown inside your own product" width="839" height="319" data-path="images/embedded-connector-picker.png" />
</Frame>

**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.

<Frame caption="Chift connector-picker: your end-user chooses their software on a Chift-hosted page.">
  <img src="https://mintcdn.com/chift/vSJ6kANJcydTHQ9s/images/chift-connector-picker.png?fit=max&auto=format&n=vSJ6kANJcydTHQ9s&q=85&s=5af1fad4444aa7507f5a6a024878d0ad" alt="Connector picker on the Chift-hosted page" width="1282" height="737" data-path="images/chift-connector-picker.png" />
</Frame>

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

<Steps>
  <Step title="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.

    ```bash theme={null}
    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](/developer-guides/syncs/activation-and-redirects). |

    <Note>
      Already have a `consumerid` for this end-user? Skip this step.
    </Note>

    [API reference: Create new consumer ↗](/api-reference/endpoints/consumers/create-new-consumer)
  </Step>

  <Step title="Fetch the connectors (embedded connector-picker only)">
    Skip this step if you use the Chift connector-picker.

    ```bash theme={null}
    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 ↗](/api-reference/endpoints/integrations/get-list-of-integrations)
  </Step>

  <Step title="Present the connector-picker">
    Choose the option that matches your setup (see [Two ways to present the choice](#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.
  </Step>

  <Step title="Create the sync activation link">
    Create the link for this consumer with a `POST`. Pass the `syncid` of the sync Chift built for you.

    ```bash theme={null}
    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`.

    <Note title="Which connectors to pass">
      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`.
    </Note>

    [API reference: Retrieve the url of a sync for a specific consumer ↗](/api-reference/endpoints/consumers/retrieve-the-url-of-a-sync-for-a-specific-consumer)
  </Step>

  <Step title="Send your end-user to the activation link">
    Redirect your end-user to the returned `url`, or email it to them.

    <Warning>
      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.
    </Warning>

    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](#two-ways-to-present-the-choice)).
  </Step>

  <Step title="Confirm the setup">
    When your end-user finishes, read the sync status for the consumer. Confirm the status is `active`.

    ```bash theme={null}
    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](/developer-guides/syncs/monitor-executions) to monitor the sync over time.

    [API reference: Get sync information for one consumer ↗](/api-reference/endpoints/consumers/get-sync-information-for-one-consumer)
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Activation links & redirects" icon="arrow-right-arrow-left" href="/developer-guides/syncs/activation-and-redirects">
    The sync activation link, connector pre-selection, and the redirect.
  </Card>

  <Card title="Monitor sync executions" icon="heart-pulse" href="/developer-guides/syncs/monitor-executions">
    Confirm setup, list executions, and trigger a run.
  </Card>

  <Card title="Error codes" icon="triangle-exclamation" href="/developer-guides/errors">
    Every code the endpoints above can return.
  </Card>
</CardGroup>