CRM API Reference

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 Freshsales account using your API key.

  1. API key

    Each user in Freshsales 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.freshsales.io/api/leads/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:

https://your_crm_domain_name/api/resource_name

For example, if you are Rebecca Moris and you’d like to fetch the contact with id 144 from your account "widgetz.freshsales.io", the syntax would be

https://widgetz.freshsales.io/api/contacts/144

Note:
We’ve shortened the API resource URLs throughout this document by omitting the domain name, meaning, /api/leads is actually a shorter version of https://domain.freshsales.io/api/leads

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 lead's owner within the lead 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.freshsales.io/apileads/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"
	}],
	lead: {
		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: "/leads/1/conversations?include=email_conversation_recipients,targetable,phone_number,phone_caller,note,user&per_page=3",
			activities: "/leads/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 lead 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 lead with an invalid ID will return a HTTP 404 status code to let you know that no such lead 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/designations Fetch all entity team designations in Freshasles.
Will give ID, designation name.

Leads

A lead is a prospect who has expressed interest in your product by signing up for a trial or subscribing to your newsletter etc. Using the API’s you can do the following with lead data,

ATTRIBUTE TYPE DESCRIPTION
id number Unique ID of the lead
first_name string First name of the lead
last_name string Last name of the lead
subscription_status Array of hashes Status of subscription that the contact is in
job_title string Designation of the lead in the company he belongs to
emailπ†† string Primary email address of the lead
emailsπ Array of hashes Email addresses of the lead
work_number string Work phone number of the lead
mobile_number∑π string Mobile phone number of the lead
address string Address of the lead
city string City that the lead belongs to
state string State that the lead belongs to
zipcode string Zipcode of the region that the lead belongs to
country string Country that the lead belongs to
lead_stage_idΩ number ID of the lead stage that the lead belongs to
lead_reason_idΩ number ID of the lead reason - Reason to unqualify the lead
Can be set only if the lead is in "Unqualified" stage.
lead_source_idΩ number ID of the source where lead came from
owner_idΩ number ID of the user to whom the lead has been assigned
medium string The medium that led your lead to your website/ web app
campaign_idΩ number The campaign that led your lead to your web app.
keyword string The keywords that the lead used to reach your website/web app
time_zone string Timezone that the lead belongs to
facebook string Facebook account of the lead
twitterπ string Twitter account of the lead
linkedin string LinkedIn account of the lead
territory_idΩ number ID of the territory that the lead belongs to
company[name]† string Name of the company that the lead belongs to
company[address] string Address of the company that the lead belongs to
company[city] string City that the lead’s company belongs to
company[state] string State that the leads’ company belongs to
company[zipcode] string Zipcode of the region that the lead’s company belongs to
company[country] string Country that the lead’s company belongs to
company[industry_type_id]Ω number ID of the industry that the lead’s company belongs to
company[business_type_id]Ω number ID of the business that the lead’s company belongs to
company[number_of_employees] number Number of employees in the lead’s company
company[annual_revenue] decimal (18,0) Annual revenue of the lead’s company
company[website] string Website of the lead’s company
company[phone] string Phone number of the lead’s company
deal[name] string Name of the lead’s deal
deal[amount] decimal (15,2) Value of the lead’s deal
deal[currency_id] number ID of the currency that the lead’s deal belongs to
deal[base_currency_amount] decimal (19,4) Value of the lead's deal amount in base currency
deal[expected_close] date The date when the deal is expected to close
deal[deal_product_id]Ω number ID of the product that the lead’s deal belongs to(in a multi product company)
created_at datetime Lead creation timestamp
updated_at datetime Lead updated timestamp
* Mandatory fields for creating lead.
π Either Email/Mobile/Twitter ID is required to create a lead.
∑ This field is unique.
† 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
Properties:
Company[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 a Lead

Using this API, you’d be able to create leads.

post
/api/leads
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"lead":{"first_name":"Eric", "last_name":"Sampleton (sample)", "mobile_number":"1-926-652-9503", "company": {"name":"Widgetz.io (sample)"} }}' -X POST "https://domain.freshsales.io/api/leads"
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
{
	"lead": {
		"id": 2,
		"job_title": null,
		"email": null,
		"work_number": null,
		"mobile_number": "1-926-652-9504",
		"address": null,
		"city": null,
		"state": null,
		"zipcode": null,
		"country": null,
		"time_zone": null,
		"display_name": "Eric Sampleton (sample)",
		"avatar": null,
		"keyword": null,
		"medium": null,
		"last_seen": null,
		"last_contacted": null,
		"lead_score": 0,
		"stage_updated_time": "2016-05-31T09:26:56Z",
		"first_name": "Eric",
		"last_name": "Sampleton (sample)",
		"company": {
			"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,
			"industry_type_id": null,
			"business_type_id": null
		},
		"deal": null,
		"links": {
			"conversations": "/leads/2/conversations?include=email_conversation_recipients,targetable,phone_number,phone_caller,note,user&per_page=3",
			"activities": "/leads/2/activities"
		},
		"updated_at": "2016-05-31T09:26:56Z",
		"facebook": null,
		"twitter": null,
		"linkedin": null
	}
}
EXPAND ↓

Additional Examples

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

Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"lead":{"first_name":"Eric", "last_name":"Sampleton (sample)", "mobile_number":"1-926-652-9504", "company": {"name":"Widgetz.io (sample)"}, "custom_field": {"cf_primary": true} }}' -X POST 'https://domain.freshsales.io/api/leads'
EXPAND ↓

