A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Freshsales API is how an app or AI agent works with a Freshsales CRM account: creating and updating contacts, accounts, and deals, logging tasks, appointments, and sales activities, and adding notes to records. Access is granted through a per-user API key, which carries exactly that user's permissions and has no separate per-endpoint scopes, so a key reaches whatever its user can in the CRM. The API is unversioned, a single continuously updated reference, and it has no way to receive events, so notifications are set up inside the product instead.
How an app or AI agent connects to Freshsales determines what it can reach. There is one route, the REST API, reached at a per-account bundle host and governed by the API key behind it.
The REST API answers at a per-account bundle host of the form {domain}.myfreshworks.com/crm/sales/api. It is unversioned, returns JSON, and authenticates with a per-user API key in the Authorization header.
Freshsales has no API for receiving events. Outbound notifications are configured inside the CRM through Workflows, which can call an external URL when a record is created or updated.
Each user has a personal API key, sent as 'Authorization: Token token=
The Freshsales API is split into areas an agent can act on, like contacts, accounts, deals, tasks, appointments, and notes. Each area has its own methods, and writes in some areas change real customer records or delete them outright.
Create, read, update, delete, and clone contacts, list them from a saved view, and forget a contact to erase their data.
Create, read, update, delete, and clone sales accounts, the companies a contact belongs to, and list them from a saved view.
Create, read, update, delete, and clone deals, the sales opportunities in a pipeline, and list them from a saved view.
Create, read, update, and upsert leads in the older Freshsales Classic product, where leads are a separate record from contacts.
Create, read, update, complete, and delete tasks, and list them with a filter.
Create, read, update, and delete appointments, and list them with a filter.
Add a note to a record, update a note, and delete a note.
Create, read, update, and delete sales activities, the logged interactions such as calls and meetings.
Create, read, update, and delete products in the price catalogue used to build deals.
List the saved views available for a record type, search across records, and look up a record by a field such as email.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ContactsCreate, read, update, delete, and clone contacts, list them from a saved view, and forget a contact to erase their data.7 | ||||||
| POST | /api/contacts | Create a contact. | write | — | Current | |
The API has no per-endpoint scopes. The API key acts as the user it belongs to, so this call works only if that user can create contacts. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/contacts/{id} | View a contact by id. | read | — | Current | |
Returns only data the key's user is allowed to see. Related records can be embedded with an include parameter. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/contacts/{id} | Update a contact. | write | — | Current | |
The API key acts as its user; the call works only if that user can edit the contact. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/contacts/{id} | Delete a contact, moving it to the recycle bin. | write | — | Current | |
A standard delete is recoverable from the recycle bin; forget is the permanent erase. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/contacts/{id}/forget | Forget a contact, permanently erasing the record and its data. | write | — | Current | |
Forget is irreversible and removes the contact's personal data, unlike a standard delete. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/contacts/{id}/clone | Clone a contact into a new record. | write | — | Current | |
Creates a new contact, so it counts as a write even though it copies an existing one. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/contacts/view/{view_id} | List contacts in a saved view. | read | — | Current | |
There is no list-all endpoint; listing goes through a saved view, whose id comes from the filters endpoint. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Sales accountsCreate, read, update, delete, and clone sales accounts, the companies a contact belongs to, and list them from a saved view.6 | ||||||
| POST | /api/sales_accounts | Create a sales account, the company a contact belongs to. | write | — | Current | |
Companies are stored as sales accounts in Freshsales. The API key acts as its user. Acts onsales account Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/sales_accounts/{id} | View a sales account by id. | read | — | Current | |
Returns only data the key's user can see. Related records can be embedded with an include parameter. Acts onsales account Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/sales_accounts/{id} | Update a sales account. | write | — | Current | |
The API key acts as its user; the call works only if that user can edit the account. Acts onsales account Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/sales_accounts/{id} | Delete a sales account. | write | — | Current | |
A standard delete is recoverable from the recycle bin; the forget endpoint permanently erases the account. Acts onsales account Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/sales_accounts/{id}/clone | Clone a sales account into a new record. | write | — | Current | |
Creates a new account, so it counts as a write. Acts onsales account Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/sales_accounts/view/{view_id} | List sales accounts in a saved view. | read | — | Current | |
Listing goes through a saved view, whose id comes from the accounts filters endpoint. Acts onsales account Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DealsCreate, read, update, delete, and clone deals, the sales opportunities in a pipeline, and list them from a saved view.6 | ||||||
| POST | /api/deals | Create a deal in a pipeline. | write | — | Current | |
A deal is a sales opportunity moving through stages. The API key acts as its user. Acts ondeal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/deals/{id} | View a deal by id. | read | — | Current | |
Returns only data the key's user can see. Related records can be embedded with an include parameter. Acts ondeal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/deals/{id} | Update a deal, including its stage and amount. | write | — | Current | |
Moving a deal through the pipeline is done by changing its stage here. Acts ondeal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/deals/{id} | Delete a deal. | write | — | Current | |
A standard delete is recoverable from the recycle bin; the forget endpoint permanently erases the deal. Acts ondeal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/deals/{id}/clone | Clone a deal into a new record. | write | — | Current | |
Creates a new deal, so it counts as a write. Acts ondeal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/deals/view/{view_id} | List deals in a saved view. | read | — | Current | |
Listing goes through a saved view, whose id comes from the deals filters endpoint. Acts ondeal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Leads (legacy)Create, read, update, and upsert leads in the older Freshsales Classic product, where leads are a separate record from contacts.2 | ||||||
| POST | /api/leads/upsert | Create or update a lead by a unique identifier, in Freshsales Classic. | write | — | Current | |
Leads are a separate record only in the older Freshsales Classic product; the current Freshsales merges them into contacts with lifecycle stages. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/leads/{id} | View a lead by id, in Freshsales Classic. | read | — | Current | |
Available only in Freshsales Classic. The current product has no standalone lead record. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TasksCreate, read, update, complete, and delete tasks, and list them with a filter.4 | ||||||
| POST | /api/tasks | Create a task. | write | — | Current | |
A task can be linked to a contact, account, or deal. The API key acts as its user. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/tasks/{id} | View a task by id. | read | — | Current | |
Tasks are listed with a filter parameter rather than a saved view. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/tasks/{id} | Update a task, including marking it done. | write | — | Current | |
Completing a task sets its status here. The API key acts as its user. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/tasks/{id} | Delete a task. | write | — | Current | |
The API key acts as its user; the call works only if that user can delete the task. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AppointmentsCreate, read, update, and delete appointments, and list them with a filter.4 | ||||||
| POST | /api/appointments | Create an appointment. | write | — | Current | |
An appointment can be linked to a contact, account, or deal. The API key acts as its user. Acts onappointment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/appointments/{id} | View an appointment by id. | read | — | Current | |
Appointments are listed with a filter parameter rather than a saved view. Acts onappointment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/appointments/{id} | Update an appointment. | write | — | Current | |
The API key acts as its user; the call works only if that user can edit the appointment. Acts onappointment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/appointments/{id} | Delete an appointment. | write | — | Current | |
The API key acts as its user; the call works only if that user can delete the appointment. Acts onappointment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
NotesAdd a note to a record, update a note, and delete a note.3 | ||||||
| POST | /api/notes | Add a note to a contact, account, or deal. | write | — | Current | |
A note is attached to a parent record, named when the note is created. The API key acts as its user. Acts onnote Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/notes/{id} | Update a note. | write | — | Current | |
Notes have no standalone read endpoint; they are returned embedded on their parent record. Acts onnote Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/notes/{id} | Delete a note. | write | — | Current | |
The API key acts as its user; the call works only if that user can delete the note. Acts onnote Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Sales activitiesCreate, read, update, and delete sales activities, the logged interactions such as calls and meetings.4 | ||||||
| POST | /api/sales_activities | Create a sales activity, like a logged call or meeting. | write | — | Current | |
A sales activity records an interaction against a contact, account, or deal. The API key acts as its user. Acts onsales activity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/sales_activities/{id} | View a sales activity by id. | read | — | Current | |
Returns only data the key's user can see. Acts onsales activity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/sales_activities/{id} | Update a sales activity. | write | — | Current | |
The API key acts as its user; the call works only if that user can edit the activity. Acts onsales activity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/sales_activities/{id} | Delete a sales activity. | write | — | Current | |
The API key acts as its user; the call works only if that user can delete the activity. Acts onsales activity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProductsCreate, read, update, and delete products in the price catalogue used to build deals.4 | ||||||
| GET | /api/cpq/products | List products in the price catalogue. | read | — | Current | |
Products sit under the cpq path, the configure-price-quote catalogue used to build deals. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/cpq/products | Create a product. | write | — | Current | |
The product catalogue is shared across the account, so a write here affects every deal that uses it. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/cpq/products/{id} | Update a product. | write | — | Current | |
The API key acts as its user; the call works only if that user can edit products. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/cpq/products/{id} | Delete a product. | write | — | Current | |
Removing a product changes the catalogue every deal draws from. A bulk restore endpoint can undo a bulk delete. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Filtered views & lookupsList the saved views available for a record type, search across records, and look up a record by a field such as email.4 | ||||||
| GET | /api/contacts/filters | List the saved views available for contacts. | read | — | Current | |
The view id returned here is what the contacts view endpoint needs to list records. Acts onfiltered view Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/deals/filters | List the saved views available for deals. | read | — | Current | |
The view id returned here is what the deals view endpoint needs to list records. Acts onfiltered view Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/search | Search across records by a query string. | read | — | Current | |
An include parameter narrows the search to chosen record types. Returns only records the key's user can see. Acts onsearch result Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/lookup | Look up a record by a field such as email. | read | — | Current | |
Used to find a record by a unique field, such as a contact by email, before reading or updating it. Acts onlookup result Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Freshsales has no API for receiving events. Notifications are configured inside the CRM through Workflows, which can post to an external URL when a record changes, so an integration is set up in the product rather than through the API.
| Event | What it signals | Triggered by |
|---|
Freshsales limits how much an app or AI agent can call through an hourly request quota that depends on the account's plan, counted across the whole account rather than per user.
Freshsales sets a single quota of requests per hour per account, counted across the whole account rather than per user. The ceiling depends on the plan: 1,000 requests per hour on the Free and Growth plans, 2,000 on Pro, and 5,000 on Enterprise. Going over the quota returns a 429 status with a 'Too many requests' error, and the quota resets each hour. A higher limit can be requested from Freshworks support.
List endpoints return 25 records per page by default. The page is chosen with a page query parameter that starts at 1, and pages are walked by incrementing it. Listing a record type goes through a saved view rather than a flat list-all endpoint, so the view id is fetched from the filters endpoint first.
Requests and responses are JSON over HTTPS. Timestamps are returned in UTC. Bulk write endpoints, such as bulk upsert, accept at most 100 records in a single request. Related records can be pulled into a response with an include parameter rather than as separate calls.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Client or Validation Error | The request is malformed, or a field failed validation. The body holds an errors object describing what went wrong. | Read the message in the errors object, correct the request, and resend. |
| 401 | Authentication Failure | The API key is missing or invalid, or the Authorization header is wrong. | Send a valid key as 'Authorization: Token token= |
| 403 | Access Denied | The key is valid but its user is not allowed to perform this action on this record. | Use a key whose user has the needed access, since the key inherits that user's permissions. |
| 404 | Requested Resource not Found | The record does not exist, or the key's user cannot see it. | Confirm the id and that the key's user has access to the record. |
| 429 | Too many requests | The account's hourly request quota has been exceeded. | Slow down and retry after the hour resets; request a higher limit from Freshworks if needed. |
| 500 | Unexpected Server Error | Something failed on the Freshsales side while handling the request. | Retry after a short wait; if it persists, contact Freshworks support. |
The Freshsales API is unversioned. There is a single, continuously updated API, with no dated version to pin and no version header to send.
The Freshsales API has no dated versions. There is a single, continuously updated REST API, documented in the developer reference, with no version header to send and no migration between versions. Changes ship to the live reference. Leads are a separate record only in the older Freshsales Classic product; the current Freshsales merges them into contacts with lifecycle stages.
There is no version to pin, so an integration tracks the live reference for changes.
Freshsales API reference ↗Bollard AI sits between a team's AI agents and Freshsales. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.