Create a connection

A connection links one of your end-users to one of their software packages. This page walks through creating one, from an empty consumer to a link your end-user can open. New to the model? Read How it works first. It defines connector, consumer, and connection in two minutes.

Prerequisites

An API key, and a bearer token obtained from it — see Authenticate with Chift API.
At least one active connector on your account — see Activate a connector. Connectors you have not activated are invisible to the API and cannot be connected.

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 list of connectors to choose from. 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. The most seamless, on-brand experience for your end-user, but you build and maintain that screen.

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

Chift connector-picker — Chift hosts the connector picker. Nothing to build on your side, but your end-user briefly leaves your interface for a Chift-hosted page.

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

Both end the same way: a link you send your end-user. The mechanics differ only slightly. The embedded path uses the fetch-connectors step and passes an integrationid; the Chift path skips both.

The flow

Create the consumer

Create one consumer per end-user. Store the returned consumerid on your end-user record — you reuse it for every 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/integrations/callback"
  }'

Field	Required	Notes
`name`	Yes	Shown in your Chift platform and used in automated emails.
`email`	No	Used for activation reminders and emailing the local agent installer.
`internal_reference`	No	Your own ID for this end-user. Makes reconciliation much easier later.
`redirect_url`	No	Where the end-user lands after activation. Can also be set once for the whole account — see Activation links and 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 gives you:

integrationid — an integer, the value you send in 4. Note it is not a uuid, unlike most Chift identifiers.
name, description, api — for display and grouping.
logo_url, icon_url — ready-to-use image URLs. A base64 endpoint also exists if you prefer to proxy them.
supported_countries, local_agent — useful for filtering or warning the user upfront.

API reference: Get list of integrations ↗

Present the connector-picker

Two ways to do this — pick the one matching your setup (see Two ways to present the choice):Embedded connector-picker — render the list from step 2 in your own UI. To narrow it, filter on supported_countries, or on api if this part of your product only needs one Unified API. You pass the chosen integrationid in the next step.Chift connector-picker — nothing to build here. Skip this step and omit integrationid in the next step; your end-user picks their software on the Chift-hosted page after you send them the link.

Create the connection

Create the connection for this consumer with POST:

curl -X POST https://api.chift.eu/consumers/{consumerid}/connections \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationid": 42,
    "name": "Odoo"
  }'

Field	Required	Notes
`integrationid`	No	Integer from step 2. Omit it to let the user choose on Chift’s connector-picker page.
`name`	No	Display name. Only valid together with `integrationid`.
`redirect`	No	Default `false`. Ignored when `integrationid` is set. See Activation links and redirects.
`country`	No	ISO 3166-1 alpha-2, filters the connector-picker list. Ignored when `integrationid` is set.
`apis`	No	Restricts the connector-picker to given Unified APIs. Ignored when `integrationid` is set.

The call returns a single field: url.

If the consumer already has this connection (for example to refresh expired credentials) update it instead of creating a new one. This issues a fresh activation link while preserving the connection and its history. See Update an existing connection ↗.

Add new connection ↗

Send the user to the activation link

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

The link is secured by a token that expires after 30 minutes. Generate it when the user is about to click it, not in advance.

With integrationid set, the link goes straight to that connector; without it, your end-user first picks their software on the Chift connector-picker (see Two ways to present the choice).What the user then sees depends on the connector: an OAuth2 consent screen, a credentials form, or instructions to install the local agent. Some connectors then ask follow-up questions — which accounting folder, which POS location.

Handle the return

When the user finishes, reload their connections and confirm at least one is active. Then you can call the Unified API for that consumer.Do not rely on the redirect alone — a user who abandons the flow never triggers it. See Monitoring & updating connections for the webhook, polling, and redirect-parameter options, and which combination to use.

Next steps

Monitor connections

Confirm activation, then keep connections healthy.

Activation links and redirects

Control where the user lands afterwards.

Error codes

Every code the endpoints above can return.

Getting started

Unified API

Syncs

Datalayer

Core concepts

Accounting

Invoicing

POS

eCommerce

PMS

Payment

Banking

Create a connection

Prerequisites

Two ways to present the choice

The flow

Next steps

Monitor connections

Activation links and redirects

Error codes

​Prerequisites

​Two ways to present the choice

​The flow

​Next steps

Monitor connections

Activation links and redirects

Error codes

Prerequisites

Two ways to present the choice

The flow

Next steps