2. Create a lead with Company name
If you’d like to create a lead with its Company name, use this API.

Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"lead":{"first_name":"Eric", "last_name":"Sampleton (sample)", "mobile_number":"1-926-652-9503", "company": {"name":"Widgetz.io (sample)"} }}' -X POST 'https://domain.freshsales.io/api/leads'
EXPAND ↓

3. Create a lead with Deal
If you’d like to create a lead with a deal, use this API.

Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"lead":{"first_name":"Eric", "last_name":"Sampleton (sample)", "mobile_number":"1-926-652-9503", "company": {"name":"Widgetz.io (sample)"}, "deal":{"name":"Sample Deal", "amount": 15678} }}' -X POST 'https://domain.freshsales.io/api/leads'
EXPAND ↓

View a Lead

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

get
/api/leads/[id]

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

Embed Handle
owner "api/leads/[id]?include=owner
Will return the owner id, name and email"
creater "api/leads/[id]?include=creater
Will return the creater id, name and email"
updater "api/leads/[id]?include=updater
Will return the updater id, name and email"
source "api/leads/[id]?include=source
Will return the id and name of the source"
lead_stage "api/leads/[id]?include=lead_stage
Will return the id and name of the lead stage"
lead_reason "api/leads/[id]?include=lead_reason
Will return the id and name of the lead reason"
territory "api/leads/[id]?include=territory
Will return the id and name of the territory"
campaign "api/leads/[id]?include=campaign
Will return the id and name of the campaign"
tasks "api/leads/[id]?include=tasks
Will return the task id, title, due_date, status and owner_id"
appointments "api/leads/[id]?include=appointments
Will return the appointment id, title, time_zone, from_date, end_date and creater_id"
notes "api/leads/[id]?include=notes
Will return the note id, description and creater_id"
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.freshsales.io/api/leads/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
{
	"lead": {
		"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": 2000010568,
			"name": "Widgetz.io (sample)",
			"address": "160-6802 Aliquet Rd.",
			"city": "New Haven",
			"state": "Connecticut",
			"zipcode": "68089",
			"country": "United States",
			"number_of_employees": null,
			"annual_revenue": null,
			"website": "widgetz.io",
			"phone": "503-615-3947",
			"industry_type_id": 2492,
			"business_type_id": 354
		},
		"deal": null,
		"links": {
			"conversations": "/leads/1/conversations?include=email_conversation_recipients%2Ctargetable%2Cphone_number%2Cphone_caller%2Cnote%2Cuser\u0026per_page=3",
			"activities": "/leads/1/activities"
		},
		"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"
	}
}
EXPAND ↓

Convert a Lead

This API allows you to convert a lead to a contact.

post
api/leads/[id]/convert

Note:
It is mandatory to send last_name and company[name] in the request for converting a Lead.

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"lead":{"first_name":"Jane", "last_name":"Sampleton (sample)", "email": "janesampleton@gmail.com", "company": {"name":"Widgetz.io (sample)"} }}' -X POST "https://domain.freshsales.io/api/leads/1/convert"
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
{
   "contact":{
      "id":1,
      "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",
      "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",
      "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-09T23:07:58+05:30",
      "keyword":null,
      "medium":null,
      "facebook":null,
      "twitter":null,
      "linkedin":null
   },
   "meta":{
      "success_msg":"Lead converted successfully"
   }
}
EXPAND ↓

Creating a deal while converting a Lead

If you’d like to create a deal while you convert a lead to a contact, use the following API

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"lead":{"first_name":"Jane", "last_name":"Sampleton (sample)", "email": "janesampleton@gmail.com", "company": {"name":"Widgetz.io (sample)"}, "deal": {"name": "Sample Deal", "amount": "11000"} }}' -X POST "https://domain.freshsales.io/api/leads/1/convert"
EXPAND ↓

List All Leads

Using this API, you’d be able to fetch a list of leads.

get
/api/leads/view/[view_id]

You can filter your leads and also sort them to get a list of specific leads

1. Filtering Leads

If you’d like to view specific leads, use views to fetch. To fetch leads from a view, first fetch the view id using the filters API and then use the view API to fetch.

get
/api/leads/filters

