Skip to main content

Create data connectors for Fin

How to set up Fin with personalized answers that require data from external systems.

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.

Note:

Create a data connector

To set up a custom data connector for Fin, navigate to Settings > Integrations > Data connectors and click + New.

Phase 1: API

The configuration editor is organized into four tabs: API, Data, Fin, and Security. Work through each tab to build your connector before setting it live.

Identity

First, provide a short name to describe what this data connector does such as “Get unpaid account balance”. Next, provide a detailed description explaining when Fin should use it.

Include examples of the data this data connector provides and customer queries it helps answer.

For example:

Use this data connector to retrieve recent transactions for a customer. This data connector provides key information such as… Example customer queries include… "Can you check if I have any outstanding balance on my account?" "Is there any payment due on my account right now?" "Do I owe anything on my account?" "Can you tell me if I have any unpaid bills or charges?" "Is there any balance I need to clear on my account?" "Can you confirm if my account is fully paid up?"

API connection

If you want, you can specify if Fin should collect any data before using this data connector. This can be helpful in cases where you need to make sure data exists before the data connector is run. For example, you might want to ask the customer for their account number if this is not stored on their user profile in Intercom.

To collect data inputs, click on + Add data input and pick the format of the data that should be collected (text, number, decimal number, or true/false) and give it a name and description so Fin knows how to collect it.

Note:

  • When available, Fin will gather the information from the conversation context.

  • You can connect data connectors to APIs that return XML. Intercom will automatically convert XML responses to JSON, so you don’t need to do any manual conversion or use a third-party tool. This means you can connect to a wider range of external systems, even if they don’t support JSON natively.

Next, you must specify the HTTPS URL of your API and select the request method: GET, POST, PUT, DELETE, or PATCH.

You may want to use attributes available within your workspace, such as a customer’s user ID or email, to perform a lookup. You also need to make sure to specify the correct authentication token and to specify correct headers (for example: Accept: application/json or Content-Type: application/json).

Once done, test your connection to validate the setup before moving to the Data tab.

Test response

You’ll need to test this action to make sure it’s fetching the right data from the API you’re connecting to. You can test your data connector using two methods:

  1. Live response: Test with live response data from your API request to ensure correct configuration. Live response will make an actual API call to your endpoint so be careful in case this request affects any real-world data.

  2. Example response: Provide example JSON data which is useful if your API is not yet fully developed or you need to simulate/mock a particular response.

If everything looks good, continue to the Data tab to configure how the response is shaped.

Phase 2: Data

This tab controls how the API response is shaped before Fin uses it.

Restrict and shape

By default, Fin can access the full response data to generate replies. Select Manually restrict access if you wish to limit the data Fin can read. Then check the data fields you want to give Fin access to.

You can also edit the individual data items by clicking on the edit icon to give your response data a customer facing name as well as specify any transformations to the data.

For example, if the API response returns a balance of 0, instead of Fin stating the unpaid balance is 0, it can reply stating that there is currently no unpaid balance remaining.

Use code to filter or transform the response

With code blocks for data connectors, we're empowering you to directly transform and manipulate API responses using Python—right inside your connector setup.

Unstructured or overly large payloads from APIs can cause AI-based responses (like Fin or other AI agents) to hallucinate, misinterpret, or simply fail to deliver clear answers. Now, you can programmatically preprocess, filter, or massage API responses before they're sent to Fin or mapped to Intercom objects without needing backend changes or third-party integrations.

How it works

  • return statement: The main result your code block produces must be returned with a return statement. Only what’s returned will be sent forward to Fin or the rest of your connector.

  • print() statements: Use these only for debug or progress logging. These outputs are captured separately and are NOT sent as the API result.

  • Standard modules only: You’re limited to a set of standard Python modules (math, decimal, re, datetime, datetime.timezone, json, random, time). We will add more modules over time as they are needed.

Note:

  • Non-JSON Test Responses: Code blocks require that your API test response is a valid JSON object or array. Non-JSON payloads are not supported (and will cause failures).

  • Non-successful API requests: Code blocks can only transform successful API responses (status code 200). Error responses with status codes like 400, 404, or 500 are not supported for code block transformation.

How to configure code blocks for data connectors

Go to Settings > Integrations > data connectors and select the data connector you'd like to use code blocks with. Then click on Data transformation and select the "Use code to filter or transform the response" option.

