Data connectors let Fin access live data from your external systems mid-conversation such as order details, account status, and subscription info, without requiring a human to look things up. This article is your table of contents for the complete setup process. Follow the sections in order if you're starting from scratch, or jump to a specific topic if you need a refresher.
Before you start
Read the conceptual overview first. It explains what data connectors and custom objects are, how they relate to each other, and when you need one vs. the other:
Data connectors and Custom Objects explained — covers the core concepts, the relationship between connectors and custom objects, and the difference between Fin connectors and Workflow connectors.
Step 1: Design APIs and configure your connector
Start by designing your APIs then creating the Data connector and defining how it calls your API.
Designing and using your APIs with Data connectors — covers how to structure your API endpoints to work well with Fin data connectors, before you begin connector configuration.
How to set up Data connectors — covers all four setup phases in detail, including the API (data inputs and API endpoints), data (shaping the API response), Fin (how Fin triggers the connector), and security (access control and going live).
Use Data connector templates — get started quickly from a data connector template using third-party apps installed on your workspace.
Step 2: Authentication and security
Before going live, configure how your connector authenticates with your external API and whether customers must be verified before data is exposed to them.
Setting up Data connectors authentication — covers authentication token types (text, OAuth, JWT), the Credentials page, and how to enable customer authentication on individual connectors.
Secure Data connectors with One-Time Passcode — enforce OTP verification before Fin exposes customer data.
Best practices when using Data connectors with Fin — covers the built-in security checks on the Security tab, common risks, and recommendations before going live.
Important: If you don't enforce customer authentication, malicious actors could impersonate your users and access their data. At a minimum, review the Security tab's built-in checks before setting any connector live.
Step 3: Response schemas, objects, and arrays
Your API's response shape determines how Fin reads and uses the returned data. This section covers how to handle different response structures.
JSON objects and arrays supported for Data connectors response mapping — covers flat objects, nested objects, arrays, and XML responses (automatically converted to JSON). Read this if your API returns complex or nested data.
Step 4: Custom objects and properties
Custom objects let you store structured, multi-property data in Intercom such as orders, subscriptions, or appointments, that isn't captured by standard contact or conversation attributes. You typically populate them by mapping a connector's response data to the object.
Setting up a Custom Object — covers creating object types, defining properties, populating the object via a data connector, and setting up references to People and Conversation objects.
Step 5: Object mappings
Object mapping tells the connector where in Intercom to store the API response data. You can map to standard objects (contact and conversation attributes) or custom objects.
Setting up references with Custom Objects — covers how to map API response fields directly to Intercom contact or company attributes, automatically syncing data from your external system to your Intercom workspace.
How to set up Data connectors for Workflows and Inbox — contains additional detail on mapping to custom objects, including the external_id requirement.
Step 6: Testing
Each connector has a built-in test tool that lets you validate the API call and response shape before going live. Use the Test connection button on the connector's Data tab to confirm the full request and response. For end-to-end testing of how Fin uses the connector in a conversation, use audience rules to target the connector at your own user email.
How to roll out Data connectors safely — explains how to monitor and manage your data connectors, and view data connector activity in the inbox.
Step 7: Using data connectors in Fin procedures
Fin can call a Data connector directly to answer a customer question, but connectors are also a core building block for more complex, multi-step procedures — for example, looking up an order, then offering to update it, then confirming the change.
How to use Data connectors in Fin Procedures — teaches you how Fin can read and act on external API data and perform automated actions during customer conversations.
Troubleshooting and FAQs
If your connector isn't behaving as expected, start with the troubleshooting article. For security and privacy questions, the FAQs article covers the most common concerns.
Understanding Data connector errors — teaches you how to read and interpret data connector logs, identify the cause of connector errors, and take the right steps to resolve them.
Troubleshooting Fin Procedures and Data connectors — covers the most common failure patterns, including connectors that pass testing but fail in a live procedure, input errors, and response parsing issues.
Data connectors FAQs — covers data privacy, security, impersonation risks, and other frequently asked questions.
Quick reference: all Data connector articles
Use this table to jump directly to any article in the Data connectors documentation.
Article | What it covers |
Core concepts and when to use each | |
Structuring your API endpoints to work well with Fin | |
Primary connector setup guide, covers all four setup phases in detail | |
Quick-start templates using third-party apps | |
Auth tokens, credentials, customer authentication | |
Security checks, best practices before going live | |
Response schemas, nested objects, arrays, XML | |
Custom object types, properties, population via connector | |
API response mapping to Intercom attributes | |
Fin usage and health indicators | |
Data connector use cases and examples | |
Allowing Fin to read and act on external API data | |
Workflow/Inbox use case, object mapping detail | |
Data connector logs and errors | |
Common failures and fixes | |
Privacy, security, and common questions |
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts