API Reference

Thanks for subscribing.

Overview

Freshmarketer'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 marketing system.

Which are the API commands used in Freshmarketer?

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

  1. API key

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

    1. Click Settings from let nav panel
    2. Click the API Settings
    3. You can find your API key in the field Your API key.

    Learn more about finding your API key.

For example, if your API key is sfg999666t673t7t82, the curl command to use is:

curl -H fm-token=sfg999666t673t7t82" -XGET https://domain.freshmarketer.com/mas/api/v1/contacts

What are the resources available via the API?

Any information in your Freshmarketer’s account can be identified by its own unique identifier or "URI". If you want data from your marketing system, be it a contact or list 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_domain_name/mas/api/v1/resource_name

For example, if you’d like to fetch the contact with id 144 from your account "smarketing.freshmarketer.com", the syntax would be

https://smarketing.freshmarketer.com/mas/api/v1/contacts/144

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

Will everyone have the same access rights?

No. Using the API’s, users would only be able to view data that they have access to. Learn more about managing user roles and scopes.

Schema

Blank Fields:
Blank fields are made null instead of being omitted.

Timestamps:
All timestamps are returned in the UTC format, YYYY-MM-DDTHH:MM:SSZ. For example, 2016-02-13T23:27:49Z

Date Fields:
Input for date fields is expected to be in one of the following formats:
YYYY-MM-DD
YYYY-MM-DDTHH:MM
YYYY-MM-DDTHH:MMZ
YYYY-MM-DDTHH:MM:SS
YYYY-MM-DDTHH:MM:SSZ
YYYY-MM-DDTHH:MM:SS±hh:mm
YYYY-MM-DDTHH:MM:SS±hh
YYYY-MM-DDTHH:MM:SS±hhmm
If the time zone information is not present, it will be assumed to be in UTC.
A few valid date fields - 2016-02-15T21:16:25Z ,    2012-12-24T12:56:15+05:30,    2010-03-23T12:00

Errors

I have encountered an error. How do I fix this?

API requests that result in errors will return an appropriate HTTP status code to help you identify the type of error and fix it. You can use the table below to understand what each code means.

HTTP Status Code Text Description
400* Client or Validation Error Indicates that the request is not in the correct format. For example, the Create a contact API requires a valid email address to be sent as part of the request. If you are missing @ as part of the email address in the request, you would get this error code.
401 Authentication Failure Indicates that the Authorization header is either missing or incorrect. You can learn more about the Authorization header here.
403 Access Denied This indicates that the user whose credentials were used in making this request was not authorized to perform this API call. It could be that this API call requires admin level credentials or perhaps the Freshmarketer portal doesn't have corresponding feature enabled.
404 Requested Resource not Found This status code is returned when the request contains invalid ID/Freshmarketer domain in the URL or an invalid URL itself. For example, an API call to retrieve a contact with an invalid ID will return a HTTP 404 status code to let you know that no such contact exists.
429 Too many requests This status code appears when the user has exceeded the API limit set per hour per account. In Fresmarketer, 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 Freshmarketer'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.

Contacts

Contacts represent the companies (Accounts) that you do business with.

ATTRIBUTE TYPE DESCRIPTION
first_name string First name of the contact
middle_name string Middle name of the contact
last_name string Last name of the contact
email* string Primary email address of the contact
source string Where the contact from
subscriptions string Lists which contact subscribe to
company string Company of the contact
phone string Work phone number of the contact
mobile string Mobile phone number of the contact
facebook string Facebook account of the contact
twitter string Twitter account of the contact
linkedin string LinkedIn account 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
custom_field string List of custom fields
* Mandatory fields for creating contact.

Add/update a Contact

This API allows you to if a contact doesn't already exist, it will be created. If a contact with the same email address exists, it will be updated.

put
/mas/api/v1/contacts
Sample code | Curl
Copied Copy
1
curl -H fm-token:"sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"first_name":"David", "last_name":"Thompson (sample)", "email":"david.thompson@sample.com"}' -X PUT "https://domain.freshmarketer.com/mas/api/v1/contacts" |json_pp
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ "contact" : { "source" : "native_form", "created_at" : "2019-03-27T13:14:13.308+0000", "id" : 299418, "uuid" : "27faf72e-ef06-443e-9119-053d8a6ba112", "first_name" : "mps", "org_id" : 200002004, "last_name" : "Thompson (sample)", "updated_at" : "2019-03-27T13:14:13.308+0000", "contactable" : true, "source_id" : 1, "email" : "samraj@sample.com" } }
EXPAND ↓

