Connection flow through Chift's API

This guide introduces the connection flow in Chift and explains how to connect your end-users (called consumers) to a connector through the API.

A connection represents the link between a consumer (your end-customer) and a software integration or connector (e.g., Odoo, Sage, QuickBooks).

Each consumer typically has one connection. For advanced scenarios with multiple connections per consumer, see Multiple connections on same consumer for same API.

Connections store the credentials and configuration required to access the software and interact with Chift’s Unified API.

For more details on connections, see Connections ↗️.

---

1. Retrieve Active Integrations (connectors)

This step is only required if you want to build your own marketplace inside your product.
It lets you retrieve all active integrations (connectors) from your Chift platform, including their technical integration_id and logos.

• If you build your own marketplace → use this endpoint.
• If you use Chift’s hosted marketplace → you can skip this step.

Endpoint: Get list of integrations
API Reference ↗️

Notes:

• Use the query parameter status=active to get the list of available connectors.
• Logos can be retrieved as base64 for display in your interface:
  Returns a logo/icon (as base64) ↗️

---

2. Create the Consumer

A consumer represents your end-customer within Chift.

Endpoint: Create new consumer
API Reference ↗️

Fields:

• name: Required — Consumer name.
• redirect_url: URL to redirect the user after activation.
  • Can be customized per consumer.
  • Or defined as a static default for your account and connectors (see Configure account ↗️).
  • A detailed explanation of how redirection works is provided in the Annex on Redirect URL.
• internal_reference: Your internal ID/reference for this consumer, used to reconcile with your internal systems.
• email: Used for automated reminders and local agent deployment (if applicable).

---

3. Generate the Activation Link

Once the consumer exists, generate an activation link so they can connect their software.

Endpoint: Add new connection
API Reference ↗️

Fields:

A - Using your marketplace:

• name: Required — Display name of the connection.

• consumerId: Required — From Step 2.

• integrationId: From Step 1.

  B - Using Chift’s marketplace:

• name: Required — Display name of the connection.

• consumerId: Required — From Step 2.

• redirect: Optional (true / false, default = false). See Redirect URL.

The activation link must then be shared with the consumer.
It is secured by a token and valid for 30 minutes.

After this step, your consumer must authorize and sometimes provide additional information to complete the connection activation.
👉 Connection status and updates are covered in the following article Monitoring & Updating Connections.

---

Appendix

🔄 Redirect URL

The redirect behavior in Chift refers to the process of sending the consumer back to a specific URL (typically within your software) once the connection flow has been completed.
It is controlled by two parameters:

• redirect — a boolean that determines whether Chift should redirect the user after completing or failing the connection flow.
• redirect_url — the destination URL where the user is redirected after the connection process.
  This can be defined per consumer or globally in your account settings.
  See Configure account ↗️

1. During Connection Creation

Scenario	Behavior
integration_id provided	Automatically redirects the user to their redirect_url after the connection is successfully activated.
redirect = true and integration_id = null	Redirects the user to the redirect_url after completing the connection flow through the Chift Marketplace.
redirect = false and integration_id provided	Same as the first case — redirects directly to the user’s redirect_url after activation.

---

2. During Connection Update

Scenario	Behavior
redirect = true and success	Redirects the user directly to the defined redirect_url.
redirect = true and error or user cancel	Remains on the current page to allow retry. If the user clicks Cancel or Back to [account name], they are redirected to the redirect_url.
redirect = false and success	Redirects the user to the Chift Marketplace page.
redirect = false and error or user cancel	Remains on the current page to allow retry. If the user clicks Cancel or Back to [account name], they are redirected to the redirect_url.

---

Note

• When defined at both levels, the consumer-level redirect_url takes precedence.

---

🔗 URL Parameters

When redirection occurs, Chift automatically appends query parameters to provide context on the connection result (e.g., connectionStatus, error).
See Configure account ↗️ for details and to ensure it is activated.

---

✅ Summary

• Default behavior: redirect = false
• redirect_url can be defined per consumer or globally in account settings.
• Redirection behavior is consistent for both new and updated connections.