Filter API

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.freshsales.io/api/leads/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
84
85
86
87
88
89
90
91
92
93
94
{
   "filters":[
      {
         "id":1,
         "name":"My Leads",
         "model_class_name":"Lead",
         "user_id":-1,
         "is_default":true,
         "is_public":true,
         "updated_at":"2016-05-31T03:32:55-07:00"
      },
      {
         "id":2,
         "name":"New Leads",
         "model_class_name":"Lead",
         "user_id":-1,
         "is_default":true,
         "is_public":true,
         "updated_at":"2016-05-31T03:32:55-07:00"
      },
      {
         "id":3,
         "name":"Unassigned Leads",
         "model_class_name":"Lead",
         "user_id":-1,
         "is_default":true,
         "is_public":true,
         "updated_at":"2016-05-31T03:32:55-07:00"
      },
      {
         "id":4,
         "name":"All Leads",
         "model_class_name":"Lead",
         "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":"Lead",
         "user_id":-1,
         "is_default":true,
         "is_public":true,
         "updated_at":"2016-05-31T03:32:55-07:00"
      },
      {
         "id":6,
         "name":"My Territory Leads",
         "model_class_name":"Lead",
         "user_id":-1,
         "is_default":true,
         "is_public":true,
         "updated_at":"2016-05-31T03:32:55-07:00"
      },
      {
         "id":7,
         "name":"Never Contacted",
         "model_class_name":"Lead",
         "user_id":-1,
         "is_default":true,
         "is_public":true,
         "updated_at":"2016-05-31T03:32:55-07:00"
      },
      {
         "id":8,
         "name":"Hot Leads",
         "model_class_name":"Lead",
         "user_id":-1,
         "is_default":false,
         "is_public":true,
         "updated_at":"2016-05-31T03:32:55-07:00"
      },
      {
         "id":9,
         "name":"Warm Leads",
         "model_class_name":"Lead",
         "user_id":-1,
         "is_default":false,
         "is_public":true,
         "updated_at":"2016-05-31T03:32:55-07:00"
      },
      {
         "id":10,
         "name":"Cold Leads",
         "model_class_name":"Lead",
         "user_id":-1,
         "is_default":false,
         "is_public":true,
         "updated_at":"2016-05-31T03:32:55-07:00"
      }
   ]
}
EXPAND ↓

View API

This API is designed for retrieving a defined set of records. For the retrieval of all available records, please utilize the Scroll API

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.freshsales.io/api/leads/view/4"
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
{
"leads": [{
  "id": 1,
  "job_title": "Sales Manager",
  "lead_score": 96,
  "last_contacted_mode": "email_incoming",
  "email": "janesampleton@gmail.com",
  "work_number": "(368) 493-2360",
  "mobile_number": "1-726-652-9503",
  "display_name": "Jane Sampleton (sample)",
  "avatar": "https://lh3.googleusercontent.com/-BomfmRA2WqA/Vi4cXSJzXPI/AAAAAAAAABg/LO4MyF96ZQ4/w140-h140-p/Image1.png",
  "company": {
    "id": 1,
    "name": "Widgetz.io (sample)"
  },
  "last_contacted": "2016-02-08T02:36:06-08:00",
  "stage_updated_time": "2016-02-10T02:36:06-08:00",
  "first_name": "Jane",
  "last_name": "Sampleton (sample)",
  "city": "Glendale",
  "country": "USA",
  "created_at": "2016-02-04T02:36:05-08:00",
  "updated_at": "2016-05-31T03:33:41-07:00"
}],
"meta": {
  "total_pages": 1,
  "total": 1
}
}
EXPAND ↓

2. Sort Leads

You can use the parameters sort and sort_type to sort leads. The lead fields that you can use to sort are
  • lead_score
  • created_at
  • updated_at
  • lead_stage
  • last_contacted
You can sort the leads in an ascending or descending order too using the parameter sort_type and choosing between
  • asc
  • desc

3. Scroll Leads

To scroll through all leads in ascending order by their ID, use last_fetched_id and has_next_page to iterate to the next records, To fetch a specific number of records, include the limit in the query path.

get
/api/leads/scroll/[view_id]

Scroll API

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.freshsales.io/api/leads/scroll/199?limit=2&last_fetched_id=5"
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
{
  "leads": [{
      "id": 5,
      "job_title": "CEO",
      "lead_score": 0,
      "last_contacted_mode": "email_incoming",
      "email": "lannie.schaden@johnston.test",
      "work_number": "(473)-160-8261",
      "mobile_number": "1-926-555-9503",
      "display_name": "Monahan",
      "avatar": "https://lh3.googleusercontent.com/-BomfmRA2WqA/Vi4cXSJzXPI/AAAAAAAAABg/LO4MyF96ZQ4/w140-h140-p/Image1.png",
      "company": {
        "id": 1,
        "name": "Widgetz.io (sample)"
      },
      "last_contacted": "2024-06-25 06:57:50",
      "stage_updated_time": "2024-06-27T10:38:35Z",
      "first_name": "James",
      "last_name": "Monahan",
      "city": "San Diego",
      "country": "USA",
      "created_at": "2024-06-27T10:38:35Z",
      "updated_at": "2024-06-27T10:38:43Z"
    },
    {
      "id": 6,
      "job_title": "Sales Manager",
      "lead_score": 0,
      "last_contacted_mode": "email_incoming",
      "email": "claretha.beer@quigley-barrows.test",
      "work_number": "(473)-160-8261",
      "mobile_number": "1-926-555-9503",
      "display_name": "Tremblay",
      "avatar": "https://lh3.googleusercontent.com/-BomfmRA2WqA/Vi4cXSJzXPI/AAAAAAAAABg/LO4MyF96ZQ4/w140-h140-p/Image1.png",
      "company": {
        "id": 1,
        "name": "Widgetz.io (sample)"
      },
      "last_contacted": "2016-02-08T02:36:06-08:00",
      "stage_updated_time": "2024-06-27T10:38:36Z",
      "first_name": "James",
      "last_name": "Tremblay",
      "city": "Glendale",
      "country": "USA",
      "created_at": "2024-06-27T10:38:36Z",
      "updated_at": "2024-06-27T10:38:44Z"
    }],
    "meta": {
      "last_fetched_id": 6,
      "has_next_page": true,
      "avatar_data": {"Lead": {"5": null, "6": null}}
    }
  }