Note

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 fm-token=sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"contact":{"first_name":"David", "last_name":"Thompson (sample)", "mobile_number":"1-926-555-9503", "custom_field": {"cf_is_active": true} }}' -X PUT "https://domain.freshmarketer.com/mas/api/v1/contacts"
EXPAND ↓

2. Add Contact to a list
It is possible to add a contact and add them to a list in a single API call, you just need to provide an additional contact field called "lists" with list ids.

Copied Copy
1
curl -H fm-token:"sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"first_name":"David", "last_name":"Thompson (sample)", "email":"david.thompson@sample.com","lists":[101,102]}}' -X PUT "https://domain.freshmarketer.com/mas/api/v1/contacts" |json_pp
EXPAND ↓

3. Changing a customer email address
We can not update contact's email address via the regular "email" field. to update the email address have to provide the new email address in the field called "new_email" .

Copied Copy
1
curl -H fm-token:"sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"first_name":"David", "last_name":"Thompson (sample)", "email":"david.thompson@sample.com","new_email":"davidjohnes.thompson@sample.com"}}' -X PUT "https://domain.freshmarketer.com/mas/api/v1/contacts" |json_pp
EXPAND ↓

View a Contact

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

get
/mas/api/v1/contacts/[id]
Sample code | Curl
Copied Copy
1
curl -H fm-token:"sfg999666t673t7t82" -XGET "https://domain.freshmarketer.com/mas/api/v1/contacts/1" |json_pp
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{ "contact" : { "first_name" : "mps", "org_id" : 200002004, "created_at" : "2019-03-27T13:14:13.000+0000", "id" : 299418, "uuid" : "27faf72e-ef06-443e-9119-053d8a6ba112", "email" : "samraj@test.com", "source_id" : 1, "previous" : 299417, "contactable" : true, "source" : "native_form", "updated_at" : "2019-03-27T13:14:13.000+0000", "subscriptions" : [], "custom_field" : {}, "last_name" : "Thompson (sample)" } }
EXPAND ↓

View all Contact

This API allows you to view the all contacts.

get
/mas/api/v1/contacts
Sample code | Curl
Copied Copy
1
curl -H fm-token:"sfg999666t673t7t82" -XGET "https://domain.freshmarketer.com/mas/api/v1/contacts" |json_pp
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
{ "meta": { "page_count": 100, "items_per_page": 100, "current_page": 1, "total_items": 150, "total_pages": 2 }, "contacts": [ { "custom_field": {}, "source_id": 1, "contactable": true, "first_name": "mps", "uuid": "42653f08-abce-45ab-9ae8-95404560708e", "id": 111614, "email": "samraj@test.com", "last_name": "Thompson (sample)", "created_at": "2019-02-21T09:00:03.000+0000", "updated_at": "2019-02-21T09:00:03.000+0000", "org_id": 200002004, "source": "imported" }, { "id": 202629, "uuid": "2ac76446-9845-42df-b782-e9e39ba96931", "first_name": "Artemus", "contactable": true, "source_id": 1, "custom_field": {}, "source": "imported", "updated_at": "2019-03-05T06:06:45.000+0000", "org_id": 200002004, "created_at": "2019-03-05T06:06:45.000+0000", "last_name": "Aizik", "email": "aaizikgt@pagesperso-orange.fr" } ] }
EXPAND ↓

Update a Contact

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

PATCH
/mas/api/v1/contacts/[id]
Sample code | Curl
Copied Copy
1
curl -H fm-token:"sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"first_name":"mps","email":"samraj@test.com"}' -X PATCH "https://domain.freshmarketer.com/mas/api/v1/contacts/1" |json_pp
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ "contact" : { "first_name" : "mps", "uuid" : "27faf72e-ef06-443e-9119-053d8a6ba112", "custom_field" : {}, "email" : "samraj@test.com", "id" : 299418, "org_id" : 200002004, "source_id" : 1, "contactable" : true, "source" : "native_form", "created_at" : "2019-03-27T13:14:13.000+0000", "updated_at" : "2019-03-28T10:37:46.842+0000" } }
EXPAND ↓

Delete a Contact

This API allows you to delete a contact.

delete
/mas/api/v1/contacts/[contact_id_or_email]
Sample code | Curl
Copied Copy
1
curl -H fm-token:sfg999666t673t7t82" -X DELETE "https://domain.freshmarketer.com/mas/api/v1/contacts/david.thompson@sample.com
EXPAND ↓
Response
1
true
EXPAND ↓

Add a list

This API allows you to create a list.

