Overview

Freshsales 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.

Freshsale'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 Freshsales?

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. Inorder to authenticate you need to know your API key and Bundle alias

  1. Bundle alias

    You can have multiple CRM accounts in your Freshworks Org. To specify the CRM account to be used in the API, you need to know the bundle alias of the CRM account. To find your Bundle alias

    1. Click your profile picture and select Profile Settings.
    2. Click the API Settings tab.
    3. You can find your Bundle alias below your API key.

    All API URLs follow the following format

    <Bundle Alias>/api/<resource_name>

    https://widgetz.myfreshworks.com/crm/sales/api/contacts/144

    https://widgetz.freshworks.com/crm/sales/api/contacts/144

  2. API key

    Each user in Freshworks CRM is provided with a unique API key. To find your API key

    1. Click your profile picture and select Profile Settings.
    2. Click the API Settings tab.
    3. 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 Freshsale’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:

<Bundle Alias>/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
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/apicontacts/1?include=owner"
EXPAND ↓
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
	}
}
EXPAND ↓

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 Freshsales portal doesn't have corresponding feature enabled.
404 Requested Resource not Found This status code is returned when the request contains invalid ID/Freshsales 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 Freshsales, 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 Freshsales's side. Please email us your API script along with the response headers. We will reach you out to you and fix this ASAP.
301/302 HTTP Redirect This tells the client to perform an HTTP Redirect to a certain endpoint. This could mean that you are hitting a non-HTTPS endpoint. You can solve this issue by ensuring that your API client follows redirects. One example is here.
*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"
        }
}

Error Response Fields
Field Description
code HTTP error status code
message Description about the error.

Configuration

API Description
api/selector/owners Fetch all existing users' details in the Freshsales portal.
Will give id, name of the users
api/selector/territories Fetch all existing territories' details in the Freshsales portal.
Will give id, name of the territories
api/selector/deal_stages Fetch all existing deal stages' details in the Freshsales portal.
Will give id, name of the deal stages
api/selector/currencies Fetch all existing currency details in the Freshsales portal.
Will give id, currency code and other details of currencies
api/selector/deal_reasons Fetch all existing deal reasons' details in the Freshsales portal.
Will give id, name of the deal reasons
api/selector/deal_types Fetch all existing deal types' details in the Freshsales portal.
Will give id, name of the deal types
api/selector/lead_sources Fetch all existing lead sources' details in the Freshsales portal.
Will give id, name of the lead sources
api/selector/industry_types Fetch all existing industry types' details in the Freshsales portal.
Will give id, name of the industry types
api/selector/business_types Fetch all existing business types' details in the Freshsales portal.
Will give id, name of the business types
api/selector/campaigns Fetch all existing campaigns details' in the Freshsales portal.
Will give id, name of the campaigns
api/selector/deal_payment_statuses Fetch all existing deal payment statuses' details in the Freshsales portal.
Will give id, name of the deal payment statuses
api/selector/deal_products Fetch all existing deal products' details in the Freshsales portal.
Will give id, name of the deal products
api/selector/deal_pipelines Fetch all existing deal pipelines' details in the Freshsales portal.
Will give id, name of the deal pipelines
api/selector/deal_stages Fetch all existing deal stages' details of default pipeline in the Freshsales 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 Freshsales portal.
Will give id, name of the contact statuses.
api/selector/sales_activity_types Fetch all existing sales activity types' details in the Freshsales portal.
Will give id, name of the sales activity types.
api/selector/sales_activity_outcomes Fetch all existing sales activity outcomes' details in the Freshsales 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 Freshsales 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 Freshsales portal.
Will give id, name and contact statuses of the lifecycle stage.

Contacts

Contacts represent people you interact with as part of your business.

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∑ Array of hashes 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. We have 5 default options:
i. Newsletter (id : 2)
ii. Promotional (id : 3)
iii. Product updates (id : 4)
iv. Confrences & Events (id : 5)
v. Non-marketing emails from our company (id : 1)
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
facebook string Facebook username of the contact
twitter∑ string Twitter username of the contact
linkedin 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.

post
/api/contacts
Sample code | Curl
Copied Copy 
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"
EXPAND ↓
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
	}
}
EXPAND ↓

Additional Examples

1. Create a contact with custom fields
If you’d like to create a contact along with custom fields, use this API.

Copied Copy 
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"
EXPAND ↓

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.

Copied Copy 
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"
EXPAND ↓

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.

Copied Copy 
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"
EXPAND ↓

View a Contact

This API allows you to view the details of a contact.

get
/api/contacts/[id]

Use 'include' to embed additional details in the response.

Embed Handle
sales_activities api/contacts/[id]?include=sales_activities
Will return the sales activities associated with this contact
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
Copied Copy 
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"
EXPAND ↓
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
                }]
	}
}
EXPAND ↓

List All Contacts

If you’d like to fetch a list of contacts, use this API.

get
/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.

get
/api/contacts/filters

Filters API

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/contacts/filters"
EXPAND ↓
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"
	}]
}
EXPAND ↓

View API:

To fetch all contacts (view_id => 3 from the filters API)

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/contacts/view/3"
EXPAND ↓
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
	}
}
EXPAND ↓

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
You can sort the contacts in an ascending or descending order too by using the parameter sort_type and choosing between
  • asc
  • desc

Update a Contact

This API allows you to update the information of a contact.

put
/api/contacts/[id]
Sample code | Curl
Copied Copy 
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"
EXPAND ↓
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
	}
}
EXPAND ↓

Upsert a Contact

This API allows you to create or update a contact based on the unique identifier value provided. It searches for a record with the value mentioned and updates it if found, else it creates the record.

post
/api/contacts/upsert
ATTRIBUTE TYPE DESCRIPTION
unique_identifier∑ string Field based on which entity needs to be created or updated
contact hash Contact property data object
∑ This needs to be unique in the form. Along with this "id" parameter is also allowed.

Note:
1. Only "id" and unique fields in the form can be used to search for an entity (provided as unique_identifier value).
2. In case of duplicates, API will error out with a list of entity ids to be merged. Use this context to remove duplicates before proceeding.
3. "email" attribute is deprecated and not supported as unique identifier. Instead use "emails" attribute.
4. Response code will be 200 and 201 for updating entity and creating entity respectively.

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"unique_identifier":{"emails": "jamessampleton@gmail.com"}, "contact":{"first_name":"James", "last_name":"Sampleton (sample)"}}' -X POST "https://domain.myfreshworks.com/crm/sales/api/contacts/upsert"
EXPAND ↓
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": "jamessampleton@gmail.com",
		"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
	}
}
EXPAND ↓

Bulk Upsert Contact

This API allows you to create or update contacts in bulk.

post
/api/contacts/bulk_upsert
ATTRIBUTE TYPE DESCRIPTION
contacts Array of hashes Each of the hash values should be in this format:
{"unique_identifier_name": "unique_identifier_value", "data": {} }
data corresponds to contact property hash

Note:
1. Maximum of 10 concurrent in-progress Bulk-upsert API calls can be made from an account.
2. Maximum of 100 entities can be created or updated using a single bulk API request.
3. Exactly one (unique_identifier_name, unique_identifier_value) hash has to be provided per parameter.
4. Each of the upsert parameters in the batch request should abide by the validations on the unique identifier.
5. You can make use of Job Status API to track the status.

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"contacts":[{"emails": "jamessampleton@gmail.com", "data":{"first_name":"James", "last_name":"Sampleton (sample)"}}, {"id": "123", "data":{"first_name":"Steve"}}]}' -X POST "https://domain.myfreshworks.com/crm/sales/api/contacts/bulk_upsert"
EXPAND ↓
Response 
1
2
3
4
{
	"message": "Batch job b7b68d8f629336346f884006 initiated. Please track progress in the job_status_url",
        "job_status_url": "http://domain.myfreshworks.io/api/job_statuses/<job_id>"
}
EXPAND ↓

Bulk assign Owner

If you’d like to assign an owner to a list of contacts, use this API.

post
/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
Copied Copy 
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"
EXPAND ↓
Response 
1
2
3
4
5
6
7
{
	"contacts": [{
		"1": true
	}, {
		"2": true
	}]
}
EXPAND ↓

Clone a Contact

Using this API, you’d be able to clone contacts.

post
/api/contacts/[id]/clone
Sample code | Curl
Copied Copy 
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"
EXPAND ↓
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
	}
}
EXPAND ↓

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.

Copied Copy 
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'
EXPAND ↓

Delete a Contact

This API allows you to delete a contact.

delete
/api/contacts/[id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/contacts/1"
EXPAND ↓
Response 
1
true
EXPAND ↓

Forget a Contact

This API will allow you to hard delete a contact and all the associated data. Learn more about forget option here.

delete
/api/contacts/[id]/forget
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/contacts/1/forget"
EXPAND ↓
Response 
1
true
EXPAND ↓

Bulk Delete Contacts

If you’d like to delete contacts in bulk, use this API.

post
/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
Copied Copy 
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"
EXPAND ↓
Response 
1
2
3
4
5
6
7
{
	"contacts": [{
		"1": true
	}, {
		"2": true
	}]
}
EXPAND ↓

List All Contact Fields

If you’d like to view all the contact fields, use this API.

get
/api/settings/contacts/fields

If you’d like to view the contact fields along with the groups that they belong to, use,

get
/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
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/settings/contacts/fields"
EXPAND ↓
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
      },
      ...
    ]
}
EXPAND ↓

List all Activites

This API allows you to get the activities of a contact.

get
/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
Copied Copy 
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"
EXPAND ↓
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
	}]
}
EXPAND ↓

Marketing Lists

Marketing lists help you group contacts into lists that you can quickly invoke for marketing campaigns and bulk emailing.

ATTRIBUTE TYPE DESCRIPTION
Id∑ number Unique ID of the list
name* string Name of the Marketing List
* Mandatory field for creating list.
∑ This field is unique.

Create a List

This API allows you to create a marketing list.

post
/api/lists
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"name":"sample list"}' -X POST "https://domain.myfreshworks.com/crm/sales/api/lists"
EXPAND ↓
Response 
1
2
3
4
5
6
{
  "list": {
    "id": 1,
    "list_name": "sample list"
  }
}
EXPAND ↓

Fetch All Lists

This API allows you to fetch all the marketing lists created.

get
/api/lists
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/lists"
EXPAND ↓
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
{
    "lists": [
        {
            "id": 1,
            "name": "Sample list1"
        },
        {
            "id": 2,
            "name": "Sample list2"
        },
        {
            "id": 3,
            "name": "Sample list3"
        },
        {
            "id": 4,
            "name": "Sample list4"
        },
        {
            "id": 5,
            "name": "Sample list5"
        },
        {
            "id": 6,
            "name": "Sample list6"
        }
    ],
      "meta": {
        "total_pages": 1,
        "total": 6
    }
}
EXPAND ↓

Update a List

This API allows you to update a marketing list.

put
/api/lists/[id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"name":"updated list_name"}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/lists/1"
EXPAND ↓

Fetch All Contacts from the List

This API allows you to fetch all the contacts from a particular marketing list (identified by its unique ID).

get
/api/contacts/lists/[id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/contacts/lists/1"
EXPAND ↓
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
{
  "contacts": [
    {
      "id": 1,
      "first_name": "James",
      "last_name": "Sampleton",
      "display_name": "James Sampleton",
      "avatar": null,
      "job_title": null,
      "city": null,
      "state": null,
      "zipcode": null,
      "country": null,
      "email": "jamessampleton@gmail.com",
      "emails": [
      {
        "id": 1,
        "value": "jamessampleton@gmail.com",
        "is_primary": true,
        "label": null,
        "_destroy": false
      }
      ],
      "time_zone": null,
      "work_number": null,
      "mobile_number": null,
      "address": null,
      "last_seen": null,
      "lead_score": 0,
      "last_contacted": null,
      "open_deals_amount": "0.0",
      "won_deals_amount": "0.0",
      "last_contacted_sales_activity_mode": null,
      "custom_field": {},
      "created_at": "2022-07-27T12:02:15Z",
      "updated_at": "2022-08-08T05:33:53Z",
      "keyword": null,
      "medium": null,
      "last_contacted_mode": null,
      "recent_note": null,
      "won_deals_count": 0,
      "last_contacted_via_sales_activity": null,
      "completed_sales_sequences": null,
      "active_sales_sequences": null,
      "web_form_ids": null,
      "open_deals_count": 0,
      "last_assigned_at": "2022-07-27T12:02:14Z",
      "tags": [],
      "facebook": null,
      "twitter": null,
      "linkedin": null,
      "is_deleted": false,
      "team_user_ids": null,
      "external_id": null,
      "work_email": null,
      "subscription_status": 1,
      "subscription_types": "2;3;4;5;1",
      "customer_fit": 0,
      "record_type_id": "1000000074",
      "whatsapp_subscription_status": 2,
      "sms_subscription_status": 2,
      "last_seen_chat": null,
      "first_seen_chat": null,
      "locale": null,
      "total_sessions": null,
      "phone_numbers": []
    },
    {
      "id": 2,
      "first_name": "Jane",
      "last_name": "Sampleton (sample)",
      "display_name": "Jane Sampleton (sample)",
      "avatar": null,
      "job_title": null,
      "city": null,
      "state": null,
      "zipcode": null,
      "country": null,
      "email": "janesampleton@gmail.com",
      "emails": [
      {
        "id": 2,
        "value": "janesampleton@gmail.com",
        "is_primary": true,
        "label": "Other",
        "_destroy": false
      }
      ],
      "time_zone": null,
      "work_number": null,
      "mobile_number": "1234567890",
      "address": null,
      "last_seen": null,
      "lead_score": 0,
      "last_contacted": null,
      "open_deals_amount": "0.0",
      "won_deals_amount": "0.0",
      "last_contacted_sales_activity_mode": null,
      "custom_field": {},
      "created_at": "2022-08-01T07:47:42Z",
      "updated_at": "2022-08-08T08:45:33Z",
      "keyword": null,
      "medium": null,
      "last_contacted_mode": null,
      "recent_note": null,
      "won_deals_count": 0,
      "last_contacted_via_sales_activity": null,
      "completed_sales_sequences": null,
      "active_sales_sequences": null,
      "web_form_ids": null,
      "open_deals_count": 0,
      "last_assigned_at": "2022-08-01T07:47:41Z",
      "tags": [],
      "facebook": null,
      "twitter": null,
      "linkedin": null,
      "is_deleted": false,
      "team_user_ids": null,
      "external_id": null,
      "work_email": null,
      "subscription_status": 1,
      "subscription_types": "2;3;4;5;1",
      "customer_fit": 0,
      "record_type_id": "1000000074",
      "whatsapp_subscription_status": 2,
      "sms_subscription_status": 2,
      "last_seen_chat": null,
      "first_seen_chat": null,
      "locale": null,
      "total_sessions": null,
      "phone_numbers": []
    }
  ],
  "meta": {
    "total_pages": 1,
    "total": 2,
    "avatar_data": {
    "Contact": {
      "1": null,
      "2": null
    }
    }
  }
}
EXPAND ↓

Copy Contacts to List

This API allows you to copy one or more contacts from one marketing list to another.

put
/api/lists/[list_id]/add_contacts
ATTRIBUTE TYPE DESCRIPTION
ids[] Array of numbers An array of contact ids that you’d like to copy from one marketing list to another
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"ids":[1,2]}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/lists/1/add_contacts"
EXPAND ↓
Response 
1
2
3
{
    "message": "2 contacts updated."
  }
EXPAND ↓

Add Contacts to List

This API allows you to add one or more contacts to the selected marketing list.

put
/api/lists/[list_id]/add_contacts
ATTRIBUTE TYPE DESCRIPTION
ids[] Array of numbers An array of contact ids that you’d like to add to the selected marketing list
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"ids":[1,2]}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/lists/1/add_contacts"
EXPAND ↓
Response 
1
2
3
{
  "message": "2 contacts updated."
}
EXPAND ↓

Remove Contacts From List

This API allows you to remove one or more contacts from the selected marketing list.

put
/api/lists/[list_id]/remove_contacts
ATTRIBUTE TYPE DESCRIPTION
ids[] Array of numbers An array of contact ids that you’d like to remove from the selected marketing list
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"ids":[1,2]}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/lists/1/remove_contacts"
EXPAND ↓
Response 
1
2
3
{
  "message": "2 contacts updated."
}
EXPAND ↓

Additional Example

When an API is called with '{"all": true}' then all contacts in the marketing list will be removed.

Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"all": true}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/lists/1/remove_contacts"
EXPAND ↓

Move Contacts from list

This API allows you to move one or more contacts from one marketing list to another.