EXPAND ↓

Update a Lead

Using this API, you’d be able to update the information of a lead.

put
/api/leads/[id]
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"lead":{"mobile_number":"1-726-652-9503", "custom_field": {"cf_primary": true} }}' -X PUT "https://domain.freshsales.io/api/leads/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
{
	"lead": {
		"id": 1,
		"job_title": "Sales Manager",
		"email": "janesampleton@gmail.com",
		"work_number": "(368) 493-2360",
		"mobile_number": "1-726-652-9503",
		"address": "604-5854 Beckford St.",
		"city": "Glendale",
		"state": "Arizona",
		"zipcode": "100652",
		"country": "USA",
		"time_zone": null,
		"display_name": "Jane Sampleton (sample)",
		"avatar": "https://lh3.googleusercontent.com/-BomfmRA2WqA/Vi4cXSJzXPI/AAAAAAAAABg/LO4MyF96ZQ4/w140-h140-p/Image1.png",
		"keyword": "B2B Success",
		"medium": "Blog",
		"last_seen": "2016-02-10T02:36:06-08:00",
		"last_contacted": "2016-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": 2492,
			"business_type_id": 354
		},
		"deal": null,
		"links": {
			"conversations": "/leads/1/conversations?include=email_conversation_recipients%2Ctargetable%2Cphone_number%2Cphone_caller%2Cnote%2Cuser\u0026per_page=3",
			"activities": "/leads/1/activities"
		},
		"custom_field": {
			"cf_primary": true
		},
		"updated_at": "2016-05-31T03:33:41-07:00",
		"facebook": null,
		"twitter": "https://twitter.com/janesampleton",
		"linkedin": "http://linkedin.com/pub/jane-sampleton/109/39/b0"
	}
}
EXPAND ↓

Update Lead Team

This API allows you to add/update/remove team members of the lead team.

post
/api/leads/[id]/manage_team_members
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"team_users":[{"user_id":18813,"designation_id": 33},{"user_id": 18814, "designation_id": 34}]}' -X POST "https://domain.freshsales.io/api/leads/10/manage_team_members"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "team_users": [
        {
            "entity_id": 16273,
            "user_id": 18813,
            "designation_id": 33,
            "created_at": "2024-09-03T10:40:21Z",
            "updated_at": "2024-09-03T10:40:21Z"
        },
        {
            "entity_id": 16273,
            "user_id": 18814,
            "designation_id": 34,
            "created_at": "2024-09-03T10:40:21Z",
            "updated_at": "2024-09-03T10:40:21Z"
        }
    ]
  }
EXPAND ↓

Note: To remove a specific user, set the _destroy attribute to true, along with the other required details.

Additional Example

If you want to remove team members from the lead team, use the _destroy attribute.
In the below example, user ID 18814 will be removed once the API is called.

Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"team_users":[{"user_id":18813,"designation_id": 33},{"user_id": 18814, "designation_id": 34, "_destroy": true}]}' -X POST "https://domain.freshsales.io/api/leads/10/manage_team_members"
EXPAND ↓

Upsert a Lead

