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).
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).
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 temporary attributes, 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. You can access this data by using (@ read attributes). This means Fin can reuse that data across all steps and sub-procedures without needing to call the same connector again.
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 use 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
Fin retains the data from a connector for the duration of the procedure. 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
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.
❌ Unnecessarily complex:
First ask the customer for their email, then call @get_order_details with that email
✅ Simple and clear instructions:
Call @get_order_details
Note: If you are noticing any performance or reliability issues with input collection then you can explicitly prompt Fin when to collect this data.
Handling arrays
When a data connector returns a list, Fin exposes only the root array as a temporary 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 > titleGet orders > items > price
Fin can still reason over array contents when you reference the array in an instruction.
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["temporary"] 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.
Note: Generating and referencing data connector temporary attributes is not supported via SDK.
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts