API Reference

Thanks for subscribing.

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. There are two ways to do it,

  1. Using your API key.
  2. Using your username and password (Basic authentication)
  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.

    Alternatively, you can get your API key by using the following curl command too.

    curl -i -H "Content-Type:application/json" -H "Accept:application/json" -d '{"user":{"email":"username","password":"password"}}' -X POST https://domain.freshsales.io/api/sign_in

    Response

    {"login":"success","auth_token":"sfg999666t673t7t82"}

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

  1. Basic authentication

    You’d simply have to provide the username and password that you use to log in to your Freshsales account to use the API’s.

Curl -H "Authorization: Basic username:password" "Content-Type: application/json" -X GET https://domain.freshsales.io/api/leads/1

Note:
Make sure that your "username:password" is Base64-encoded before passing it as an "Authorization" header.

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
59
60
61
{ users: [{ id: 1, display_name: "Sample Admin", email: "admin@yourcompany.com" }], lead: { id: 1, job_title: "Sales Manager", department: "Sales", 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, do_not_disturb: false, 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", has_authority: false, 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
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.

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/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_stages Fetch all existing lead stages' details in the Freshsales portal.
Will give id, name of the lead stages
api/selector/lead_sources Fetch all existing lead sources' details in the Freshsales portal.
Will give id, name of the lead sources
api/selector/lead_reasons Fetch all existing lead reasons' details in the Freshsales portal.
Will give id, name of the lead reasons
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

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
job_title string Designation of the lead in the company he belongs to
department string The department that the lead belongs to
email string Primary email address 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
has_authority boolean The lead has authority to take decisions regarding the purchase.
do_not_disturb boolean The lead have enabled do not disturb or unsubscribed to your mails
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 in dollars
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.
Ω 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
50
51
52
{ "lead": { "id": 2, "job_title": null, "department": 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, "do_not_disturb": false, "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", "has_authority": false, "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
50
51
52
{ "lead": { "id": 1, "job_title": "Sales Manager", "department": "Sales", "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, "do_not_disturb": false, "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", "has_authority": false, "facebook": null, "twitter": "https://twitter.com/janesampleton", "linkedin": "http://linkedin.com/pub/jane-sampleton/109/39/b0" } }
EXPAND ↓

Lead Convert

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

post
api/leads/[id]/convert

Note:
It is mandatory to send last_name, email 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
40
41
42
{ "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", "do_not_disturb":false, "has_authority":false, "time_zone":null, "department":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

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

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
53
54
55
{ "lead": { "id": 1, "job_title": "Sales Manager", "department": "Sales", "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, "do_not_disturb": false, "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", "has_authority": false, "facebook": null, "twitter": "https://twitter.com/janesampleton", "linkedin": "http://linkedin.com/pub/jane-sampleton/109/39/b0" } }
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 ↓

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 ↓

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
76
77
78
79
80
81
82
83
84
85
86
87
88
89
{ "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":2000002169, "label":"Department", "name":"department", "type":"text", "default":true, "actionable":false, "position":4, "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 the companies (Accounts) that you do business with.

ATTRIBUTE TYPE DESCRIPTION
id number Unique ID of the contact
first_name string First name of the contact
last_name* string Last name of the contact
job_title string Designation of the contact in the account he belongs to
department string The department that the contact belongs to
email string Primary email address of the contact
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_account_id number ID of the account 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
has_authority boolean The contact has authority to take decisions regarding the purchase.
do_not_disturb boolean The contact have enabled do not disturb or unsubscribed to your mails.
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 account of the contact
twitter string Twitter account of the contact
linkedin string LinkedIn account of the contact
created_at datetime Contact creation timestamp
updated_at datetime Contact updated timestamp
* Mandatory fields for creating 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).
Ω 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
37
38
39
{ "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, "do_not_disturb": false, "has_authority": false, "time_zone": null, "department": 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 a new account
If you’d like to associate the contact with an account, 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}, "sales_accunt":{"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
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_account api/contacts/[id]?include=sales_account
Will return the connected account id, name, avatar and website 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/contacts/1?include=sales_account"
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
{ "sales_accounts": [{ "partial": true, "id": 1, "name": "Sample Account", "avatar": null, "website": null }], "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, "do_not_disturb": false, "has_authority": false, "time_zone": null, "department": 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_account_id": 1 } }
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
{ "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": "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": 3, "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": 4, "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": 5, "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": 6, "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": 7, "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": 8, "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": 9, "name": "Slipping Away", "model_class_name": "Contact", "user_id": -1, "is_default": false, "is_public": true, "updated_at": "2016-02-11T02:36:05-08:00" }] }
EXPAND ↓

View API:

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

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

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
37
38
39
{ "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, "do_not_disturb": false, "has_authority": false, "time_zone": null, "department": 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 ↓

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 ↓

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 ↓

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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
{ "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":2000001201, "label":"Department", "name":"department", "type":"text", "default":true, "actionable":false, "position":4, "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 account of the account
twitter string Twitter accountof the account 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
* 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 ↓

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
sales_account api/sales_accounts/[id]?include=industry_type
Will return the id and name of the industry_type
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

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

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 ↓

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 ↓

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

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 in dollars
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
* 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
{ "users": [{ "id": 1, "display_name": "Sample User", "email": "sampleuser@yourcompany.com" }], "deal": { "id": 1, "name": "Sample deal", "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
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
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
{ "users": [{ "id": 1, "display_name": "Sample User", "email": "sampleuser@yourcompany.com" }], "deal": { "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": 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)

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

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
{ "users": [{ "id": 2000000108, "display_name": "Sample User", "email": "sampleuser@yourcompany.com" }], "deal": { "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, "updater_id": 2000000108 } }
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 ↓

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
* Mandatory fields for creating task.
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 Timestamp that denotes the start of appointment
end_date* datetime Timestamp that denotes the end of 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
* Mandatory fields for creating appointment.

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
{ "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", "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
{ "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", "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 i.e get your past and upcoming appointments.

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

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
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 ↓

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

Help and Support
Send us a message
Chat with us