Freshsales

Freshsales is a CRM by Freshworks. It manages contacts, accounts (companies), deals (opportunities), tasks, notes, appointments, and sales activities.

Data Model

• Contacts — people you interact with. Have email, phone, lead_score, lifecycle_stage, and custom fields. Full CRUD + upsert.
• Accounts (sales_accounts) — companies. Contacts are associated to accounts. Full CRUD + upsert.
• Deals — sales opportunities in pipeline stages. Linked to accounts and contacts. Full CRUD + upsert.
• Tasks — to-do items assigned to users, linked to contacts/accounts/deals. Full CRUD. Set status=1 to mark done.
• Notes — free-text annotations on contacts, accounts, or deals. Create, update, delete.
• Appointments — scheduled meetings with attendees and time zones. Full CRUD. Filters: upcoming, past, overdue.
• Sales Activities — logged activities (calls, emails, custom types) on contacts/accounts/deals. Full CRUD.

Typical workflow

First steps (always do these first)

1. Resolve filters — obtain view IDs for contacts, deals, or accounts only. Required before listing those types. Tasks and appointments skip this step.
2. Resolve selectors — picklist values (owners, deal_stages, territories, lead_sources, currencies).
3. Resolve fields — field definitions and custom field names for any entity type.

Reading data

• Every contact/deal/account listing needs a view_id from the filters step.
• Use include to embed related data (owner, tasks, notes, deals, sales_account, etc.).
• Search — fuzzy text across contacts, accounts, deals.
• Lookup — exact-match on a field (e.g., contact by exact email).
• Contact timeline — activity stream for one contact (calls, emails, notes, tasks).

Writing data

• Create: send the full payload for the entity type; optional fields follow the schema defaults.
• Update: send only fields you are changing.
• Upsert: idempotent create-or-update — pass unique_identifier to match (e.g. {"emails": "jane@co.com"} for contacts, {"name": "Acme"} for accounts/deals).
• Clone: duplicate a contact, deal, or account with all fields copied.
• Delete: permanent — cannot be undone.

Key Patterns

• Views (filters): Listing contacts, deals, or accounts requires a view_id from the filters tool (contacts/deals/accounts only). There is no /tasks/filters API — list tasks with filter=open|due_today|due_tomorrow|overdue|completed.
• Embeds: Many reads accept include to pull related data (owner, tasks, notes, deals, sales_account, etc.) in one round trip.
• Pagination: Collection responses are paginated (25 per page default). Use page=2 for subsequent pages.
• Custom fields: Access via custom_field hash in request/response bodies. Internal names are prefixed with cf_.
• Search vs Lookup: Search does fuzzy text matching. Lookup does exact field matching (e.g., exact email). Use lookup when you know the exact value.
• Selectors: resolve picklist values (owners, deal_stages, territories, lead_sources, etc.).
• Tasks filter: open, due_today, due_tomorrow, overdue, completed.
• Appointments filter: upcoming, past, overdue.
• Contact timeline: the activity feed returns all interactions (calls, emails, notes, tasks) for a contact in chronological order.

Gotchas

• View ID required for lists: You cannot list all contacts/deals/accounts without a view_id. Resolve filters first to obtain view IDs. Do not pass tasks to the filters tool — it 404s upstream.
• Account field naming: Accounts use sales_account (singular) and sales_accounts (plural) in responses and paths—not just account.
• Upsert unique_identifier: Upsert flows need a unique_identifier object to match existing records. For contacts, use emails (plural), NOT email. For accounts/deals, use name or id.
• Lookup requires exact match: Partial strings return no results. 'janesample' won't match 'janesampleton@gmail.com'.
• Task status: 0 = open, 1 = completed. Update a task with status=1 to mark done.
• Notes: Typically loaded together with a contact, account, or deal—not as a standalone global list.
• Appointments attendees: Pass as array of {"email": "...", "name": "..."} objects in create/update.
• Clone creates a new ID: Cloned records get new IDs. All fields are copied except unique identifiers.