put
/api/lists/[list_id]/move_contacts
ATTRIBUTE TYPE DESCRIPTION
ids[] Array of numbers An array of contact ids that you’d like to move from one marketing list to another
from_list_id number id of the list from which you’d like to move
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"ids": [1,2], "from_list_id": 1}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/lists/2/move_contacts"
EXPAND ↓
Response 
1
2
3
{ 
  "message":"Updating now... we'll let you know once this is done."
}
EXPAND ↓

Additional Example

When an API is called only with '{"from_list_id": 1}' then all contacts in the marketing list will be moved.

Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"from_list_id": 1}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/lists/2/move_contacts"
EXPAND ↓

Accounts

Companies with whom you have an existing business relationship are saved as Accounts in Freshsales. 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
facebook string Facebook username of the account
twitter string Twitter username of the account
linkedin 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.

post
/api/sales_accounts
Sample code | Curl
Copied Copy 
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"
EXPAND ↓
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
	}
}
EXPAND ↓

Create an account with custom fields

If you’d like to create an account along with custom fields, use this API.

Sample code | Curl
Copied Copy 
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"
EXPAND ↓

Create an account by associating it to a new parent account

Sample code | Curl
Copied Copy 
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"
EXPAND ↓

View an Account

This API allows you to view the details of an account.

get
/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
Copied Copy 
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"
EXPAND ↓
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
	}
}
EXPAND ↓

List All Accounts

If you’d like to fetch a list of accounts, use this API.

get
/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.

get
/api/sales_accounts/filters

Filters API

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/sales_accounts/filters"
EXPAND ↓
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"
      }
   ]
}
EXPAND ↓

View API

Sample code | Curl
Copied Copy 
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"
EXPAND ↓
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
	}
}
EXPAND ↓

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
You can sort the accounts in an ascending or descending order too by using the parameter sort_type and choosing between
  • asc
  • desc

Update an Account

This API allows you to update the information of an account.

put
/api/sales_accounts/[id]
Sample code | Curl
Copied Copy 
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"
EXPAND ↓
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
	}
}
EXPAND ↓

Upsert an Account

This API allows you to create or update a sales_account based on the unique identifier value provided. It searches for a record with the value mentioned and updates it if found, else it creates the record.

post
/api/sales_accounts/upsert
ATTRIBUTE TYPE DESCRIPTION
unique_identifier∑ string Field based on which entity needs to be created or updated
sales_account hash sales_account property data object
∑ This needs to be unique in the form. Along with this "id" parameter is also allowed.

Note:
1. Only "id" and unique fields in the form can be used to search for an entity (provided as unique_identifier value).
2. In case of duplicates, API will error out with a list of entity ids to be merged. Use this context to remove duplicates before proceeding.
3. "email" attribute is deprecated and not supported as unique identifier. Instead use "emails" attribute.
4. Response code will be 200 and 201 for updating entity and creating entity respectively.

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"unique_identifier":{"name": "Widgetz.io"}, "sales_account":{"city":"Sample city"}}' -X POST "https://domain.myfreshworks.com/crm/sales/api/sales_accounts/upsert"
EXPAND ↓
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": "Sample city",
		"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
	}
}
EXPAND ↓

Bulk Upsert Account

This API allows you to create or update sales_accounts in bulk.

post
/api/sales_accounts/bulk_upsert
ATTRIBUTE TYPE DESCRIPTION
sales_accounts Array of hashes Each of the hash values should be in this format:
{"unique_identifier_name": "unique_identifier_value", "data": {} }
data corresponds to sales_account property hash

Note:
1. Maximum of 10 concurrent in-progress Bulk-upsert API calls can be made from an account.
2. Maximum of 100 entities can be created or updated using a single bulk API request.
3. Exactly one (unique_identifier_name, unique_identifier_value) hash has to be provided per parameter.
4. Each of the upsert parameters in the batch request should abide by the validations on the unique identifier.
5. You can make use of Job Status API to track the status.

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"sales_accounts":[{"name": "Account Name", "data":{"city": "City_1"}}, {"id": "123", "data":{"city":"City_2"}}]}' -X POST "https://domain.myfreshworks.com/crm/sales/api/sales_accounts/bulk_upsert"
EXPAND ↓
Response 
1
2
3
4
{
	"message": "Batch job b7b68d8f629336346f884006 initiated. Please track progress in the job_status_url",
        "job_status_url": "http://domain.myfreshworks.io/api/job_statuses/<job_id>"
}
EXPAND ↓

Clone an Account

Using this API, you’d be able to clone accounts.

post
/api/sales_accounts/[id]/clone
Sample code | Curl
Copied Copy 
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"
EXPAND ↓
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
	}
}
EXPAND ↓

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.

Copied Copy 
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'
EXPAND ↓

Delete an Account

This API allows you to delete an account.

delete
/api/sales_accounts/[id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/sales_accounts/1"
EXPAND ↓
Response 
1
true
EXPAND ↓

Additional Examples

If you’d like to delete an account along with the associated contacts and open deals, use this API.

Copied Copy 
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"
EXPAND ↓

Forget an Account

This API will allow you to hard delete an account and all the associated data. Learn more about forget option here.

delete
/api/sales_accounts/[id]/forget
Sample code | Curl
Copied Copy 
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"
EXPAND ↓
Response 
1
true
EXPAND ↓

Bulk Delete Accounts

If you’d like to delete accounts in bulk, use this API.

post
/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
Copied Copy 
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"
EXPAND ↓
Response 
1
2
3
4
5
6
7
{
	"sales_accounts": [{
		"1": true
	}, {
		"2": true
	}]
}
EXPAND ↓

Additional Examples

If you’d like to delete an account along with the associated contacts and open deals, use this API.

Copied Copy 
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"
EXPAND ↓

List All Account Fields

If you’d like to view all the account fields, use this API.

get
/api/settings/sales_accounts/fields

If you'd like to view account fields along with the groups that they belong to, use,

get
/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
Copied Copy 
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"
EXPAND ↓
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
	},
	...
	]
}
EXPAND ↓

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.

post
/api/deals
Sample code | Curl
Copied Copy 
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"
EXPAND ↓
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
	}
}
EXPAND ↓

Additional Examples

1. Create a deal with custom fields
If you’d like to create a deal along with custom fields, use this API.

Copied Copy 
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"
EXPAND ↓

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.

Copied Copy 
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"
EXPAND ↓

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.

Copied Copy 
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"
EXPAND ↓

View a Deal

This API allows you to view the details of a deal.

get
/api/deals/[id]

Use 'include' to embed additional details in the response.

Embed Handle
sales_activities api/deals/[id]?include=sales_activities
Will return the sales activities associated with this deal
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
Copied Copy 
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"
EXPAND ↓
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
	}
}
EXPAND ↓

List All Deals

If you’d like to fetch a list of deals, use this API.

get
/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.

get
/api/deals/filters

Filters API:

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/deals/filters"
EXPAND ↓
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"
		}

	]
}
EXPAND ↓

View API

To fetch all deals (view_id => 4 from the filters API)

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/deals/view/4"
EXPAND ↓
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
	}
}
EXPAND ↓

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
You can sort the deals in an ascending or descending order too using the parameter sort_type and choosing between
  • asc
  • desc

Update a Deal

This API allows you to update the information of a deal.

put
/api/deals/[id]
Sample code | Curl
Copied Copy 
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"
EXPAND ↓
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
	}
}
EXPAND ↓

Upsert a Deal

This API allows you to create or update a deal based on the unique identifier value provided. It searches for a record with the value mentioned and updates it if found, else it creates the record.

post
/api/deals/upsert
ATTRIBUTE TYPE DESCRIPTION
unique_identifier∑ string Field based on which entity needs to be created or updated
deal hash deal property data object
∑ This needs to be unique in the form. Along with this "id" parameter is also allowed.

Note:
1. Only "id" and unique fields in the form can be used to search for an entity (provided as unique_identifier value).
2. In case of duplicates, API will error out with a list of entity ids to be merged. Use this context to remove duplicates before proceeding.
3. "email" attribute is deprecated and not supported as unique identifier. Instead use "emails" attribute.
4. Response code will be 200 and 201 for updating entity and creating entity respectively.

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"unique_identifier":{"name": "Sample deal"}, "deal":{"amount":"23456.0"}}' -X POST "https://domain.myfreshworks.com/crm/sales/api/deals/upsert"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
	"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
	}
}
EXPAND ↓

Bulk Upsert Deal

This API allows you to create or update deals in bulk.

post
/api/deals/bulk_upsert
ATTRIBUTE TYPE DESCRIPTION
deals Array of hashes Each of the hash values should be in this format:
{"unique_identifier_name": "unique_identifier_value", "data": {} }
data corresponds to deal property hash

Note:
1. Maximum of 10 concurrent in-progress Bulk-upsert API calls can be made from an account.
2. Maximum of 100 entities can be created or updated using a single bulk API request.
3. Exactly one (unique_identifier_name, unique_identifier_value) hash has to be provided per parameter.
4. Each of the upsert parameters in the batch request should abide by the validations on the unique identifier.
5. You can make use of Job Status API to track the status.

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"deals":[{"name": "Account Name", "data":{"amount": "1000"}}, {"id": "123", "data":{"amount":"2000"}}]}' -X POST "https://domain.myfreshworks.com/crm/sales/api/deals/bulk_upsert"
EXPAND ↓
Response 
1
2
3
4
{
	"message": "Batch job b7b68d8f629336346f884006 initiated. Please track progress in the job_status_url",
        "job_status_url": "http://domain.myfreshworks.io/api/job_statuses/<job_id>"
}
EXPAND ↓

Clone a Deal

Using this API, you’d be able to clone deals.

post
/api/deals/[id]/clone
Sample code | Curl
Copied Copy 
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"
EXPAND ↓
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
	}
}
EXPAND ↓

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.

Copied Copy 
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'
EXPAND ↓

Delete a Deal

This API allows you to delete a deal.

delete
/api/deals/[id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/deals/1"
EXPAND ↓
Response 
1
true
EXPAND ↓

Forget a Deal

This API will allow you to hard delete a deal and all the associated data. Learn more about forget option here.

delete
/api/deals/[id]/forget
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/deals/1/forget"
EXPAND ↓
Response 
1
true
EXPAND ↓

Bulk Delete Deals

If you’d like to delete deals in bulk, use this API.

post
/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
Copied Copy 
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"
EXPAND ↓
Response 
1
2
3
4
5
6
7
{
	"deals": [{
		"1": true
	}, {
		"2": true
	}]
}
EXPAND ↓

List All Deal Fields

If you’d like to view all the deal fields, use this API.

get
/api/settings/deals/fields

If you’d like to view the deal fields along with the groups that they belong to, use,

get
/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
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/settings/deals/fields"
EXPAND ↓
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
	},
	...
	]
}
EXPAND ↓

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.

post
/api/notes

Create a note for a Contact

Sample code | Curl
Copied Copy 
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"
EXPAND ↓
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"
	}
}
EXPAND ↓

Create a note for a Contact

Sample code | Curl
Copied Copy 
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"
EXPAND ↓
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"
	}
}
EXPAND ↓
Create a Note for an Account
Sample code | Curl
Copied Copy 
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
EXPAND ↓
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"
	}
}
EXPAND ↓
Create a Note for a Deal
Sample code | Curl
Copied Copy 
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
EXPAND ↓
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"
	}
}
EXPAND ↓

Update a note

This API allows you to update a note.

put
/api/notes/[id]

Update a note for a Contact

Sample code | Curl
Copied Copy 
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"
EXPAND ↓
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"
	}
}
EXPAND ↓

Update a note for a Contact

Sample code | Curl
Copied Copy 
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"
EXPAND ↓
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"
	}
}
EXPAND ↓
Update a note for an Account
Sample code | Curl
Copied Copy 
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"
EXPAND ↓
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"
	}
}
EXPAND ↓

Delete a note

This API allows you to delete a note.

delete
/api/notes/[id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/notes/1"
EXPAND ↓
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"
	}
}
EXPAND ↓

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

post
/api/tasks
Sample code | Curl
Copied Copy 
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"
EXPAND ↓
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
   }
}
EXPAND ↓

View a Task

This API allows you to view the details of a task.

get
/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
Copied Copy 
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"
EXPAND ↓
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
		}
	}
}
EXPAND ↓

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.

get
/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
Copied Copy 
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
EXPAND ↓
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
	}
}
EXPAND ↓

Update a Task

This API allows you to update a task.

put
/api/tasks/[:task_id]
Sample code | Curl
Copied Copy 
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
EXPAND ↓
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]
	}
}
EXPAND ↓

Mark Task as Done

This API allows you to mark a task as done.

put
/api/tasks/[:task_id]
Sample code | Curl
Copied Copy 
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
EXPAND ↓
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]
	}
}
EXPAND ↓

Delete Task

This API allows you to delete a task.

delete
/api/tasks/[:task_id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE https://domain.myfreshworks.com/crm/sales/api/tasks/1
EXPAND ↓
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
	}
}
EXPAND ↓

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.

POST
/api/appointments
Sample code | Curl
Copied Copy 
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
EXPAND ↓
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
		]
	}
}
EXPAND ↓

View an Appointment

This API allows you to view an appointment.

get
/api/appointments/[:appointment_id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET https://domain.myfreshworks.com/crm/sales/api/appointments/1
EXPAND ↓
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
	}
}
EXPAND ↓

List All Appointments

Get filtered appointments
You can use this API to receive a list of filtered appointments. Use open/overdue/complete in the filter parameter. For example, to filter by upcoming appointments, use 'open'.

get
/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=open&include=creater
Will return the Collaborators id, avatar, type and display_name
targetable /api/appointments?filter=open&include=targetable
Will return the targetable’s id, avatar and display_name
appointment_attendees /api/appointments?filter=open&include=appointment_attendees
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET https://domain.myfreshworks.com/crm/sales/api/appointments?filter=open&include=creater
EXPAND ↓
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
	}
}
EXPAND ↓

Update an Appointment

This API allows you to update an appointment.

PUT
/api/appointments/[:appointment_id]
Sample code | Curl
Copied Copy 
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
EXPAND ↓
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
      ]
   }
}
EXPAND ↓

Delete an Appointment

This API allows you to delete an appointment.

delete
/api/appointments/[:appointment_id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE https://domain.myfreshworks.com/crm/sales/api/appointments/1
EXPAND ↓
Response 
1
2
3
{
  "success":"200"
}
EXPAND ↓

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.

POST
/api/sales_activities
Sample code | Curl
Copied Copy 
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
EXPAND ↓
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"
  }
}
EXPAND ↓

Additional Examples

1. Create a sales activity with custom fields
If you’d like to create a sales activity along with custom fields, use this API.

Copied Copy 
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","custom_field": {"cf_customer_option": true}}}' -X POST https://domain.myfreshworks.com/crm/sales/api/sales_activities
EXPAND ↓

View a Sales activity

This API allows you to view a sales activity

get
/api/sales_activities/[:sales_activity_id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET https://domain.myfreshworks.com/crm/sales/api/sales_activities/1
EXPAND ↓
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
{
   "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",
      "custom_field": {
        "cf_customer_option": true
     }
   }
}
EXPAND ↓

List All Sales activities

This API allows you to list all the sales activities

get
/api/sales_activities
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET https://domain.myfreshworks.com/crm/sales/api/sales_activities
EXPAND ↓
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
{
   "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",
         "custom_field": {
            "cf_customer_option": true
         }
      }
   ],
   "meta": {
      "total_pages":1,
      "total":1
   }
}
EXPAND ↓

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.

Copied Copy 
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"
EXPAND ↓

2. Get 10 sales activities for one page.
If you’d like to list 10 sales activities for first page use this API.

Copied Copy 
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"
EXPAND ↓

List All Sales Activity Fields

This API allows you to view the list of sales activity fields

get
/api/settings/sales_activities/fields

This API allows you to view the list of sales activity fields along with their groups they belong