post
/mas/api/v1/lists
Sample code | Curl
Copied Copy
1
curl -H fm-token:sfg999666t673t7t82" -H "Content-Type: application/json" -d "{\"deleted\": false, \"name\": \"apitestlist\", \"source\": \"native_form\", \"source_id\": 1, \"type\": \"fixed\"}' -X POST "https://domain.freshmarketer.com/mas/api/v1/lists
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{ "list": { "id": 41, "uuid": "56439a79-f37c-4004-8e0e-921949770a22", "name": "apitestlist", "source": "native_form", "type": "fixed", "org_id": 200003000, "created_at": "2019-03-05T08:29:31.469+0000", "updated_at": "2019-03-05T08:29:31.469+0000", "source_id": 1, "no_of_segments": 0, "no_of_subscribers": 0 } }
EXPAND ↓

Get all lists

This API allows you to get all lists.

get
/mas/api/v1/lists
Sample code | Curl
Copied Copy
1
curl -H fm-token:sfg999666t673t7t82" -XGET "https://domain.freshmarketer.com/mas/api/v1/lists
EXPAND ↓
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
"lists": [ { "id": 41, "uuid": "56439a79-f37c-4004-8e0e-921949770a22", "name": "apitestlist", "source": "native_form", "type": "fixed", "org_id": 200003000, "created_at": "2019-03-05T08:29:31.000+0000", "updated_at": "2019-03-05T08:29:31.000+0000", "source_id": 1, "no_of_segments": 0, "no_of_subscribers": 0 } ]
EXPAND ↓

Subscribe contact(s) to a list

This API allows you to subscribe contact to a list.

PATCH
/mas/api/v1/lists/[list_id]/subscribers
Sample code | Curl
Copied Copy
1
curl -H fm-token:sfg999666t673t7t82" -H "Content-Type: application/json" -d '{ \"contact\": { \"email\": \"paneer@freshworks.com\", \"source\": \"native_form\", \"source_id\": 1 }, \"source\": \"native_form\", \"source_id\": 1, \"subscriber_status\": \"subscribed\"}' -X POST "https://domain.freshmarketer.com/mas/api/v1/lists/[list_id]/subscribers
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
{ "subscriber": { "id": 215128, "uuid": "40468ccb-1c7d-4cf7-83fb-ac719bbac2c7", "source": "native_form", "source_id": 1, "contact": { "id": 203025, "uuid": "29dd6bf5-9aff-4120-ab85-34b8b0c41ee9", "email": "paneer@freshworks.com", "source": "native_form", "source_id": 1, "contactable": true, "org_id": 200003000, "created_at": "2019-03-05T08:43:26.686+0000", "updated_at": "2019-03-05T08:43:26.686+0000" }, "org_id": 200003000, "created_at": "2019-03-05T08:43:26.700+0000", "updated_at": "2019-03-05T08:43:26.700+0000", "subscriber_status": "subscribed" } }
EXPAND ↓

Unsubscribe contact(s) from a list

This API allows you to create a contact.

delete
/mas/api/v1/lists/[list_id]/subscribers/[contact_id]/unsubscribe
Sample code | Curl
Copied Copy
1
curl -H fm-token:sfg999666t673t7t82" -X POST "https://domain.freshmarketer.com/mas/api/v1/lists/[list_id]/subscribers/[contact_id]/unsubscribe
EXPAND ↓

Get contacts in a list

This API allows you to get contacts in a list.

get
/mas/api/v1/lists/[list_id]/subscribers
Sample code | Curl
Copied Copy
1
curl -H fm-token:sfg999666t673t7t82" -XGET "https://domain.freshmarketer.com/mas/api/v1/lists/[list_id]/subscribers
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
{ "meta": { "total_pages": 1, "size": 20, "number_of_items": 1, "total_items": 1, "current_page": 1 }, "subscribers": [ { "id": 215128, "uuid": "40468ccb-1c7d-4cf7-83fb-ac719bbac2c7", "source": "native_form", "source_id": 1, "contact": { "id": 203025, "uuid": "29dd6bf5-9aff-4120-ab85-34b8b0c41ee9", "email": "paneer@freshworks.com", "source": "native_form", "source_id": 1, "contactable": true, "org_id": 200003000, "created_at": "2019-03-05T08:43:27.000+0000", "updated_at": "2019-03-05T08:43:27.000+0000", "custom_field": {} }, "org_id": 200003000, "created_at": "2019-03-05T08:43:27.000+0000", "updated_at": "2019-03-05T08:43:27.000+0000", "subscriber_status": "subscribed" } ] }
EXPAND ↓

Enter your domain and API key the CURL commands will become executable.