Create a connection

A connection links one of your customers 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

The one thing that differs is who shows your end-user the list of connectors to choose from. Everything else in the flow is the same. It is a trade-off between a native experience and how much you build. Embedded marketplace — 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 marketplace: your end-user picks their software inside your product.

Chift marketplace — 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 marketplace — Chift marketplace: 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 (once per customer)

Only if you don’t already have a consumerid for this customer.

curl -X POST https://api.chift.eu/consumers \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your customer's company name",
    "internal_reference": "your-internal-customer-id",
    "email": "contact@your-customer.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 customer. 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.

Store the returned consumerid on your customer record.API reference: Create new consumer ↗

Fetch the connectors (embedded marketplace only)

Skip this step if you use the Chift marketplace.

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 step 5. 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 ↗

Let the user pick a connector

Render the list in your UI. To narrow it, filter on supported_countries, or on api if this part of your product only needs one Unified API.

Check for an existing connection

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

This tells you whether to create or update, and lets you show current state in your UI. A consumer can have only one connection per connector, so creating a duplicate returns 400.Check the status on each entry — only an active connection can serve Unified API calls.API reference: Get connections ↗

Create or update the connection

No connection yet — 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 marketplace 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 marketplace list. Ignored when `integrationid` is set.
`apis`	No	Restricts the marketplace to given Unified APIs. Ignored when `integrationid` is set.

Connection already exists (expired credentials, or activation never finished) — PATCH it instead of deleting and recreating:

curl -X PATCH https://api.chift.eu/consumers/{consumerid}/connections/{connectionid} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"redirect": true}'

Never delete and recreate a connection to fix expired credentials. PATCH issues a fresh activation link while preserving the connection and its history.

Both calls return a single field: url.Add new connection ↗ · Update an existing 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. If it expires, PATCH the connection for a fresh one.

With integrationid set, the link goes straight to that connector; without it, your end-user first picks their software on the Chift marketplace (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

Core docs & concepts

Datalayer

API's guides

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