Each data connector consists of an API call which you can configure behind the scenes. Fin will automatically choose when to use it and deliver a personalized answer to the customer.
You can connect any system which has an API; that might be your unique internal backend tool you have built for your business, or a third party app you're using like Shopify, Salesforce, Stripe, Jira, and more.
The Messenger preview here uses example data. When setting the data connector live, Fin will use your real customer data.
Data connectors require AI Answers to be enabled in the workflow step for Fin to use them. AI Answers cannot be enabled in test workspaces, so data connectors can only be fully tested in production environments. Use test user profiles in production for safe testing.
Connect to external systems
Navigate to Settings > Integrations > data connectors and click New data connector.
Note: You need the “Can access developer hub” permission to configure an data connector or set an data connector live.
If you have one of the supported apps installed, you’ll see a template for this app listed under Create data connector. We currently support templates for Shopify, Stripe, and Statuspage (more on that below).
Create a data connector
From a 3rd party template
data connector templates are available when the following apps are installed in your workspace:
If the app is not already installed, go to the App Store to install. Once the app is installed, data connector templates for each app will appear as an data connector ready to set live.
When you click on a template, you’ll see some information about what the data connector does and you can test it in the Messenger preview. If you’re happy with the data connector behavior, just select Set live for AI Agent.
The Messenger preview here uses example data. When setting the data connector live, Fin will use your real customer data.
If you want to configure the data connector you can click on Customize, which will take you to the data connector builder for advanced configuration.
If you don’t have one of our supported apps installed, the apps will appear here for you to install them on your workspace. After installation, the relevant data connector templates will appear in the section above.
Learn more about available data connector templates and use cases for Fin.
From an AI recommendation
To see AI recommended data connectors, go to Settings > Integrations > data connectors and click New data connector.
You’ll see your unique AI recommended data connectors under "Create data connector from template". These are generated based on your conversation history to help you identify potential data connectors, see what percentage of conversation volume they could resolve, and preview them in the Messenger, before setting anything up.
For AI recommendations to appear, Fin needs to be live on your workspace and you must have sufficient conversation volume.
When you click on an AI recommended data connector, you’ll find information about what the data connector does and you can preview it in the Messenger (using example data). AI recommended data connectors are merely suggestions based on your conversation volume, but they require an API to be connected manually in order to work.
To set the data connector live, click Set up to configure the API details.
Now all you need to do is connect the data connector to your API by adding the HTTPS URL.
To further customize this data connector, see the custom data connector section below. 👇
From a custom data connector
To set up your own custom data connector for Fin, navigate to Settings > Integrations > data connectors and click + New > + Create from scratch.
Phase 1: API
This tab defines how Intercom communicates with your external system.
Identity
Give your connector a short, descriptive name — for example, "Get unpaid account balance." This helps Fin understand when to use it. Add an internal description for your team's reference.
See best practices for writing data connector descriptions.
Note: Emojis aren't supported in data connector names and will throw an error if included.
Data inputs
Data inputs let you specify what information Fin needs to collect before the connector runs — for example, a customer's account number if it's not already stored in Intercom.
Click + Data input and choose a format:
Text
Number
Decimal number
True/False
Give each input a name and description so Fin knows how to collect it. You can also set a fallback value for cases where the API returns a null or missing response.
For each input, choose where the data comes from:
Let Fin collect — Fin gathers it from the conversation automatically
People attribute — pulled from an existing Intercom attribute
Custom value — a fixed value you define
API endpoint
Add the HTTPS URL for your API and select the request method: GET, POST, PUT, DELETE, or PATCH.
Use the Attribute Inserter to pass dynamic values — like a customer's user ID — directly in the URL path or request body.
Authentication and headers
Select an authentication token and add any custom key-value headers your API requires (for example, Content-Type: application/json).
Note: You can attach multiple tokens to a single connector. Each token must use a different header key — all attached tokens are sent with every request.
Once done, click Test connection to validate your setup before moving on.
Phase 2: Data
This tab controls how the API response is shaped before Fin uses it.
Restrict and shape
By default, Fin has access to the full API response. To limit what Fin can read, switch to Manually restrict access and select only the fields you want to expose.
Choose how you'd like to transform the response:
Table view — filter fields, rename them, and set field-level transformations using a visual editor
Python — write Python code to clean, reshape, or reformat the response before it reaches Fin
Object mapping
Map API response fields directly to Intercom objects to automate data syncing with your workspace.
Use Test code and Test connection to validate your logic before proceeding.
Phase 3: Fin
This tab determines how Fin interacts with the connector.
How should Fin use this connector?
Enabled (direct trigger)
Fin triggers the connector automatically based on the customer's question — no workflow required. Best for read-only connectors like "Check order status" and high-volume, repeatable queries.
You can control who this data connector is available to with reusable Fin audiences, or by creating a custom audience specifically for this connector. For example, you might make it available to customers in your "Enterprise plan" audience, or restrict it to a custom audience such as logged-in users with a verified email who ask about their account balance.
Note: You can now use Fin audiences with data connectors. Fin audiences are reusable customer groups you create once and then apply across multiple connectors—making it easier to keep things consistent.
You can choose Everyone, a reusable Fin audience, or a Custom audience for one-off rules.
You can select multiple Fin audiences, but you can’t combine Custom rules with a Fin audience.
Any existing data connector audience rules you configured will become a Custom audience to preserve functionality.
Tip: If you want to test the data connector before enabling it for customers, use the audience rules to enable the data connector just for you or your teammates initially.
Disabled (manual trigger)
The connector won't run automatically. You'll need to add it manually to a Workflow, Task, Procedure, or Macro. Best for sensitive or write-active connectors — like "Delete account" — where you want human or workflow oversight before anything runs.
Use Fin preview to see exactly how Fin will respond using this connector before setting it live.
Phase 4: Security
The final step before going live. This tab handles access control for customer data.
Customer authentication
Toggle this on to enforce your workspace's authentication rules before the connector can access or display sensitive information. Authentication rules are configured at Settings > Workspace > Security > Customer authentication.
Security check
Run a diagnostic to assess the health and security of your API setup. Any risks are surfaced with actionable recommendations — resolve them before setting the connector live.
Once all checks pass, save your connector and set it live.
Important: There are a few potential ways that Fin could accidentally share information from another user when parameter passing. See our recommended settings to best mitigate the risks.
Rolling out data connectors
We recommend using audience rules to roll out data connectors in phases to your customer base. This enables you to validate the performance of the data connector and make tweaks/changes where necessary.
Monitor and manage
To find existing data connectors, navigate to Settings > Integrations > data connectors. Each row shows the connector name, status, general usage, Fin usage (including resolution rate and audience), health (success rate and overall indicator), security, and configuration details. Clicking a connector opens its health dashboard, where you can review usage, performance metrics, and execution logs, or open the configuration editor to make changes.
Viewing in the inbox
Go to the Inbox conversation and select Show conversation events. Events will show if Fin has access to the data connector and if the data connector is successfully triggered.
Note:
If there’s an error with the data connector triggering, select Logs to find out why.
Fin may not always choose to use the data connector despite making an API request if other content is determined to be more relevant.
Fin cannot query custom attributes or event data for answers. To enable Fin to respond with real-time asset data, set up Data Connectors so Fin can access external data sources via API.
Inbox views can be created with the attribute “Fin AI Agent: Action used in reply”. This attribute is set if Fin calls an data connector and uses some or all of the response in an answer.
Versioning
Each data connector has a live version and a draft version. Edits are made to the draft without affecting the running live version.
Each data connector has a live version and a draft version. Edits are made to the draft without affecting the running live version.
When you publish a draft, a new version snapshot is created and becomes the live version. You can add notes at publish time. The previous live version is archived.
Each version records a version number, who created it, change notes (if added), and a timestamp.
The full history of changes is traceable and you can roll back to any previous version.
Public APIs
Two public APIs give you programmatic access to data connector configurations and execution results. Full documentation is available in the Intercom Developer Hub.
Configuration API
The Configuration API is a set of CRUD endpoints for programmatically managing data connectors. Use it to implement new connectors, keep connectors in sync with your internal systems, and automate connector management at scale.
Method | Endpoint | Purpose |
GET | /data_connectors | Returns a paginated list of all data connectors for the workspace, ordered by most recently updated first. |
GET | /data_connectors/:id | Retrieves the full detail of a single data connector by ID, including configuration, data inputs, response fields, and object mappings. |
POST | /data_connectors | Creates a new data connector in draft state. Configure its URL, headers, data inputs, and other settings, then set it live when ready. |
PATCH | /data_connectors/:id | Updates an existing data connector. Only provided fields are changed. Set state to live or draft to change the connector's state. |
DELETE | /data_connectors/:id | Deletes an existing data connector. The connector must be in draft state and must not be in use by any workflows or AI agents. |
Authentication uses OAuth. Read and write access requires the read_write_data_connectors scope; read-only access requires the read_workflow_connector_execution_result scope.
Results API
The Results API gives you programmatic access to execution data for each data connector. Use it to build custom dashboards, feed alerting systems, or perform deeper analysis than the in-product health dashboard provides.
GET /data_connectors/:id/execution_results — retrieves paginated execution logs. Results from the last hour are returned by default. Use
start_tsandend_tsto customise the time range. Request/response bodies are excluded by default — useinclude_bodies=trueto include them.GET /data_connectors/:id/execution_results/:result_id — retrieves a single execution result, always including full request/response bodies for deep debugging.
Filtering options include success status, specific error types, time ranges (Unix timestamps), and cursor-based pagination (up to 30 results per page). Authentication uses OAuth with the read_workflow_connector_execution_result scope.
Troubleshooting
Logs
For troubleshooting purposes, all response data generated from data connectors triggered by Fin is recorded for up to 14 days. You can access these logs under the specific data connector in Logs.
Data Connector Execution Webhook
For real-time signals on success and failure rates, you can use the Data Connector Execution Webhook. This can be useful to receive execution events from Intercom for creating real-time dashboards, alerts and SLA monitoring in your external services.
Notes:
You will need to create an app, set up Webhooks and subscribe to the Data connector execution webhook before you can receive any data connector notifications.
The data connector execution webhook will be skipped if the Data connector is triggered as part of a preview conversation.
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts