How to Integrate Retool with Freshsales

In Freshsales, click your profile avatar in the top-right corner and select Settings. In the Settings sidebar, scroll down to the API Settings section. You'll see a field labeled Your API Key with a visible or masked value — click the copy icon to copy it. Your Freshworks domain is the subdomain visible in your browser URL when logged into Freshsales. If you access Freshsales at https://acme.myfreshworks.com, your domain is 'acme'. The full API base URL will be: https://acme.myfreshworks.com/crm/sales/api/v2. Freshsales API keys are account-level and have the same permissions as the user account they belong to. For a shared Retool tool that needs access to all contacts, deals, and accounts across the entire organization, use the API key from an admin account. Individual user API keys may be restricted by Freshsales territory rules or deal visibility settings. Note: Freshworks recently rebranded from Freshsales Suite to Freshworks CRM. The API endpoints and authentication mechanism remain the same — the API key approach works for both older Freshsales and newer Freshworks CRM accounts.

In Retool, navigate to the Resources tab and click Add Resource. Select REST API from the connector list. Name: Freshsales API Base URL: https://YOUR_DOMAIN.myfreshworks.com/crm/sales/api/v2 Replace YOUR_DOMAIN with your actual Freshworks subdomain. Include /crm/sales/api/v2 in the base URL. Authentication: Select Bearer Token. In the Token field, enter your Freshsales API key. For better security, store the API key in a Retool Configuration Variable first: Settings → Configuration Variables → create FRESHSALES_API_KEY → mark as secret. Then reference it in the Token field as {{ retoolContext.configVars.FRESHSALES_API_KEY }}. Add a default header: Content-Type: application/json. Click Create Resource. Test the connection immediately with a simple query: GET /contacts/filters with no additional parameters. This endpoint returns the list of available contact filter views and should respond with a 200 OK and a JSON body containing filter objects. If you get 401, verify the API key is correct and the Authorization header is being sent as 'Token token=YOUR_KEY' (some Freshsales API versions require this format rather than standard Bearer).

Freshsales uses a filter-based system for listing records. To fetch contacts, use POST /contacts/filter with a JSON body specifying the filter criteria. This is Freshsales' preferred approach for programmatic queries — the GET /contacts endpoint returns all contacts without filtering, which is impractical for large databases. Create a getContacts query: POST /contacts/filter with body: { "filter_rule": [], "sort": "last_contacted", "sort_type": "desc", "page": 1, "per_page": 25 }. An empty filter_rule array returns all contacts. Add filter rules to narrow results — for example, to filter contacts assigned to a specific rep: { "attribute": "owner_id", "operator": "is_in", "value": [{{ select_owner.value }}] }. For leads, use POST /leads/filter with the same structure. Freshsales treats leads (prospects who haven't been qualified) separately from contacts (qualified prospects connected to accounts). Create a searchCRM query for global search: GET /search?q={{ textInput_search.value }}&include=contact,lead,deal,account. This searches across all CRM entity types simultaneously. Bind getContacts to a Table component. Configure columns: display_name, email, phone, mobile_number, owner_name, created_at, and last_contacted. Freshsales returns nested objects — the owner is in a contact.owner object, so you'll need a transformer to flatten these.

1// Transformer for Freshsales contacts
2const contacts = data?.contacts || [];
3return contacts.map(contact => ({
4  id: contact.id,
5  name: contact.display_name || `${contact.first_name || ''} ${contact.last_name || ''}`.trim(),
6  email: contact.email || '',
7  phone: contact.work_number || contact.mobile_number || '',
8  company: contact.company_name || '',
9  owner: contact.owner?.name || 'Unassigned',
10  owner_id: contact.owner?.id || null,
11  lead_score: contact.lead_score || 0,
12  created_at: contact.created_at ? new Date(contact.created_at).toLocaleDateString() : '',
13  last_contacted: contact.last_contacted ? new Date(contact.last_contacted).toLocaleDateString() : 'Never',
14  stage: contact.lifecycle_stage?.name || '',
15  tags: (contact.tags || []).join(', ')
16}));