This API allows you to create or update a lead 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/leads/upsert
ATTRIBUTE TYPE DESCRIPTION
unique_identifier∑ string Field based on which entity needs to be created or updated
lead hash lead 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"}, "lead":{"first_name":"James", "last_name":"Sampleton (sample)", "mobile_number":"1-926-555-9503"}}' -X POST "https://domain.freshsales.io/api/leads/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
{
	"lead": {
		"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_leaded": null,
		"open_deals_amount": "0.0",
		"links": {
			"conversations": "/leads/1/conversations?include=email_conversation_recipients%2Ctargetable%2Cphone_number%2Cphone_caller%2Cnote%2Cuser\u0026page=1\u0026per_page=3",
			"activities": "/leads/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 Lead

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

post
/api/leads/bulk_upsert
ATTRIBUTE TYPE DESCRIPTION
leads Array of hashes Each of the hash values should be in this format:
{"unique_identifier_name": "unique_identifier_value", "data": {} }
data corresponds to lead 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 '{"leads":[{"emails": "jamessampleton@gmail.com", "data":{"first_name":"James", "last_name":"Sampleton (sample)"}}, {"id": "123", "data":{"first_name":"Steve"}}]}' -X POST "https://domain.freshsales.io/api/leads/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.freshsales.io/api/job_statuses/<job_id>"
}
EXPAND ↓

Bulk assign Owner

If you’d like to assign an owner to a list of leads, this API would help you achieve that.

post
/api/leads/bulk_assign_owner
ATTRIBUTE TYPE DESCRIPTION
selected_ids[] Array of numbers An array of lead 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.freshsales.io/api/leads/bulk_assign_owner"
EXPAND ↓
Response 
1
2
3
4
5
6
7
{
	"leads": [{
		"1": true
	}, {
		"2": true
	}]
}
EXPAND ↓

Clone a Lead

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

post
/api/leads/[id]/clone
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{}' -X POST "https://domain.freshsales.io/api/leads/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
37
38
39
40
41
42
43
44
45
46
47
48
49
{
	"lead": {
		"id": 2,
		"job_title": null,
		"email": null,
		"work_number": null,
		"mobile_number": "1-926-652-9504",
		"address": null,
		"city": null,
		"state": null,
		"zipcode": null,
		"country": null,
		"time_zone": null,
		"display_name": "Eric Sampleton (sample)",
		"avatar": null,
		"keyword": null,
		"medium": null,
		"last_seen": null,
		"last_contacted": null,
		"lead_score": 0,
		"stage_updated_time": "2016-05-31T09:26:56Z",
		"first_name": "Eric",
		"last_name": "Sampleton (sample)",
		"company": {
			"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,
			"industry_type_id": null,
			"business_type_id": null
		},
		"deal": null,
		"links": {
			"conversations": "/leads/2/conversations?include=email_conversation_recipients,targetable,phone_number,phone_caller,note,user&per_page=3",
			"activities": "/leads/2/activities"
		},
		"updated_at": "2016-05-31T09:26:56Z",
		"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 lead will be copied to the new lead. If you would like to pass certain properties for the new lead, you can do it similar to the Create A Lead API.

Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"lead":{"first_name":"Eric", "last_name":"Sampleton (sample)", "mobile_number":"1-926-652-9504", "company": {"name":"Widgetz.io (sample)"} }}' -X POST 'https://domain.freshsales.io/api/leads/1/clone'
EXPAND ↓

Delete a Lead

This API allows you to delete a lead.

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

Forget a Lead

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

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

Bulk Delete Leads

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

post
/api/leads/bulk_destroy
ATTRIBUTE TYPE DESCRIPTION
selected_ids[] Array of numbers An array of lead 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.freshsales.io/api/leads/bulk_destroy"
EXPAND ↓
Response 
1
2
3
4
5
6
7
{
	"leads": [{
		"1": true
	}, {
		"2": true
	}]
}
EXPAND ↓

List all Lead fields

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

get
/api/settings/leads/fields

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

get
/api/settings/leads/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 lead fields.

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.freshsales.io/api/settings/leads/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
{
   "fields":[
      {
         "id":2000002166,
         "label":"First name",
         "name":"first_name",
         "type":"text",
         "default":true,
         "actionable":false,
         "position":1,
         "choices":[

         ],
         "base_model":"Lead",
         "required":false
      },
      {
         "id":2000002167,
         "label":"Last name",
         "name":"last_name",
         "type":"text",
         "default":true,
         "actionable":false,
         "position":2,
         "choices":[

         ],
         "base_model":"Lead",
         "required":true
      },
      {
         "id":2000002168,
         "label":"Job title",
         "name":"job_title",
         "type":"text",
         "default":true,
         "actionable":false,
         "position":3,
         "choices":[

         ],
         "base_model":"Lead",
         "required":false
      },
      {
         "id":2000002170,
         "label":"Email",
         "name":"email",
         "type":"text",
         "default":true,
         "actionable":false,
         "position":5,
         "choices":[

         ],
         "base_model":"Lead",
         "required":false
      },
      {
         "id":2000002171,
         "label":"Work",
         "name":"work_number",
         "type":"text",
         "default":true,
         "actionable":false,
         "position":6,
         "choices":[

         ],
         "base_model":"Lead",
         "required":false
      },
      ...
    ]
}
EXPAND ↓

List all Activites

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

get
/api/leads/[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.freshsales.io/api/leads/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
{
	"users": [{
		"id": 1,
		"display_name": "Sample Admin",
		"email": "admin@yourcompany.com"
	}],
	"activities": [{
		"composite_id": "1_PAGE_VIEWS",
		"action_data": "Visited pricing page",
		"action_type": "PAGE_VIEWS",
		"created_at": "2016-02-10T02:36:06-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": "2_APP_EVENTS",
		"action_data": {
			"name": "Created a ticket",
			"count": 1
		},
		"action_type": "APP_EVENTS",
		"created_at": "2016-02-10T02:36:06-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": "3_EMAIL_REPLIED",
		"action_data": {
			"email_id": 1,
			"subject": "(Sample) Re: Require a demo?"
		},
		"action_type": "EMAIL_REPLIED",
		"created_at": "2016-02-10T02:36:05-08:00",
		"user_activity": false,
		"targetable_type": "Lead",
		"targetable_id": 1,
		"actionable_type": "Email::Conversation",
		"actionable_id": 1,
		"targetable_name": null,
		"user_id": 1
	}]
}
EXPAND ↓

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 lead
work_number string Work phone number 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 string Status of subscription that the contact is in.
medium string The medium that led your contact to your website/ web app
campaign_idΩ number The campaign that led your contact to your web app.
keyword string The keywords that the contact used to reach your website/web app
time_zone string Timezone that the contact belongs to
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.
* 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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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)
This API is designed for retrieving a defined set of records. For the retrieval of all available records, please utilize the Scroll API

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.freshsales.io/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

3. Scroll Contacts

To scroll through all contacts in ascending order by their ID, use last_fetched_id and has_next_page to iterate to the next records, To fetch a specific number of records, include the limit in the query path.

get
/api/contacts/scroll/[view_id]

Scroll API

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.freshsales.io/api/contacts/scroll/211?limit=2&last_fetched_id=5"
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": [{
		"id": 2521,
		"job_title": "CEO",
		"lead_score": 99,
		"email": "jamessampleton@gmail.com",
		"work_number": "(473)-160-8261",
		"mobile_number": "1-926-555-9503",
		"open_deals_amount": "7000.0",
		"display_name": "James Sampleton (sample)",
		"avatar": "https://img.fullcontact.com/static/9af39c456e2492d9a22f880d73e81d26_ea96fe813e01a479869b1bd43340c56a17828fb8a0c10e18325a6e0b574bd80a",
		"last_contacted_mode": "Email opened by recipient",
		"last_contacted": "2024-06-24T09:57:29Z",
		"first_name": "James",
		"last_name": "Sampleton (sample)",
		"city": "San Diego",
		"country": "USA",
		"created_at": "2024-06-26T09:57:29Z",
		"updated_at": "2024-06-26T09:58:59Z"
	},
	{
		"id": 2522,
		"job_title": "Co-founder",
		"lead_score": 0,
		"email": "spectorcalista@gmail.com",
		"work_number": "+13684945781",
		"mobile_number": "+19266520001",
		"open_deals_amount": "7000.0",
		"display_name": "Calista (sample)",
		"avatar": "https://img.fullcontact.com/static/9af39c456e2492d9a22f880d73e81d26_ea96fe813e01a479869b1bd43340c56a17828fb8a0c10e18325a6e0b574bd80a",
		"last_contacted_mode": "Email opened by recipient",
		"last_contacted": "2024-06-22 12:43:57",
		"first_name": "Spector",
		"last_name": "6015",
		"city": "Westbury",
		"country": "United States",
		"created_at": "2024-06-26T10:14:01Z",
		"updated_at": "2024-06-26T10:23:30Z"
	}],
	"meta": {
		"last_fetched_id": 2522,
		"has_next_page": true,
		"avatar_data": {"Contact": {"2521": "https://img.fullcontact.com/static/9af39c456e2492d9a22f880d73e81d26_ea96fe813e01a479869b1bd43340c56a17828fb8a0c10e18325a6e0b574bd80a", "2522": null}}
	}
}
EXPAND ↓

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.freshsales.io/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 ↓

