Overview
Freshworks CRM is an intuitive CRM that helps sales reps take the guesswork out of sales. With the built-in phone and email, tasks, appointments and notes, sales reps needn’t have to toggle between tabs to follow up on prospects. You can manage your deals better with the pipeline view and drive more deals to closure. Also, with custom reports, tracking sales performance a cinch.
Freshwork CRM's APIs belong to the Representational State Transfer (REST) category. They allow you to perform 'RESTful' operations such as reading, modifying, adding or deleting data from your helpdesk.
Which are the API commands used in Freshworks CRM?
Command | Purpose |
---|---|
POST | Create an object |
GET | Fetch one or more objects |
PUT | Update an object |
DELETE | Remove an object |
Authentication
To use the API’s listed above, you need to authenticate your id as you would when you log in to your Freshworks CRM account using your API key.
-
API key
Each user in Freshworks CRM is provided with a unique API key. To find your API key
- Click your profile picture and select Profile Settings.
- Click the API Settings tab.
- You can find your API key in the field Your API key.
Learn more about finding your API key.
For example, if your API key is sfg999666t673t7t82, the curl command to use is:
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET https://domain.myfreshworks.com/crm/sales/api/contacts/1
What are the resources available via the API?
Any information in your Freshwork CRM’s account can be identified by its own unique identifier or "URI". If you want data from your account, be it a deal or the owner of an account, you’d need its respective identifier to fetch the data via the API’s. All URIs follow the following format:
https://your_crm_domain_name/api/resource_name
For example, if you are Rebecca Moris and you’d like to fetch the contact with id 144 from your account "widgetz.myfreshworks.com/crm/sales", the syntax would be
https://widgetz.myfreshworks.com/crm/sales/api/contacts/144
Note:
We’ve shortened the API resource URLs throughout this document by omitting the domain name, meaning, /api/contacts is actually a shorter version of https://domain.myfreshworks.com/crm/sales/api/contacts
Will everyone have the same access rights?
No. Using the API’s, users would only be able to view data that they have access to. Learn more about managing user roles and scopes.
Schema
Blank Fields:
Blank fields are made null instead of being omitted.
Timestamps:
All timestamps are returned in the UTC format, YYYY-MM-DDTHH:MM:SSZ. For example, 2016-02-13T23:27:49Z
Date Fields:
Input for date fields is expected to be in one of the following formats:
YYYY-MM-DD
YYYY-MM-DDTHH:MM
YYYY-MM-DDTHH:MMZ
YYYY-MM-DDTHH:MM:SS
YYYY-MM-DDTHH:MM:SSZ
YYYY-MM-DDTHH:MM:SS±hh:mm
YYYY-MM-DDTHH:MM:SS±hh
YYYY-MM-DDTHH:MM:SS±hhmm
If the time zone information is not present, it will be assumed to be in UTC.
A few valid date fields - 2016-02-15T21:16:25Z , 2012-12-24T12:56:15+05:30, 2010-03-23T12:00
Embedding
You can request for additional resources using the "include" keyword. For example you can embed the contact's owner within the contact list view API by,
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/apicontacts/1?include=owner" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 | { users: [{ id: 1, display_name: "Sample Admin", email: "admin@yourcompany.com" }], contact: { id: 1, job_title: "Sales Manager", email: "janesampleton@gmail.com", work_number: "(368) 493-2360", mobile_number: "1-926-652-9503", address: "604-5854 Beckford St.", city: "Glendale", state: "Arizona", zipcode: "100652", country: "USA", time_zone: null, display_name: "Jane Sampleton (sample)", avatar: "https://lh3.googleusercontent.com/-BomfmRA2WqA/Vi4cXSJzXPI/AAAAAAAAABg/LO4MyF96ZQ4/w140-h140-p/Image1.png", keyword: "B2B Success", medium: "Blog", last_seen: "2016-02-10T02:36:06-08:00", last_contacted: "2016-02-08T02:36:06-08:00", lead_score: 96, stage_updated_time: "2016-02-10T02:36:06-08:00", first_name: "Jane", last_name: "Sampleton (sample)", company: { id: 1, name: "Widgetz.io (sample)", address: "160-6802 Aliquet Rd.", city: "New Haven", state: "Connecticut", zipcode: "68089", country: "United States", number_of_employees: null, annual_revenue: null, website: "widgetz.io", phone: "503-615-3947", industry_type_id: 1, business_type_id: 1 }, deal: null, links: { conversations: "/contacts/1/conversations?include=email_conversation_recipients,targetable,phone_number,phone_caller,note,user&per_page=3", activities: "/contacts/1/activities" }, custom_field: { cf_primary: false }, updated_at: "2016-02-10T02:36:06-08:00", facebook: null, twitter: "https://twitter.com/janesampleton", linkedin: "http://linkedin.com/pub/jane-sampleton/109/39/b0", owner_id: 1 } } |
Errors
I have encountered an error. How do I fix this?
API requests that result in errors will return an appropriate HTTP status code to help you identify the type of error and fix it. You can use the table below to understand what each code means.
HTTP Status Code | Text | Description |
---|---|---|
400* | Client or Validation Error | Indicates that the request is not in the correct format. For example, the Create a contact API requires a valid email address to be sent as part of the request. If you are missing @ as part of the email address in the request, you would get this error code. |
401 | Authentication Failure | Indicates that the Authorization header is either missing or incorrect. You can learn more about the Authorization header here. |
403 | Access Denied | This indicates that the user whose credentials were used in making this request was not authorized to perform this API call. It could be that this API call requires admin level credentials or perhaps the Freshworks CRM portal doesn't have corresponding feature enabled. |
404 | Requested Resource not Found | This status code is returned when the request contains invalid ID/Freshworks CRM domain in the URL or an invalid URL itself. For example, an API call to retrieve a contact with an invalid ID will return a HTTP 404 status code to let you know that no such contact exists. |
429 | Too many requests | This status code appears when the user has exceeded the API limit set per hour per account. In Freshworks CRM, this limit is 1000 API requests per hour per account. |
500 | Unexpected Server Error | Phew!! You can't do anything more here. This indicates an error at Freshworks CRM's side. Please email us |
*Previously, we have been returning status code: 500 for validation errors and on August 17th, 2018, we have made changes to our status codes to reflect status code: 400 for validation errors. Please note that this new status code is returned only for accounts signed up on or after August 17th, 2018. Users who have signed up before August 17, 2018, and have been using our API would still continue to receive status code: 500 for validation errors. We recommend such users who perform actions based on validation errors (if any) to make necessary changes to their API request as we would be deprecating the status code: 500 for validation errors on December 31st, 2018. |
Error Response
In addition to the HTTP status code, most errors would also return a response body that contains more information on the error. Here’s a sample error response,
Sample Error
1 2 3 4 5 6 7 | { "errors": { "code":"Status code of the error", "message":"Error Description" } } |
Field | Description |
---|---|
code | HTTP error status code |
message | Description about the error. |
Pagination
API responses that return a list of objects, such as View List of contacts or View List of deals are paginated. To scroll through the pages, add the parameter page to the query string. The page number starts with 1.
By default, the number of objects returned per page is 25. For example, if you’d like to retrieve the contacts from 26 to 50 use,
https://domain.myfreshworks.com/crm/sales/api/contacts/view/[:view_id]?page=2
Configuration
API | Description |
---|---|
api/selector/owners | Fetch all existing users' details in the Freshworks CRM portal. Will give id, name of the users |
api/selector/territories | Fetch all existing territories' details in the Freshworks CRM portal. Will give id, name of the territories |
api/selector/deal_stages | Fetch all existing deal stages' details in the Freshworks CRM portal. Will give id, name of the deal stages |
api/selector/currencies | Fetch all existing currency details in the Freshworks CRM portal. Will give id, currency code and other details of currencies |
api/selector/deal_reasons | Fetch all existing deal reasons' details in the Freshworks CRM portal. Will give id, name of the deal reasons |
api/selector/deal_types | Fetch all existing deal types' details in the Freshworks CRM portal. Will give id, name of the deal types |
api/selector/industry_types | Fetch all existing industry types' details in the Freshworks CRM portal. Will give id, name of the industry types |
api/selector/business_types | Fetch all existing business types' details in the Freshworks CRM portal. Will give id, name of the business types |
api/selector/campaigns | Fetch all existing campaigns details' in the Freshworks CRM portal. Will give id, name of the campaigns |
api/selector/deal_payment_statuses | Fetch all existing deal payment statuses' details in the Freshworks CRM portal. Will give id, name of the deal payment statuses |
api/selector/deal_products | Fetch all existing deal products' details in the Freshworks CRM portal. Will give id, name of the deal products |
api/selector/deal_pipelines | Fetch all existing deal pipelines' details in the Freshworks CRM portal. Will give id, name of the deal pipelines |
api/selector/deal_stages | Fetch all existing deal stages' details of default pipeline in the Freshworks CRM portal. Will give id, name, deal_pipeline_id of the deal stages. |
api/selector/deal_pipelines/[id]/deal_stages | Fetch all existing deal_stages' details only of the pipeline specified. Will give id, name, deal_pipeline_id of the deal stages. |
api/selector/contact_statuses | Fetch all existing contact statuses' details in the Freshworks CRM portal. Will give id, name of the contact statuses. |
api/selector/sales_activity_types | Fetch all existing sales activity types' details in the Freshworks CRM portal. Will give id, name of the sales activity types. |
api/selector/sales_activity_outcomes | Fetch all existing sales activity outcomes' details in the Freshworks CRM portal. Will give id, name of the sales activity outcomes. |
api/selector/sales_activity_entity_types | Fetch all existing sales activity entity types' details in the Freshworks CRM portal. Will give id, name of the sales activity entity types. |
api/selector/sales_activity_types/[id]/sales_activity_outcomes | Fetch all existing sales activity outcomes' details only of the sales activity type specified. Will give id, name, sales_activity_type_id of the sales activity outcomes. |
api/selector/lifecycle_stages | Fetch all existing lifecycle_stages' details in the Freshworks CRM portal. Will give id, name and contact statuses of the lifecycle stage. |
Contacts
Contacts represent the companies (Accounts) that you do business with.
ATTRIBUTE | TYPE | DESCRIPTION |
---|---|---|
id∑ | number | Unique ID of the contact |
first_name | string | First name of the contact |
last_name | string | Last name of the contact |
subscription_status | Array of hashes | Status of subscription that the contact is in |
job_title | string | Designation of the contact in the account he belongs to |
emailπ†† | string | Primary email address of the contact |
emails∑ | string | Email addresses of the contact |
work_number | string | Work phone number of the contact |
external_id∑π | string | External ID of the contact |
mobile_number∑π | string | Mobile phone number of the contact |
address | string | Address of the contact |
city | string | City that the contact belongs to |
state | string | State that the contact belongs to |
zipcode | string | Zipcode of the region that the contact belongs to |
country | string | Country that the contact belongs to |
sales_accountsμ | Array of hashes | Accounts which contact belongs to |
territory_idΩ | number | ID of the territory that the contact belongs to |
lead_source_idΩ | number | ID of the source where contact came from |
owner_idΩ | number | ID of the user to whom the contact has been assigned |
subscription_status | Array of hashes | Status of subscription that the contact is in |
subscription_types | Array of hashes | Type of subscription that the contact is in |
medium | string | The medium that led your contact to your website/ web app |
campaign_idΩ | number | The campaign that led your contact to your web app. |
keyword | string | The keywords that the contact used to reach your website/web app |
time_zone | string | Timezone that the contact belongs to |
string | Facebook username of the contact | |
twitter∑ | string | Twitter username of the contact |
string | LinkedIn account of the contact | |
created_at | datetime | Contact creation timestamp |
updated_at | datetime | Contact updated timestamp |
contact_status_idΩ | number | ID of the contact status that the contact belongs to |
sales_account_id† | number | ID of the primary account that the contact belongs to Usage of this key is deprecated. Use sales_accounts key to associate accounts to a contact. |
lifecycle_stage_id | number | ID of the lifecycle stage that the contact belongs to |
* Mandatory fields for creating contact. π Either Email/Mobile/Twitter ID is required to create a contact. ∑ This field is unique. μ This field is optional. You can associate multiple accounts to a contact (Refer "Create a contact by associating to multiple accounts " shown below). † NOTE: Usage of this key is deprecated. Use sales_accounts key to associate accounts to a contact. This field is optional. Either you can send ID of an existing account or add a new account on the fly (Refer "Create a contact by associating to a new account" shown below). †† NOTE: Usage of this key is deprecated. Use emails key to associate emails to a contact. Ω To know all available options for this field, refer Configuration |
Create a Contact
This API allows you to create a contact.
/api/contacts
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"contact":{"first_name":"James", "last_name":"Sampleton (sample)", "mobile_number":"1-926-555-9503"}}' -X POST "https://domain.myfreshworks.com/crm/sales/api/contacts" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | { "contact": { "id": 1, "first_name": "James", "last_name": "Sampleton (sample)", "display_name": "James Sampleton (sample)", "avatar": null, "job_title": null, "city": null, "state": null, "zipcode": null, "country": null, "email": null, "time_zone": null, "work_number": null, "mobile_number": "1-926-555-9503", "address": null, "last_seen": null, "lead_score": 0, "last_contacted": null, "open_deals_amount": "0.0", "links": { "conversations": "/contacts/1/conversations?include=email_conversation_recipients%2Ctargetable%2Cphone_number%2Cphone_caller%2Cnote%2Cuser\u0026page=1\u0026per_page=3", "activities": "/contacts/1/activities" }, "custom_field": { }, "updated_at": "2016-06-01T02:54:41-07:00", "keyword": null, "medium": null, "facebook": null, "twitter": null, "linkedin": null } } |
Additional Examples
1. Create a contact with custom fields
If you’d like to create a contact along with custom fields, use this API.
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"contact":{"first_name":"James", "last_name":"Sampleton (sample)", "mobile_number":"1-926-555-9503", "custom_field": {"cf_is_active": true} }}' -X POST "https://domain.myfreshworks.com/crm/sales/api/contacts" |
2. Create a contact by associating to multiple accounts.
To create an account, refer Create an Account
If you’d like to associate the contact with multiple accounts, use below API.
** For sales_accounts, id is the sales account id and is_primary is the flag for marking the specific sales account primary.
It is mandatory to have one (and only one) primary account if any sales accounts are associated to the contact.
You can associate upto 10 accounts to a contact.
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"contact":{"first_name":"James", "last_name":"Sampleton (sample)", "mobile_number":"1-926-555-9503", "custom_field": {"cf_is_active": true}, "sales_accounts":[{"id" : 1, "is_primary" : true}, {"id" : 2, "is_primary": false}] }}' -X POST "https://domain.myfreshworks.com/crm/sales/api/contacts" |
3. Create a contact by associating to a new primary account
If you’d like to associate the contact with a new primary account, use this API.
Note : Usage of this key is deprecated. Use sales_accounts to associate accounts to a contact. Sales accounts should be created before associating them to contacts.
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"contact":{"first_name":"James", "last_name":"Sampleton (sample)", "mobile_number":"1-926-555-9503", "custom_field": {"cf_is_active": true}, "sales_account":{"name":"Sample Account"} }}' -X POST "https://domain.myfreshworks.com/crm/sales/api/contacts" |
View a Contact
This API allows you to view the details of a contact.
/api/contacts/[id]
Use 'include' to embed additional details in the response.
Embed | Handle |
---|---|
owner | api/contacts/[id]?include=owner Will return the owner id, name and email |
creater | api/contacts/[id]?include=creater Will return the creater id, name and email |
updater | api/contacts/[id]?include=updater Will return the updater id, name and email |
source | api/contacts/[id]?include=source Will return the id and name of the source |
campaign | api/contacts/[id]?include=campaign Will return the id and name of the campaign |
tasks | api/contacts/[id]?include=tasks Will return the task id, title, due_date, status and owner_id |
appointments | api/contacts/[id]?include=appointments Will return the appointment id, title, time_zone, from_date, end_date and creater_id |
notes | api/contacts/[id]?include=notes Will return the note id, description and creater_id |
deals | api/contacts/[id]?include=deals Will return the connected deal details |
sales_accounts | api/contacts/[id]?include=sales_accounts
Will return the connected accounts detials - id, name, avatar and website details. |
territory | "api/contacts/[id]?include=territory Will return the id and name of the territory" |
sales_account | api/contacts/[id]?include=sales_account
Will return the connected primary account id, name, avatar and website details. Usage of this key is deprecated. Please use sales_accounts key to fetch all accounts associated to a contact. |
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/contacts/1?include=sales_accounts" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 | { "contact": { "id": 1, "first_name": "James", "last_name": "Sampleton (sample)", "display_name": "James Sampleton (sample)", "avatar": null, "job_title": null, "city": null, "state": null, "zipcode": null, "country": null, "email": null, "time_zone": null, "work_number": null, "mobile_number": "1-926-555-9503", "address": null, "last_seen": null, "lead_score": -96, "last_contacted": null, "open_deals_amount": "0.0", "links": { "conversations": "/contacts/1/conversations?include=email_conversation_recipients%2Ctargetable%2Cphone_number%2Cphone_caller%2Cnote%2Cuser\u0026page=1\u0026per_page=3", "activities": "/contacts/1/activities" }, "custom_field": { "cf_is_active": true }, "updated_at": "2016-06-01T03:14:52-07:00", "keyword": null, "medium": null, "facebook": null, "twitter": null, "linkedin": null, "sales_accounts": [{ "avatar": null, "id": 1, "is_primary": true, "name": "Sample Account", "partial": true, "website": null }] } } |
List All Contacts
If you’d like to fetch a list of contacts, use this API.
/api/contacts/view/[view_id]
You can filter your contacts and also sort them to get a list of specific contacts
1. Filtering Contacts
If you’d like to view specific contacts, use views. To fetch contacts from a view, first fetch the view id using the filters API and then use view API to fetch.
/api/contacts/filters
Filters API
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/contacts/filters" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 | { "filters": [{ "id": 1, "name": "My Contacts", "model_class_name": "Contact", "user_id": -1, "is_default": true, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }, { "id": 2, "name": "My Territory Contacts", "model_class_name": "Contact", "user_id": -1, "is_default": true, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }, { "id": 3, "name": "New Contacts", "model_class_name": "Contact", "user_id": -1, "is_default": true, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }, { "id": 4, "name": "All Contacts", "model_class_name": "Contact", "user_id": -1, "is_default": true, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }, { "id": 5, "name": "Recently Modified", "model_class_name": "Contact", "user_id": -1, "is_default": true, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }, { "id": 6, "name": "Never Contacted", "model_class_name": "Contact", "user_id": -1, "is_default": true, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }, { "id": 7, "name": "Needs Followup", "model_class_name": "Contact", "user_id": -1, "is_default": true, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }, { "id": 8, "name": "Active", "model_class_name": "Contact", "user_id": -1, "is_default": false, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }, { "id": 9, "name": "Inactive", "model_class_name": "Contact", "user_id": -1, "is_default": false, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }, { "id": 10, "name": "Slipping Away", "model_class_name": "Contact", "user_id": -1, "is_default": false, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }] } |
View API:
To fetch all contacts (view_id => 3 from the filters API)
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/contacts/view/3" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | { "contacts": [{ "partial": true, "id": 2000003516, "job_title": "CEO", "lead_score": 0, "email": "jamessampleton@gmail.com", "work_number": "(473)-160-8261", "mobile_number": "1-926-555-9503", "open_deals_amount": "0.0", "display_name": "James Sampleton (sample)", "avatar": "https://lh3.googleusercontent.com/-DbQggdfJ2_w/Vi4cRujEXKI/AAAAAAAAABs/-Byl2CFY3lI/w140-h140-p/Image3.png", "last_contacted_mode": "email_outgoing", "last_contacted": "2016-02-08T02:36:07-08:00", "first_name": "James", "last_name": "Sampleton (sample)", "city": "San Diego", "country": "USA", "created_at": "2016-02-11T02:36:06-08:00", "updated_at": "2016-02-10T02:36:07-08:00" }], "meta": { "total": 1 } } |
2. Sort Contacts
You can use the parameters sort and sort_type to sort contacts. The contact fields that you can use to sort are- lead_score
- created_at
- updated_at
- open_deals_amount
- last_contacted
- asc
- desc
Update a Contact
This API allows you to update the information of a contact.
/api/contacts/[id]
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"contact":{"mobile_number":"5-626-852-0503", "custom_field": {"cf_is_active": false} }}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/contacts/1" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | { "contact": { "id": 1, "first_name": "James", "last_name": "Sampleton (sample)", "display_name": "James Sampleton (sample)", "avatar": null, "job_title": null, "city": null, "state": null, "zipcode": null, "country": null, "email": null, "time_zone": null, "work_number": null, "mobile_number": "5-626-852-0503", "address": null, "last_seen": null, "lead_score": -96, "last_contacted": null, "open_deals_amount": "0.0", "links": { "conversations": "/contacts/1/conversations?include=email_conversation_recipients%2Ctargetable%2Cphone_number%2Cphone_caller%2Cnote%2Cuser\u0026page=1\u0026per_page=3", "activities": "/contacts/1/activities" }, "custom_field": { "cf_is_active": false }, "updated_at": "2016-06-01T03:27:56-07:00", "keyword": null, "medium": null, "facebook": null, "twitter": null, "linkedin": null } } |
Bulk assign Owner
If you’d like to assign an owner to a list of contacts, use this API.
/api/contacts/bulk_assign_owner
ATTRIBUTE | TYPE | DESCRIPTION |
---|---|---|
selected_ids[] | Array of numbers | An array of contact ids that you'd like to assign an owner to. |
owner_id | number | id of the user. |
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"selected_ids":[1,2],"owner_id":1}' -X POST "https://domain.myfreshworks.com/crm/sales/api/contacts/bulk_assign_owner" |
Response
1 2 3 4 5 6 7 | { "contacts": [{ "1": true }, { "2": true }] } |
Clone a Contact
Using this API, you’d be able to clone contacts.
/api/contacts/[id]/clone
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{}' -X POST "https://domain.myfreshworks.com/crm/sales/api/contacts/1/clone" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | { "contact": { "id": 2, "first_name": "James", "last_name": "Sampleton (sample)", "display_name": "James Sampleton (sample)", "avatar": null, "job_title": null, "city": null, "state": null, "zipcode": null, "country": null, "email": null, "time_zone": null, "work_number": null, "mobile_number": "1-926-555-9503", "address": null, "last_seen": null, "lead_score": 0, "last_contacted": null, "open_deals_amount": "0.0", "links": { "conversations": "/contacts/1/conversations?include=email_conversation_recipients%2Ctargetable%2Cphone_number%2Cphone_caller%2Cnote%2Cuser\u0026page=1\u0026per_page=3", "activities": "/contacts/1/activities" }, "custom_field": { }, "updated_at": "2016-06-01T02:54:41-07:00", "keyword": null, "medium": null, "facebook": null, "twitter": null, "linkedin": null } } |
Additional Examples
By Default, when a clone API is called with empty body all the properties of the existing contact will be copied to the new contact. If you would like to pass certain properties for the new contact, you can do it similar to the Create A Contact API.
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"contact":{"first_name":"James", "last_name":"Sampleton (sample)", "mobile_number":"1-926-555-9503"}}' -X POST 'https://domain.myfreshworks.com/crm/sales/api/contacts/1/clone' |
Delete a Contact
This API allows you to delete a contact.
/api/contacts/[id]
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/contacts/1" |
Response
1 | true |
Forget a Contact
This API will allow you to hard delete a contact and all the associated data. Learn more about forget option here.
/api/contacts/[id]/forget
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/contacts/1/forget" |
Response
1 | true |
Bulk Delete Contacts
If you’d like to delete contacts in bulk, use this API.
/api/contacts/bulk_destroy
ATTRIBUTE | TYPE | DESCRIPTION |
---|---|---|
selected_ids[] | Array of numbers | An array of contact ids that you'd like to delete. |
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"selected_ids":[1,2]}' -X POST "https://domain.myfreshworks.com/crm/sales/api/contacts/bulk_destroy" |
Response
1 2 3 4 5 6 7 | { "contacts": [{ "1": true }, { "2": true }] } |
List All Contact Fields
If you’d like to view all the contact fields, use this API.
/api/settings/contacts/fields
If you’d like to view the contact fields along with the groups that they belong to, use,
/api/settings/contacts/fields?include=field_group
Note:
The agent whose credentials (API key or username/password) are being used to make this API call should be authorised to view the contact fields.
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/settings/contacts/fields" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 | { "fields":[ { "id":2000001198, "label":"First name", "name":"first_name", "type":"text", "default":true, "actionable":false, "position":1, "choices":[ ], "base_model":"Contact", "required":false }, { "id":2000001199, "label":"Last name", "name":"last_name", "type":"text", "default":true, "actionable":false, "position":2, "choices":[ ], "base_model":"Contact", "required":true }, { "id":2000001200, "label":"Job title", "name":"job_title", "type":"text", "default":true, "actionable":false, "position":3, "choices":[ ], "base_model":"Contact", "required":false }, { "id":2000001202, "label":"Email", "name":"email", "type":"text", "default":true, "actionable":false, "position":5, "choices":[ ], "base_model":"Contact", "required":false }, { "id":2000001203, "label":"Work", "name":"work_number", "type":"text", "default":true, "actionable":false, "position":6, "choices":[ ], "base_model":"Contact", "required":false }, { "id":2000001204, "label":"Mobile", "name":"mobile_number", "type":"text", "default":true, "actionable":false, "position":7, "choices":[ ], "base_model":"Contact", "required":false }, ... ] } |
List all Activites
This API allows you to get the activities of a contact.
/api/contacts/[id]/activities
You can embed the include param to get the user details. Limit param can be used to limit the number of results.
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/contacts/1/activities.json?include=user&limit=3" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 | { "users": [{ "id": 1, "display_name": "Sample Admin", "email": "admin@yourcompany.com" }], "activities": [{ "composite_id": "4_STAGE_CHANGE", "action_data": { "stage_id": 6, "stage_name": "Won" }, "action_type": "STAGE_CHANGE", "created_at": "2016-02-10T02:36:07-08:00", "user_activity": true, "targetable_type": "Deal", "targetable_id": 1, "actionable_type": null, "actionable_id": null, "targetable_name": "Gold plan (sample)", "user_id": 1 }, { "composite_id": "5_APP_EVENTS", "action_data": { "name": "Added a user", "count": 1 }, "action_type": "APP_EVENTS", "created_at": "2016-02-10T02:36:07-08:00", "user_activity": false, "targetable_type": null, "targetable_id": null, "actionable_type": null, "actionable_id": null, "targetable_name": null, "user_id": null }, { "composite_id": "6_APPOINTMENT_CREATED", "action_data": { "description": "Meeting James to resolve any concerns and close the deal.", "end_date": "2016-02-13T18:00:00+00:00", "from_date": "2016-02-13T16:00:00+00:00", "time_zone": "Arizona", "title": "(Sample) Meeting - final discussion about the deal" }, "action_type": "APPOINTMENT_CREATED", "created_at": "2016-02-09T02:36:07-08:00", "user_activity": true, "targetable_type": "Contact", "targetable_id": 1, "actionable_type": "Appointment", "actionable_id": 1, "targetable_name": null, "user_id": 1 }] } |
Accounts
Companies with whom you have an existing business relationship are saved as Accounts in Freshworks CRM. Usually one or more individuals (contacts) are associated to the account with whom you pursue sales opportunities
ATTRIBUTE | TYPE | DESCRIPTION |
---|---|---|
id | number | Unique ID of the account |
name* | string | Name of the account |
address | string | Address of the account |
city | string | City that the account belongs to |
state | string | State that the account belongs to |
zipcode | string | Zipcode of the region that the account belongs to |
country | string | Country that the account belongs to |
industry_type_idΩ | number | ID of the industry that the account belongs to |
business_type_idΩ | number | ID of the business that the account belongs to |
number_of_employees | number | Number of employees in the account |
annual_revenue | decimal (18,0) | Annual revenue of the account |
website | string | Website of the account |
phone | string | Phone number of the account |
owner_idΩ | number | ID of the user to whom the account has been assigned |
string | Facebook username of the account | |
string | Twitter username of the account | |
string | LinkedIn account of the account | |
territory_idΩ | number | ID of the territory that the account belongs to |
created_at | datetime | Account creation timestamp |
updated_at | datetime | Account updated timestamp |
parent_sales_account_id | number | Parent account id of the account |
* Mandatory fields for creating account Ω To know all available options for this field, refer Configuration |
Properties:
Number of Employees | Value |
---|---|
"1-10" | 1 |
"11-50" | 11 |
"51-200 | 51 |
"201-500" | 201 |
"501-1000" | 501 |
"1001-5000" | 1001 |
"5001-10000" | 5001 |
"10000+" | 10001 |
Create an Account
This API allows you to create an account.
/api/sales_accounts
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"sales_account":{"name":"Widgetz.io (sample)"} }' -X POST "https://domain.myfreshworks.com/crm/sales/api/sales_accounts" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | { "sales_account": { "id": 1, "name": "Widgetz.io (sample)", "address": null, "city": null, "state": null, "zipcode": null, "country": null, "number_of_employees": null, "annual_revenue": null, "website": null, "phone": null, "open_deals_amount": "0.0", "last_contacted": null, "last_contacted_mode": null, "facebook": null, "twitter": null, "linkedin": null, "links": { "conversations": "/sales_accounts/1/conversations?include=email_conversation_recipients%2Ctargetable%2Cphone_number%2Cphone_caller%2Cuser%2Cnote\u0026per_page=3" }, "custom_field": { "cf_domain_name": "sampledomain.yourcompany.com" }, "updated_at": "2016-06-01T04:36:31-07:00", "open_deals_count": 0, "avatar": null } } |
Create an account with custom fields
If you’d like to create an account along with custom fields, use this API.Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"sales_account":{"name":"Widgetz.io (sample)", "custom_field":{"cf_domain_name":"sampledomain.yourcompany.com"} }}' -X POST "https://domain.myfreshworks.com/crm/sales/api/sales_accounts" |
Create an account by associating it to a new parent account
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json"-d '{"sales_account":{"name":"Widgetz.io (sample)", “parent_sales_account”:{“name”:”Parent”} }}' -X POST "https://domain.myfreshworks.com/crm/sales/api/sales_accounts" |
View an Account
This API allows you to view the details of an account.
/api/sales_accounts/[id]
Use 'include' to embed additional details in the response
Embed | Handle |
---|---|
owner | api/sales_accounts/[id]?include=owner Will return the owner id, name and email |
creater | api/sales_accounts/[id]?include=creater Will return the creater id, name and email |
updater | api/sales_accounts/[id]?include=updater Will return the updater id, name and email |
territory | api/sales_accounts/[id]?include=territory Will return the id and name of the territory |
business_type | api/sales_accounts/[id]?include=business_type Will return the id and name of the business_type |
tasks | api/sales_accounts/[id]?include=tasks Will return the task id, title, due_date, status and owner_id |
appointments | api/sales_accounts/[id]?include=appointments Will return the appointment id, title, time_zone, from_date, end_date and creater_id |
contacts | api/sales_accounts/[id]?include=contacts Will return the connected contact details |
deals | api/sales_accounts/[id]?include=deals Will return the connected deal details |
industry_type | api/sales_accounts/[id]?include=industry_type Will return the id and name of the industry_type |
child_sales_accounts | api/sales_accounts/[id]?include=child_sales_accounts Will return the child sales accounts details |
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/sales_accounts/1?include=owner" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | { "users": [{ "id": 1, "display_name": "Sample User", "email": "sampleuser@yourcompany.com" }], "sales_account": { "id": 1, "name": "Widgetz.io", "address": null, "city": null, "state": null, "zipcode": null, "country": null, "number_of_employees": null, "annual_revenue": null, "website": null, "phone": null, "open_deals_amount": "0.0", "last_contacted": null, "last_contacted_mode": null, "facebook": null, "twitter": null, "linkedin": null, "links": { "conversations": "/sales_accounts/1/conversations?include=email_conversation_recipients%2Ctargetable%2Cphone_number%2Cphone_caller%2Cuser%2Cnote\u0026per_page=3" }, "custom_field": { "cf_domain_name": "sampledomain.yourcompany.com" }, "updated_at": "2016-06-01T04:42:54-07:00", "open_deals_count": 0, "avatar": null, "owner_id": 1 } } |
List All Accounts
If you’d like to fetch a list of accounts, use this API.
/api/sales_accounts/view/[view_id]
You can filter your accounts and also sort them to get a list of specific accounts
1. Filtering Accounts
If you’d like to view specific accounts, use views. To fetch accounts from a view, first fetch the view id using the filters API and then use view API to fetch.
/api/sales_accounts/filters
Filters API
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/sales_accounts/filters" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | { "filters":[ { "id":1, "name":"My Accounts", "model_class_name":"SalesAccount", "user_id":-1, "is_default":true, "is_public":true, "updated_at":"2016-03-07T01:46:44-08:00" }, { "id":2, "name":"All Accounts", "model_class_name":"SalesAccount", "user_id":-1, "is_default":true, "is_public":true, "updated_at":"2016-03-07T01:46:44-08:00" }, { "id":3, "name":"MY Territory Accounts", "model_class_name":"SalesAccount", "user_id":-1, "is_default":true, "is_public":true, "updated_at":"2016-03-07T01:46:44-08:00" } ] } |
View API
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/sales_accounts/view/2" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | { "sales_accounts": [{ "id": 1, "name": "Widgetz.io (sample)", "last_contacted": "2016-02-09T02:36:07-08:00", "last_contacted_mode": "email_outgoing", "city": "New Haven", "state": "Connecticut", "country": "United States", "open_deals_amount": "0.0", "avatar": null, "created_at": "2016-02-11T02:36:06-08:00", "updated_at": "2016-02-11T02:36:06-08:00" }], "meta": { "total_pages": 1, "total": 1 } } |
2. Sort Accounts
You can use the parameters sort and sort_type to sort accounts. The account fields that you can use to sort are- open_deals_amount
- created_at
- updated_at
- last_contacted
- asc
- desc
Update an Account
This API allows you to update the information of an account.
/api/sales_accounts/[id]
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"sales_account":{"custom_field": {"cf_domain_name": "samplewebsite.yourcompany.com"} }}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/sales_accounts/1" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | { "sales_account": { "id": 1, "name": "Widgetz.io", "address": null, "city": null, "state": null, "zipcode": null, "country": null, "number_of_employees": null, "annual_revenue": null, "website": null, "phone": null, "open_deals_amount": "0.0", "last_contacted": null, "last_contacted_mode": null, "facebook": null, "twitter": null, "linkedin": null, "links": { "conversations": "/sales_accounts/1/conversations?include=email_conversation_recipients%2Ctargetable%2Cphone_number%2Cphone_caller%2Cuser%2Cnote\u0026per_page=3" }, "custom_field": { "cf_domain_name": "samplewebsite.yourcompany.com" }, "updated_at": "2016-06-01T04:52:21-07:00", "open_deals_count": 0, "avatar": null } } |
Clone an Account
Using this API, you’d be able to clone accounts.
/api/sales_accounts/[id]/clone
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{}' -X POST "https://domain.myfreshworks.com/crm/sales/api/sales_accounts/1/clone" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | { "sales_account": { "id": 2, "name": "Widgetz.io (sample)", "address": null, "city": null, "state": null, "zipcode": null, "country": null, "number_of_employees": null, "annual_revenue": null, "website": null, "phone": null, "open_deals_amount": "0.0", "last_contacted": null, "last_contacted_mode": null, "facebook": null, "twitter": null, "linkedin": null, "links": { "conversations": "/sales_accounts/1/conversations?include=email_conversation_recipients%2Ctargetable%2Cphone_number%2Cphone_caller%2Cuser%2Cnote\u0026per_page=3" }, "custom_field": { "cf_domain_name": "sampledomain.yourcompany.com" }, "updated_at": "2016-06-01T04:36:31-07:00", "open_deals_count": 0, "avatar": null } } |
Additional Examples
By Default, when a clone API is called with empty body all the properties of the existing account will be copied to the new account. If you would like to pass certain properties for the new account, you can do it similar to the Create An Account API.
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"sales_account":{"name":"Widgetz.io (sample)"} }' -X POST 'https://domain.myfreshworks.com/crm/sales/api/sales_accounts/1/clone' |
Delete an Account
This API allows you to delete an account.
/api/sales_accounts/[id]
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/sales_accounts/1" |
Response
1 | true |
Additional Examples
If you’d like to delete an account along with the associated contacts and open deals, use this API.
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/sales_accounts/1?delete_associated_contacts_deals=true" |
Forget an Account
This API will allow you to hard delete an account and all the associated data. Learn more about forget option here.
/api/sales_accounts/[id]/forget
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/sales_accounts/1/forget" |
Response
1 | true |
Bulk Delete Accounts
If you’d like to delete accounts in bulk, use this API.
/api/sales_accounts/bulk_destroy
ATTRIBUTE | TYPE | DESCRIPTION |
---|---|---|
selected_ids[] | Array of numbers | An array of account ids that you'd like to delete. |
delete_associated_contacts_deals | boolean | Option to delete associated contacts and open deals. Default value is false |
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"selected_ids":[1,2]}' -X POST "https://domain.myfreshworks.com/crm/sales/api/sales_accounts/bulk_destroy" |
Response
1 2 3 4 5 6 7 | { "sales_accounts": [{ "1": true }, { "2": true }] } |
Additional Examples
If you’d like to delete an account along with the associated contacts and open deals, use this API.
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"selected_ids":[1,2],"delete_associated_contacts_deals":true}' -X POST "https://domain.myfreshworks.com/crm/sales/api/sales_accounts/bulk_destroy" |
List All Account Fields
If you’d like to view all the account fields, use this API.
/api/settings/sales_accounts/fields
If you'd like to view account fields along with the groups that they belong to, use,
/api/settings/sales_accounts/fields?include=field_group
Note:
The agent whose credentials (API key or username/password) are being used to make this API call should be authorised to view the account fields.
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/settings/sales_accounts/fields" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 | { "fields": [{ "id": 2000000743, "label": "Name", "name": "name", "type": "text", "default": true, "actionable": false, "position": 1, "choices": [ ], "base_model": "SalesAccount", "required": true }, { "id": 2000000744, "label": "Address", "name": "address", "type": "text", "default": true, "actionable": false, "position": 2, "choices": [ ], "base_model": "SalesAccount", "required": false }, { "id": 2000000745, "label": "City", "name": "city", "type": "text", "default": true, "actionable": false, "position": 3, "choices": [ ], "base_model": "SalesAccount", "required": false }, { "id": 2000000746, "label": "State", "name": "state", "type": "text", "default": true, "actionable": false, "position": 4, "choices": [ ], "base_model": "SalesAccount", "required": false }, { "id": 2000000747, "label": "Zipcode", "name": "zipcode", "type": "text", "default": true, "actionable": false, "position": 5, "choices": [ ], "base_model": "SalesAccount", "required": false }, { "id": 2000000748, "label": "Country", "name": "country", "type": "text", "default": true, "actionable": false, "position": 6, "choices": [ ], "base_model": "SalesAccount", "required": false }, ... ] } |
Deals
Deals are the expected sales opportunities from an account.
ATTRIBUTE | TYPE | DESCRIPTION |
---|---|---|
id | number | Unique ID of the deal |
name* | string | Name of the deal |
amount* | decimal (15,2) | Value of the deal |
currency_idΩ | number | ID of the currency that the deal belongs to |
base_currency_amount | decimal (19,4) | Value of the deal in base currency |
sales_account_id† | number | ID of the account that the deal belongs to |
deal_stage_idΩ | number | ID of the deal stage that the deal belongs to |
deal_reason_idΩ | number | ID of the deal reason - Reason for losing the deal Can be set only if the deal is in "Lost" stage. |
deal_type_idΩ | number | ID of the deal type that the deal belongs to |
owner_idΩ | number | ID of the user to whom the deal has been assigned |
expected_close | date | The date when the deal is expected to close |
closed_date | date | The date when the deal is closed |
lead_source_idΩ | number | ID of the source where deal came from |
campaign_idΩ | number | ID of the campaign that landed this deal |
deal_product_idΩ | number | ID of the product that the deal belongs to(in a multi product company) |
deal_payment_status_idΩ | number | ID of the mode of payment for the deal |
probability | number (>=0 and <=100) | The probability of winning the deal |
created_at | datetime | Deal creation timestamp |
updated_at | datetime | Deal updated timestamp |
territory_idΩ | number | ID of the territory that the deal belongs to |
deal_pipeline_idΩ | number | ID of the deal pipeline that it belongs to |
* Mandatory fields for creating deal. † This field is mandatory. Either you must send ID of an existing account or add a new account on the fly (Refer "Create a deal by associating to a new account" shown below). Ω To know all available options for this field, refer Configuration |
Create a Deal
This API allows you to create a deal.
/api/deals
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"deal":{"name":"Sample deal", "amount":23456, "sales_account_id":1}}' -X POST "https://domain.myfreshworks.com/crm/sales/api/deals" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | { "users": [{ "id": 1, "display_name": "Sample User", "email": "sampleuser@yourcompany.com" }], "deal": { "id": 1, "name": "Sample deal", "amount": "23456.0", "base_currency_amount": "23456.0", "expected_close": null, "closed_date": null, "stage_updated_time": "2016-06-01T05:36:16-07:00", "custom_field": { }, "probability": null, "updated_at": "2016-06-01T05:36:16-07:00", "created_at": "2016-06-01T05:36:16-07:00", "age": null, "creater_id": 1 } } |
Additional Examples
1. Create a deal with custom fields
If you’d like to create a deal along with custom fields, use this API.
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"deal":{"name":"Sample deal", "amount":23456, "sales_account_id":1, "custom_field":{"cf_number_of_agents":45} }}' -X POST "https://domain.myfreshworks.com/crm/sales/api/deals" |
2. Create a deal by associating to a new account
If you’d like to create a deal and associate the deal with an account, use this API.
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"deal":{"name":"Sample deal", "amount":23456, "sales_account":{"name":"Sample Account"}, "custom_field":{"cf_number_of_agents":45} }}' -X POST "https://domain.myfreshworks.com/crm/sales/api/deals" |
3. Create a deal by associating to a contact
If you’d like to create a deal and associate the deal with a contact, use this API.
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"deal":{"name":"Sample deal", "amount":23456, "sales_account":{"name":"Sample Account"}, "custom_field":{"cf_number_of_agents":45}, "contacts_added_list":[1,2] }}' -X POST "https://domain.myfreshworks.com/crm/sales/api/deals" |
View a Deal
This API allows you to view the details of a deal.
/api/deals/[id]
Use 'include' to embed additional details in the response.
Embed | Handle |
---|---|
owner | api/deals/[id]?include=owner Will return the owner id, name and email |
creater | api/deals/[id]?include=creater Will return the creater id, name and email |
updater | api/deals/[id]?include=updater Will return the updater id, name and email |
source | api/deals/[id]?include=source Will return the source id, name |
contacts | api/deals/[id]?include=contacts Will return the connected contact details |
sales_account | api/deals/[id]?include=sales_account Will return the connected account details |
deal_stage | api/deals/[id]?include=deal_stage Will return the deal_stage id, name |
deal_type | api/deals/[id]?include=deal_type Will return the deal_type id, name |
deal_reason | api/deals/[id]?include=deal_reason Will return the deal_reason id, name |
campaign | api/deals/[id]?include=campaign Will return the campaign id, name |
deal_payment_status | api/deals/[id]?include=deal_payment_status Will return the deal_payment_status id, name |
deal_product | api/deals/[id]?include=deal_product Will return the deal_product id, name |
currency | api/deals/[id]?include=currency Will return the currency id, name |
probability | number (>=0 and <=100) |
created_at | datetime |
updated_at | datetime |
updated_at | datetime |
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/deals/1?include=owner" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | { "users": [{ "id": 1, "display_name": "Sample User", "email": "sampleuser@yourcompany.com" }], "deal": { "id": 1, "name": "Sample deal", "amount": "23456.0", "base_currency_amount": "23456.00", "expected_close": null, "closed_date": null, "stage_updated_time": "2016-06-01T05:45:27-07:00", "custom_field": { "cf_number_of_agents": 45 }, "probability": null, "updated_at": "2016-06-01T05:56:19-07:00", "created_at": "2016-06-01T05:45:27-07:00", "age": null, "owner_id": 1 } } |
List All Deals
If you’d like to fetch a list of deals, use this API.
/api/deals/view/[view_id]
You can filter your deals and also sort them to get a list of specific deals
1. Filtering deals
If you’d like to view specific deals, use views. To fetch deals from a view, first fetch the view id using the filters API and then use view API to fetch.
/api/deals/filters
Filters API:
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/deals/filters" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 | { "filters": [{ "id": 1, "name": "Open Deals", "model_class_name": "Deal", "user_id": -1, "is_default": true, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }, { "id": 2, "name": "My Deals", "model_class_name": "Deal", "user_id": -1, "is_default": true, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }, { "id": 3, "name": "My Territory Deals", "model_class_name": "Deal", "user_id": -1, "is_default": true, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }, { "id": 4, "name": "Recent Deals", "model_class_name": "Deal", "user_id": -1, "is_default": true, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }, { "id": 5, "name": "Lost Deals", "model_class_name": "Deal", "user_id": -1, "is_default": false, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }, { "id": 6, "name": "Won Deals", "model_class_name": "Deal", "user_id": -1, "is_default": false, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }, { "id": 7, "name": "Hot Deals", "model_class_name": "Deal", "user_id": -1, "is_default": false, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }, { "id": 8, "name": "Cold Deals", "model_class_name": "Deal", "user_id": -1, "is_default": false, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" } ] } |
View API
To fetch all deals (view_id => 4 from the filters API)
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/deals/view/4" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | { "deals": [{ "id": 1, "name": "Sample deal", "amount": "23456.0", "expected_close": null, "closed_date": null, "stage_updated_time": "2016-06-01T05:45:27-07:00", "custom_field": { "cf_number_of_agents": 56 }, "probability": 30, "updated_at": "2016-06-01T06:03:35-07:00", "created_at": "2016-06-01T05:45:27-07:00", "age": null }], "meta": { "total": 1 } } |
2. Sort Deals
You can use the parameters sort and sort_type to sort deals. The deal fields that you can use to sort are- amount
- expected_close
- created_at
- updated_at
- last_contacted
- asc
- desc
Update a Deal
This API allows you to update the information of a deal.
/api/deals/[id]
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"deal":{"probability":30, "custom_field": {"cf_number_of_agents": 56}, "contacts_removed_list":[2] }}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/deals/1" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | { "users": [{ "id": 2000000108, "display_name": "Sample User", "email": "sampleuser@yourcompany.com" }], "deal": { "id": 1, "name": "Sample deal", "amount": "23456.0", "base_currency_amount": "23456.0", "expected_close": null, "closed_date": null, "stage_updated_time": "2016-06-01T05:45:27-07:00", "custom_field": { "cf_number_of_agents": 56 }, "probability": 30, "updated_at": "2016-06-01T06:03:35-07:00", "created_at": "2016-06-01T05:45:27-07:00", "age": null, "updater_id": 2000000108 } } |
Clone a Deal
Using this API, you’d be able to clone deals.
/api/deals/[id]/clone
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{}' -X POST "https://domain.myfreshworks.com/crm/sales/api/deals/1/clone" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | { "users": [{ "id": 1, "display_name": "Sample User", "email": "sampleuser@yourcompany.com" }], "deal": { "id": 2, "name": "Sample deal", "amount": "23456.0", "base_currency_amount": "23456.0", "expected_close": null, "closed_date": null, "stage_updated_time": "2016-06-01T05:36:16-07:00", "custom_field": { }, "probability": null, "updated_at": "2016-06-01T05:36:16-07:00", "created_at": "2016-06-01T05:36:16-07:00", "age": null, "creater_id": 1 } } |
Additional Examples
By Default, when a clone API is called with empty body all the properties of the existing deal will be copied to the new deal. If you would like to pass certain properties for the new deal, you can do it similar to the Create A Deal API.
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"deal":{"name":"Sample deal", "amount":23456, "sales_account_id":1}}' -X POST 'https://domain.myfreshworks.com/crm/sales/api/deals/1/clone' |
Forget a Deal
This API will allow you to hard delete a deal and all the associated data. Learn more about forget option here.
/api/deals/[id]/forget
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/deals/1/forget" |
Response
1 | true |
Bulk Delete Deals
If you’d like to delete deals in bulk, use this API.
/api/deals/bulk_destroy
ATTRIBUTE | TYPE | DESCRIPTION |
---|---|---|
selected_ids[] | Array of numbers | This is an array of deal ids that you'd like to delete. |
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"selected_ids":[1,2]}' -X POST "https://domain.myfreshworks.com/crm/sales/api/deals/bulk_destroy" |
Response
1 2 3 4 5 6 7 | { "deals": [{ "1": true }, { "2": true }] } |
List All Deal Fields
If you’d like to view all the deal fields, use this API.
/api/settings/deals/fields
If you’d like to view the deal fields along with the groups that they belong to, use,
/api/settings/deals/fields?include=field_group
Note:
The agent whose credentials (API key or username/password) are being used to make this API call should be authorised to view the deal fields.
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/settings/deals/fields" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 | { "fields": [{ "id": 2000000522, "label": "Name", "name": "name", "type": "text", "default": true, "actionable": false, "position": 1, "choices": [ ], "base_model": "Deal", "required": true }, { "id": 2000000523, "label": "Deal value", "name": "amount", "type": "number", "default": true, "actionable": false, "position": 2, "choices": [ ], "base_model": "Deal", "required": true }, { "id": 2000000524, "label": "Deal stage", "name": "deal_stage_id", "type": "dropdown", "default": true, "actionable": true, "position": 3, "choices": [{ "id": 2000000249, "value": "New", "position": 1, "choice_type": 1 }, { "id": 2000000250, "value": "Follow-up", "position": 2, "choice_type": 2 }, { "id": 2000000251, "value": "Under review", "position": 3, "choice_type": 2 }, { "id": 2000000252, "value": "Demo", "position": 4, "choice_type": 2 }, { "id": 2000000253, "value": "Negotiation", "position": 5, "choice_type": 2 }, { "id": 2000000254, "value": "Won", "position": 7, "choice_type": 4 }, { "id": 2000000255, "value": "Lost", "position": 8, "choice_type": 4 }], "base_model": "Deal", "required": false }, { "id": 2000000525, "label": "Lost reason", "name": "deal_reason_id", "type": "dropdown", "default": true, "actionable": true, "position": 4, "choices": [{ "id": 2000000316, "value": "Opted our rival", "position": 1 }, { "id": 2000000317, "value": "Price is too high", "position": 2 }, { "id": 2000000318, "value": "Junk Contact", "position": 3 }, { "id": 2000000319, "value": "Not interested", "position": 4 }, { "id": 2000000320, "value": "No requirement", "position": 5 }, { "id": 2000000321, "value": "Need only in future", "position": 6 }, { "id": 2000000322, "value": "Product not satisfying", "position": 7 }, { "id": 2000000323, "value": "No proper follow-up", "position": 8 }, { "id": 2000000324, "value": "Appointment missed", "position": 9 }], "base_model": "Deal", "required": false }, { "id": 2000000526, "label": "Type", "name": "deal_type_id", "type": "dropdown", "default": true, "actionable": true, "position": 5, "choices": [{ "id": 2000000105, "value": "New Business", "position": 1 }, { "id": 2000000106, "value": "Existing Business-Renewal", "position": 2 }, { "id": 2000000107, "value": "Existing Business-Upgrade", "position": 3 }], "base_model": "Deal", "required": false }, ... ] } |
Notes
Notes are great way to add details about a contact that could come in handy when you connect with them in future.
Attribute | Type | Description |
---|---|---|
description* | Text | Description of the note |
targetable_id* | number | ID of contact/account against whom note has been created |
targetable_type* | string | String that denotes against which entity note has been created. Possible values are either "Contact" or "SalesAccount" or "Deal". |
* Mandatory fields for creating note. |
Create a Note
This API allows you to create a note.
/api/notes
Create a note for a Contact
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"note":{"description":"Sample note for contact create", "targetable_type":"Contact", "targetable_id":1}}' -X POST "https://domain.myfreshworks.com/crm/sales/api/notes" |
Response
1 2 3 4 5 6 7 8 | { "note": { "id": 1, "description": "Sample note for contact create", "created_at": "2016-06-13T17:22:19+05:30", "updated_at": "2016-06-13T17:22:19+05:30" } } |
Create a note for a Contact
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"note":{"description":"Sample note for contact create", "targetable_type":"Contact", "targetable_id":1}}' -X POST "https://domain.myfreshworks.com/crm/sales/api/notes" |
Response
1 2 3 4 5 6 7 8 | { "note": { "id": 2, "description": "Sample note for contact create", "created_at": "2016-06-13T17:23:19+05:30", "updated_at": "2016-06-13T17:23:19+05:30" } } |
Create a Note for an Account
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"note":{"description":"Create Sample note for an account", "targetable_type":"SalesAccount", "targetable_id":1}}' -X POST https://domain.myfreshworks.com/crm/sales/api/notes |
Sample Response
1 2 3 4 5 6 7 8 | { "note": { "id": 3, "description": "Create Sample note for an account", "created_at": "2016-06-13T17:22:19+05:30", "updated_at": "2016-06-13T17:22:19+05:30" } } |
Create a Note for a Deal
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"note":{"description":"Create Sample note for a deal", "targetable_type":"Deal", "targetable_id":1}}' -X POST https://domain.myfreshworks.com/crm/sales/api/notes |
Sample Response
1 2 3 4 5 6 7 8 | { "note": { "id": 3, "description": "Create Sample note for a deal", "created_at": "2016-06-13T17:22:19+05:30", "updated_at": "2016-06-13T17:22:19+05:30" } } |
Update a note
This API allows you to update a note.
/api/notes/[id]
Update a note for a Contact
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"note":{"description":"Sample note for contact update", "targetable_type":"Contact", "targetable_id":1}}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/notes/1" |
Response
1 2 3 4 5 6 7 8 | { "note": { "id": 1, "description": "Sample note for contact update", "created_at": "2016-06-13T17:22:19+05:30", "updated_at": "2016-06-13T17:24:19+05:30" } } |
Update a note for a Contact
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"note":{"description":"Sample note for contact update", "targetable_type":"Contact", "targetable_id":1}}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/notes/2" |
Response
1 2 3 4 5 6 7 8 | { "note": { "id": 2, "description": "Sample note for contact update", "created_at": "2016-06-13T17:23:19+05:30", "updated_at": "2016-06-13T17:25:19+05:30" } } |
Update a note for an Account
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"note":{"description":"Update the Sample note for an account", "targetable_type":"SalesAccount", "targetable_id":1}}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/notes/3" |
Sample Response
1 2 3 4 5 6 7 8 | { "note": { "id": 3, "description": "Update the Sample note for an account", "created_at": "2016-06-13T17:22:19+05:30", "updated_at": "2016-06-13T17:24:19+05:30" } } |
Delete a note
This API allows you to delete a note.
/api/notes/[id]
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/notes/1" |
Response
1 2 3 4 5 6 7 8 | { "note": { "id": 1, "description": "Sample note for contact update", "created_at": "2016-06-13T17:22:19+05:30", "updated_at": "2016-06-13T17:24:19+05:30" } } |
Tasks
Task are a great way to collaborate with your team and get things done.
ATTRIBUTE | TYPE | DESCRIPTION |
---|---|---|
id | number | Unique ID of the task |
title* | string | Title of the task |
description | text | Description of the task |
due_date* | datetime | Timestamp that denotes when the task is due to be completed |
targetable_id* | number | ID of contact/account against whom task has been created |
targetable_type* | string | String that denotes against which entity task has been created. Possible values are either "Contact" or "SalesAccount" or "Deal" |
owner_id* | number | ID of the user to whom the task has been assigned |
status | boolean | Status of the task. Refer the below properties table for possible values. |
creater_id | number | ID of the user who created the task |
created_at | datetime | Task creation timestamp |
updated_at | datetime | Task updated timestamp |
outcome_idΩ | number | ID of outcome of Task sales activity type |
task_type_idΩ | number | ID of type of Task sales activity type |
* Mandatory fields for creating task. Ω To know all available options for this field, refer Configuration |
Properties:
Status | Value |
---|---|
Open | 0 |
Completed | 1 |
Create a Task
This API allows you to create a task
/api/tasks
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{ "task":{ "title":"Sample Task", "description":"This is just a sample task.", "due_date":"Tue Jun 21 2016 11:00:00 GMT+0000","owner_id":"1", "targetable_id":"1","targetable_type":"Contact", "task_users_attributes":[ { "user_id":"1"} ] }}' -X POST "https://domain.myfreshworks.com/crm/sales/api/tasks" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 | { "task":{ "id":1, "status":0, "title":"Sample Task", "description":"This is just a sample task.", "created_at":"2016-06-17T03:56:22Z", "updated_at":"2016-06-17T03:56:22Z", "owner_id":1, "due_date":"2016-06-21T11:00:00Z", "creater_id":1 } } |
View a Task
This API allows you to view the details of a task.
/api/tasks/[id]
Use 'include' to embed additional details in the response
EMBED | HANDLE |
---|---|
users | /api/tasks/[id]?include=users Will return the Collaborator's id, avatar, type and display_name |
targetable | /api/tasks/[id]?include=targetable Will return the contact's id, avatar and display_name Will return the account’s id, avatar and name |
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/tasks/1?include=users,targetable" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | { "users": [{ "id": 1, "display_name": "Sample User1", "avatar": null, "type": "FdMultitenant::User" }, { "id": 2, "display_name": "Sample User2", "avatar": null, "type": "FdMultitenant::User" }], "contacts": [{ "id": 1, "avatar": null, "display_name": "Jane Sampleton (sample)" }], "task": { "id": 1, "status": 0, "title": "Sample Task", "description": "This is just a sample task.", "created_at": "2016-06-17T03:56:22Z", "updated_at": "2016-06-17T04:03:16Z", "owner_id": 1, "due_date": "2016-06-21T11:00:00Z", "creater_id": 1, "user_ids": [2], "targetable": { "type": "contact", "id": 1 } } } |
List All Tasks
Get filtered tasks
You can use this API to receive a list of filtered tasks i.e get your open, due today, due tomorrow, overdue and completed tasks./api/tasks?filter=[filter param]
- The parameter filter is mandatory.
- Only one filter is allowed at a time. Getting multiple filtered tasks is not possible. For example, you can’t get both open and overdue tasks in a single request.
- Use 'include' to embed additional details in the response. Multiple values can be embedded in single request separated by a comma (include=users,targetable).
Embed | Handle |
---|---|
users |
/api/tasks?filter=open&include=users Will return the Collaborator's id, avatar, type and display_name |
targetable |
/api/tasks?filter=open&include=targetable Will return the targetable’s id, avatar and display_name |
owner |
/api/tasks?filter=open&include=owner Will return the owner’s id, avatar, type and display_name |
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET https://domain.myfreshworks.com/crm/sales/api/tasks?filter=open&include=owner |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 | { "users": [{ "id": 1, "display_name": "Sales Agent", "avatar": null, "type": "FdMultitenant::User" }], "tasks": [{ "id": 2, "status": 0, "title": "(Sample) Send the proposal document", "description": "Send the proposal document and follow up with this contact after it.", "created_at": "2016-07-14T14:00:52+05:30", "updated_at": "2016-07-18T14:00:52+05:30", "owner_id": 1, "due_date": "2016-07-19T08:00:00+05:30", "creater_id": 1 }, { "id": 1, "status": 0, "title": "(Sample) Follow-up with Jane", "description": "Do a follow-up call with Jane.", "created_at": "2016-07-12T14:00:49+05:30", "updated_at": "2016-07-18T14:00:49+05:30", "owner_id": 1, "due_date": "2016-07-19T10:00:00+05:30", "creater_id": 1 }, { "id": 3, "status": 0, "title": "(Sample) Send the pricing quote", "description": "Coordinate with Steve for the pricing quote and send it to James.", "created_at": "2016-07-14T14:00:52+05:30", "updated_at": "2016-07-18T14:00:52+05:30", "owner_id": 1, "due_date": "2016-07-20T09:00:00+05:30", "creater_id": 1 }], "meta": { "total": 3 } } |
Update a Task
This API allows you to update a task.
/api/tasks/[:task_id]
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{ "task":{ "title":"Updated Sample Task","description":"This is just an edited version of sample Task.","due_date":"Tue Jun 21 2016 11:00:00 GMT+0000","owner_id":"1","targetable_id":"1","targetable_type":"Contact","task_users_attributes":[{"user_id":"2"}] }}' -X PUT https://domain.myfreshworks.com/crm/sales/api/tasks/1 |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | { "users": [{ "id": 1, "display_name": "Sample User1", "avatar": null, "type": "FdMultitenant::User" }, { "id": 2, "display_name": "Sample User2", "avatar": null, "type": "FdMultitenant::User" }], "task": { "id": 1, "status": 0, "title": "Updated Sample Task", "description": "This is just an edited version of sample Task.", "created_at": "2016-06-17T03:56:22Z", "updated_at": "2016-06-17T04:03:16Z", "owner_id": 1, "due_date": "2016-06-21T11:00:00Z", "creater_id": 1, "user_ids": [2] } } |
Mark Task as Done
This API allows you to mark a task as done.
/api/tasks/[:task_id]
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"task": {"status" :1}' -X PUT https://domain.myfreshworks.com/crm/sales/api/tasks/1 |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | { "users": [{ "id": 1, "display_name": "Sample User1", "avatar": null, "type": "FdMultitenant::User" }, { "id": 2, "display_name": "Sample User2", "avatar": null, "type": "FdMultitenant::User" }], "task": { "id": 1, "status": 1, "title": "Updated Sample Task", "description": "This is just an edited version of sample Task.", "created_at": "2016-06-17T03:56:22Z", "updated_at": "2016-06-17T04:09:34Z", "owner_id": 1, "due_date": "2016-06-21T11:00:00Z", "creater_id": 1, "user_ids": [2] } } |
Delete Task
This API allows you to delete a task.
/api/tasks/[:task_id]
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE https://domain.myfreshworks.com/crm/sales/api/tasks/1 |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 | { "task": { "id": 1, "status": 0, "title": "Updated Sample Task", "description": "This is just an edited version of sample Task.", "created_at": "2016-06-17T03:56:22Z", "updated_at": "2016-06-17T04:03:16Z", "owner_id": 1, "due_date": "2016-06-21T11:00:00Z", "creater_id": 1 } } |
Appointments
Appointments are great way to meet with your prospects as attendees of appointments get notified about the time, venue and purpose of the meeting automaticaly
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the appointment |
from_date* | datetime/ date |
Timestamp that denotes the start of appointment/ Start date if this is an all day appointment |
end_date* | datetime/ date |
Timestamp that denotes the end of appointment/ End date if this is an all day appointment |
time_zone | text | Timezone that the appointment is scheduled in |
title* | text | Title of the appointment |
description | text | Description of the appointment |
creater_id | number | ID of the user who created the appointment |
targetable_id | number | ID of contact/account against whom appointment has been created. |
targetable_type | text | String that denotes against which entity appointment has been created. Possible values are either "Contact" or "SalesAccount" or "Deal". |
location | text | Location of the appointment. |
created_at | datetime | Appointment creation timestamp |
updated_at | datetime | Appointment updated timestamp |
is_allday | boolean | Specifies if appoinment is an all day appointment or not, default value is false. It is a mandatory attribute for all day appointment. |
appointment_attendees_attributes | Array of Objects | All attendees associated to the appointment. |
outcome_idΩ | number | ID of outcome of Appointment sales activity type |
latitude | text | Latitude of the location when you check in for an appointment |
longitude | text | Longitude of the location when you check in for an appointment |
checkedin_at | datetime | Timestamp denoting the date and time of your check-in for an appointment |
* Mandatory fields for creating appointment. Ω To know all available options for this field, refer Configuration |
Create a Appointment
This API allows you to create an appointment.
/api/appointments
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"appointment":{"title":"Sample Appointment","description":"This is just a sample Appointment.","from_date":"Mon Jun 20 2016 10:30:00 GMT+0530 (IST)","end_date":"Mon Jun 20 2016 11:30:00 GMT+0530 (IST)","time_zone":"Chennai","location":"Chennai, TN, India","targetable_id":"115765","targetable_type":"Contact", "appointment_attendees_attributes":[{ "attendee_type":"FdMultitenant::User","attendee_id":"223"},{"attendee_type":"FdMultitenant::User","attendee_id":"222"},{"attendee_type":"Contact","attendee_id":"115773"}] }}' -X POST https://domain.myfreshworks.com/crm/sales/api/appointments |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 | { "appointment_attendees": [{ "id": 94648, "attendee": { "type": "user", "id": 223 } }, { "id": 94649, "attendee": { "type": "user", "id": 222 } }, { "id": 94650, "attendee": { "type": "contact", "id": 115773 } }], "users": [{ "id": 223, "display_name": "Sample User1", "avatar": null, "type": "FdMultitenant::User" }, { "id": 222, "display_name": "Sample User2", "avatar": null, "type": "FdMultitenant::User" }], "contacts": [{ "id": 115773, "display_name": "Jane Sampleton (sample)", "avatar": null, "type": "Contact" }], "appointment": { "id": 1, "time_zone": "Chennai", "title": "Sample Appointment", "description": "This is just a sample Appointment.", "location": "Chennai, TN, India", "from_date": "2016-06-20T05:00:00Z", "end_date": "2016-06-20T06:00:00Z", "latitude": "34.4208", "longitude": "119.6982", "appointment_attendee_ids": [ 94648, 94649, 94650 ] } } |
View an Appointment
This API allows you to view an appointment.
/api/appointments/[:appointment_id]
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET https://domain.myfreshworks.com/crm/sales/api/appointments/1 |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 | { "appointment_attendees": [{ "id": 94649, "attendee": { "type": "user", "id": 222 } }, { "id": 94648, "attendee": { "type": "user", "id": 223 } }, { "id": 94650, "attendee": { "type": "contact", "id": 115773 } }], "users": [{ "id": 222, "display_name": "Sample User2", "avatar": null, "type": "FdMultitenant::User" }, { "id": 223, "display_name": "Sample User1", "avatar": null, "type": "FdMultitenant::User" }], "contacts": [{ "id": 115773, "display_name": "Jane Sampleton (sample)", "avatar": null, "type": "Contact" }, { "id": 115765, "avatar": null, "display_name": "Eric Sampleton" }], "appointment": { "id": 1, "time_zone": "Chennai", "title": "Sample Appointment", "description": "This is just a sample Appointment.", "location": "Chennai, TN, India", "from_date": "2016-06-20T05:00:00Z", "end_date": "2016-06-20T06:00:00Z", "latitude": "34.4208", "longitude": "119.6982", "checkedin_at": "2019-01-22T23:27:56-08:00", "appointment_attendee_ids": [ 94649, 94648, 94650 ], "targetable": { "type": "contact", "id": 115765 }, "creater_id": 223 } } |
List All Appointments
Get filtered appointments
You can use this API to receive a list of filtered appointments i.e get your past and upcoming appointments./api/appointments?filter=[filter param]
- The parameter filter is mandatory.
- Only one filter is allowed at a time. Getting multiple filtered appointments is not possible. For example, you can’t get both past and upcoming appointments with a single request.
- Use 'include' to embed additional details in the response. Multiple values can be embedded in a single request separated by a comma(include=creater,targetable).
Embed | Handle |
---|---|
creater |
/api/appointments?filter=upcoming&include=creater Will return the Collaborators id, avatar, type and display_name |
targetable |
/api/appointments?filter=upcoming&include=targetable Will return the targetable’s id, avatar and display_name |
appointment_attendees | /api/appointments?filter=upcoming&include=appointment_attendees |
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET https://domain.myfreshworks.com/crm/sales/api/appointments?filter=upcoming&include=creater |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 | { "users": [{ "id": 1, "display_name": "Sales Agent", "email": "sample@myfreshworks.com/crm/sales" }], "appointments": [{ "id": 1, "time_zone": "Arizona", "title": "(Sample) Product Demo ", "description": "The Contact expressed interest to know more about the product. Giving her a demo.", "location": "Elite conference room", "from_date": "2016-07-20T10:00:00+05:30", "end_date": "2016-07-20T12:00:00+05:30", "creater_id": 1, "latitude":"34.4208", "longitude":"119.6982", "checkedin_at":"2019-01-22T23:27:56-08:00" }, { "id": 2, "time_zone": "Arizona", "title": "(Sample) Meeting - final discussion about the deal", "description": "Meeting James to resolve any concerns and close the deal.", "location": "Hilton Hotel, Bucks Road", "from_date": "2016-07-20T16:00:00+05:30", "end_date": "2016-07-20T18:00:00+05:30", "creater_id": 1, "latitude":null, "longitude":null, "checkedin_at":null }], "meta": { "total": 2 } } |
Update an Appointment
This API allows you to update an appointment.
/api/appointments/[:appointment_id]
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{ "appointment":{"title":"Updated Appointment","description":"This is just an updated version of sample Appointment.","from_date":"Tue Jun 21 2016 08:00:00 GMT+0530 (IST)", "end_date":"Tue Jun 21 2016 08:30:00 GMT+0530 (IST)", "time_zone":"Hawaii","location":"Hawaii", "targetable_id":"115765","targetable_type":"Contact", "appointment_attendees_attributes":[{"attendee_type":"FdMultitenant::User", "attendee_id":"222" },{ "attendee_type":"FdMultitenant::User","attendee_id":"223"}] }}' -X PUT https://domain.myfreshworks.com/crm/sales/api/appointments/1 |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 | { "appointment_attendees":[ { "id":94649, "attendee":{ "type":"user", "id":222 } }, { "id":94648, "attendee":{ "type":"user", "id":223 } }, { "id":94650, "attendee":{ "type":"contact", "id":115773 } } ], "users":[ { "id":222, "display_name":"Sample User2", "avatar":null, "type":"FdMultitenant::User" }, { "id":223, "display_name":"Sample User1", "avatar":null, "type":"FdMultitenant::User" } ], "contacts":[ { "id":115773, "display_name":"Jane Sampleton (sample)", "avatar":null, "type":"Contact" } ], "appointment":{ "id":1, "time_zone":"Hawaii", "title":"Updated Appointment", "description":"This is just an updated version of sample Appointment.", "location":"Hawaii", "from_date":"2016-06-21T02:30:00Z", "end_date":"2016-06-21T03:00:00Z", "latitude": "34.4208", "longitude": "119.6982", "appointment_attendee_ids":[ 94649, 94648, 94650 ] } } |
Delete an Appointment
This API allows you to delete an appointment.
/api/appointments/[:appointment_id]
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE https://domain.myfreshworks.com/crm/sales/api/appointments/1 |
Response
1 2 3 | { "success":"200" } |
Sales Activities
Sales activities are a great way to track activities related to a contact/deal/account. This comes in handy to get to know an entity's lifecycle
Attribute | Type | Description |
---|---|---|
id | number | Unique ID of the sales activity |
title* | text | Title of the sales activity |
sales_activity_type_id*Ω | number | ID of a sales activity type for which the sales activity has been created |
sales_activity_outcome_idΩ | number | ID of a sales activity's outcome |
start_date* | datetime | Timestamp that denotes the end of sales activity |
end_date* | datetime | Timestamp that denotes the end of sales activity |
notes | text | Description about the sales activity |
owner_id* | number | ID of the user who owns the sales activity |
targetable_id* | number | ID of the contact/deal/account related to the sales activity created |
targetable_type* | text | String that denotes the entity for which the sales activity has been created. Possible values are either "Contact" or "SalesAccount" or "Deal" |
creater_id | number | ID of the user who created the sales activity |
created_at | datetime | Sales activity creation timestamp |
updated_at | datetime | Sales activity updation timestamp |
location | text | Location of the sales activity |
latitude | text | Latitude of the location when you check in on a sales activity |
longitude | text | Longitude of the location when you check in for a sales activity |
checkedin_at | datetime | Timestamp denoting the date and time of your check-in for a sales activity |
* Mandatory fields for creating sales activity. Ω To know all available options for this field, refer Configuration |
Create a Sales activity
This API allows you to create a sales activity.
/api/sales_activities
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"sales_activity":{"title":"ticket","notes":"sample","targetable_id":"1","targetable_type":"Contact","start_date":"2017-12-04T17:00:00+05:30","end_date":"2017-12-04T17:30:00+05:30","owner_id":"1", "sales_activity_type_id":"2", "sales_activity_outcome_id":"1"}}' -X POST https://domain.myfreshworks.com/crm/sales/api/sales_activities |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | { "sales_activity":{ "id":1, "title":"testing", "start_date":"2017-12-04T17:00:00+05:30", "end_date":"2017-12-04T17:30:00+05:30", "sales_activity_type_id":2, "created_at":"2017-12-04T17:54:04+05:30", "updated_at":"2017-12-04T17:54:04+05:30", "notes":"sample", "owner_id":1, "sales_activity_outcome_id":1, "remote_id":null, "import_id":null, "creater_id":1, "updater_id":null, "conversation_time":"2017-12-04T17:00:00+05:30", "targetable_id":1, "targetable_type":"Contact", "latitude": "34.4208", "longitude": "119.6982", "location": "Santa Barbara" } } |
View a Sales activity
This API allows you to view a sales activity
/api/sales_activities/[:sales_activity_id]
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET https://domain.myfreshworks.com/crm/sales/api/sales_activities/1 |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | { "sales_activity":{ "id":1, "title":"testing", "start_date":"2017-12-11T14:15:00+05:30", "end_date":"2017-12-11T14:45:00+05:30", "sales_activity_type_id":2, "created_at":"2017-12-11T15:04:11+05:30", "updated_at":"2017-12-11T15:04:11+05:30", "notes":null, "owner_id":2, "sales_activity_outcome_id":null, "remote_id":null, "import_id":null, "creater_id":2, "updater_id":null, "conversation_time":"2017-12-11T14:15:00+05:30", "targetable_id":3, "targetable_type":"Contact", "latitude": "34.4208", "longitude": "119.6982", "location": "Santa Barbara", "checkedin_at": "2017-12-11T15:04:11+05:30" } } |
List All Sales activities
This API allows you to list all the sales activities
/api/sales_activities
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET https://domain.myfreshworks.com/crm/sales/api/sales_activities |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | { "sales_activities":[ { "id":1, "title":"testing", "start_date":"2017-12-11T14:15:00+05:30", "end_date":"2017-12-11T14:45:00+05:30", "sales_activity_type_id":2, "created_at":"2017-12-11T15:04:11+05:30", "updated_at":"2017-12-11T15:04:11+05:30", "notes":null, "owner_id":2, "sales_activity_outcome_id":null, "remote_id":null, "import_id":null, "creater_id":2, "updater_id":null, "conversation_time":"2017-12-11T14:15:00+05:30", "targetable_id":3, "targetable_type":"Contact", "latitude": "34.4208", "longitude": "119.6982", "location": "Santa Barbara", "checkedin_at": "2017-12-11T15:04:11+05:30" } ], "meta": { "total_pages":1, "total":1 } } |
Additional Examples
1. Get the first page of a list of sales activities.
If you’d like to get sales activities of first page, use this API.
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/sales_activities?page=1" |
2. Get 10 sales activities for one page.
If you’d like to list 10 sales activities for first page use this API.
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/sales_activities?per_page=10&page=1" |
Update a Sales activity
This API allows you to update a sales activity
/api/sales_activities/[:sales_activity_id]
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"sales_activity":{"title":"sample test","notes":"sample","targetable_id":"1","targetable_type":"Contact","owner_id":"2","sales_activity_type_id":"2", "sales_activity_outcome_id":"1"}}' -X PUT https://domain.myfreshworks.com/crm/sales/api/sales_activities/1 |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | { "sales_activity":{ "id":1, "title":"sample test", "start_date":"2017-12-04T17:00:00+05:30", "end_date":"2017-12-04T17:30:00+05:30", "sales_activity_type_id":2, "created_at":"2017-12-04T17:54:04+05:30", "updated_at":"2017-12-04T17:54:04+05:30", "notes":sample, "owner_id":2, "sales_activity_outcome_id":1, "remote_id":null, "import_id":null, "creater_id":1, "updater_id":null, "conversation_time":"2017-12-04T17:00:00+05:30", "targetable_id":1, "targetable_type":"Contact", "latitude": "34.4208", "longitude": "119.6982", "location": "Santa Barbara" } } |
Delete a Sales activity
This API allows you to delete a sales activity
/api/sales_activities/[:sales_activity_id]
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE https://domain.myfreshworks.com/crm/sales/api/sales_activities/1 |
Response
1 2 3 | { "success":"200" } |
Search
Using this API you can search for records by entering search queries of your choice. The results would include names or email addresses of records that match the search query.
/api/search?q=[query param]&include=[entities]
The parameters used are include and q. They are mandatory to perform a search. If they aren’t provided you’d receive an empty array as a response.
Use include to query against related entities. You can include multiple entities at once. Each result’s response would contain a ‘type’ key specifying the type of entity for identification.
Embed | Handle |
---|---|
user |
/api/search?q=[query param]&include=user
Will return the user id, name and email Type will be user |
contact |
/api/search?q=[query param]&include=contact
Will return the contact id, name, email and avatar(if exists) Type will be contact |
sales_account |
/api/search?q=[query param]&include=sales_account
Will return the sales_account id, name and avatar(if exists) Type will be sales_account |
deal |
/api/search?q=[query param]&include=deal
Will return the deal id and name Type will be deal |
Number of search results
The number of results displayed is 10 by default. You can change this limit using the 'per_page' parameter. But you can’t have more than 100 results displayed.Assume that you are searching for a key word called ‘sample’ in your contacts.
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET https://domain.myfreshworks.com/crm/sales/api/search?q=sample&include=contact&per_page=25 |
Response
1 2 3 4 5 6 7 | [{ "id": "1", "type": "contact", "name": "James Sampleton (sample)", "email": "jamessampleton@gmail.com", "avatar": "https://lh3.googleusercontent.com/-DbQggdfJ2_w/Vi4cRujEXKI/AAAAAAAAABs/-Byl2CFY3lI/w140-h140-p/Image3.png" }] |
Note:
If the search query or the include param value doesn’t match any entity, you’d receive an empty array as a response. (say you provide include=contacts instead of include=contact)
Filtered search
You can use filtered search to find records that are an exact match to the search query.
/api/filtered_search/contact
It can be used to find contacts or contacts with the same email address.
Number of search results
The number of results displayed is 10 by default. You can change this limit using the ‘per_page’ parameter. But you can’t have more than 100 results displayed.Here’s an example of filtered search on contacts.
Sample code | Curl
1 | curl -H 'Authorization: Token token=sfg999666t673t7t82' -H 'Content-Type:application/json' -X POST https://domain.myfreshworks.com/crm/sales/api/filtered_search/contact -d '{ "filter_rule" : [{"attribute" : "contact_email.email", "operator":"is_in", "value":"janesampleton@gmail.com"}] }' |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 | { "contacts": [{ "id": 1, "job_title": "Sales Manager", "lead_score": 99, "last_contacted_mode": "call_outgoing", "email": "janesampleton@gmail.com", "work_number": "(368) 493-2360", "mobile_number": "1-726-652-9503", "display_name": "Jane Sampleton (sample)", "avatar": "https://lh3.googleusercontent.com/-BomfmRA2WqA/Vi4cXSJzXPI/AAAAAAAAABg/LO4MyF96ZQ4/w140-h140-p/Image1.png", "company": { "id": 1, "name": "Widgetz.io (sample)" }, "last_contacted": "2016-07-06T06:05:51-07:00", "stage_updated_time": "2016-02-10T02:36:06-08:00", "first_name": "Jane", "last_name": "Sampleton (sample)", "city": "Glendale", "country": "USA", "created_at": "2016-02-04T02:36:05-08:00", "updated_at": "2016-05-31T03:33:41-07:00" }], "meta": { "total": 1 } } |
Sample empty response
1 2 3 4 5 6 | { "contacts": [], "meta": { "total": 0 } } |
Here’s an example of filtered search on contacts,
/api/filtered_search/contact
Sample code | Curl
1 | curl -H 'Authorization: Token token=sfg999666t673t7t82' -H 'Content-Type:application/json' -X POST https://domain.myfreshworks.com/crm/sales/api/filtered_search/contact -d '{ "filter_rule" : [{"attribute" : "contact_email.email", "operator":"is_in", "value":"jamessampleton@gmail.com"}] } |
Sample Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | { "contacts": [{ "partial": true, "id": 1, "job_title": "CEO", "lead_score": 49, "email": "jamessampleton@gmail.com", "work_number": "(473)-160-8261", "mobile_number": "1-926-555-9503", "open_deals_amount": "0.0", "display_name": "James Sampleton (sample)", "avatar": "https://lh3.googleusercontent.com/-DbQggdfJ2_w/Vi4cRujEXKI/AAAAAAAAABs/-Byl2CFY3lI/w140-h140-p/Image3.png", "last_contacted_mode": "email_outgoing", "last_contacted": "2016-02-08T02:36:07-08:00", "first_name": "James", "last_name": "Sampleton (sample)", "city": "San Diego", "country": "USA", "created_at": "2016-02-11T02:36:06-08:00", "updated_at": "2016-02-10T02:36:07-08:00" }], "meta": { "total": 1 } } |
Lookup Search
This API is used to search for the name or email address of records.
/api/lookup?q=[query param]&f=email&entities=contact
- The parameters entities, f and q are mandatory. (If they are not provided an empty array is given as a response).
- The request can be searched only on one field.
- This request only displays results that are an exact match to the search query. For eg: if a contact email is janesampleton@gmail.com and If the value is given as ‘janesample’ you will not get any results.
Use ‘entities’ to query against related entities. You can include multiple entities at once, provided the field is available in both entities or else you’d receive an error response.
Embed | Handle |
---|---|
contact | /api/lookup?q=[query param]&entities=contact |
sales_account | /api/lookup?q=[query param]&entities=sales_account |
deal | /api/lookup?q=[query param]&entities=deal |
Use ‘f’ to provide the field against which the entities have to be searched.
Entity | Fields supported |
---|---|
contact | name, email and custom fields of type "Text field", "Number", "Dropdown", "Radio button" |
sales_account | name and custom fields of type "Text field", "Number", "Dropdown", "Radio button" |
deal | name and custom fields of type "Text field", "Number", "Dropdown", "Radio button" |
So when f=email you can use multiple entities like,
/api/lookup?q=[query param]&f=email&entities=contact,contact
Using this query you can fetch all contacts and contacts with same email address.
In this query,
/api/lookup?q=[query param]&f=company_name&entities=contact,contact
you’d get an error response as company_name is not a contact field.
If you’d like to search the custom dropdown fields, you can do so by using their internal names. In the following example, cf_something is the internal name for a contact dropdown field.
/api/lookup?q=[query param]&f=cf_something&entities=contact
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET https://domain.myfreshworks.com/crm/sales/api/lookup?q=janesampleton@gmail.com&f=email&entities=contact |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 | { "contacts": { "contacts": [{ "id": 1, "job_title": "Sales Manager", "email": "janesampleton@gmail.com", "work_number": "(368) 493-2360", "mobile_number": "1-726-652-9503", "address": "604-5854 Beckford St.", "city": "Glendale", "state": "Arizona", "zipcode": "100652", "country": "USA", "time_zone": null, "display_name": "Jane Sampleton (sample)", "avatar": "https://lh3.googleusercontent.com/-BomfmRA2WqA/Vi4cXSJzXPI/AAAAAAAAABg/LO4MyF96ZQ4/w140-h140-p/Image1.png", "keyword": "B2B Success", "medium": "Blog", "last_seen": "2016-02-10T02:36:06-08:00", "last_contacted": "2016-07-06T06:05:51-07:00", "lead_score": 99, "stage_updated_time": "2016-02-10T02:36:06-08:00", "first_name": "Jane", "last_name": "Sampleton (sample)", "company": { "id": 1, "name": "Widgetz.io (sample)", "address": "160-6802 Aliquet Rd.", "city": "New Haven", "state": "Connecticut", "zipcode": "68089", "country": "United States", "number_of_employees": null, "annual_revenue": null, "website": "widgetz.io", "phone": "503-615-3947", "industry_type_id": 2492, "business_type_id": 354 }, "deal": null, "links": { "conversations": "/contacts/1/conversations?include=email_conversation_recipients%2Ctargetable%2Cphone_number%2Cphone_caller%2Cnote%2Cuser\u0026per_page=3", "activities": "/contacts/1/activities" }, "custom_field": { "cf_primary": true, "cf_tamper": null }, "updated_at": "2016-05-31T03:33:41-07:00", "facebook": null, "twitter": "https://twitter.com/janesampleton", "linkedin": "http://linkedin.com/pub/jane-sampleton/109/39/b0" }] } } |
Phone
Freshworks CRM has a robust built in phone that you can use to make and receive calls, log calls automatically and manually and add notes too. You can also create new contacts for anonymous phone numbers or associate the number with existing records.
ATTRIBUTE | TYPE | DESCRIPTION | |
---|---|---|---|
id | number | ||
call_direction | boolean | ||
targetable_type | text | ||
work_number | string | ||
mobile_number | string | ||
targetable_type | string | ||
first_name | text | ||
last_name | text | ||
outcome_idΩ | number | ID of outcome of Phone sales activity type | |
Ω To know all available options for this field, refer Configuration |
Phone Call Properties:
call_direction | Value |
---|---|
incoming | true |
outgoing | false |
Manual Call Log
Create a manual call log for an existing contact
You can use this API to create a manual call log and associate it with an existing contact./api/phone_calls
- The parameter call_direction is mandatory.
- You can also add a note to the contact or choose to skip it by removing the parameter note from the POST data.
- If you’re adding the parameter note in the POST data, then the description field is mandatory.
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"phone_call": { "call_direction": true, "targetable_type": "contact", "targetable": { "id": "1", "first_name": "Jane", "last_name": "Sampleton (sample)", "work_number ":"5304915427", "mobile_number ":"11919457004 " }, "note ": { "description": "Sample note"} }}' -X POST https://domain.myfreshworks.com/crm/sales/api/phone_calls |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | { "contacts": [{ "partial": true, "id": 1 }], "phone_numbers": [], "phone_callers": [], "notes": [{ "id": 4, "description": "Sample note", "created_at": "2016-09-12T08:23:43Z", "updated_at": "2016-09-12T08:23:43Z", "creater_id": 1, "targetable_id": 1 }], "user": [{ "id": 1, "display_name": "Sample User", "email": "sampleuser@yourcompany.com", "is_active": true }], "targetables": [{ "id": 1, "display_name": "Jane Sampleton (sample)", "email": "janesampleton@gmail.com" }], "phone_calls": { "id": 1, "call_duration": null, "call_direction": true, "recording_duration": null, "status": "incoming", "recording": null, "conversation_time": "2016-09-12T08:23:43Z", "cost": 0, "is_manual": true, "targetable": { "type": "contact", "id": 1 }, "phone_number_id": null, "phone_caller_id": null, "note_id": 4 } } |
Create a manual call log for a new contact
You can use this API to create a new contact and a manual call log which is then associated with the newly created contact./api/phone_calls
- The parameter call_direction is mandatory.
- You can also add a note to the contact or choose to skip it by removing the parameter note from the POST data.
- If you’re adding the parameter note in the POST data, then the description field is mandatory.
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d ' {"phone_call": {"call_direction": true, "targetable_type": "contact", "targetable": { "first_name": "Jane", "last_name": "Sampleton (sample)", "work_number":"5304915427", "mobile_number":"11919457004", "company": { "name": "api" }}, "note": { "description": "Sample note"}}}' -X POST https://domain.myfreshworks.com/crm/sales/api/phone_calls |
Sample empty response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 | { "contacts": [ { "partial": true, "id": 1 } ], "phone_numbers": [], "phone_callers": [], "notes": [ { "id": 4, "description": "Sample note", "created_at": "2016-09-12T08:23:43Z", "updated_at": "2016-09-12T08:23:43Z", "creater_id": 1, "targetable_id": 1 } ], "user": [ { "id": 1, "display_name": "Sample User", "email": "sampleuser@yourcompany.com", "is_active": true } ], "targetables": [ { "id": 1, "display_name": "Jane Sampleton (sample)", "email": "janesampleton@gmail.com" } ], "phone_calls": { "id": 1, "call_duration": null, "call_direction": true, "recording_duration": null, "status": "incoming", "recording": null, "conversation_time": "2016-09-12T08:23:43Z", "cost": 0, "is_manual": true, "targetable": { "type": "contact", "id": 1 }, "phone_number_id": null, "phone_caller_id": null, "note_id": 4 } } |
Create a manual call log for an existing contact
You can use this API to create a manual call log and associate it with an existing contact./api/phone_calls
- The parameter call_direction is mandatory.
- You can also add a note to the contact or choose to skip it by removing the parameter note from the POST data.
- If you’re adding the parameter note in the POST data, then the description field is mandatory.
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d ' {"phone_call": { "call_direction": true, "targetable_type": "contact", "targetable": { "id": "1", "first_name": "Jane", "last_name": "Sampleton (sample)", "work_number ":"5304915427", "mobile_number ":"11919457004 " }, "note ": { "description": "Sample note"} }}' -X POST https://domain.myfreshworks.com/crm/sales/api/phone_calls |
Sample Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | { "contacts": [{ "partial": true, "id": 1 }], "phone_numbers": [], "phone_callers": [], "notes": [{ "id": 4, "description": "Sample note ", "created_at": "2016-09-12T08:23:43Z", "updated_at": "2016-09-12T08:23:43Z", "creater_id": 1, "targetable_id": 1 }], "user": [{ "id": 1, "display_name": "Sample User", "email": "sampleuser@yourcompany.com", "is_active": true }], "targetables": [{ "id": 1, "display_name": "Jane Sampleton (sample)", "email": "janesampleton@gmail.com" }], "phone_calls": { "id": 1, "call_duration": null, "call_direction": true, "recording_duration": null, "status": "incoming", "recording": null, "conversation_time": "2016-09-12T08:23:43Z", "cost": 0, "is_manual": true, "targetable": { "type": "contact", "id": 1 }, "phone_number_id": null, "phone_caller_id": null, "note_id": 4 } } |
Create a manual call log for a new contact
You can use this API to create a new contact and a manual call log which is then associated with the newly created contact./api/phone_calls
- The parameter call_direction is mandatory.
- You can also add a note to the contact or choose to skip it by removing the parameter note from the POST data.
- If you’re adding the parameter note in the POST data, then the description field is mandatory.
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d ' {"phone_call": {"call_direction": true, "targetable_type": "contact", "targetable": { "first_name": "Jane", "last_name": "Sampleton (sample)", "work_number":"5304915427", "mobile_number":"11919457004"}, "note": { "description": "Sample note "}}}' -X POST https://domain.myfreshworks.com/crm/sales/api/phone_calls |
Sample Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 | { "contacts": [ { "partial": true, "id": 1 } ], "phone_numbers": [], "phone_callers": [], "notes": [ { "id": 4, "description": "Sample note", "created_at": "2016-09-12T08:23:43Z", "updated_at": "2016-09-12T08:23:43Z", "creater_id": 1, "targetable_id": 1 } ], "user": [ { "id": 1, "display_name": "Sample User", "email": "sampleuser@yourcompany.com", "is_active": true } ], "targetables": [ { "id": 1, "display_name": "Jane Sampleton (sample)", "email": "janesampleton@gmail.com" } ], "phone_calls": { "id": 1, "call_duration": null, "call_direction": true, "recording_duration": null, "status": "incoming", "recording": null, "conversation_time": "2016-09-12T08:23:43Z", "cost": 0, "is_manual": true, "targetable": { "type": "contact", "id": 1 }, "phone_number_id": null, "phone_caller_id": null, "note_id": 4 } } |
Create a manual call log for an existing sales account
You can use this API to create a manual call log and associate it with an existing account./api/phone_calls
- The parameter call_direction is mandatory.
- You can also add a note to the contact or choose to skip it by removing the parameter note from the POST data.
- If you’re adding the parameter note in the POST data, then the description field is mandatory.
Sample code | Curl
1 | curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d ' {"phone_call": {"call_direction": true, "targetable_type": "salesAccount", "targetable": { "id": "82", "name": "test", "phone": "5304915427" }, "note": { "description": "Sample contact notes "}}}' -X POST https://domain.myfreshworks.com/crm/sales/api/phone_calls |
Sample Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | { "sales_accounts": [{ "partial": true, "id": 1 }], "phone_numbers": [], "phone_callers": [], "notes": [{ "id": 4, "description": "Sample note ", "created_at": "2016-09-12T08:23:43Z", "updated_at": "2016-09-12T08:23:43Z", "creater_id": 1, "targetable_id": 1 }], "user": [{ "id": 1, "display_name": "Sample User", "email": "sampleuser@yourcompany.com", "is_active": true }], "targetables": [{ "id": 1, "display_name": "Jane Sampleton (sample)", "email": "janesampleton@gmail.com" }], "phone_calls": { "id": 1, "call_duration": null, "call_direction": true, "recording_duration": null, "status": "incoming", "recording": null, "conversation_time": "2016-09-12T08:23:43Z", "cost": 0, "is_manual": true, "targetable": { "type": "sales_account", "id": 1 }, "phone_number_id": null, "phone_caller_id": null, "note_id": 4 } } |
Files
Files can be attached to a contact, sales account or a deal in Freshworks CRM. Files are great way to keep track of and refer back to attachments related to a contact.
ATTRIBUTE | TYPE | DESCRIPTION |
---|---|---|
file* | File | File to be uploaded |
file_name | string | Name of the file to be uploaded, name of the file will be taken if this field is left blank |
is_shared | boolean | File will be shared if this field is true |
targetable_id* | number | ID of contact/sales account/deal against whom the link is created |
targetable_type* | string | String that denotes against which entity file link is created. Possible values are "Contact"/"SalesAccount"/"Deal" |
* Mandatory fields for creating file. |
Links
Links(url) of Files can be attached to a contact, sales account or a deal in Freshworks CRM. Files are great way to keep track of and refer back to attachments related to a contact.
ATTRIBUTE | TYPE | DESCRIPTION |
---|---|---|
url* | string | Url of the file |
name | string | Name of the file Link to be uploaded, the link will be replaced as the name if this field is left blank |
is_shared | boolean | File Link will be shared if this field is true |
targetable_id* | number | ID of contact/sales account/deal against whom the link is created |
targetable_type* | string | String that denotes against which entity file link is created. Possible values are "Contact"/"SalesAccount"/"Deal" |
* Mandatory fields for creating file link. |
Create a File
This API will help you upload and attach a file to a contact, sales account or a deal.
Note: Set Content-Type for the request as multipart/form-data in the request header
/api/documents
Sample code | Curl
1 | curl -X POST -H 'Authorization: Token token=sfg999666t673t7t82' -H 'Content-Type: multipart/form-data' -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' -F file=@/Users/user1/Downloads/download.jpeg -F file_name=nameForFile -F is_shared=true -F targetable_id=1 -F targetable_type=Contact -X POST "https://domain.myfreshworks.com/crm/sales/api/documents" |
Response
1 2 3 4 5 | { "id": 219, "msg": "File uploaded successfully", "url": "https://s3.amazonaws.com/cdn.freshsales-dev.com/1/documents/219/original/download.jpeg?AWSAccessKeyId=AKIAJ5VBQHE2V7NFOQ4A&Expires=1523858739&Signature=RQT7W98uXHRj0dOWDbImZ1oXl%2B0%3D" } |
Create a Link
This API will help you attach links of files to a contact, sales account or a deal.
/api/document_links
Sample code | Curl
1 | curl -X POST -H 'Authorization: Token token=sfg999666t673t7t82' -H 'Content-Type: application/json' -d '{"url":"https://docs.google.com/document/d/abcd123", "is_shared":false, "targetable_id":1, "targetable_type":"Contact", "name":"contact 1 doc" }' -X POST "https://domain.myfreshworks.com/crm/sales/api/document_links" |
Response
1 2 3 4 5 | { "id": 52, "msg": "File link added successfully", "url": "https://docs.google.com/document/d/abcd123" } |
List all Files and Links
This API will help you upload and attach a file to a contact, sales account or a deal.
/api/contacts/[id]/document_associations
Sample code | Curl
1 | curl -X GET -H 'Authorization: Token token=sfg999666t673t7t82' "https://domain.myfreshworks.com/crm/sales/api/contacts/1/document_associations" |
Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | { "users": [ { "id": 9, "display_name": "username", "email": "username@domain.com", "is_active": true, "work_number": "9876543210", "mobile_number": null } ], "documents": [ { "id": 11, "url": "https://s3.amazonaws.com/cdn.freshsales-dev.com/1/documents/114/original/uploadedFile.jpeg?AWSAccessKeyId=AKIAJ5VBQHE2V7NFOQ4A&Expires=1523860454&Signature=dh5W3dzjisy%2BqI94%2BZX92JrWgDo%3D", "name": "uploadedFile.jpeg", "is_shared": true, "content_file_size": 8393, "content_content_type": "image/jpeg", "content_updated_at": "2018-03-22T16:00:34+05:30", "content_file_size_readable": "8.2 KB", "created_at": "2018-03-22T16:00:34+05:30", "is_attached": false, "creater_id": 9 } ], "document_links": [ { "id": 5, "url": "https://docs.google.com/document/d/abcd123", "name": "fileLink", "is_shared": false, "created_at": "2018-03-22T17:49:27+05:30", "is_attached": false, "creater_id": 9 } ] } |