get
/api/settings/sales_activities/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
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET https://domain.myfreshworks.com/crm/sales/api/settings/sales_activities/fields
EXPAND ↓
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
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
{
  "fields": [
    {
      "id": 1,
      "label": "Title",
      "name": "title",
      "type": "text",
      "default": true,
      "actionable": true,
      "position": 1,
      "choices": [],
      "base_model": "SalesActivity",
      "required": true,
      "quick_add_position": 1,
      "visible": true
    },
    {
      "id": 2,
      "label": "Start date",
      "name": "start_date",
      "type": "date_time_split",
      "default": true,
      "actionable": true,
      "position": 2,
      "choices": [],
      "base_model": "SalesActivity",
      "required": true,
      "quick_add_position": 2,
      "visible": true
    },
    {
      "id": 3,
      "label": "End date",
      "name": "end_date",
      "type": "date_time_split",
      "default": true,
      "actionable": true,
      "position": 3,
      "choices": [],
      "base_model": "SalesActivity",
      "required": true,
      "quick_add_position": 3,
      "visible": true
    },
    {
      "id": 4,
      "label": "Related to",
      "name": "targetable",
      "type": "auto_complete",
      "default": true,
      "actionable": true,
      "position": 4,
      "choices": [],
      "base_model": "SalesActivity",
      "required": true,
      "quick_add_position": 4,
      "visible": true,
      "auto_suggest_url": "/search?per_page=5&include=lead,contact,sales_account,deal&q="
    },
    {
      "id": 5,
      "label": "Owner",
      "name": "owner_id",
      "type": "dropdown",
      "default": true,
      "actionable": true,
      "position": 5,
      "choices": [
        {
          "id": 126574,
          "value": "Mohit Agrawal",
          "position": 1,
          "is_active": true,
          "deal_pipeline_id": 98090
        },
        {
          "id": 126598,
          "value": "Suresh Gajendran",
          "position": 2,
          "is_active": true,
          "deal_pipeline_id": 98090
        },
        {
          "id": 126610,
          "value": "Venkatesan Deivasigamani",
          "position": 3,
          "is_active": true,
          "deal_pipeline_id": 98090
        },
        {
          "id": 139942,
          "value": "Jaithoonnisha Asifali",
          "position": 4,
          "is_active": true,
          "deal_pipeline_id": 98090
        },
        {
          "id": 140012,
          "value": "Karthik Rajkumar",
          "position": 5,
          "is_active": true,
          "deal_pipeline_id": 98090
        }
      ],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": 5,
      "visible": true
    },
    {
      "id": 6,
      "label": "Notes",
      "name": "notes",
      "type": "textarea",
      "default": true,
      "actionable": true,
      "position": 6,
      "choices": [],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": 6,
      "visible": true
    },
    {
      "id": 7,
      "label": "Sales activity type",
      "name": "sales_activity_type_id",
      "type": "dropdown",
      "default": true,
      "actionable": true,
      "position": 1,
      "choices": [
        {
          "id": 569025,
          "value": "Facebook sync up",
          "position": 1,
          "choice_type": 2
        },
        {
          "id": 528967,
          "value": "Coffee",
          "position": 2,
          "choice_type": 2
        }
      ],
      "base_model": "SalesActivity",
      "required": true,
      "quick_add_position": 8,
      "visible": true
    },
    {
      "id": 8,
      "label": "Location",
      "name": "location",
      "type": "text",
      "default": true,
      "actionable": true,
      "position": 1,
      "choices": [],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": null,
      "visible": true
    },
    {
      "id": 9,
      "label": "Checked in time",
      "name": "checkedin_at",
      "type": "date",
      "default": true,
      "actionable": true,
      "position": 2,
      "choices": [],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": null,
      "visible": true
    },
    {
      "id": 10,
      "label": "Checked out location",
      "name": "checkedout_location",
      "type": "text",
      "default": true,
      "actionable": true,
      "position": 3,
      "choices": [],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": null,
      "visible": true
    },
    {
      "id": 11,
      "label": "Checked out time",
      "name": "checkedout_at",
      "type": "date",
      "default": true,
      "actionable": true,
      "position": 4,
      "choices": [],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": null,
      "visible": true
    },
    {
      "id": 12,
      "label": "Time spent (in seconds)",
      "name": "checkedin_duration",
      "type": "number",
      "default": true,
      "actionable": true,
      "position": 5,
      "choices": [],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": null,
      "visible": true
    },
    {
      "id": 13,
      "label": "Mark as completed",
      "name": "status",
      "type": "checkbox",
      "default": true,
      "actionable": true,
      "position": 6,
      "choices": [
        {
          "id": "1007865561",
          "value": "true",
          "position": 1
        },
        {
          "id": "1007865562",
          "value": "false",
          "position": 2
        }
      ],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": null,
      "visible": true
    },
    {
      "id": 14,
      "label": "Completed date",
      "name": "completed_date",
      "type": "date_time_split",
      "default": true,
      "actionable": true,
      "position": 1,
      "choices": [],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": null,
      "visible": true
    },
    {
      "id": 15,
      "label": "Outcome",
      "name": "sales_activity_outcome_id",
      "type": "dropdown",
      "default": true,
      "actionable": true,
      "position": 7,
      "choices": [
        {
          "id": 2415997,
          "value": "Left message",
          "position": 1,
          "choice_type": 2
        },
        {
          "id": 3512941,
          "value": "6",
          "position": 1,
          "choice_type": 2
        },
        {
          "id": 3512942,
          "value": "5",
          "position": 2,
          "choice_type": 2
        },
        {
          "id": 2415998,
          "value": "No response",
          "position": 2,
          "choice_type": 2
        },
        {
          "id": 2415999,
          "value": "Not able to reach",
          "position": 3,
          "choice_type": 2
        },
        {
          "id": 3512943,
          "value": "6",
          "position": 3,
          "choice_type": 2
        },
        {
          "id": 2416000,
          "value": "Not interested",
          "position": 4,
          "choice_type": 2
        },
        {
          "id": 2415996,
          "value": "Interested",
          "position": 5,
          "choice_type": 2
        },
        {
          "id": 3512944,
          "value": "test",
          "position": 6,
          "choice_type": 2
        },
        {
          "id": 3512945,
          "value": "test",
          "position": 7,
          "choice_type": 2
        }
      ],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": null,
      "visible": true
    },
    {
      "id": 16,
      "label": "tf3",
      "name": "cf_tf3",
      "type": "text",
      "default": false,
      "actionable": true,
      "position": 2,
      "choices": [],
      "base_model": "SalesActivity",
      "required": true,
      "quick_add_position": 17,
      "visible": true
    },
    {
      "id": 18,
      "label": "ta1",
      "name": "cf_ta1",
      "type": "textarea",
      "default": false,
      "actionable": true,
      "position": 4,
      "choices": [],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": null,
      "visible": true
    },
    {
      "id": 23,
      "label": "num1",
      "name": "cf_num1",
      "type": "number",
      "default": false,
      "actionable": true,
      "position": 9,
      "choices": [],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": null,
      "visible": true
    },
    {
      "id": 28,
      "label": "dd1",
      "name": "cf_dd1",
      "type": "dropdown",
      "default": false,
      "actionable": true,
      "position": 14,
      "choices": [
        {
          "id": 9,
          "value": "11",
          "position": 1
        },
        {
          "id": 234,
          "value": "12",
          "position": 2
        }
      ],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": null,
      "visible": true
    },
    {
      "id": 29,
      "label": "chk1",
      "name": "cf_chk1",
      "type": "checkbox",
      "default": false,
      "actionable": true,
      "position": 15,
      "choices": [],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": null,
      "visible": true
    },
    {
      "id": 30,
      "label": "rad1",
      "name": "cf_rad1",
      "type": "radio",
      "default": false,
      "actionable": true,
      "position": 16,
      "choices": [
        {
          "id": 823,
          "value": "11",
          "position": 1
        },
        {
          "id": 100,
          "value": "12",
          "position": 2
        }
      ],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": null,
      "visible": true
    },
    {
      "id": 31,
      "label": "dat1",
      "name": "cf_dat1",
      "type": "date",
      "default": false,
      "actionable": true,
      "position": 17,
      "choices": [],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": null,
      "visible": true
    },
    {
      "id": 32,
      "label": "lu1",
      "name": "cf_lu1",
      "type": "auto_complete",
      "default": false,
      "actionable": true,
      "position": 18,
      "choices": [],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": null,
      "visible": true,
      "auto_suggest_url": "/search.json?include=cm_test_import&q="
    },
    {
      "id": 33,
      "label": "mu1",
      "name": "cf_mu1",
      "type": "multi_select_dropdown",
      "default": false,
      "actionable": true,
      "position": 19,
      "choices": [
        {
          "id": 999,
          "value": "2",
          "position": 1
        },
        {
          "id": 1988,
          "value": "e2",
          "position": 2
        }
      ],
      "base_model": "SalesActivity",
      "required": false,
      "quick_add_position": null,
      "visible": true
    }
  ]
}
EXPAND ↓

Update a Sales activity

This API allows you to update a sales activity

PUT
/api/sales_activities/[:sales_activity_id]
Sample code | Curl
Copied Copy 
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
EXPAND ↓
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
{
   "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",
      "custom_field": {
        "cf_customer_option": true
     }
   }
}
EXPAND ↓

Delete a Sales activity

This API allows you to delete a sales activity

delete
/api/sales_activities/[:sales_activity_id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE https://domain.myfreshworks.com/crm/sales/api/sales_activities/1
EXPAND ↓
Response 
1
2
3
{
  "success":"200"
}
EXPAND ↓

Phone

Freshsales 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.

post
/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
Copied Copy 
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
EXPAND ↓
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
	}
}
EXPAND ↓

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.

post
/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
Copied Copy 
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
EXPAND ↓
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
  }
}
EXPAND ↓

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.

post
/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
Copied Copy 
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
EXPAND ↓
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
	}
}
EXPAND ↓

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.

post
/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
Copied Copy 
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
EXPAND ↓
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
  }
}
EXPAND ↓

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.

post
/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
Copied Copy 
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
EXPAND ↓
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
	}
}
EXPAND ↓

Products

Products represent an entity you sell. You can associate them with deals to turn them into sales opportunities.

ATTRIBUTE TYPE DESCRIPTION
id∑ number Unique ID of the product
name*∑ string Name of the product
description string Description about the product
category string Category of the product. Value should be from one of the configured choices of category fields in the products form.
is_active boolean Denotes whether a product can be associated with the deal
product_code string Code of the product
sku_number string SKU ID of the product
owner_id number ID of the user to whom the product has been assigned
valid_till datetime Timestamp that denotes the validity of the product
parent_product number ID of the parent product
created_at datetime Product creation timestamp
updated_at datetime Product updated timestamp
* Mandatory fields for creating a product
∑ This field is unique

Create a Product

This API allows you to create a product.

post
/api/cpq/products
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"product":{"name":"Sample Product","description":"This is a sample product","category":"Software","is_active":true,"parent_product":1,"product_code":"sample_product","sku_number":"sample_sku","valid_till":"Sat Nov 06 2021 00:00:00 GMT+0500","owner_id":3}}' -X POST "https://domain.myfreshworks.com/crm/sales/api/cpq/products"
EXPAND ↓
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
{
  "product": {
    "id": 1,
    "name": "Sample Product",
    "category": "Software",
    "product_code": "sample_product",
    "sku_number": "sample_sku",
    "parent_product": 1,
    "territory_id": null,
    "valid_till": "2021-11-06T13:47:13+05:00",
    "is_active": true,
    "owner_id": 3,
    "is_deleted": false,
    "created_at": "2021-10-06T14:01:27+05:00",
    "updated_at": "2021-10-06T14:01:27+05:00",
    "pricing_type": 0,
    "product_pricings": [],
    "avatar": null,
    "base_currency_amount": null,
    "creater_id": 3,
    "updater_id": null,
    "description": "This is a sample product",
    "lookup_information": {}
  }
}
EXPAND ↓

Additional Examples

1. Create a product with custom fields
If you’d like to create a product along with custom fields, use this API.

Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"product":{"name":"Sample Product","description":"This is a sample product","category":"Software","is_active":true,"parent_product":1,"product_code":"sample_product","sku_number":"sample_sku","valid_till":"2021-11-06T13:47:13+05:00","owner_id":3,"custom_field":{"cf_rating":"Excellent","cf_quantity":10}}}' -X POST "https://domain.myfreshworks.com/crm/sales/api/cpq/products"
EXPAND ↓

View a Product

This API allows you to view the details of a product.

get
/api/cpq/products/[id]

Use 'include' to embed additional details in the response.

Embed Handle
product_pricings api/cpq/products/[id]?include=product_pricings
Will return the configured prices of the products
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/cpq/products/1?include=product_pricings"
EXPAND ↓
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
{
  "product": {
    "id": 1,
    "name": "Sample Product",
    "category": "Software",
    "custom_field": {
      "cf_rating": "5",
      "cf_quantity": 10.0
    },
    "product_code": "sample_product",
    "sku_number": "sample_sku",
    "parent_product": 1,
    "territory_id": null,
    "valid_till": "2021-11-06T13:47:13+05:00",
    "is_active": true,
    "owner_id": 3,
    "is_deleted": false,
    "created_at": "2021-10-06T15:24:19+05:00",
    "updated_at": "2021-10-06T15:26:05+05:00",
    "pricing_type": 1,
    "product_pricings": [
      {
        "id": 6,
        "currency_code": "USD",
        "_destroy": false,
        "billing_cycle": null,
        "billing_type": null,
        "unit_price": 1000.0,
        "setup_fee": null,
        "is_locked": false
      }
    ],
    "avatar": null,
    "base_currency_amount": 1000.0,
    "creater_id": 3,
    "updater_id": 3,
    "description": "This is a sample product"
  }
}
EXPAND ↓

Update a Product

This API allows you to update the details of a product.

put
/api/cpq/products/[id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"product":{"category":"Hardware","is_active":false,"custom_field":{"cf_rating":"4"}}}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/cpq/products/1"
EXPAND ↓
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
{
	"product": {
		"id": 1,
		"name": "Sample Product",
		"category": "Hardware",
		"custom_field": {
			"cf_rating": "4",
			"cf_quantity": 10.0
		},
		"product_code": "sample_product",
		"sku_number": "sample_sku",
		"parent_product": 1,
		"territory_id": null,
		"valid_till": "2021-11-06T13:47:13+05:00",
		"is_active": false,
		"owner_id": 3,
		"is_deleted": false,
		"created_at": "2021-10-06T15:24:19+05:00",
		"updated_at": "2021-10-06T15:50:17+05:00",
		"pricing_type": 1,
		"avatar": null,
		"base_currency_amount": 1000.0,
		"creater_id": 3,
		"updater_id": 3,
		"description": "This is a sample product"
	}
}
EXPAND ↓

Bulk-update Products

If you’d like to update products in bulk, use this API.

put
/api/cpq/products/products_bulk_update
ATTRIBUTE TYPE DESCRIPTION
ids[] Array of numbers An array of product IDs that you'd like to update
product object An object that contains properties to update.
eg: {"owner_id":3,"description":"Sample description"}
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"product":{"owner_id":3,"description":"Sample description"},"ids":[1,2]}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/cpq/products/products_bulk_update"
EXPAND ↓
Response 
1
2
3
{
  "message": "Field update added to queue, you will be notified on success."
}
EXPAND ↓

Bulk-assign Owner

If you’d like to assign an owner to a list of products, use this API.

post
/api/cpq/products/products_bulk_assign
ATTRIBUTE TYPE DESCRIPTION
selected_ids[] Array of numbers An array of product IDs that you'd like to assign an owner to
owner_id number ID of the user
Sample code | Curl
Copied Copy 
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/cpq/products/products_bulk_assign"
EXPAND ↓
Response 
1
2
3
{
  "message": "Sales owner assignment added to queue, you will be notified on success."
}
EXPAND ↓

Delete a Product

This API allows you to delete a product.

delete
/api/cpq/products/[id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/cpq/products/1"
EXPAND ↓
Response 
1
2
3
4
5
6
{
  "msg": {
    "id": 1,
    "code": "success"
  }
}
EXPAND ↓

Restore a Product

This API allows you to restore a product.

put
/api/cpq/products/[id]/restore
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X PUT "https://domain.myfreshworks.com/crm/sales/api/cpq/products/1/restore"
EXPAND ↓
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
{
  "product": {
    "id": 1,
    "name": "Sample Product",
    "category": "Hardware",
    "custom_field": {
      "cf_rating": "4",
      "cf_quantity": 10.0
    },
    "product_code": "sample_product",
    "sku_number": "sample_sku",
    "parent_product": 1,
    "valid_till": "2021-11-06T13:47:13+05:00",
    "is_active": false,
    "owner_id": 3,
    "is_deleted": false,
    "created_at": "2021-10-06T15:24:19+05:00",
    "updated_at": "2021-10-06T18:48:38+05:00",
    "pricing_type": 1,
    "base_currency_amount": 1000.0,
    "creater_id": 3,
    "updater_id": 3,
    "description": "This is a sample product"
  }
}
EXPAND ↓

Bulk-delete Products

If you’d like to delete products in bulk, use this API.

post
/api/cpq/products/products_bulk_delete
ATTRIBUTE TYPE DESCRIPTION
selected_ids[] Array of numbers An array of product IDs that you'd like to delete
Sample code | Curl
Copied Copy 
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/cpq/products/products_bulk_delete"
EXPAND ↓
Response 
1
2
3
{
  "message": "Bulk deletion added to queue, you will be notified on success."
}
EXPAND ↓

Bulk-restore Products

If you’d like to restore deleted products in bulk, use this API.

post
/api/cpq/products/products_bulk_restore
ATTRIBUTE TYPE DESCRIPTION
selected_ids[] Array of numbers An array of deleted product IDs that you'd like to restore
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"selected_ids":[1,2]}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/cpq/products/products_bulk_restore"
EXPAND ↓
Response 
1
2
3
{
  "message": "Restoring your products, you'll get a notification when this is complete."
}
EXPAND ↓