Update Contact Team

This API allows you to add/update/remove team members of the contact team.

post
/api/contacts/[id]/manage_team_members
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"team_users":[{"user_id":18813,"designation_id": 33},{"user_id": 18814, "designation_id": 34}]}' -X POST "https://domain.freshsales.io/api/contacts/10/manage_team_members"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "team_users": [
        {
            "entity_id": 16273,
            "user_id": 18813,
            "designation_id": 33,
            "created_at": "2024-09-03T10:40:21Z",
            "updated_at": "2024-09-03T10:40:21Z"
        },
        {
            "entity_id": 16273,
            "user_id": 18814,
            "designation_id": 34,
            "created_at": "2024-09-03T10:40:21Z",
            "updated_at": "2024-09-03T10:40:21Z"
        }
    ]
  }
EXPAND ↓

Note: To remove a specific user, set the _destroy attribute to true, along with the other required details.

Additional Example

If you want to remove team members from the contact team, use the _destroy attribute.
In the below example, user ID 18814 will be removed once the API is called.

Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"team_users":[{"user_id":18813,"designation_id": 33},{"user_id": 18814, "designation_id": 34, "_destroy": true}]}' -X POST "https://domain.freshsales.io/api/contacts/10/manage_team_members"
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)", "mobile_number":"1-926-555-9503"}}' -X POST "https://domain.freshsales.io/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.freshsales.io/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.freshsales.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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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 ↓

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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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

This API is designed for retrieving a defined set of records. For the retrieval of all available records, please utilize the Scroll API

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.freshsales.io/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

3. Scroll Accounts

To scroll through all accounts in ascending order by their ID, use last_fetched_id and has_next_page to iterate to the next records, To fetch a specific number of records, include the limit in the query path.

get
/api/sales_accounts/scroll/[view_id]

