Refiner

Learn how to use Refiner with Composio

Overview

SLUG: REFINER

Description

Refiner is a customer feedback and survey tool designed to help businesses collect and analyze user insights.

Authentication Details

generic_api_key
stringRequired

Connecting to Refiner

Create an auth config

Use the dashboard to create an auth config for the Refiner toolkit. This allows you to connect multiple Refiner accounts to Composio for agents to use.

1

Select App

Navigate to Refiner.

2

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

3

Create and Get auth config ID

Click “Create Refiner Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using API Key

1from composio import Composio
2
3# Replace these with your actual values
4refiner_auth_config_id = "ac_YOUR_REFINER_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000" # UUID from database/app
6
7composio = Composio()
8
9def authenticate_toolkit(user_id: str, auth_config_id: str):
10 # Replace this with a method to retrieve an API key from the user.
11 # Or supply your own.
12 user_api_key = input("[!] Enter API key")
13
14 connection_request = composio.connected_accounts.initiate(
15 user_id=user_id,
16 auth_config_id=auth_config_id,
17 config={"auth_scheme": "API_KEY", "val": user_api_key}
18 )
19
20 # API Key authentication is immediate - no redirect needed
21 print(f"Successfully connected Refiner for user {user_id}")
22 print(f"Connection status: {connection_request.status}")
23
24 return connection_request.id
25
26
27connection_id = authenticate_toolkit(user_id, refiner_auth_config_id)
28
29# You can verify the connection using:
30connected_account = composio.connected_accounts.get(connection_id)
31print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Refiner toolkit’s playground

Python
1from composio import Composio
2from openai import OpenAI
3import json
4
5openai = OpenAI()
6composio = Composio()
7
8# User ID must be a valid UUID format
9user_id = "0000-0000-0000" # Replace with actual user UUID from your database
10
11tools = composio.tools.get(user_id=user_id, toolkits=["REFINER"])
12
13print("[!] Tools:")
14print(json.dumps(tools))
15
16def invoke_llm(task = "What can you do?"):
17 completion = openai.chat.completions.create(
18 model="gpt-4o",
19 messages=[
20 {
21 "role": "user",
22 "content": task, # Your task here!
23 },
24 ],
25 tools=tools,
26 )
27
28 # Handle Result from tool call
29 result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30 print(f"[!] Completion: {completion}")
31 print(f"[!] Tool call result: {result}")
32
33invoke_llm()

Tool List

Tool Name: Delete Contact

Description

Tool to delete a specific contact by its identifier. use after confirming the contact's id, email, or uuid.

Action Parameters

email
string
id
string
uuid
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Account Info

Description

Tool to fetch refiner account subscription and environment usage details. use when you need to audit your current plan and usage.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Contact

Description

Tool to retrieve details of a specific contact by its id. use when you need all stored traits for a known user.

Action Parameters

email
string
id
string
uuid
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Contacts

Description

Tool to retrieve a list of contacts from your refiner account. use when you need to filter or paginate through contacts.

Action Parameters

form_uuid
string
order_by
stringDefaults to first_seen_at
page
integerDefaults to 1
page_cursor
string
page_length
integerDefaults to 50
segment_uuid
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Forms

Description

Tool to retrieve a list of forms (surveys) from your refiner account with optional filtering and pagination. use when you need to list surveys by state, page, or include extra info/config.

Action Parameters

include_config
boolean
include_info
boolean
list
stringDefaults to all
page
integerDefaults to 1
page_length
integerDefaults to 50

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Reporting

Description

Tool to retrieve aggregated reporting data for surveys including metrics and analytics. use when you need survey analytics over a time range filtered by type, question identifiers, tags, forms, or segments.

Action Parameters

date_range_end
date_range_start
form_uuids
array
question_identifiers
array
segment_uuids
array
tag_uuids
array
type
stringRequired

Action Response

average
number
count
integer
csat
integer
data
object
datapoints
integer
date_range_end
Required
date_range_start
Required
error
string
nps
integer
responses
integer
successful
booleanRequired
sum
integer
views
integer

Tool Name: Get Survey Responses

Description

Tool to retrieve all survey responses from your refiner account with optional filtering and pagination. use after confirming survey creation to pull response data.

Action Parameters

date_range_end
date_range_start
form_uuid
string
form_uuids
array
include
stringDefaults to completed
page
integerDefaults to 1
page_cursor
string
page_length
integerDefaults to 50
search
string
segment_uuid
string
segment_uuids
array
with_attributes
boolean

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Segments

Description

Tool to retrieve a list of user segments from your refiner account. use when you need to view or paginate segments.

Action Parameters

page
integerDefaults to 1
page_cursor
string
page_length
integerDefaults to 50

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Track Event

Description

Tool to record a user event by name for a user identified via user id or email. use after confirming the identifier and event name.

Action Parameters

email
string
event
stringRequired
id
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Contact

Description

Tool to update an existing contact's attributes or account. use when you have a contact `id` or `email` and want to modify traits or grouping.

Action Parameters

account
object
attributes
object
email
string
id
string

Action Response

data
objectRequired
error
string
successful
booleanRequired