Add Prices to the Product

This API allows you to add the prices to the product.

put
api/cpq/products/[id]?include=product_pricings
ATTRIBUTE TYPE DESCRIPTION
pricing_type number Denotes the pricing type, it can be either 1 (one-time) or 2 (subscription). You can pass this key only when you're adding products for the first time.
product_pricings Array of objects Each object denotes the price details of a currency. Please find the schema of the product_pricings given below.

Attributes of product_pricings object

ATTRIBUTE TYPE DESCRIPTION
id∑ number Unique ID of the price for a currency
currency_code*Ω string Currency code
unit_price* decimal(15,4) Unit price of the product
setup_fee decimal(15,4) Setup fee of the product, value needs to be passed in the API only when the pricing_type is 2.
billing_cycle number Denotes the billing cycle, value needs to be passed only when the pricing_type is 2.
billing_type number 1 - Monthly, 2 - Quarterly 3 - Half-yearly 4 - Yearly.
Value needs to be passed only when the pricing_type is 2.
* Mandatory fields for creating a product
∑ This field is unique
Ω To know all available options for this field, refer Configuration
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"product":{"pricing_type":1,"product_pricings":[{"currency_code":"USD","unit_price":1000},{"currency_code":"INR","unit_price":74000}]}}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/cpq/products/1?include=product_pricings"
EXPAND ↓
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
{
  "product": {
      "id": 1,
      "name": "Sample Product",
      "category": "Hardware",
      "custom_field": {
          "cf_rating": "4",
          "cf_quantity": 10.0
      },
      "product_code": "sample_product",
      "sku_number": "sample_sku",
      "parent_product": 1,
      "territory_id": null,
      "valid_till": "2021-11-06T00:47:13-08:00",
      "is_active": true,
      "owner_id": 3,
      "is_deleted": false,
      "created_at": "2021-10-06T02:24:19-08:00",
      "updated_at": "2021-10-31T02:51:03-08:00",
      "pricing_type": 1,
      "product_pricings": [
          {
              "id": 1,
              "currency_code": "USD",
              "_destroy": false,
              "billing_cycle": null,
              "billing_type": null,
              "unit_price": 1000.0,
              "setup_fee": null,
              "is_locked": false
          },
          {
              "id": 2,
              "currency_code": "INR",
              "_destroy": false,
              "billing_cycle": null,
              "billing_type": null,
              "unit_price": 74000.0,
              "setup_fee": null,
              "is_locked": false
          }
      ],
      "avatar": null,
      "base_currency_amount": 1000.0,
      "creater_id": 3,
      "updater_id": 3,
      "description": "This is a sample product"
  }
}
EXPAND ↓

Additional Examples

1. Add prices with pricing_type as 2 (subscription)
This API allows you to add the prices of the product with pricing_type as 2 (subscription).

Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"product":{"pricing_type":2,"product_pricings":[{"currency_code":"USD","unit_price":100,"setup_fee":10,"billing_cycle":6,"billing_type":1},{"currency_code":"INR","unit_price":7400,"setup_fee":740,"billing_cycle":6,"billing_type":1}]}}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/cpq/products/1?include=product_pricings"
EXPAND ↓

Edit Prices of the Product

This API allows you to edit the prices of the product. Please make sure to pass all the required keys inside an object in the product_pricing array since it will overwrite the existing price data with the new details.

put
api/cpq/products/[id]?include=product_pricings
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"product":{"product_pricings":[{"id":"18","currency_code":"USD","unit_price":100,"setup_fee":10,"billing_cycle":2,"billing_type":2},{"id":"19","currency_code":"INR","unit_price":7400,"setup_fee":740,"billing_cycle":2,"billing_type":2}]}}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/cpq/products/1?include=product_pricings"
EXPAND ↓
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
{
  "product": {
    "id": 1,
    "name": "Sample Product",
    "category": "Hardware",
    "custom_field": {
      "cf_rating": "4",
      "cf_quantity": 10.0
    },
    "product_code": "sample_product",
    "sku_number": "sample_sku",
    "parent_product": 1,
    "territory_id": null,
    "valid_till": "2021-11-06T13:47:13+05:00",
    "is_active": false,
    "owner_id": 3,
    "is_deleted": false,
    "created_at": "2021-10-06T15:24:19+05:00",
    "updated_at": "2021-10-07T15:42:42+05:00",
    "pricing_type": 2,
    "product_pricings": [
      {
        "id": 18,
        "currency_code": "USD",
        "_destroy": false,
        "billing_cycle": 2,
        "billing_type": 2,
        "unit_price": 100.0,
        "setup_fee": 10.0,
        "is_locked": false
      },
      {
        "id": 19,
        "currency_code": "INR",
        "_destroy": false,
        "billing_cycle": 2,
        "billing_type": 2,
        "unit_price": 7400.0,
        "setup_fee": 740.0,
        "is_locked": false
      }
    ],
    "avatar": null,
    "base_currency_amount": 100.0,
    "creater_id": 3,
    "updater_id": 3,
    "description": "This is a sample product"
  }
}
EXPAND ↓

Delete Prices of the Product

This API allows you to delete the prices of the product.

put
api/cpq/products/[id]?include=product_pricings
ATTRIBUTE TYPE DESCRIPTION
id number Unique ID of the price for a currency
_destroy boolean Pass value as true
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"product":{"product_pricings":[{"id":"19","_destroy":true}]}}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/cpq/products/1?include=product_pricings"
EXPAND ↓
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
{
  "product": {
    "id": 1,
    "name": "Sample Product",
    "category": "Hardware",
    "custom_field": {
      "cf_rating": "4",
      "cf_quantity": 10.0
    },
    "product_code": "sample_product",
    "sku_number": "sample_sku",
    "parent_product": 1,
    "territory_id": null,
    "valid_till": "2021-11-06T13:47:13+05:00",
    "is_active": false,
    "owner_id": 3,
    "is_deleted": false,
    "created_at": "2021-10-06T15:24:19+05:00",
    "updated_at": "2021-10-07T15:42:42+05:00",
    "pricing_type": 2,
    "product_pricings": [
      {
        "id": 18,
        "currency_code": "USD",
        "_destroy": false,
        "billing_cycle": 2,
        "billing_type": 2,
        "unit_price": 100.0,
        "setup_fee": 10.0,
        "is_locked": false
      }
    ],
    "avatar": null,
    "base_currency_amount": 100.0,
    "creater_id": 3,
    "updater_id": 3,
    "description": "This is a sample product"
  }
}
EXPAND ↓

Add Products to the Deal

This API allows you to add the products to the deal. Maximum of 100 products can be added to the deal.

put
api/deals/[id]?include=products
ATTRIBUTE TYPE DESCRIPTION
products Array of objects Each object represents a product that can be added to the deal. Please find the schema of the products object given below.

Attributes of products object

ATTRIBUTE TYPE DESCRIPTION
id* number Unique ID of the product
quantity number Denotes the quantity of the product
discount decimal(5,2) Discount that needs to be given
billing_cycle number Optional field which denotes the billing cycle. If this key is not passed, the default billing cycle of the product will be taken. This field is applicable only when the pricing type of the product is subscription.
unit_price decimal(15,4) Optional field which denotes the unit price. If this key is not passed, the default unit price of the product will be taken. This field is applicable only when the user has the edit product privilege.
setup_fee decimal(15,4) Optional field which denotes the setup fee. If this key is not passed, the default setup fee of the product will be taken. This field is applicable only when the user has the edit product privilege and the pricing type of the product is subscription.
* Mandatory field
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"deal":{"products":[{"id":1,"quantity":1,"discount":0,"billing_cycle":6,"unit_price":2000,"setup_fee":200},{"id":2,"quantity":2,"discount":10}]}}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/deals/1?include=products"
EXPAND ↓
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
{
  "deal": {
    "id": 1,
    "name": "Gold plan (sample)",
    "amount": "8360.0",
    "base_currency_amount": "8360.0",
    "expected_close": "2021-10-01",
    "closed_date": null,
    "stage_updated_time": "2021-10-21T07:54:11-08:00",
    "custom_field": {
      "cf_custom_date": null
    },
    "probability": 100,
    "updated_at": "2022-01-03T22:00:16-09:00",
    "created_at": "2021-09-19T05:37:52-08:00",
    "deal_pipeline_id": 1,
    "deal_stage_id": 2,
    "age": 107,
    "links": {
      "conversations": "/deals/1/conversations/all?include=email_conversation_recipients%2Ctargetable%2Cphone_number%2Cphone_caller%2Cnote%2Cuser&per_page=3",
      "document_associations": "/deals/1/document_associations",
      "notes": "/deals/1/notes?include=creater",
      "tasks": "/deals/1/tasks?include=creater,owner,updater,targetable,users,task_type",
      "appointments": "/deals/1/appointments?include=creater,owner,updater,targetable,appointment_attendees,conference,note"
    },
    "recent_note": null,
    "completed_sales_sequences": null,
    "active_sales_sequences": null,
    "web_form_id": null,
    "upcoming_activities_time": null,
    "collaboration": {},
    "last_assigned_at": "2021-09-19T05:37:52-08:00",
    "tags": [],
    "last_contacted_sales_activity_mode": null,
    "last_contacted_via_sales_activity": null,
    "expected_deal_value": "8360.0",
    "is_deleted": false,
    "team_user_ids": null,
    "avatar": null,
    "fc_widget_collaboration": {
      "convo_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJDb252b0lkIjoiMSIsInR5cGUiOiJkZWFsIn0.Y15lvAElMjqJjrbMObkd0N66cVY919Fye-GnMM6OUSQ",
      "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJVc2VyVVVJRCI6IjM2NTA4OTQ5OTYyNjUwNDExMyJ9.TrF3ZcI-Bd8UyqrjJaplsXkxGszubc-1wUDJDg-3HEY",
      "encoded_jwt_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwcm9kdWN0IjoiZnJlc2hzYWxlcyIsImNvbnRleHRfaWQiOiIxIiwiY29udGV4dF90eXBlIjoiRGVhbCIsInByb2R1Y3RfYWNjb3VudF9pZCI6IjE2MzI0OTAzNzAiLCJwcm9kdWN0X2FjY291bnRfZG9tYWluIjoibXlzcWwuZnJlc2hzYWxlcy1kZXYuY29tIiwidXNlcl9lbWFpbCI6ImpvdGhpc3dhcmFuLnNlbGxhbXV0aHUxQGZyZXNod29ya3MuY29tIiwiaXNfc2VydmVyIjp0cnVlLCJleHAiOjE2NDEyNzk3Mzd9.x3VqRdO9cUZQKt9L2Fz8CzpN195Ol5cIykutbqd2OCc"
    },
    "forecast_category": 1000000166,
    "deal_prediction": 0,
    "deal_prediction_last_updated_at": null,
    "record_type_id": null,
    "rotten_days": 77,
    "has_products": true,
    "products": [
      {
        "product_id": 1,
        "unit_price": 2000.0,
        "setup_fee": 200.0,
        "billing_type": 1,
        "billing_cycle": 6,
        "currency_code": "USD",
        "quantity": 1,
        "discount": 0.0,
        "deal_id": 1,
        "_id": "1-1",
        "id": 1,
        "name": "Sample Product",
        "pricing_type": 2,
        "avatar": null,
        "owner_id": 3,
        "category": "Hardware"
      },
      {
        "product_id": 2,
        "unit_price": 3000.0,
        "setup_fee": null,
        "billing_type": null,
        "billing_cycle": null,
        "currency_code": "USD",
        "quantity": 2,
        "discount": 10.0,
        "deal_id": 1,
        "_id": "1-2",
        "id": 2,
        "name": "Sample Product 2",
        "pricing_type": 1,
        "avatar": null,
        "owner_id": 3,
        "category": null
      }
    ]
  }
}
EXPAND ↓

Edit Products of the Deal

This API allows you to edit the products of the deal. If we pass only one product to this API, it will remove other existing products attached to the deal and add/update only the product passed. In the below example, it just updates the product with id 1 attached to the deal and removes other products attached.

put
api/deals/[id]?include=products
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"deal":{"products":[{"id":1,"quantity":2,"discount":100,"billing_cycle":6,"unit_price":4000,"setup_fee":400}]}}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/deals/1?include=products"
EXPAND ↓
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
{
  "deal": {
    "id": 1,
    "name": "Gold plan (sample)",
    "amount": "0.0",
    "base_currency_amount": "0.0",
    "expected_close": "2021-10-01",
    "closed_date": null,
    "stage_updated_time": "2021-10-21T07:54:11-08:00",
    "custom_field": {
      "cf_custom_date": null
    },
    "probability": 100,
    "updated_at": "2022-01-03T22:05:15-09:00",
    "created_at": "2021-09-19T05:37:52-08:00",
    "deal_pipeline_id": 1,
    "deal_stage_id": 2,
    "age": 107,
    "links": {
      "conversations": "/deals/1/conversations/all?include=email_conversation_recipients%2Ctargetable%2Cphone_number%2Cphone_caller%2Cnote%2Cuser&per_page=3",
      "document_associations": "/deals/1/document_associations",
      "notes": "/deals/1/notes?include=creater",
      "tasks": "/deals/1/tasks?include=creater,owner,updater,targetable,users,task_type",
      "appointments": "/deals/1/appointments?include=creater,owner,updater,targetable,appointment_attendees,conference,note"
    },
    "recent_note": null,
    "completed_sales_sequences": null,
    "active_sales_sequences": null,
    "web_form_id": null,
    "upcoming_activities_time": null,
    "collaboration": {},
    "last_assigned_at": "2021-09-19T05:37:52-08:00",
    "tags": [],
    "last_contacted_sales_activity_mode": null,
    "last_contacted_via_sales_activity": null,
    "expected_deal_value": "0.0",
    "is_deleted": false,
    "team_user_ids": null,
    "avatar": null,
    "fc_widget_collaboration": {
      "convo_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJDb252b0lkIjoiMSIsInR5cGUiOiJkZWFsIn0.Y15lvAElMjqJjrbMObkd0N66cVY919Fye-GnMM6OUSQ",
      "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJVc2VyVVVJRCI6IjM2NTA4OTQ5OTYyNjUwNDExMyJ9.TrF3ZcI-Bd8UyqrjJaplsXkxGszubc-1wUDJDg-3HEY",
      "encoded_jwt_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwcm9kdWN0IjoiZnJlc2hzYWxlcyIsImNvbnRleHRfaWQiOiIxIiwiY29udGV4dF90eXBlIjoiRGVhbCIsInByb2R1Y3RfYWNjb3VudF9pZCI6IjE2MzI0OTAzNzAiLCJwcm9kdWN0X2FjY291bnRfZG9tYWluIjoibXlzcWwuZnJlc2hzYWxlcy1kZXYuY29tIiwidXNlcl9lbWFpbCI6ImpvdGhpc3dhcmFuLnNlbGxhbXV0aHUxQGZyZXNod29ya3MuY29tIiwiaXNfc2VydmVyIjp0cnVlLCJleHAiOjE2NDEyODAwMzZ9.ENZwXPezAVpuGQM_IndSc3WORT6oztqfh9G7soEAlvU"
    },
    "forecast_category": 1000000166,
    "deal_prediction": 0,
    "deal_prediction_last_updated_at": null,
    "record_type_id": null,
    "rotten_days": 77,
    "has_products": true,
    "products": [
      {
        "product_id": 1,
        "unit_price": 4000.0,
        "setup_fee": 400.0,
        "billing_type": 1,
        "billing_cycle": 6,
        "currency_code": "USD",
        "quantity": 2,
        "discount": 100.0,
        "deal_id": 1,
        "_id": "1-1",
        "id": 1,
        "name": "Sample Product",
        "pricing_type": 2,
        "avatar": null,
        "owner_id": 3,
        "category": "Hardware"
      }
    ]
  }
}
EXPAND ↓

Delete Products of the Deal

This API allows you to delete all the products of the deal. Pass empty array as value to the products attribute.