Scroll API

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.freshsales.io/api/sales_accounts/scroll/223?limit=2&last_fetched_id=5"
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
{
	"sales_accounts": [{
		"id": 20,
		"name": "Widgetz.io (sample)",
		"last_contacted": "2024-06-24T09:57:29Z",
		"last_contacted_mode": "email_outgoing",
		"city": "New Haven",
		"state": "Connecticut",
		"country": "United States",
		"open_deals_amount": "7000.0",
		"avatar": null,
		"created_at": "2024-06-26T09:57:28Z",
		"updated_at": "2024-06-26T09:58:45Z"
	},
	{
		"id": 21,
		"name": "Monahan",
		"last_contacted": "2024-06-22 12:43:57",
		"last_contacted_mode": "email_outgoing",
		"city": "Glendale",
		"state": "Arizona",
		"country": "USA",
		"open_deals_amount": null,
		"avatar": null,
		"created_at": "2024-06-25 12:43:42",
		"updated_at": "2024-06-25 12:45:21"
	}],
	"meta": {
		"last_fetched_id": 21,
		"has_next_page": true,
		"avatar_data": {"SalesAccount": {"20": null, "21": null}}
	}
}
EXPAND ↓

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.freshsales.io/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 ↓

Update Account Team

This API allows you to add/update/remove team members of the account team.

post
/api/sales_accounts/[id]/manage_team_members
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"team_users":[{"user_id":18813,"designation_id": 33},{"user_id": 18814, "designation_id": 34}]}' -X POST "https://domain.freshsales.io/api/sales_accounts/10/manage_team_members"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "team_users": [
        {
            "entity_id": 16273,
            "user_id": 18813,
            "designation_id": 33,
            "created_at": "2024-09-03T10:40:21Z",
            "updated_at": "2024-09-03T10:40:21Z"
        },
        {
            "entity_id": 16273,
            "user_id": 18814,
            "designation_id": 34,
            "created_at": "2024-09-03T10:40:21Z",
            "updated_at": "2024-09-03T10:40:21Z"
        }
    ]
  }
EXPAND ↓

Note: To remove a specific user, set the _destroy attribute to true, along with the other required details.

Additional Example

If you want to remove team members from the account team, use the _destroy attribute.
In the below example, user ID 18814 will be removed once the API is called.

Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"team_users":[{"user_id":18813,"designation_id": 33},{"user_id": 18814, "designation_id": 34, "_destroy": true}]}' -X POST "https://domain.freshsales.io/api/sales_accounts/10/manage_team_members"
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.freshsales.io/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.freshsales.io/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.freshsales.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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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)
This API is designed for retrieving a defined set of records. For the retrieval of all available records, please utilize the Scroll API

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.freshsales.io/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

3. Scroll Deals

To scroll through all deals in ascending order by their ID, use last_fetched_id and has_next_page to iterate to the next records, To fetch a specific number of records, include the limit in the query path.

get
/api/deals/scroll/[view_id]

Scroll API

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -X GET "https://domain.freshsales.io/api/deals/scroll/223?limit=2&last_fetched_id=5"
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
{
	"deals": [{
		"id": 26,
		"name": "Gold plan (sample)",
		"amount": "7000.0",
		"expected_close": "2024-07-03",
		"closed_date": null,
		"stage_updated_time": "2024-06-25T09:57:29Z",
		"custom_field": {},
		"probability": 20,
		"updated_at": "2024-06-26T09:57:29Z",
		"created_at": "2024-06-21T09:57:29Z",
		"age": 26
	},
	{
		"id": 27,
		"name": "McClure",
		"amount": "43739.0",
		"expected_close": "2024-07-03",
		"closed_date": null,
		"stage_updated_time": "2024-06-27T10:48:09Z",
		"custom_field": {},
		"probability": 20,
		"updated_at": "2024-06-27T10:48:09Z",
		"created_at": "2024-06-27T10:48:09Z",
		"age": 20
	}],
	"meta": {
		"last_fetched_id": 27,
		"has_next_page": true,
		"avatar_data": {"Deal": {"26": null, "27": null}}
	}
}
EXPAND ↓

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.freshsales.io/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 ↓

Update Deal Team

This API allows you to add/update/remove team members of the deal team.

post
/api/deals/[id]/manage_team_members
Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"team_users":[{"user_id":18813,"designation_id": 33},{"user_id": 18814, "designation_id": 34}]}' -X POST "https://domain.freshsales.io/api/deals/10/manage_team_members"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "team_users": [
        {
            "entity_id": 16273,
            "user_id": 18813,
            "designation_id": 33,
            "created_at": "2024-09-03T10:40:21Z",
            "updated_at": "2024-09-03T10:40:21Z"
        },
        {
            "entity_id": 16273,
            "user_id": 18814,
            "designation_id": 34,
            "created_at": "2024-09-03T10:40:21Z",
            "updated_at": "2024-09-03T10:40:21Z"
        }
    ]
  }
EXPAND ↓

Note: To remove a specific user, set the _destroy attribute to true, along with the other required details.

Additional Example