Create a getDeals query: POST /deals/filter with body: { "filter_rule": [], "sort": "updated_at", "sort_type": "desc", "page": 1, "per_page": 25, "include": "deal_stage,owner,account" }. The include parameter embeds related objects so you get deal stage name and owner name without separate lookups. Freshsales deals contain: id, name, amount, deal_stage (object with id and name), expected_close, owner (object with id and name), account (object with id and name), probability, and updated_at. Create a getDealStages query: GET /deals/stages to fetch all pipeline stages. This returns an array of stage objects with id and name that you can use to populate a Stage dropdown filter and for the pipeline column layout. For the pipeline view, build a transformer that groups deals by stage name: const byStage = {}; deals.forEach(deal => { const stage = deal.deal_stage || 'Unassigned'; byStage[stage] = [...(byStage[stage] || []), deal]; }); Create an updateDeal query: PUT /deals/{{ table_deals.selectedRow.data.id }} with body including the fields to update. Use this to move deals between stages and update expected close dates from Retool without switching to Freshsales.

1// Transformer for deals with pipeline grouping
2const deals = data?.deals || [];
3return deals.map(deal => ({
4  id: deal.id,
5  name: deal.name,
6  amount: deal.amount ? `$${parseFloat(deal.amount).toLocaleString()}` : '$0',
7  amount_raw: parseFloat(deal.amount || 0),
8  stage: deal.deal_stage?.name || 'Unknown',
9  stage_id: deal.deal_stage?.id || null,
10  probability: `${deal.probability || 0}%`,
11  expected_close: deal.expected_close ? new Date(deal.expected_close).toLocaleDateString() : 'None',
12  owner: deal.owner?.name || 'Unassigned',
13  account: deal.account?.name || 'No Account',
14  updated_at: new Date(deal.updated_at).toLocaleDateString(),
15  weighted_value: ((parseFloat(deal.amount || 0) * (deal.probability || 0)) / 100).toFixed(0)
16}));

Build contact creation with a Modal containing form fields: First Name, Last Name, Email (required), Phone, Company Name, and Owner Select (populated from GET /selector/owners which returns all team members available for assignment). Create a createContact query: POST /contacts with body: { "contact": { "first_name": "{{ input_firstName.value }}", "last_name": "{{ input_lastName.value }}", "email": "{{ input_email.value }}", "work_number": "{{ input_phone.value }}", "company_name": "{{ input_company.value }}", "owner_id": {{ select_owner.value }} } }. For activity logging (calling, emailing, meeting), use POST /sales_activities with body: { "sales_activity": { "title": "{{ input_title.value }}", "note": "{{ textArea_note.value }}", "start_date": "{{ datepicker_start.value }}", "end_date": "{{ datepicker_end.value }}", "sales_activity_type_id": {{ select_activityType.value }}, "targetable_id": {{ table_contacts.selectedRow.data.id }}, "targetable_type": "Contact" } }. Fetch activity types for the dropdown: GET /selector/sales_activity_types. This returns types like Call, Email, Meeting, and Demo that map to activity_type_id values. For complex Freshsales setups combining lead scoring, automated sequences, and multi-territory visibility rules with your internal database, RapidDev's team can help architect the Retool solution.

1// createContact request body
2{
3  "contact": {
4    "first_name": "{{ input_firstName.value }}",
5    "last_name": "{{ input_lastName.value }}",
6    "email": "{{ input_email.value }}",
7    "work_number": "{{ input_phone.value }}",
8    "company_name": "{{ input_company.value }}",
9    "owner_id": {{ select_owner.value }},
10    "lead_source_id": {{ select_leadSource.value || 'null' }},
11    "tags": {{ JSON.stringify((input_tags.value || '').split(',').map(t => t.trim()).filter(Boolean)) }}
12  }
13}