put
api/deals/[id]?include=products
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"deal":{"products":[]}}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/deals/1?include=products"
EXPAND ↓
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
{
  "deal": {
    "id": 1,
    "name": "Gold plan (sample)",
    "amount": "0.0",
    "base_currency_amount": "0.0",
    "expected_close": "2021-10-01",
    "closed_date": null,
    "stage_updated_time": "2021-09-23T18:37:56+05:00",
    "custom_field": {},
    "probability": 100,
    "updated_at": "2021-10-08T21:38:44+05:00",
    "created_at": "2021-09-19T18:37:52+05:00",
    "deal_pipeline_id": 1,
    "deal_stage_id": 1,
    "age": 19,
    "links": {
      "conversations": "/deals/1/conversations/all?include=email_conversation_recipients%2Ctargetable%2Cphone_number%2Cphone_caller%2Cnote%2Cuser&per_page=3",
      "document_associations": "/deals/1/document_associations",
      "notes": "/deals/1/notes?include=creater",
      "tasks": "/deals/1/tasks?include=creater,owner,updater,targetable,users,task_type",
      "appointments": "/deals/1/appointments?include=creater,owner,updater,targetable,appointment_attendees,conference,note"
    },
    "recent_note": null,
    "completed_sales_sequences": null,
    "active_sales_sequences": null,
    "web_form_id": null,
    "upcoming_activities_time": null,
    "collaboration": {},
    "last_assigned_at": "2021-09-19T18:37:52+05:00",
    "tags": [],
    "last_contacted_sales_activity_mode": null,
    "last_contacted_via_sales_activity": null,
    "expected_deal_value": "0.0",
    "is_deleted": false,
    "team_user_ids": null,
    "avatar": null,
    "fc_widget_collaboration": {
      "convo_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJDb252b0lkIjoiMSIsInR5cGUiOiJkZWFsIn0.Y15lvAElMjqJjrbMObkd0N66cVY919Fye-GnMM6OUSQ",
      "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJVc2VyVVVJRCI6IjM2NTA4OTQ5OTYyNjUwNDExMyJ9.TrF3ZcI-Bd8UyqrjJaplsXkxGszubc-1wUDJDg-3HEY",
      "encoded_jwt_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwcm9kdWN0IjoiZnJlc2hzYWxlcyIsImNvbnRleHRfaWQiOiIxIiwiY29udGV4dF90eXBlIjoiRGVhbCIsInByb2R1Y3RfYWNjb3VudF9pZCI6IjE2MzI0OTAzNzAiLCJwcm9kdWN0X2FjY291bnRfZG9tYWluIjoibXlzcWwuZnJlc2hzYWxlcy1kZXYuY29tIiwidXNlcl9lbWFpbCI6ImpvdGhpc3dhcmFuLnNlbGxhbXV0aHUxQGZyZXNod29ya3MuY29tIiwiaXNfc2VydmVyIjp0cnVlLCJleHAiOjE2MzM3MTEyNDR9.Ju0dhgXiP2BNnaMwpHn7x6gCTBsyfXHriG8FY_uu2To"
    },
    "forecast_category": 2,
    "rotten_days": null,
    "has_products": false,
    "products": []
  }
}
EXPAND ↓

Documents

Documents can be used to negotiate with customers during your sales cycle.

ATTRIBUTE TYPE DESCRIPTION
id∑ number Unique ID of the document
display_name*∑ string Display name of the document
document_type* string Type of the document. Value should be from one of the configured choices of 'Document types' in the CPQ settings page.
cpq_document_template_name* string Template name of the document. Value should be from one of the existing templates.
deal_id* number ID of the deal that the document belongs to. To get the list of available deal IDs, please refer this Section
sales_account_id number ID of the account that the document belongs to. To get the list of available account IDs, please refer this Section
contact_id* number ID of the contact that the document belongs to. To get the list of available contact IDs, please refer this Section
amount decimal(15,4) Denotes the value of the document. Once the products are added to the document, amount can't be updated directly.
stage string Stage of the document. Value should be from one of the configured choices of 'Document stage' field in the documents form.
valid_till datetime Timestamp that denotes the validity of the document
shipping_address string Shipping address
shipping_city string Shipping city
shipping_state string Shipping state
shipping_zipcode string Shipping zipcode
shipping_country string Shipping country
billing_address string Billing address
billing_city string Billing city
billing_state string Billing state
billing_zipcode string Billing zipcode
billing_country string Billing country
owner_id number ID of the user to whom the document has been assigned
territory_id number ID of the territory that the document belongs to
created_at datetime Document creation timestamp
updated_at datetime Document updated timestamp
* Mandatory fields for creating a document
∑ This field is unique

Create a Document

This API allows you to create a document.

post
/api/cpq/cpq_documents
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"cpq_document":{"deal_id":1,"sales_account_id":1,"contact_id":1,"document_type":"Quote","stage":"Draft","valid_till":"Thu Oct 21 2021 00:00:00 GMT+0500","shipping_address":"604-5854 Beckford St.","shipping_city":"Glendale","shipping_state":"Arizona","shipping_zipcode":"100652","shipping_country":"USA","billing_address":"604-5854 Beckford St.","billing_city":"Glendale","billing_state":"Arizona","billing_zipcode":"100652","billing_country":"USA","amount":100,"display_name":"Sample Document","currency_code":"USD","owner_id":1,"territory_id":1,"cpq_document_template_name":"Sample Template"}}' -X POST "https://domain.myfreshworks.com/crm/sales/api/cpq/cpq_documents"
EXPAND ↓
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
{
  "cpq_document": {
    "id": 1,
    "deal_id": 1,
    "contact_id": 1,
    "sales_account_id": 1,
    "document_type": "Quote",
    "stage": "Draft",
    "valid_till": "2021-10-28T11:00:00-08:00",
    "shipping_address": "604-5854 Beckford St.",
    "shipping_city": "Glendale",
    "shipping_state": "Arizona",
    "shipping_zipcode": "100652",
    "shipping_country": "USA",
    "billing_address": "604-5854 Beckford St.",
    "billing_city": "Glendale",
    "billing_state": "Arizona",
    "billing_zipcode": "100652",
    "billing_country": "USA",
    "owner_id": 1,
    "amount": 100.0,
    "currency_code": "USD",
    "base_currency_amount": 100.0,
    "creater_id": 3,
    "updater_id": null,
    "custom_field": {
      "cf_custom_status": null,
      "cf_rating": null
    },
    "created_at": "2021-10-24T21:17:08-08:00",
    "updated_at": "2021-10-24T21:17:08-08:00",
    "is_deleted": false,
    "document_number": "DOC-1",
    "territory_id": 1,
    "is_deal_primary": false,
    "products": [],
    "display_name": "Sample Document",
    "html_content": null,
    "html_content_css": null,
    "html_content_settings": {},
    "html_header": null,
    "html_footer": null,
    "email_template_id": null,
    "cpq_document_template_name": "Sample Template",
    "has_products": false
  }
}
EXPAND ↓

Additional Examples

1. Create a document with custom fields
If you’d like to create a document along with custom fields, use this API.

Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"cpq_document":{"deal_id":1,"sales_account_id":1,"contact_id":1,"document_type":"Quote","stage":"Draft","valid_till":"Thu Oct 29 2021 00:00:00 GMT+0500","shipping_address":"604-5854 Beckford St.","shipping_city":"Glendale","shipping_state":"Arizona","shipping_zipcode":"100652","shipping_country":"USA","billing_address":"604-5854 Beckford St.","billing_city":"Glendale","billing_state":"Arizona","billing_zipcode":"100652","billing_country":"USA","amount":100,"display_name":"Sample Document 1","currency_code":"USD","owner_id":1,"territory_id":1,"cpq_document_template_name":"Sample Template","custom_field":{"cf_custom_status":"Pending","cf_rating":"Excellent"}}}' -X POST "https://domain.myfreshworks.com/crm/sales/api/cpq/cpq_documents"
EXPAND ↓

View a Document

This API allows you to view the details of a document.

get
/api/cpq/cpq_documents/[id]

Use 'include' to embed additional details in the response.

Embed Handle
products api/cpq/cpq_documents/[id]?include=products
Will return the products added to the document along with the price details
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/cpq/cpq_documents/1?include=products"
EXPAND ↓
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
{
  "cpq_document": {
    "id": 1,
    "deal_id": 1,
    "contact_id": 1,
    "sales_account_id": 1,
    "document_type": "Quote",
    "stage": "Draft",
    "valid_till": "2021-10-28T11:00:00-08:00",
    "shipping_address": "604-5854 Beckford St.",
    "shipping_city": "Glendale",
    "shipping_state": "Arizona",
    "shipping_zipcode": "100652",
    "shipping_country": "USA",
    "billing_address": "1552 camp st",
    "billing_city": "San Diego",
    "billing_state": "CA",
    "billing_zipcode": "92093",
    "billing_country": "USA",
    "owner_id": 1,
    "amount": 2483.0,
    "currency_code": "USD",
    "base_currency_amount": 2483.0,
    "creater_id": 3,
    "updater_id": 3,
    "custom_field": {
      "cf_custom_status": null,
      "cf_rating": null
    },
    "created_at": "2021-10-24T21:17:08-08:00",
    "updated_at": "2021-10-26T01:56:02-08:00",
    "is_deleted": false,
    "document_number": "DOC-1",
    "territory_id": 1,
    "is_deal_primary": false,
    "products": [
      {
        "id": 1,
        "product_id": 1,
        "cpq_document_id": 1,
        "currency_code": "USD",
        "billing_cycle": 6,
        "billing_type": 1,
        "unit_price": 100.0,
        "setup_fee": 10.0,
        "quantity": 1,
        "discount": 0.0,
        "item_id": "1-1",
        "name": "Sample Product",
        "pricing_type": 2,
        "avatar": null,
        "owner_id": 3
      },
      {
        "id": 2,
        "product_id": 2,
        "cpq_document_id": 1,
        "currency_code": "USD",
        "billing_cycle": null,
        "billing_type": null,
        "unit_price": 1000.0,
        "setup_fee": null,
        "quantity": 2,
        "discount": 10.0,
        "item_id": "1-2",
        "name": "Sample Product 2",
        "pricing_type": 1,
        "avatar": null,
        "owner_id": 3
      }
    ],
    "display_name": "Sample Document",
    "email_template_id": null,
    "cpq_document_template_name": "Sample Template",
    "has_products": true
  }
}
EXPAND ↓

Update a Document

This API allows you to update the details of a document.

put
/api/cpq/cpq_documents/[id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"cpq_document":{"stage":"Sent to customer","custom_field":{"cf_custom_status":"Completed"}}}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/cpq/cpq_documents/1"
EXPAND ↓
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
{
	"cpq_document": {
		"id": 1,
		"deal_id": 1,
		"contact_id": 1,
		"sales_account_id": 1,
		"document_type": "Quote",
		"stage": "Sent to customer",
		"valid_till": "2021-10-28T11:00:00-08:00",
		"shipping_address": "604-5854 Beckford St.",
		"shipping_city": "Glendale",
		"shipping_state": "Arizona",
		"shipping_zipcode": "100652",
		"shipping_country": "USA",
		"billing_address": "1552 camp st",
		"billing_city": "San Diego",
		"billing_state": "CA",
		"billing_zipcode": "92093",
		"billing_country": "USA",
		"owner_id": 1,
		"amount": 2483.0,
		"currency_code": "USD",
		"base_currency_amount": 2483.0,
		"creater_id": 3,
		"updater_id": 3,
		"custom_field": {
			"cf_custom_status": "Completed",
			"cf_rating": null
		},
		"created_at": "2021-10-24T21:17:08-08:00",
		"updated_at": "2021-10-26T02:23:01-08:00",
		"is_deleted": false,
		"document_number": "DOC-1",
		"territory_id": 1,
		"is_deal_primary": false,
		"display_name": "Sample Document",
		"email_template_id": null,
		"cpq_document_template_name": "Sample Template",
		"has_products": true
	}
}
EXPAND ↓

Bulk-update Documents

If you’d like to update documents in bulk, use this API.

put
/api/cpq/cpq_documents/cpq_documents_bulk_update
ATTRIBUTE TYPE DESCRIPTION
ids[] Array of numbers An array of document IDs that you'd like to update
cpq_document object An object that contains properties to update.
eg: {"owner_id":3,"amount":300}
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"cpq_document":{"owner_id":3,"amount":300},"ids":[1, 2]}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/cpq/cpq_documents/cpq_documents_bulk_update"
EXPAND ↓
Response 
1
2
3
{
  "message": "Field update added to queue, you will be notified on success."
}
EXPAND ↓

Bulk-assign Owner

If you’d like to assign an owner to a list of documents, use this API.

post
/api/cpq/cpq_documents/cpq_documents_bulk_assign
ATTRIBUTE TYPE DESCRIPTION
selected_ids[] Array of numbers An array of document IDs that you'd like to assign an owner to
owner_id number ID of the user
Sample code | Curl
Copied Copy 
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/cpq/cpq_documents/cpq_documents_bulk_assign"
EXPAND ↓
Response 
1
2
3
{
  "message": "Sales owner assignment added to queue, you will be notified on success."
}
EXPAND ↓

Delete a Document

This API allows you to delete a document.

delete
/api/cpq/cpq_documents/[id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/cpq/cpq_documents/1"
EXPAND ↓
Response 
1
2
3
4
5
6
{
  "msg": {
    "id": 1,
    "code": "success"
  }
}
EXPAND ↓

Restore a Document

This API allows you to restore a document.

put
/api/cpq/cpq_documents/[id]/restore
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X PUT "https://domain.myfreshworks.com/crm/sales/api/cpq/cpq_documents/1/restore"
EXPAND ↓
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
{
  "cpq_document": {
    "id": 1,
    "deal_id": 1,
    "contact_id": 1,
    "sales_account_id": 1,
    "document_type": "Quote",
    "stage": "Draft",
    "valid_till": "2021-10-28T11:00:00-08:00",
    "shipping_address": "604-5854 Beckford St.",
    "shipping_city": "Glendale",
    "shipping_state": "Arizona",
    "shipping_zipcode": "100652",
    "shipping_country": "USA",
    "billing_address": "604-5854 Beckford St.",
    "billing_city": "Glendale",
    "billing_state": "Arizona",
    "billing_zipcode": "100652",
    "billing_country": "USA",
    "owner_id": 1,
    "amount": 300.0,
    "currency_code": "USD",
    "base_currency_amount": 300.0,
    "creater_id": 3,
    "updater_id": 3,
    "custom_field": {},
    "created_at": "2021-10-24T21:17:08-08:00",
    "updated_at": "2021-10-25T03:24:50-08:00",
    "is_deleted": false,
    "document_number": "DOC-1",
    "territory_id": 1,
    "is_deal_primary": false,
    "display_name": "Sample Document",
    "cpq_document_template_name": "Sample Template",
    "has_products": false
  }
}
EXPAND ↓

Bulk-delete Documents

If you’d like to delete documents in bulk, use this API.

post
/api/cpq/cpq_documents/cpq_documents_bulk_delete
ATTRIBUTE TYPE DESCRIPTION
selected_ids[] Array of numbers An array of document IDs that you'd like to delete
Sample code | Curl
Copied Copy 
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/cpq/cpq_documents/cpq_documents_bulk_delete"
EXPAND ↓
Response 
1
2
3
{
  "message": "Bulk deletion added to queue, you will be notified on success."
}
EXPAND ↓

Bulk-restore Documents

If you’d like to restore deleted documents in bulk, use this API.

post
/api/cpq/cpq_documents/cpq_documents_bulk_restore
ATTRIBUTE TYPE DESCRIPTION
selected_ids[] Array of numbers An array of deleted document IDs that you'd like to restore
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"selected_ids":[1,2]}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/cpq/cpq_documents/cpq_documents_bulk_restore"
EXPAND ↓
Response 
1
2
3
{
  "message": "Restoring your documents, you'll get a notification when this is complete."
}
EXPAND ↓

Forget a Document

This API will allow you to permanently delete a document and all the associated data. Learn more about forget option here.

delete
/api/cpq/cpq_documents/[id]/forget
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/cpq/cpq_documents/1/forget"
EXPAND ↓
Response 
1
2
3
4
5
6
{
  "msg": {
    "id": 1,
    "code": "success"
  }
}
EXPAND ↓

Add Products to the Document

This API allows you to add the products to the document. Maximum of 100 products can be added to the document.

put
api/cpq/cpq_documents/[id]?include=products
ATTRIBUTE TYPE DESCRIPTION
products Array of objects Each object represents a product that can be added to the document. Please find the schema of the products object given below.

Attributes of products object