If you want to remove team members from the deal team, use the _destroy attribute.
In the below example, user ID 18814 will be removed once the API is called.

Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"team_users":[{"user_id":18813,"designation_id": 33},{"user_id": 18814, "designation_id": 34, "_destroy": true}]}' -X POST "https://domain.freshsales.io/api/deals/10/manage_team_members"
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.freshsales.io/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.freshsales.io/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.freshsales.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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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 Lead",
			"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 lead or 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 lead/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 "Lead" or "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 Lead

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"note":{"description":"Sample note for lead create", "targetable_type":"Lead", "targetable_id":1}}' -X POST "https://domain.freshsales.io/api/notes"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
{
	"note": {
		"id": 1,
		"description": "Sample note for lead 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.freshsales.io/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.freshsales.io/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.freshsales.io/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 Lead

Sample code | Curl
Copied Copy 
1
curl -H "Authorization: Token token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"note":{"description":"Sample note for lead update", "targetable_type":"Lead", "targetable_id":1}}' -X PUT "https://domain.freshsales.io/api/notes/1"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
{
	"note": {
		"id": 1,
		"description": "Sample note for lead 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.freshsales.io/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.freshsales.io/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.freshsales.io/api/notes/1"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
{
	"note": {
		"id": 1,
		"description": "Sample note for lead 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 lead/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 "Lead" or "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":"Lead", "task_users_attributes":[ { "user_id":"1"} ] }}' -X POST "https://domain.freshsales.io/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 lead's/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.freshsales.io/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"
	}],
	"leads": [{
		"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": "lead",
			"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.freshsales.io/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":"Lead","task_users_attributes":[{"user_id":"2"}] }}' -X PUT https://domain.freshsales.io/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.freshsales.io/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.freshsales.io/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 lead/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 "Lead" or "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":"Lead", "appointment_attendees_attributes":[{  "attendee_type":"FdMultitenant::User","attendee_id":"223"},{"attendee_type":"FdMultitenant::User","attendee_id":"222"},{"attendee_type":"Lead","attendee_id":"115773"}] }}' -X POST https://domain.freshsales.io/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": "lead",
			"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"
	}],
	"leads": [{
		"id": 115773,
		"display_name": "Jane Sampleton (sample)",
		"avatar": null,
		"type": "Lead"
	}],
	"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.freshsales.io/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": "lead",
			"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"
	}],
	"leads": [{
		"id": 115773,
		"display_name": "Jane Sampleton (sample)",
		"avatar": null,
		"type": "Lead"
	}, {
		"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": "lead",
			"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.freshsales.io/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@freshsales.io"
	}],
	"appointments": [{
		"id": 1,
		"time_zone": "Arizona",
		"title": "(Sample) Product Demo ",
		"description": "The lead 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":"Lead", "appointment_attendees_attributes":[{"attendee_type":"FdMultitenant::User", "attendee_id":"222" },{ "attendee_type":"FdMultitenant::User","attendee_id":"223"}] }}' -X PUT https://domain.freshsales.io/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":"lead",
            "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"
      }
   ],
   "leads":[
      {
         "id":115773,
         "display_name":"Jane Sampleton (sample)",
         "avatar":null,
         "type":"Lead"
      }
   ],
   "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.freshsales.io/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 lead/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 lead/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 "Lead" or "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.freshsales.io/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 sales activity with custom fields
If you’d like to create 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.freshsales.io/api/sales_activity"
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.freshsales.io/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":"Lead",
      "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.freshsales.io/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":"Lead",
         "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.freshsales.io/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.freshsales.io/api/sales_activities?per_page=10&page=1"
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.freshsales.io/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.freshsales.io/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 leads and 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 lead
You can use this API to create a manual call log and associate it with an existing lead.

post
/api/phone_calls
  • The parameter call_direction is mandatory.
  • You can also add a note to the lead 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": "lead", "targetable": { "id": "1", "first_name": "Jane", "last_name": "Sampleton (sample)", "work_number ":"5304915427", "mobile_number ":"11919457004 " },  "note ": { "description": "Sample note"} }}' -X POST https://domain.freshsales.io/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
{
	"leads": [{
		"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": "lead",
			"id": 1
		},
		"phone_number_id": null,
		"phone_caller_id": null,
		"note_id": 4
	}
}
EXPAND ↓

Create a manual call log for a new lead
You can use this API to create a new lead and a manual call log which is then associated with the newly created lead.

post
/api/phone_calls
  • The parameter call_direction is mandatory.
  • You can also add a note to the lead 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": "lead", "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.freshsales.io/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
{
  "leads": [
    {
      "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": "lead",
      "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.freshsales.io/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.freshsales.io/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 lead notes "}}}' -X POST https://domain.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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.freshsales.io/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 lead, 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 lead, 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 lead/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 "Lead"/"Contact"/"SalesAccount"/"Deal"/"Product"
* Mandatory fields for creating file.

Create a File

This API will help you upload and attach a file to a lead, 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=Lead -X POST   "https://domain.freshsales.io/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 lead, contact, sales account, deal or a product.

get
/api/leads/[id]/document_associations
Sample code | Curl
Copied Copy 
1
curl -X GET -H 'Authorization: Token token=sfg999666t673t7t82' "https://domain.freshsales.io/api/leads/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.

Error Response Fields
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.freshsales.io/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 ↓

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

Help and Support
Send us a message
Chat with us