Data connectors allow Fin to interact with external systems via API endpoints. Fin can use data connectors to:

Read information from the data connector (e.g. what plan the user is on).
Perform actions (e.g. Using a POST to cancel a subscription in an external system).

Note: Fin Procedures is currently in managed availability. Access is limited during this period and available only to select customers with a contract. Please contact your account manager to confirm eligibility and learn how to join.

Get started

Adding a data connector to an Instruction step

Inside an Instruction step, type @ to open the tools menu.
Select Call data connector.
Choose the specific connector you want to run (for example, Get orders to retrieve a customer’s purchase history).

Tip: Learn how to set up data connectors to pull live information from your internal systems or third-party APIs directly into your Fin Procedures.

Access the response using automatically generated attributes

Once a connector is added, you can immediately access the response in subsequent steps. This is available to Fin as context in general, but we also parse the response fields into data connectors, in order to enable you to explicitly refer to items in the response body for highest reliability.

Type @ and select Read an attribute.
You will see the data connector's response fields automatically listed at the top of the dropdown (e.g., Get delivery order > status, Get delivery order > order_id).
Select the specific attribute you need to insert it into your instruction or condition.

Context is shared across the Procedure

When you instruct Fin to use a data connector (@ use data connector), the returned data becomes available throughout the procedure.

For greater reliability, you can access this data by using (@ read attributes). Fin retains connector data for the entire duration of a Procedure, including all steps and sub-procedures. You only need to call each connector once per Procedure unless you explicitly need refreshed data.

For example, if you call the (@ use Get_Subscription_info) on step one, Fin will retain the customer’s subscription context for all subsequent steps and sub-procedures.

Best practices

Take advantage of mock data connectors to test and start building out your procedure

You don't need a fully built live API to start building procedures. You can utilize example responses to simulate data.

Example Response: In the Data Connector setup (under the "Test response" tab), select Example response and paste a mock JSON payload. This allows you to build and test the procedure flow immediately.
Dynamic Mocking: For more complex scenarios, you can use tools like Beeceptor to simulate dynamic API responses.

Optimize your API responses to be the smallest possible subset of relevant data Fin needs for the procedure

Too much irrelevant data can impact performance. Generally the smaller and crisper the better.

If a data transformation is required it is strongly recommended that you transform the data either by selecting a limited number of fields or using data connector code blocks. This will transform the API response before Fin sees it in the procedure.

Optimize to use no more than one data connector per step

A step is meant to be a single unit of work. Fin is most reliable when you call only one dat connector in a single step.

Call data connectors once per context

In Procedures, “context” refers to the entire Procedure run. Fin automatically reuses connector data across all steps and sub-procedures. You do not need to call the same API twice.

❌ It's not necessary to call the same connector twice across steps:

Step 1: 

… (@use Get_Subscription_info) … and include @read plan status in your response so the users knows 

Step 2 

… (@use Get_Subscription_info) …  and include @read refund eligibility in your response so the users knows

✅ It's simpler, cleaner, and faster to just call the connector once:

Step 1: 

… (@use Get_Subscription_info) … include @read plan status in your response so the users knows 

Step 2 

… include @read refund eligibility in your response so the users knows

If you need data from multiple systems, split the logic across multiple steps instead of calling multiple connectors in a single step.

There is no need to ask Fin to gather data that is already configured to be required inputs to a data connector

Inputs are preconfigured during data connector step up, so Fin will infer the inputs it needs to collect to call the data connector without you having to explicitly Fin to gather that data.

For example, if the data connector Get Order Details already has the input field email configured:

❌ Unnecessarily complex instruction:

First ask the customer for their email, then call @get_order_details with that email

✅ Clear instructions:

Call @get_order_details

Fin automatically infers and collects required inputs based on the connector configuration unless the input is already provided directly by Intercom.

Note: If you are noticing any performance or reliability issues with input collection then you can explicitly prompt Fin when to collect this data.

Pro Tip: When a Procedure requires accurate, unmodified, or secure data (e.g., email, user ID, or account info), inject those values directly from Intercom into the connector. By configuring the attribute directly in the connector instead of as a Fin-collected input, the data bypasses Fin's collection or reasoning entirely and remains untouched.

Handling arrays

When a data connector returns a list, Fin exposes only the root array as an attribute. Child elements inside the array are not exposed as separate attributes in the attribute picker.

For example, if a connector returns an items array, you will see:

Get orders > items

But you will not see:

Get orders > items > title
Get orders > items > price

Fin can still work with the contents of a list. For example, if you provide the following instruction: "If the customer asks what's in their order, use Get order > items to list the products and their prices."

Fin will read the full contents of the items list and respond with: "Your order includes a Wireless Mouse ($24.99) and a Laptop Stand ($39.99)."

For example: For the below response payload, only the root array element items is exposed as a temporary attribute and not its children.

{
  "order_id": "ORD-1001",
  "status": "processing",
  "created_at": "2025-01-12T14:23:00Z",
  "items": [
    {
      "product_id": "PROD-200",
      "name": "Wireless Mouse",
      "quantity": 1,
      "unit_price": 24.99
    },
    {
      "product_id": "PROD-122",
      "name": "Laptop Stand",
      "quantity": 1,
      "unit_price": 39.99
    }
  ]
}

Note: @Read Get orders > items and tell the customer the top three items in their order.

Using arrays in code conditions

Array attributes are available under the inputs["data_connector"] object, grouped by data connector name. Arrays are zero-indexed, meaning the first item is at index 0. Always check the array length before accessing a specific index.

You can still query values inside an array by using a code condition.
In code conditions, array data is accessed using Python expressions, where you explicitly reference items by index or iterate over the list.

This condition checks that the order contains at least four items, and that the quantity of the fourth item is greater than three.

Always validate the array length before accessing an index to avoid runtime errors during condition evaluation.

Note: The actions available depend on how your data connector is configured.

Data connectors support:

Create: Use POST requests to create new records in an external system.
Read: Use GET requests to retrieve existing data.
Update: Use PUT or PATCH requests to modify existing records.
Delete: Use DELETE requests to remove records.

How to use data connectors in Fin Procedures