Access input data (API Response) in your code block

To access the data returned by your API (the test response), use the inputs['data'] variable inside your code block. Typically, this gives you the entire response from your API, ready to transform however you like.

For example, at the start of your code block, you typically write:

api_response = inputs['data']

This assigns the API response (a Python dictionary or list or string, depending on your API) to the variable api_response for further processing.

Get automatic suggestions for code blocks

When you navigate to the Data transformation tab, your data connector response is automatically analyzed to identify suggestions that will improve Fin's performance.

This detects common issues like Unix timestamps and oversized payloads—unstructured or overly large data that can cause AI-based responses to hallucinate, misinterpret, or fail to deliver clear answers.

When a suggestion is found, you'll see a banner with a View suggestion button showing recommended Python code that will make your data cleaner and more reliable for Fin. Select Test code to see the result it returns.

If you're happy with the return statement, select Accept suggestion to significantly improve the quality and accuracy of Fin's responses from your connector data.

Tip: Check out these tips and practical examples for data transformation.

Object mapping

When creating data connectors for Fin, there is no need to map response data to Intercom attributes or objects. Instead, Fin directly interprets the JSON response and can then use it to resolve questions. The response is generated based on the ‘Test response’ section. Each line item corresponds to a data point in the JSON response.

Once you've configured the Data tab, continue to Phase 3: Fin to define how Fin uses this connector, and Phase 4: Security to set up authentication and run security checks before going live.

Phase 3: Fin

This tab determines how Fin interacts with the connector.

How should Fin use this connector?

Choose between two modes:

  • Enabled (direct trigger) — Fin triggers the connector automatically based on the customer's question. Best for read-only connectors like "Check order status" and high-volume, repeatable queries.

  • 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 where you want human or workflow oversight before anything runs.

Audience

Control who this connector is available for using reusable Fin audiences, or create a custom audience for one-off rules. For example, make it available to customers in your 'Enterprise plan' audience, or restrict it to logged-in users with a verified email.

Tip: 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 audience rules you've configured will become a Custom audience to preserve functionality.

Fin preview

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 security of your API setup. Any risks are surfaced with actionable recommendations — resolve them before setting the connector 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.

Once all checks pass, save your connector and set it live.

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 connectors and make tweaks/changes where necessary.

If you are experiencing issues where your data connector isn't triggering for a user, make sure that you have removed any audience rules specific to your company that you may have added in the testing phase

Troubleshooting

For troubleshooting purposes, all response data generated by data connectors triggered by Fin is recorded for up to 14 days. You can access these logs under the Data Connector > Logs tab. You can view response data based on what kind of data Fin has access to.

  • Entire response – Full, unmodified response

  • Redacted & Formatted response – After transformation

  • No response data

FAQs

Can I use Data connectors to send attributes when handing off a Fin conversation to a third-party platform (not Zendesk/Salesforce)?

If you're trying to send a POST request (e.g., with a structure like below), use your Fin workflow handoff options instead:

{
"body": "the conversation with Fin",
"from": "users_email_address",
"to": "our_ticketing_email_address"
}

Workflow handoff options include hand-off with JavaScript and hand-off to URL, with the ability to include conversation context through AI-generated summaries.

1. Hand-off with JavaScript

This allows you to define a handoff_with_javascript function in your Messenger app that can:

  • Collect the conversation summary (via “AI Add Summary Note”)

  • Access the user’s email (using attributes)

  • Send a fetch() or XMLHttpRequest to your external endpoint with the structure you want

Learn more here 👉 Hand-off with JavaScript

2. Hand-off to URL

This option only redirects the user to a specific page, it does not send a POST or carry conversation data. So it wouldn’t suit your use case if you’re trying to POST JSON.

Recommended Setup

Use the JavaScript hand-off, and include logic like:

handoff_with_javascript = function (params) {
const userEmail = params.user.email;
const summary = params.conversation_summary;

fetch('https://your-endpoint.com/api', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
body: summary,
from: userEmail,
to: 'your_support@company.com'
})
});
}

💡Tip

Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts

Related Articles
Designing and using your APIs with Data Connectors
Create authentication and API tokens
Fin Tasks and Data connectors explained
How to use data connectors in Fin Procedures
Code block tool in procedures
Did this answer your question?