Freshsales

Freshsales

This connector uses the Freshsales (Freshworks CRM) REST API: contacts, accounts (sales_accounts in the API), deals, notes, tasks, appointments, sales activities, search, marketing lists and the configuration picklists. Every call acts with the permissions of the user whose API key is set: records outside that user's scope are not visible.

Setup

1. In Freshsales click your profile picture, then Profile Settings and the API Settings tab.
2. Copy Your API key into FRESHSALES_API_KEY.
3. On the same tab copy the bundle alias (the account address) into FRESHSALES_BUNDLE_URL, for example https://acme.myfreshworks.com/crm/sales. Accounts created before the Freshworks suite use https://acme.freshsales.io. Leave out /api and any trailing slash.

The key is sent as Authorization: Token token=<key>. Requests go to <bundle URL>/api/....

Start here

• freshsales_list_owners lists the users; their ids are the owner_id of every record.
• freshsales_list_selector reads a picklist (territories, deal pipelines and stages, currencies, deal types and reasons, lead sources, industry and business types, campaigns, contact statuses, lifecycle stages, sales activity types and outcomes). freshsales_list_pipeline_stages gives the stages of one pipeline.
• freshsales_list_fields lists the fields of contacts, accounts, deals or sales activities, including custom fields: their internal names start with cf_ and go in custom_field.

Finding records

• freshsales_search: text search by name or email; include takes the singular entity names contact, sales_account, deal, user (a plural returns nothing).
• freshsales_lookup: exact match on one field, e.g. [email protected]&f=email&entities=contact.
• freshsales_filtered_search: rule-based filter on contacts, accounts or deals, e.g. {"attribute": "contact_email.email", "operator": "is_in", "value": "[email protected]"}.
• Lists always go through a view: call freshsales_list_views for the module, take the id of a view such as "All Contacts" or "My Open Deals", then freshsales_list_contacts, freshsales_list_accounts or freshsales_list_deals.

Contacts: freshsales_get_contact (embed related records with include, e.g. sales_accounts,deals,notes), freshsales_list_contact_activities for the timeline, freshsales_create_contact, freshsales_update_contact, and freshsales_upsert_contact to create or update by email.

Accounts: freshsales_get_account, freshsales_create_account (unique name), freshsales_update_account.

Deals: freshsales_get_deal, freshsales_create_deal (needs name and amount), freshsales_update_deal. Moving a deal means setting deal_stage_id to a stage of its pipeline; won and lost are stages too, and a lost deal can carry deal_reason_id.

Notes, tasks, appointments and activities are attached to a record through targetable_type (Contact, SalesAccount or Deal) and targetable_id.

• Notes: freshsales_create_note, freshsales_update_note.
• Tasks: freshsales_list_tasks (filter open, due_today, due_tomorrow, overdue or completed), freshsales_get_task, freshsales_create_task, freshsales_update_task, freshsales_complete_task.
• Appointments: freshsales_list_appointments (filter open for upcoming, past for past; older portals use upcoming), freshsales_get_appointment, freshsales_create_appointment, freshsales_update_appointment. Attendees are users (FdMultitenant::User) or contacts (Contact).
• Sales activities (logged calls, visits, custom activity types): freshsales_list_sales_activities, freshsales_get_sales_activity, freshsales_create_sales_activity.

Marketing lists: freshsales_list_marketing_lists, freshsales_list_marketing_list_contacts, freshsales_add_contacts_to_list, freshsales_remove_contacts_from_list.

Reading answers

• Timestamps come back in UTC or with an offset (2026-02-13T23:27:49Z). Date inputs accept YYYY-MM-DD or ISO 8601; without a zone UTC is assumed.
• Amounts are in the deal's currency; base_currency_amount is converted to the portal currency.
• Blank fields are returned as null. Related records embedded with include arrive in separate top-level arrays (users, sales_accounts, deals...) next to the record, linked by id.
• Lists return meta.total_pages and meta.total; pass page (from 1) and per_page (default 25, at most 100).

Leads: current Freshsales accounts keep prospects as contacts with a lifecycle stage; there is no separate leads module. Filter contacts by lifecycle stage through a view or freshsales_filtered_search.

Limits and errors: 1000 requests per hour per account (429 when exceeded). 401 means a wrong or missing key, 403 that the user lacks the permission or the feature is not on the plan, 404 a wrong id or a wrong bundle URL. Validation errors return 400 with errors.message.