ATTRIBUTE TYPE DESCRIPTION
id* number Unique ID of the product
quantity number Denotes the quantity of the product
discount decimal(5,2) Discount that needs to be given
billing_cycle number Optional field which denotes the billing cycle. If this key is not passed, the default billing cycle of the product will be taken. This field is applicable only when the pricing type of the product is subscription.
unit_price decimal(15,4) Optional field which denotes the unit price. If this key is not passed, the default unit price of the product will be taken. This field is applicable only when the user has the edit product privilege.
setup_fee decimal(15,4) Optional field which denotes the setup fee. If this key is not passed, the default setup fee of the product will be taken. This field is applicable only when the user has the edit product privilege and the pricing type of the product is subscription.
* Mandatory field
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"cpq_document":{"products":[{"id":1,"quantity":1,"discount":0,"billing_cycle":6,"unit_price":2000,"setup_fee":200},{"id":2,"quantity":2,"discount":10}]}}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/cpq/cpq_documents/1?include=products"
EXPAND ↓
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
{
  "cpq_document": {
    "id": 1,
    "deal_id": 1,
    "contact_id": 1,
    "sales_account_id": 1,
    "document_type": "Quote",
    "stage": "Sent to customer",
    "valid_till": "2021-11-17T15:00:00-09:00",
    "shipping_address": "604-5854 Beckford St.",
    "shipping_city": "Glendale",
    "shipping_state": "Arizona",
    "shipping_zipcode": "100652",
    "shipping_country": "USA",
    "billing_address": "1552 camp st",
    "billing_city": "San Diego",
    "billing_state": "CA",
    "billing_zipcode": "92093",
    "billing_country": "USA",
    "owner_id": 1,
    "amount": 8360.0,
    "currency_code": "USD",
    "base_currency_amount": 8360.0,
    "creater_id": 3,
    "updater_id": 3,
    "custom_field": {
      "cf_number_field": null,
      "cf_rating": null
    },
    "created_at": "2021-10-24T21:17:08-08:00",
    "updated_at": "2022-01-03T22:08:47-09:00",
    "is_deleted": false,
    "document_number": "DOC-1",
    "territory_id": 1,
    "is_deal_primary": false,
    "products": [
      {
        "id": 1,
        "product_id": 1,
        "cpq_document_id": 1,
        "currency_code": "USD",
        "billing_cycle": 6,
        "billing_type": 1,
        "unit_price": 2000.0,
        "setup_fee": 200.0,
        "quantity": 1,
        "discount": 0.0,
        "item_id": "1-1",
        "name": "Sample Product",
        "pricing_type": 2,
        "avatar": null,
        "owner_id": 3
      },
      {
        "id": 2,
        "product_id": 2,
        "cpq_document_id": 1,
        "currency_code": "USD",
        "billing_cycle": null,
        "billing_type": null,
        "unit_price": 3000.0,
        "setup_fee": null,
        "quantity": 2,
        "discount": 10.0,
        "item_id": "1-2",
        "name": "Sample Product 2",
        "pricing_type": 1,
        "avatar": null,
        "owner_id": 3
      }
    ],
    "display_name": "Sample Document",
    "email_template_id": null,
    "cpq_document_template_name": "Sample Template",
    "has_products": true
  }
}
EXPAND ↓

Edit Products of the Document

This API allows you to edit the products of the document. If we pass only one product to this API, it will remove other existing products attached to the document and add/update only the products passed. In the below example, it just updates the product with id 1 attached to the document and removes other products attached.

put
api/cpq/cpq_documents/[id]?include=products
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"cpq_document":{"products":[{"id":1,"quantity":2,"discount":10,"billing_cycle":6,"unit_price":4000,"setup_fee":400}]}}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/cpq/cpq_documents/1?include=products"
EXPAND ↓
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
{
  "cpq_document": {
    "id": 1,
    "deal_id": 1,
    "contact_id": 1,
    "sales_account_id": 1,
    "document_type": "Quote",
    "stage": "Sent to customer",
    "valid_till": "2021-11-17T15:00:00-09:00",
    "shipping_address": "604-5854 Beckford St.",
    "shipping_city": "Glendale",
    "shipping_state": "Arizona",
    "shipping_zipcode": "100652",
    "shipping_country": "USA",
    "billing_address": "1552 camp st",
    "billing_city": "San Diego",
    "billing_state": "CA",
    "billing_zipcode": "92093",
    "billing_country": "USA",
    "owner_id": 1,
    "amount": 8316.0,
    "currency_code": "USD",
    "base_currency_amount": 8316.0,
    "creater_id": 3,
    "updater_id": 3,
    "custom_field": {
      "cf_number_field": null,
      "cf_rating": null
    },
    "created_at": "2021-10-24T21:17:08-08:00",
    "updated_at": "2022-01-03T22:12:12-09:00",
    "is_deleted": false,
    "document_number": "DOC-1",
    "territory_id": 1,
    "is_deal_primary": false,
    "products": [
      {
        "id": 1,
        "product_id": 1,
        "cpq_document_id": 1,
        "currency_code": "USD",
        "billing_cycle": 6,
        "billing_type": 1,
        "unit_price": 4000.0,
        "setup_fee": 400.0,
        "quantity": 2,
        "discount": 10.0,
        "item_id": "1-1",
        "name": "Sample Product",
        "pricing_type": 2,
        "avatar": null,
        "owner_id": 3
      }
    ],
    "display_name": "Sample Document",
    "email_template_id": null,
    "cpq_document_template_name": "Sample Template",
    "has_products": true
  }
}
EXPAND ↓

Delete Products of the Document

This API allows you to delete all the products of the document. Pass empty array as value to the products attribute.

put
api/cpq/cpq_documents/[id]?include=products
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"cpq_document":{"products":[]}}' -X PUT "https://domain.myfreshworks.com/crm/sales/api/cpq/cpq_documents/1?include=products"
EXPAND ↓
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
{
  "cpq_document": {
    "id": 1,
    "deal_id": 1,
    "contact_id": 1,
    "sales_account_id": 1,
    "document_type": "Quote",
    "stage": "Draft",
    "valid_till": "2021-10-28T11:00:00-08:00",
    "shipping_address": "604-5854 Beckford St.",
    "shipping_city": "Glendale",
    "shipping_state": "Arizona",
    "shipping_zipcode": "100652",
    "shipping_country": "USA",
    "billing_address": "1552 camp st",
    "billing_city": "San Diego",
    "billing_state": "CA",
    "billing_zipcode": "92093",
    "billing_country": "USA",
    "owner_id": 1,
    "amount": 0.0,
    "currency_code": "USD",
    "base_currency_amount": 0.0,
    "creater_id": 3,
    "updater_id": 3,
    "custom_field": {
      "cf_custom_status": null,
      "cf_rating": null
    },
    "created_at": "2021-10-24T21:17:08-08:00",
    "updated_at": "2021-10-26T01:55:23-08:00",
    "is_deleted": false,
    "document_number": "DOC-1",
    "territory_id": 1,
    "is_deal_primary": false,
    "products": [],
    "display_name": "Sample Document",
    "email_template_id": null,
    "cpq_document_template_name": "Sample Template",
    "has_products": false
  }
}
EXPAND ↓

Files

Files can be attached to a contact, sales account, deal or a product in Freshsales. Files are great way to keep track of and refer back to attachments related to a contact, sales account, deal or a product.

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/product 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"/"Product"
* Mandatory fields for creating file.

Create a File

This API will help you upload and attach a file to a contact, sales account, deal or a product.
Note: Set Content-Type for the request as multipart/form-data in the request header

post
/api/documents
Sample code | Curl
Copied Copy 
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"
EXPAND ↓
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"
  }
EXPAND ↓

List all Files and Links

This API will help you upload and attach a file to a contact, sales account, deal or a product.

get
/api/contacts/[id]/document_associations
Sample code | Curl
Copied Copy 
1
curl -X GET -H 'Authorization: Token token=sfg999666t673t7t82' "https://domain.myfreshworks.com/crm/sales/api/contacts/1/document_associations"
EXPAND ↓
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
  }
  ]
  }
EXPAND ↓

Job Status

This API allows you to track the progress and details of a background job.

get
/api/job_statuses/[id]

Note:
This API currently supports bulk upsert jobs only.

Response Attributes
Field Description
status IN_PROGRESS | SUCCESS | FAILED
job_type_name Name of the job type corresponding to the Job ID
data Detailed report on stats of records succeeded/failed, and the reasons for the same.
It's in this format:
{ "record_status": { "succeeded": 98, "failed": 2 },
"detailed_failure_report": [{
"errored_record_unique_fld_name": "errored_record_unique_fld_value",
"error_message": ["Reasons for failure"]
}]}
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/job_statuses/[id]"
EXPAND ↓
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
{
            "status": "SUCCESS",
            "job_type_name": "BULK_UPSERT",
            "created_at": "2022-01-27T10:27:29Z",
            "status_updated_at": "2022-01-27T11:52:25Z",
            "progress": 100,
            "data": {
                "record_status": {
                    "succeeded": 97,
                    "failed": 3
                },
                "detailed_failure_report": [{
                                                "emails": "janesampleton@gmail.com",
                                                "error_message": ["Required Field Value missing"]
                                            },
                                            {
                                                "emails": "jamessampleton@gmail.com",
                                                "error_message": ["5 Contacts found with same mail id found - [21,12,3,45,5]"]
                                            },
                                            {
                                                "mobile_number": "9999999999",
                                                "error_message": ["Incorrect value provided for lifecycle stage"]
                                            }
                ]
            }
}
EXPAND ↓

Custom Modules

Custom modules are modules that you can create on your own, in addition to the 4 default modules in the CRM viz. Contacts, Accounts, and Deals. You can create up to 10 custom modules.

Headers
Key Value
Authorization Token token=<user api token>

Create Custom Modules

This API helps you create a custom module.

post
api/settings/module_customizations
Request Parameter Definitions
Parameter Type Description
singular_name*∑ string Name of custom module in singular
plural_name*∑ string Name of custom module in plural
entity_nameμ∑ string internal name for custom module. (Note: It should start with 'cm_')
descriptionμ string A brief explanation of what this module is about
icon* string Icon of the module
show_in_navigation_menuμ boolean Should show in the navigation menu or not
statusμ integer Represents active or not
* Mandatory fields for creating custom module.
∑ This field is unique.
μ This field is optional.
Allowed list of Icons
['icon-cm-auction', 'icon-cm-cart', 'icon-cm-connection', 'icon-cm-courses', 'icon-cm-employee', 'icon-cm-event', 'icon-cm-inventory', 'icon-cm-payments', 'icon-cm-people', 'icon-cm-project', 'icon-cm-property', 'icon-cm-schools', 'icon-cm-sku', 'icon-cm-subscription', 'icon-cm-ticket', 'icon-cm-transactions', 'icon-cm-asset', 'icon-cm-assistant', 'icon-cm-category', 'icon-cm-community', 'icon-cm-competitor', 'icon-cm-entitlement', 'icon-cm-file-attachment', 'icon-cm-fulfillment', 'icon-cm-goals', 'icon-cm-hierarchy', 'icon-cm-id-card', 'icon-cm-idea', 'icon-cm-invoice', 'icon-cm-items', 'icon-cm-labels', 'icon-cm-legal', 'icon-cm-location', 'icon-cm-milestone', 'icon-cm-partner', 'icon-cm-payment', 'icon-cm-purchase-order', 'icon-cm-queue', 'icon-cm-relationship', 'icon-cm-revenue-schedule', 'icon-cm-skill', 'icon-cm-storage', 'icon-cm-survey', 'icon-cm-timesheet']
Sample code | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" 
  -d '{
        "module_customization": {
          “singular_name": "Property",
          "plural_name": "Properties",
          "entity_name": "cm_property",
          "description": "This module holds property details",
          "icon": "icon-cm-property",
          "show_in_navigation_menu": false,
          "status": null
        }
      }'
  -X POST "https://domain.myfreshworks.com/crm/sales/api/settings/module_customizations"
EXPAND ↓
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
{
    "module_customization": {
      "id": 3000000034,
      "singular_name": "Property",
      "plural_name": "Properties",
      "entity_name": "cm_property",
      "description": "This module holds property details",
      "icon": "icon-cm-property",
      "position": 14,
      "show_in_navigation_menu": false,
      "custom": true,
      "resource_path_for_navigation": "/custom_module/cm_property",
      "layout_customizations": {
        "lookup_sections": [],
        "section_config": []
      },
      "status": 1,
      "created_at": "2022-04-25T17:34:54Z",
      "updated_at": "2022-04-25T17:34:54Z",
      "configs": {
        "filters_v2_enabled": true
      }
    }
  }
EXPAND ↓

Get a list of custom modules

This API helps you fetch a list of all the custom modules you’ve created.

get
api/settings/module_customizations/[id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/settings/module_customizations/3000000034"
EXPAND ↓
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
{
    "module_customization": {
      "id": 3000000034,
      "singular_name": "Property",
      "plural_name": "Properties",
      "entity_name": "cm_property",
      "description": "This module holds property details",
      "icon": "icon-cm-property",
      "position": 14,
      "show_in_navigation_menu": false,
      "custom": true,
      "resource_path_for_navigation": "/custom_module/cm_property",
      "layout_customizations": {
        "lookup_sections": [],
        "section_config": []
      },
      "status": 1,
      "created_at": "2022-04-25T17:34:54Z",
      "updated_at": "2022-04-25T17:34:54Z",
      "configs": {
        "filters_v2_enabled": true
      }
    }
  }
EXPAND ↓

Update custom module

This API helps you update a custom module’s details, like its name, icon, and description.

put
api/settings/module_customizations/[id]
Sample code | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" 
  -d '{
    "module_customization": {
      "singular_name": "Phase1 Property",
      "plural_name": "Phase1 Properties",
      "description": "This module holds phase 1 property details",
      "icon": "icon-cm-schools",
      "show_in_navigation_menu": false,
      "status": 1
    }
  }'
 -X PUT "https://domain.myfreshworks.com/crm/sales/api/settings/module_customizations/3000000034"
EXPAND ↓
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
{
    "module_customization": {
      "id": 3000000034,
      "singular_name": "Phase1 Property",
      "plural_name": "Phase1 Properties",
      "entity_name": "cm_property",
      "description": "This module holds phase 1 property details",
      "icon": "icon-cm-schools",
      "position": 14,
      "show_in_navigation_menu": false,
      "custom": true,
      "resource_path_for_navigation": "/custom_module/cm_property",
      "layout_customizations": {
        "lookup_sections": [],
        "section_config": []
      },
      "status": 1,
      "created_at": "2022-04-25T17:34:54Z",
      "updated_at": "2022-04-25T18:03:06Z",
      "configs": {
        "filters_v2_enabled": true
      }
    }
  }
EXPAND ↓

Delete custom module

This API helps you delete a custom module.

delete
api/settings/module_customizations/[id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/settings/module_customizations/3000000034"
EXPAND ↓
Response 
1
{ "message": "Module deleted successfully" }
EXPAND ↓

Fields in custom modules

Headers
Key Value
Authorization Token token=<user api token>

Create custom field

You can add different kinds of fields for the custom modules you create—like dropdowns, radio buttons, checkboxes or even lookup fields.

post
api/settings/[entity_type]/forms/[form_id]/fields
Request Parameter Definitions
Parameter Type Description
Hintμ string Tooltip to describe the field
internal_nameμ∑ string Internal name to refer the field
label*∑ string Label of the field
type* string Type of the field
editableμ boolean Represents readable field or editable field
visibleμ boolean Represents visible field or hidden field
requiredμ boolean Represents mandatory field or not
parent_idμ string Id of another field to represent its parent field. If left empty, it takes Basic information group field as the parent field.
* Mandatory fields for creating custom field.
∑ This field is unique.
μ This field is optional.

Text field

This API helps you add a text field to your custom module.

Sample code | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" 
  -d '{
        "module_customization": {
          “singular_name": "Property",
          "plural_name": "Properties",
          "entity_name": "cm_property",
          "description": "This module holds property details",
          "icon": "icon-cm-property",
          "show_in_navigation_menu": false,
          "status": null
        }
      }'
  -X POST "https://domain.myfreshworks.com/crm/sales/api/settings/cm_property/forms/1/fields"
EXPAND ↓
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
{
    "field": {
      "id": "f9841ad0-e7c7-4917-8199-48d192b266cf",
      "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
      "name": "cf_sample_text_field",
      "label": "sample text field",
      "placeholder": "Enter value",
      "type": "text",
      "position": 3,
      "fields": [],
      "field_class": "CustomModule6",
      "required": false,
      "custom": true,
      "editable": true,
      "visible": true,
      "link": null,
      "choices": [],
      "field_options": {
        "can_editable_be_changed": true,
        "can_editable_be_changed_field_permission": true,
        "can_required_be_changed": true,
        "can_label_be_renamed": true,
        "can_choices_be_customized": false,
        "can_not_be_hidden": false,
        "allow_fields_to_be_added": false,
        "system_field": false
      },
      "hint": "sample text field holds text value",
      "default_value": null,
      "allow_clearing_default_value": true,
      "form_id": 3000000101,
      "quick_add_position": null
    }
  }
EXPAND ↓

Number field

This API helps you add a number field to your custom module. Choose from four number format options: “en”, “es”, “en-IN”, and “fi.”

Sample code | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" 
  -d '{
        "field": {
          "hint": "holds sample number field value",
          "internal_name": "sample_number_field",
          "label": "sample number field",
          "type": "decimal",
          "editable": true,
          "visible": true,
          "required": false,
          "field_options": {
            "locale": "en-IN"
          },
          "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92"
        }
      }'
  -X POST "https://domain.myfreshworks.com/crm/sales/api/settings/cm_property/forms/1/fields"
EXPAND ↓
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
{
    "field": {
      "id": "3cb7aaf0-ce3f-4cfa-a00d-14d4ed8eda62",
      "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
      "name": "cf_sample_number_field",
      "label": "sample number field",
      "placeholder": "Enter value",
      "type": "decimal",
      "position": 4,
      "fields": [],
      "field_class": "CustomModule6",
      "required": false,
      "custom": true,
      "editable": true,
      "visible": true,
      "link": null,
      "choices": [],
      "field_options": {
        "locale": "en-IN",
        "can_editable_be_changed": true,
        "can_editable_be_changed_field_permission": true,
        "can_required_be_changed": true,
        "can_label_be_renamed": true,
        "can_choices_be_customized": false,
        "can_not_be_hidden": false,
        "allow_fields_to_be_added": false,
        "system_field": false
      },
      "hint": "holds sample number field value",
      "default_value": null,
      "allow_clearing_default_value": true,
      "form_id": 3000000101,
      "quick_add_position": null
    }
  }
EXPAND ↓

Radio button field

This API helps you add a radio button field to your custom module.

Sample code | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" 
  -d '{
        "field": {
          "hint": "holds sample radio field",
          "internal_name": "sample_radio_field",
          "label": "sample radio field",
          "type": "radio",
          "editable": true,
          "visible": true,
          "required": false,
          "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
          "choices": [
            {
              "value": "choice 1",
              "position": 1
            },
            {
              "value": "choice 2",
              "position": 2
            }
          ]
        }
      }'
  -X POST "https://domain.myfreshworks.com/crm/sales/api/settings/cm_property/forms/1/fields"
EXPAND ↓
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
{
    "field": {
      "id": "ddbc1de1-ef3a-4c0c-bee1-f9d02b63eb26",
      "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
      "name": "cf_sample_radio_field",
      "label": "sample radio field",
      "placeholder": "",
      "type": "radio",
      "fields": [],
      "field_class": "CustomModule6",
      "required": false,
      "custom": true,
      "editable": true,
      "visible": true,
      "link": null,
      "choices": [
        {
          "id": "4000304718",
          "value": "choice 1",
          "position": 1,
          "type": null,
          "dependent_ids": {},
          "dependency_mapping_id": "4000304718"
        },
        {
          "id": "4000304719",
          "value": "choice 2",
          "position": 2,
          "type": null,
          "dependent_ids": {},
          "dependency_mapping_id": "4000304719"
        }
      ],
      "field_options": {
        "can_editable_be_changed": true,
        "can_editable_be_changed_field_permission": true,
        "can_required_be_changed": true,
        "can_label_be_renamed": true,
        "can_choices_be_customized": true,
        "can_not_be_hidden": false,
        "allow_fields_to_be_added": false,
        "system_field": false
      },
      "hint": "holds sample radio field",
      "default_value": null,
      "allow_clearing_default_value": true,
      "form_id": 3000000101,
      "quick_add_position": null
    }
  }
EXPAND ↓

Lookup field

This API helps you add a lookup field to your custom module.

Request Parameter Definitions

Parameters for the above fields apply here as well. The parameters below are specific to lookup fields.

Parameter Type Description
field_options* hash lookup_type should be passed if it’s a lookup field
field_options hash contain below
lookup_type* string The type of entity i.e. lead, contact, account, deal, property, or any custom module’s record
Sample code | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" 
  -d '{
        "field": {
          "hint": "lookup to contact record",
          "internal_name": "lookup_to_contact",
          "label": "lookup to contact",
          "type": "auto_complete",
          "editable": true,
          "visible": true,
          "required": false,
          "field_options": {
            "lookup_type": "contact"
          },
          "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92"
        }
      }'
  -X POST "https://domain.myfreshworks.com/crm/sales/api/settings/cm_property/forms/1/fields"
EXPAND ↓
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
{
    "field": {
      "id": "d7a679c3-4f79-4a7d-86c1-79b804777625",
      "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
      "name": "cf_lookup_to_contact",
      "label": "lookup to contact",
      "placeholder": "",
      "type": "auto_complete",
      "position": 7,
      "fields": [],
      "field_class": "CustomModule6",
      "required": false,
      "custom": true,
      "editable": true,
      "visible": true,
      "link": "/search.json?include=contact&q=",
      "choices": [],
      "field_options": {
        "lookup_type": "contact",
        "lookup_prefetch_url": "/options_prefetch.json?include=contact&q[]=",
        "can_editable_be_changed": true,
        "can_editable_be_changed_field_permission": true,
        "can_required_be_changed": true,
        "can_label_be_renamed": true,
        "can_choices_be_customized": false,
        "can_not_be_hidden": false,
        "allow_fields_to_be_added": false,
        "system_field": false
      },
      "hint": "lookup to contact record",
      "default_value": null,
      "allow_clearing_default_value": true,
      "form_id": 3000000101,
      "quick_add_position": null
    }
  }
EXPAND ↓

Multiselect field

This API helps you add a multiselect field to your custom module.

Sample code | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" 
  -d '{
        "field": {
          "hint": "Holds sample multi select value",
          "internal_name": "sample_multiselect_field",
          "label": "sample multiselect field",
          "type": "multi_select_dropdown",
          "editable": true,
          "visible": true,
          "required": false,
          "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
          "choices": [
            {
              "value": "choice 1",
              "position": 1
            },
            {
              "value": "choice 2",
              "position": 2
            }
          ]
        }
      }'
  -X POST "https://domain.myfreshworks.com/crm/sales/api/settings/cm_property/forms/1/fields"
EXPAND ↓
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
{
    "field": {
      "id": "48fba048-30d6-48af-9b16-8d83dd62235f",
      "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
      "name": "cf_sample_multiselect_field",
      "label": "sample multiselect field",
      "placeholder": "Choose value(s)",
      "type": "multi_select_dropdown",
      "position": 8,
      "fields": [],
      "field_class": "CustomModule6",
      "required": false,
      "custom": true,
      "editable": true,
      "visible": true,
      "link": null,
      "choices": [
        {
          "id": "4000304720",
          "value": "choice 1",
          "position": 1,
          "type": null,
          "dependent_ids": {},
          "dependency_mapping_id": "4000304720"
        },
        {
          "id": "4000304721",
          "value": "choice 2",
          "position": 2,
          "type": null,
          "dependent_ids": {},
          "dependency_mapping_id": "4000304721"
        }
      ],
      "field_options": {
        "can_editable_be_changed": true,
        "can_editable_be_changed_field_permission": true,
        "can_required_be_changed": true,
        "can_label_be_renamed": true,
        "can_choices_be_customized": true,
        "can_not_be_hidden": false,
        "allow_fields_to_be_added": false,
        "system_field": false
      },
      "hint": "Holds sample multi select value",
      "default_value": null,
      "allow_clearing_default_value": true,
      "form_id": 3000000101,
      "quick_add_position": null
    }
  }
EXPAND ↓

Get a list of all fields

This API helps you fetch a list of all the fields in your custom module.

get
api/settings/:entity_type/forms
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/settings/cm_property/forms"
EXPAND ↓
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
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
{
    "forms": [
      {
        "id": 3000000101,
        "name": "Default form for custom_module6",
        "description": "",
        "active": true,
        "form_class": "CustomModule6Form",
        "field_class": "CustomModule6",
        "fields": [
          {
            "id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
            "parent_id": null,
            "name": "basic_information",
            "label": "Basic information",
            "placeholder": "",
            "type": "section",
            "position": 1,
            "fields": [
              {
                "id": "59b52e17-70ae-4aa9-b539-63c88d926144",
                "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
                "name": "name",
                "label": "Name",
                "placeholder": "Enter value",
                "type": "text",
                "position": 1,
                "fields": [],
                "field_class": "CustomModule6",
                "required": true,
                "custom": false,
                "editable": true,
                "visible": true,
                "link": null,
                "choices": [],
                "field_options": {
                  "can_editable_be_changed": true,
                  "can_editable_be_changed_field_permission": true,
                  "can_required_be_changed": false,
                  "can_label_be_renamed": true,
                  "can_choices_be_customized": false,
                  "can_not_be_hidden": false,
                  "allow_fields_to_be_added": false,
                  "system_field": false
                },
                "hint": "",
                "original_label": "name",
                "original_placeholder": "name",
                "default_value": null,
                "allow_clearing_default_value": true,
                "form_id": 3000000101,
                "quick_add_position": 3
              },
              {
                "id": "a54ec2c2-4779-4ead-a6a0-d51c4920cd06",
                "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
                "name": "owner_id",
                "label": "Sales owner",
                "placeholder": "",
                "type": "auto_complete",
                "position": 2,
                "fields": [],
                "field_class": "CustomModule6",
                "required": false,
                "custom": false,
                "editable": true,
                "visible": true,
                "link": "/search.json?include=user&q=",
                "choices": [],
                "field_options": {
                  "lookup_type": "user",
                  "lookup_prefetch_url": "/options_prefetch.json?include=user&q[]=",
                  "can_editable_be_changed": true,
                  "can_editable_be_changed_field_permission": true,
                  "can_required_be_changed": true,
                  "can_label_be_renamed": true,
                  "can_choices_be_customized": false,
                  "can_not_be_hidden": true,
                  "allow_fields_to_be_added": false,
                  "system_field": false
                },
                "hint": "",
                "original_label": "sales_owner_id",
                "original_placeholder": "owner_id",
                "default_value": "3000034021",
                "allow_clearing_default_value": true,
                "form_id": 3000000101,
                "quick_add_position": null
              },
              {
                "id": "f9841ad0-e7c7-4917-8199-48d192b266cf",
                "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
                "name": "cf_sample_text_field",
                "label": "sample text field",
                "placeholder": "Enter value",
                "type": "text",
                "position": 3,
                "fields": [],
                "field_class": "CustomModule6",
                "required": false,
                "custom": true,
                "editable": true,
                "visible": true,
                "link": null,
                "choices": [],
                "field_options": {
                  "can_editable_be_changed": true,
                  "can_editable_be_changed_field_permission": true,
                  "can_required_be_changed": true,
                  "can_label_be_renamed": true,
                  "can_choices_be_customized": false,
                  "can_not_be_hidden": false,
                  "allow_fields_to_be_added": false,
                  "system_field": false
                },
                "hint": "sample text field holds text value",
                "original_label": "sample text field",
                "original_placeholder": "",
                "default_value": null,
                "allow_clearing_default_value": true,
                "form_id": 3000000101,
                "quick_add_position": null
              },
              {
                "id": "3cb7aaf0-ce3f-4cfa-a00d-14d4ed8eda62",
                "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
                "name": "cf_sample_number_field",
                "label": "sample number field",
                "placeholder": "Enter value",
                "type": "decimal",
                "position": 4,
                "fields": [],
                "field_class": "CustomModule6",
                "required": false,
                "custom": true,
                "editable": true,
                "visible": true,
                "link": null,
                "choices": [],
                "field_options": {
                  "locale": "en-IN",
                  "can_editable_be_changed": true,
                  "can_editable_be_changed_field_permission": true,
                  "can_required_be_changed": true,
                  "can_label_be_renamed": true,
                  "can_choices_be_customized": false,
                  "can_not_be_hidden": false,
                  "allow_fields_to_be_added": false,
                  "system_field": false
                },
                "hint": "holds sample number field value",
                "original_label": "sample number field",
                "original_placeholder": "",
                "default_value": null,
                "allow_clearing_default_value": true,
                "form_id": 3000000101,
                "quick_add_position": null
              },
              {
                "id": "7a68af67-68a3-490f-ab16-f622ef443cb2",
                "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
                "name": "cf_sample_sales_team_field",
                "label": "sample sales team field",
                "placeholder": "Choose a value",
                "type": "dropdown",
                "position": 5,
                "fields": [],
                "field_class": "CustomModule6",
                "required": false,
                "custom": true,
                "editable": true,
                "visible": true,
                "link": null,
                "choices": [
                  {
                    "id": "4000304716",
                    "value": "USA team",
                    "position": 1,
                    "type": null,
                    "dependent_ids": {},
                    "dependency_mapping_id": "4000304716"
                  },
                  {
                    "id": "4000304717",
                    "value": "India team",
                    "position": 2,
                    "type": null,
                    "dependent_ids": {},
                    "dependency_mapping_id": "4000304717"
                  }
                ],
                "field_options": {
                  "can_editable_be_changed": true,
                  "can_editable_be_changed_field_permission": true,
                  "can_required_be_changed": true,
                  "can_label_be_renamed": true,
                  "can_choices_be_customized": true,
                  "can_not_be_hidden": false,
                  "allow_fields_to_be_added": false,
                  "system_field": false
                },
                "hint": "holds sample team field value",
                "original_label": "sample sales team field",
                "original_placeholder": "",
                "default_value": null,
                "allow_clearing_default_value": true,
                "form_id": 3000000101,
                "quick_add_position": null
              },
              {
                "id": "ddbc1de1-ef3a-4c0c-bee1-f9d02b63eb26",
                "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
                "name": "cf_sample_radio_field",
                "label": "sample radio field",
                "placeholder": "",
                "type": "radio",
                "position": 6,
                "fields": [],
                "field_class": "CustomModule6",
                "required": false,
                "custom": true,
                "editable": true,
                "visible": true,
                "link": null,
                "choices": [
                  {
                    "id": "4000304718",
                    "value": "choice 1",
                    "position": 1,
                    "type": null,
                    "dependent_ids": {},
                    "dependency_mapping_id": "4000304718"
                  },
                  {
                    "id": "4000304719",
                    "value": "choice 2",
                    "position": 2,
                    "type": null,
                    "dependent_ids": {},
                    "dependency_mapping_id": "4000304719"
                  }
                ],
                "field_options": {
                  "can_editable_be_changed": true,
                  "can_editable_be_changed_field_permission": true,
                  "can_required_be_changed": true,
                  "can_label_be_renamed": true,
                  "can_choices_be_customized": true,
                  "can_not_be_hidden": false,
                  "allow_fields_to_be_added": false,
                  "system_field": false
                },
                "hint": "holds sample radio field",
                "original_label": "sample radio field",
                "original_placeholder": "",
                "default_value": null,
                "allow_clearing_default_value": true,
                "form_id": 3000000101,
                "quick_add_position": null
              },
              {
                "id": "d7a679c3-4f79-4a7d-86c1-79b804777625",
                "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
                "name": "cf_lookup_to_contact",
                "label": "lookup to contact",
                "placeholder": "",
                "type": "auto_complete",
                "position": 7,
                "fields": [],
                "field_class": "CustomModule6",
                "required": false,
                "custom": true,
                "editable": true,
                "visible": true,
                "link": "/search.json?include=contact&q=",
                "choices": [],
                "field_options": {
                  "lookup_type": "contact",
                  "lookup_prefetch_url": "/options_prefetch.json?include=contact&q[]=",
                  "can_editable_be_changed": true,
                  "can_editable_be_changed_field_permission": true,
                  "can_required_be_changed": true,
                  "can_label_be_renamed": true,
                  "can_choices_be_customized": false,
                  "can_not_be_hidden": false,
                  "allow_fields_to_be_added": false,
                  "system_field": false
                },
                "hint": "lookup to contact record",
                "original_label": "lookup to contact",
                "original_placeholder": "",
                "default_value": null,
                "allow_clearing_default_value": true,
                "form_id": 3000000101,
                "quick_add_position": null
              },
              {
                "id": "48fba048-30d6-48af-9b16-8d83dd62235f",
                "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
                "name": "cf_sample_multiselect_field",
                "label": "sample multiselect field",
                "placeholder": "Choose value(s)",
                "type": "multi_select_dropdown",
                "position": 8,
                "fields": [],
                "field_class": "CustomModule6",
                "required": false,
                "custom": true,
                "editable": true,
                "visible": true,
                "link": null,
                "choices": [
                  {
                    "id": "4000304720",
                    "value": "choice 1",
                    "position": 1,
                    "type": null,
                    "dependent_ids": {},
                    "dependency_mapping_id": "4000304720"
                  },
                  {
                    "id": "4000304721",
                    "value": "choice 2",
                    "position": 2,
                    "type": null,
                    "dependent_ids": {},
                    "dependency_mapping_id": "4000304721"
                  }
                ],
                "field_options": {
                  "can_editable_be_changed": true,
                  "can_editable_be_changed_field_permission": true,
                  "can_required_be_changed": true,
                  "can_label_be_renamed": true,
                  "can_choices_be_customized": true,
                  "can_not_be_hidden": false,
                  "allow_fields_to_be_added": false,
                  "system_field": false
                },
                "hint": "Holds sample multi select value",
                "original_label": "sample multiselect field",
                "original_placeholder": "",
                "default_value": null,
                "allow_clearing_default_value": true,
                "form_id": 3000000101,
                "quick_add_position": null
              },
              {
                "id": "5fae90a3-f62e-43fc-b749-fd25cddc5919",
                "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
                "name": "creator_id",
                "label": "Created by",
                "placeholder": "",
                "type": "auto_complete",
                "position": 9,
                "fields": [],
                "field_class": "CustomModule6",
                "required": false,
                "custom": false,
                "editable": false,
                "visible": true,
                "link": "/search.json?include=user&q=",
                "choices": [],
                "field_options": {
                  "lookup_type": "user",
                  "lookup_prefetch_url": "/options_prefetch.json?include=user&q[]=",
                  "can_editable_be_changed": false,
                  "can_editable_be_changed_field_permission": false,
                  "can_required_be_changed": false,
                  "can_label_be_renamed": false,
                  "can_choices_be_customized": false,
                  "can_not_be_hidden": false,
                  "allow_fields_to_be_added": false,
                  "system_field": true,
                  "default_display_label": "common.system"
                },
                "hint": "",
                "original_label": "creator_id",
                "original_placeholder": "creator_id",
                "default_value": null,
                "allow_clearing_default_value": true,
                "form_id": 3000000101,
                "quick_add_position": null
              },
              {
                "id": "b137ab88-ff71-436a-af36-176c633523a1",
                "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
                "name": "created_at",
                "label": "Created at",
                "placeholder": "",
                "type": "date_time",
                "position": 10,
                "fields": [],
                "field_class": "CustomModule6",
                "required": false,
                "custom": false,
                "editable": false,
                "visible": true,
                "link": null,
                "choices": [],
                "field_options": {
                  "can_editable_be_changed": false,
                  "can_editable_be_changed_field_permission": false,
                  "can_required_be_changed": false,
                  "can_label_be_renamed": false,
                  "can_choices_be_customized": false,
                  "can_not_be_hidden": false,
                  "allow_fields_to_be_added": false,
                  "system_field": true
                },
                "hint": "",
                "original_label": "created_at",
                "original_placeholder": "created_at",
                "default_value": null,
                "allow_clearing_default_value": true,
                "form_id": 3000000101,
                "quick_add_position": null
              },
              {
                "id": "afdc09de-32f0-4545-a7ab-204c219112b3",
                "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
                "name": "updater_id",
                "label": "Updated by",
                "placeholder": "",
                "type": "auto_complete",
                "position": 11,
                "fields": [],
                "field_class": "CustomModule6",
                "required": false,
                "custom": false,
                "editable": false,
                "visible": true,
                "link": "/search.json?include=user&q=",
                "choices": [],
                "field_options": {
                  "lookup_type": "user",
                  "lookup_prefetch_url": "/options_prefetch.json?include=user&q[]=",
                  "can_editable_be_changed": false,
                  "can_editable_be_changed_field_permission": false,
                  "can_required_be_changed": false,
                  "can_label_be_renamed": false,
                  "can_choices_be_customized": false,
                  "can_not_be_hidden": false,
                  "allow_fields_to_be_added": false,
                  "system_field": true
                },
                "hint": "",
                "original_label": "updater_id",
                "original_placeholder": "updater_id",
                "default_value": null,
                "allow_clearing_default_value": true,
                "form_id": 3000000101,
                "quick_add_position": null
              },
              {
                "id": "d847b595-167a-413e-ba78-89716fd78c76",
                "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
                "name": "updated_at",
                "label": "Updated at",
                "placeholder": "",
                "type": "date_time",
                "position": 12,
                "fields": [],
                "field_class": "CustomModule6",
                "required": false,
                "custom": false,
                "editable": false,
                "visible": true,
                "link": null,
                "choices": [],
                "field_options": {
                  "can_editable_be_changed": false,
                  "can_editable_be_changed_field_permission": false,
                  "can_required_be_changed": false,
                  "can_label_be_renamed": false,
                  "can_choices_be_customized": false,
                  "can_not_be_hidden": false,
                  "allow_fields_to_be_added": false,
                  "system_field": true
                },
                "hint": "",
                "original_label": "updated_at",
                "original_placeholder": "updated_at",
                "default_value": null,
                "allow_clearing_default_value": true,
                "form_id": 3000000101,
                "quick_add_position": null
              },
              {
                "id": "9ea93d6c-ddfb-4e72-a996-60543f816581",
                "parent_id": "076f9e4e-1618-49f2-bfb0-9c37889ecf92",
                "name": "recent_note",
                "label": "Recent note",
                "placeholder": "",
                "type": "paragraph",
                "position": 13,
                "fields": [],
                "field_class": "CustomModule6",
                "required": false,
                "custom": false,
                "editable": false,
                "visible": true,
                "link": null,
                "choices": [],
                "field_options": {
                  "can_editable_be_changed": false,
                  "can_editable_be_changed_field_permission": false,
                  "can_required_be_changed": false,
                  "can_label_be_renamed": false,
                  "can_choices_be_customized": false,
                  "can_not_be_hidden": false,
                  "allow_fields_to_be_added": false,
                  "system_field": true
                },
                "hint": "",
                "original_label": "recent_note",
                "original_placeholder": "recent_note",
                "default_value": null,
                "allow_clearing_default_value": true,
                "form_id": 3000000101,
                "quick_add_position": null
              }
            ],
            "field_class": "CustomModule6",
            "required": false,
            "custom": false,
            "editable": true,
            "visible": true,
            "link": null,
            "choices": [],
            "field_options": {
              "can_editable_be_changed": false,
              "can_editable_be_changed_field_permission": false,
              "can_required_be_changed": false,
              "can_label_be_renamed": true,
              "can_choices_be_customized": false,
              "can_not_be_hidden": false,
              "allow_fields_to_be_added": true,
              "system_field": false
            },
            "hint": "",
            "original_label": "basic_information",
            "original_placeholder": "basic_information",
            "default_value": null,
            "allow_clearing_default_value": true,
            "form_id": 3000000101,
            "quick_add_position": null
          },
          {
            "id": "5392c9e5-62f3-4963-b998-98061d1d1c9c",
            "parent_id": null,
            "name": "hidden_fields",
            "label": "Hidden fields",
            "placeholder": "",
            "type": "section",
            "position": 2,
            "fields": [],
            "field_class": "CustomModule6",
            "required": false,
            "custom": false,
            "editable": true,
            "visible": false,
            "link": null,
            "choices": [],
            "field_options": {
              "can_editable_be_changed": false,
              "can_editable_be_changed_field_permission": false,
              "can_required_be_changed": false,
              "can_label_be_renamed": true,
              "can_choices_be_customized": false,
              "can_not_be_hidden": false,
              "allow_fields_to_be_added": true,
              "system_field": false
            },
            "hint": "",
            "original_label": "hidden_fields",
            "original_placeholder": "hidden_fields",
            "default_value": null,
            "allow_clearing_default_value": true,
            "form_id": 3000000101,
            "quick_add_position": null
          }
        ],
        "grouped_mandatory_fields": []
      }
    ],
    "meta": {
      "latest_forms_version_data": {
        "cm_10th_module": "1650910864",
        "cm_folders": "1650910864",
        "cm_new1": "1650910864",
        "cm_property": "1650912192",
        "cm_sathish": "1650910864",
        "cm_sathishnew": "1650910864",
        "cm_student": "1650910864",
        "cm_support_ticket": "1650910864",
        "cm_suriya_module": "1650910864",
        "contacts": "1650910864",
        "deals": "1650910864",
        "leads": "1650910864",
        "products": "1650910864",
        "sales_accounts": "1650910864",
        "sales_activities": "1650910864"
      }
    }
  }
EXPAND ↓

Records in Custom Modules

If you have a custom module (like “Loans”), records are the individual loans you create, update, delete and keep track of in the CRM.

Headers
Key Value
Authorization Token token=<user api token>

Create a record

If you have a custom module (like “Loans”), this API helps you create a loan.

post
api/custom_module/[entity_name]

Note:
Name and owner_id fields are default fields in all custom modules. In Admin Settings > Custom Modules, if you mark Owner_id and/or any custom fields as required fields, you’ll need to fill them up when you create a record.

Request Parameter Definitions
Parameter Type Description
name* string Name of the record in the custom module
owner_idμ integer Owner of the record in the custom module. If left empty, sales owner will be empty.
custom_fieldμ hash Contains the list of custom fields with which you want to create a record in custom module.
Custom field hash is given below
cf_sample_text_fieldμ string Value of text custom field in the record.
cf_sample_number_fieldμ integer Value of number custom field in the record
cf_sample_sales_team_fieldμ string Choice of custom dropdown field in the record
cf_sample_radio_fieldμ string Choice of custom radio button field in the record
cf_lookup_to_contactμ string ID of the entity that is being looked up (like a contact or account)
cf_sample_multiselect_fieldμ string Choice of custom multiselect field in the record
* Mandatory fields for creating custom module record.
∑ This field is unique.
μ This field is optional.
Sample code | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d
    '{
      "cm_property": {
        "name": "Villa 1",
        "owner_id": 3000034021,
        "custom_field": {
          "cf_sample_text_field": "sample value 1",
          "cf_sample_number_field": 12345,
          "cf_sample_sales_team_field": "India team",
          "cf_sample_radio_field": "choice 1",
          "cf_lookup_to_contact": "3007551456",
          "cf_sample_multiselect_field": "choice 2"
        }
      }
    }'
  -X POST "https://domain.myfreshworks.com/crm/sales/api/custom_module/cm_property"
EXPAND ↓
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
{
    "cm_property": {
      "id": 3000000001,
      "name": "Villa 1",
      "owner_id": 3000034021,
      "custom_field": {
        "cf_sample_text_field": "sample value 1",
        "cf_sample_number_field": 12345,
        "cf_sample_sales_team_field": "India team",
        "cf_sample_radio_field": "choice 1",
        "cf_lookup_to_contact": 3007551456,
        "cf_sample_multiselect_field": "choice 2"
      },
      "created_at": "2022-04-25T18:44:20Z",
      "creator_id": 3000034021,
      "updated_at": "2022-04-25T18:44:20Z",
      "updater_id": null,
      "avatar": null,
      "recent_note": null,
      "links": {
        "document_associations": "/custom_module/cm_property/3000000001/document_associations",
        "notes": "/custom_module/cm_property/3000000001/notes?include=creater"
      }
    }
  }
EXPAND ↓

Get a list of all records

If you have a custom module (like “Loans”), this API helps you fetch a list of all the loans created so far.

get
api/custom_module/[entity_name]/[id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.myfreshworks.com/crm/sales/api/custom_module/cm_property/3000000001"
EXPAND ↓
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
{
    "cm_property": {
      "id": 3000000001,
      "name": "Villa 1",
      "owner_id": 3000034021,
      "custom_field": {
        "cf_sample_text_field": "sample value 1",
        "cf_sample_number_field": 12345,
        "cf_sample_sales_team_field": "India team",
        "cf_sample_radio_field": "choice 1",
        "cf_lookup_to_contact": 3007551456,
        "cf_sample_multiselect_field": "choice 2"
      },
      "created_at": "2022-04-25T18:44:20Z",
      "creator_id": 3000034021,
      "updated_at": "2022-04-25T18:44:20Z",
      "updater_id": null,
      "avatar": null,
      "recent_note": null,
      "links": {
        "document_associations": "/custom_module/cm_property/3000000001/document_associations",
        "notes": "/custom_module/cm_property/3000000001/notes?include=creater"
      }
    }
  }
EXPAND ↓

Update a record

If you have a custom module (like “Loans”), this API helps you update the details of a loan.

put
api/custom_module/[entity_name]/[id]
Sample code | Curl
Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d
  '{
      "cm_property": {
        "name": "Villa 1 - phase 1",
        "owner_id": 3000034021,
        "custom_field": {
          "cf_sample_text_field": "sample value 1",
          "cf_sample_number_field": 12345,
          "cf_sample_sales_team_field": "India team",
          "cf_sample_radio_field": "choice 1",
          "cf_lookup_to_contact": 3007551456,
          "cf_sample_multiselect_field": "choice 2"
        }
      }
    }'
  -X PUT "https://domain.myfreshworks.com/crm/sales/api/custom_module/cm_property/3000000001"
EXPAND ↓
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
{
    "cm_property": {
      "id": 3000000001,
      "name": "Villa 1 - phase 1",
      "owner_id": 3000034021,
      "custom_field": {
        "cf_sample_text_field": "sample value 1",
        "cf_sample_number_field": 12345,
        "cf_sample_sales_team_field": "India team",
        "cf_sample_radio_field": "choice 1",
        "cf_lookup_to_contact": 3007551456,
        "cf_sample_multiselect_field": "choice 2"
      },
      "created_at": "2022-04-25T18:44:20Z",
      "creator_id": 3000034021,
      "updated_at": "2022-04-25T18:59:40Z",
      "updater_id": 3000034021,
      "avatar": null,
      "recent_note": null,
      "links": {
        "document_associations": "/custom_module/cm_property/3000000001/document_associations",
        "notes": "/custom_module/cm_property/3000000001/notes?include=creater"
      }
    }
  }
EXPAND ↓

Delete a record

If you have a custom module (like “Loans”), this API helps you delete a loan.

delete
api/custom_module/[entity_name]/[id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/custom_module/cm_property/3000000001"
EXPAND ↓
Response 
1
{ "message": "cm_property deleted successfully." }
EXPAND ↓

Forget a record

If you have a custom module (like “Loans”), this API helps you permanently delete (i.e. “forget”) a loan.

delete
api/custom_module/[entity_name]/[id]/forget
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X DELETE "https://domain.myfreshworks.com/crm/sales/api/custom_module/cm_property/3000000002/forget"
EXPAND ↓
Response 
1
True
EXPAND ↓

Clone a record

If you have a custom module (like “Loans”), this API helps you clone a loan.

post
api/custom_module/[entity_name]/[id]/clone

Name and owner_id fields are default fields in all custom module.

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{ "cm_property": { "name": "Villa 1 - phase 2", "owner_id": 3000034021, "custom_field": { "cf_sample_text_field": null, "cf_sample_number_field": null, "cf_sample_sales_team_field": null, "cf_sample_radio_field": null, "cf_lookup_to_contact": null, "cf_sample_multiselect_field": null } } }' -X POST "https://domain.myfreshworks.com/crm/sales/api/custom_module/cm_property/3000000003/clone"
EXPAND ↓
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
{
    "cm_property": {
      "id": 3000000004,
      "name": "Villa 1 - phase 2",
      "owner_id": 3000034021,
      "custom_field": {
        "cf_sample_text_field": null,
        "cf_sample_number_field": null,
        "cf_sample_sales_team_field": null,
        "cf_sample_radio_field": null,
        "cf_lookup_to_contact": null,
        "cf_sample_multiselect_field": null
      },
      "created_at": "2022-04-25T19:09:20Z",
      "creator_id": 3000034021,
      "updated_at": "2022-04-25T19:09:20Z",
      "updater_id": null,
      "avatar": null,
      "recent_note": null,
      "links": {
        "document_associations": "/custom_module/cm_property/3000000004/document_associations",
        "notes": "/custom_module/cm_property/3000000004/notes?include=creater"
      }
    }
  }
EXPAND ↓

Bulk-delete records

If you have a custom module (like “Loans”), this API helps you bulk-delete a selected number of loans.

post
api/custom_module/[entity_name]/bulk_destroy
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"selected_ids":["3000000004","3000000003"]}' -X POST "https://domain.myfreshworks.com/crm/sales/api/custom_module/cm_property/bulk_destroy"
EXPAND ↓
Response 
1
{ "message": "2 Properties deleted." }
EXPAND ↓

Enter your Freshsales domain and username/password and the CURL commands will become executable.

Help and Support
Send us a message
Chat with us