REST APIs

The REST APIs provide programmatic access to read and write EasyCalendar data. Create a new meeting, delete them, add notes, and more.

Overview

Below are some points that will help you get going with the REST APIs as quickly as possible.

Authenticating Requests
Rate Limiting
Endpoints

Authenticating Requests

To make a REST API call, you must include request headers including the Authorization header with your API Key and API Secret.

To get an API Key head over to developers section. Then, to authenticate your requests, you pass the api_key:api_secret credentials in the Authorization header. The authorization server then allows you to make REST API requests.

Request Header	Description
Authorization	When you request an endpoint, send the value as the HTTP basic authentication credentials by using your api_key and api_secret. For example: Authorization: api_key:api_secret.If you use cURL, specify -u “api_key:api_secret”.Required.
Accept	Set to application/json. Required.

Rate Limiting

HTTP Headers and Response Codes

Use the HTTP headers in order to understand where the application is at for a given rate limit, on the method that was just utilized.

Note that the HTTP headers are contextual. When using api_key and api_secret, they indicate the rate limit for the application context.

X-Rate-Limit-Limit:the rate limit ceiling for that given endpoint
X-Rate-Limit-Remaining:the number of requests left for the 1 hour window
X-Rate-Limit-Reset:the remaining window before the rate limit resets, in UTC epoch seconds

When an application exceeds the rate limit for a given API endpoint, the API will return a HTTP 429 “Too Many Requests” response code, along with a detailed error message in response body.

To predict the rate limits available in a better format, consider periodic usage of GET application / rate_limit_status.

Endpoints

We have endpoints for your meetings. We can also customize this data for your business or your own custom needs.

Meetings

This endpoint lets you create, delete or update meetings that you have on EasyCalendar. A sample meeting object on EasyCalendar is on the right

Sample Object

                                  

                                    
curl -X POST \
-H "Accept: application/json" \
-H "Authorization: {api_key}:{api_secret}" \
--data 
'{

"firstname":"James",
"lastname":"harden",
"email":"james.harden@gmail.com",
"title":"Meeting with James and Lakshya",
"starttime":"2020-11-18T09:15:00Z",
"endtime":"2020-11-18T10:16:10Z",
"attendees":
{
"0":"lakshya@easycalendar.com",
"1":"kartikay@hotmail.com",
"3":"arunav@gmail.com"
},
"description":"Discuss invoice status of customers",
"google_calendar_log":true,
"google_calendar":
{
"name":"help@easycalendar.com"
}'

Create Meetings

You can use this endpoint, to create meetings on Easycalendar using your api_key and api_secret.

POST : https://easycalendar.com/api/v1/meetings/new

Requestion body

Fields	Type	Details
firstname	string	Invitee's first name
lastname	string	Invitee's last name (optional)
email	string	Email address associated with the Invitee
title	string	Meeting title associated with the meeting
starttime	string	Meeting start time. Format YYYYY-mm-dd HH:mm:ssZ. The time must be in UTC.
endtime	string	Meeting end time. Format YYYYY-mm-dd HH:mm:ssZ. The time must be in UTC.
attendees	array	Array of attendees taking part in meeting
description	string	Description of meeting. Additional information you need for this meeting. (optional)
google_calendar_log	boolean	Log your appointment to Google calendar. (optional)
google_calendar	object	The name of the Google calendar. Must be provided, if google_calendar_log is true

Sample Request

                             

                                
curl -X POST \
-H "Accept: application/json" \
-H "Authorization: {api_key}:{api_secret}" \
--data 
'{
"firstname":"James",
"lastname":"harden",
"email":"james.harden@gmail.com",
"title":"Meeting with James and Lakshya",
"starttime":"2020-11-18T09:15:00Z",
"endtime":"2020-11-18T10:16:10Z",
"attendees":
{
"0":"lakshya@easycalendar.com",
"1":"kartikay@easycalendar.com",
"2":"arunav@easycalendar.com",
"3":"testjim@hotmail.com"
},
"description":"Discuss invoice status of customers",
"google_calendar_log":true,
"google_calendar":
{
"name":"test@easycalendar.com"
}
}' \
--url  
"https://easycalendar.com/api/v1/meetings/new"

Sample Response

                    
                    
"status":"success",
"meeting_id":"1245",
"created_at":"2020-11-18T15:00:10Z",
"message":"Meeting created"

Update Meeting

You can use this endpoint, to update a single meeting on EasyCalendar using your api_key and api_secret.

PATCH : https://easycalendar.com/api/v1/meetings/update/{meeting_id}

Parameters

Parameter	Type	Details
meeting_id	numeric	Id of the meeting you want to update. Only this particular meeting will be updated.

Request Body

Fields	Type	Details
firstname	string	Invitee's first name (optional)
lastname	string	Invitee's last name (optional)
title	string	Meeting title associated with the meeting (optional)
starttime	string	Meeting start time. Format YYYYY-mm-dd HH:mm:ssZ. The time must be in UTC. Must be smaller than meeting end time. (optional)
endtime	string	Meeting end time. Format YYYYY-mm-dd HH:mm:ssZ. The time must be in UTC. Must be greater than meeting start time. (optional)
attendees	array	Array of attendees taking part in meeting. New attendees will overwrite the previously added ones. (optional)
description	string	Description of meeting. Additional information you need for this meeting. (optional)

Note : Atleast one field must be provided in the request body in order to update the meeting.

Sample Request


                                
curl -X PATCH \
-H "Accept: application/json" \
-H "Authorization: {api_key}:{api_secret}" \
--data 
'{
"firstname":"Jimmy",
"lastname":"harden",
"title":"Meeting with James and Lakshya",
"starttime":"2020-11-18T09:15:00Z",
"endtime":"2020-11-18T10:16:10Z",
"attendees":{
"0":"lakshya@easycalendar.com",
"1":"kartikay@easycalendar.com",
"2":"arunav@easycalendar.com",
"3":"testjim@hotmail.com"
}
"description":"Discuss invoice status of customers"
}' \
--url  
"https://easycalendar.com/api/v1/meetings/update/2454"

Sample Response



"status": "success",
"meeting_id": "2454",
"updated_at": "2020-11-18T09:38:15Z",
"message": "Meeting details updated"

List Meetings

You can use this endpoint to get meetings of a specified period on EasyCalendar using your api_key and api_secret.

GET : https://easycalendar.com/api/v1/meetings/list

Parameters

Fields	Type	Details
start	numeric	It gives the starting point for the API to return the result. if skipped, then the API will return data from the beginning of the search result (optional)
limit	numeric	Set the limit for the API search result. By default 10, maximum 100
starttime	string	Starting from this time onwards. Format YYYYY-mm-dd HH:mm:ssZ. The time must be in UTC. Must be smaller than the endtime.
endtime	string	The ending before this time. Format YYYYY-mm-dd HH:mm:ssZ. The time must be in UTC. Must be greater than the starttime.

Sample Request


curl -X GET \
-H "Accept: application/json" \
-H "Authorization: {api_key}:{api_secret}" \
--url
"https://easycalendar.com/api/v1/meetings/list"
{
"start":2469,
"limit":2,
"starttime":"2020-11-19T07:15:00Z",
"endtime":"2020-11-19T23:00:00Z"
}

Sample Response


                                
"status": "success",
"total": 1,
"data": [
{
 "meeting_id": "2469",
 "clientemail": "jim.harden@gmail.com",
 "user_startime": "2020-11-19 16:59:00",
 "user_endtime": "2020-11-19T23:00:00Z",
 "client_fname": "James",
 "client_lname": "harden",
 "description": "Discuss invoice status of customers",
 "meeting_title": "Meeting with James and Lakshya",
 "attendees": [
  "arunav@easycalendar.com",
  "jim.harden@gmail.com",
  "lakshya@easycalendar.com"
 ],
 "meeting_timezone": null,
 "meeting_type": 0,
 "created_at": null,
 "client_starttime": "2020-11-19T07:15:00Z",
 "client_endtime": "2020-11-19T23:00:00Z",
 "google_calendar": "arunav@easycalendar.com"
}
],
"pagination": 
{
"next_meeting_id": 0
}
}

Get Meeting

You can use this endpoint, to get a single meeting on EasyCalendar using your api_key and api_secret.

GET : https://easycalendar.com/api/v1/meetings/get/{meeting_id}

Parameters

Parameters	Type	Details
meeting_id	numeric	Meeting id to get details. Only this particular meeting will be returned

Sample Request


curl -X GET \
-H "Accept: application/json" \
-H "Authorization: {api_key}:{api_secret}" \
--url
"https://easycalendar.com/api/v1/meetings/get/2454"

Sample Response


                                
"status": "success",
"meeting_id": "2454",
"message": "Meeting details found",
"data": 
{
 "meeting_title": "Meeting with James and Lakshya",
 "client_fname": "Jimmy",
 "client_lname": "harden",
 "client_email": "jim.harden@gmail.com",
 "description": "Discuss invoice status of customers and some more queries",
 "attendees": 
  [
 "lakshya@easycalendar.com",
 "kartikay@easycalendar.com",
 "arunav@easycalendar.com",
 "testjim@hotmail.com"
  ],
 "created_at": "2020-11-18 09:10:06",
 "meeting_type": 0,
 "client_starttime": "2020-11-18 16:45:00",
 "client_endtime": "2020-11-18 17:46:00",
 "user_startime": "2020-11-18 16:45:00",
 "user_endtime": "2020-11-18 17:46:00",
 "meeting_timezone": "America/New_York",
 "google_calendar": "lakshya@easycalendar.com"
}

Delete meeting

You can use this endpoint, to delete a meeting on EasyCalendar using your api_key and api_secret.

DELETE : https://easycalendar.com/api/v1/meetings/delete/{meeting_id}

Parameters

Parameters	Type	Details
meeting_id	numeric	Id of the meeting you want to delete. Only this particular meeting will be deleted.

Sample Request

                                
curl -X DELETE \
-H "Accept: application/json" \
-H "Authorization: {api_key}:{api_secret}" \
--url 
"https://easycalendar.com/api/v1/meetings/delete/2453"

Sample Response


                                
"status": "success",
"meeting_id":"2453",
"message": "Meeting deleted"

List all contacts

You can use this endpoint, to list all your contacts on JustCall using your api_key and api_secret. This api returns a paginated response that you can use to go through all your contacts.

List all contacts

POST : https://api.justcall.io/v1/contacts/list

Parameters

Parameters	Type	Details
page^	string	If it’s a paginated data, the page number you want to read
per_page^	string	The number of results you want to have per page. Defaults to 50. Maximum is 100.

^the response data is paginated with a limit of 100 per page - know more about this in our pagination section

Sample Request


                                curl -X POST \
                                -H "Accept: application/json" \
                                -H "Authorization: {api_key}:{api_secret}" \
                                --data 
                                '{
                                "page":"1",
                                "per_page":"25"
                            }' \
                            --url 
                            "https://api.justcall.io/v1/contacts/list"

Sample Response


                            {
                              "status":"success",
                              "count":3,
                              "data":
                              [
                              {
                                  "id":944188,
                                  "firstname":"Prateek",
                                  "lastname":"Jio",
                                  "company":"",
                                  "email":"prateek3101@gmail.com",
                                  "notes":"",
                                  "phone":"917007813799"
                              },
                              {
                                  "id":966400,
                                  "firstname":"Prateek",
                                  "lastname":"Khurana",
                                  "company":"SaaS Labs, Inc",
                                  "email":"prateek@justcall.io",
                                  "notes":"hello world",
                                  "phone":"12562562562"
                              },
                              {
                                  "id":1014772,
                                  "firstname":"Pratz",
                                  "lastname":"",
                                  "company":"",
                                  "email":"",
                                  "notes":"",
                                  "phone":"919871148769"
                              },
                              ]
                          }

Add Contact

You can use this endpoint, to add contacts to your existing JustCall AutoDialer campaign using your api_key and api_secret.

POST : https://api.justcall.io/v1/autodialer/campaigns/add

Parameters

Parameters	Type	Details
campaign_id	string	Campaign ID in which you wish to add this contact.
first_name	string	Contact’s first name
last_name	string	Contact’s last name
phone	string	Formatted phone number of the contact with country code
custom_props	object	Add values to your custom contact fields. The key of the object being the ID of the custom field. The ID can be found under the settings of your AutoDialer.

Note : Contacts for a particular api_key and api_secret pair are unique, hence no two contacts can have same phone numbers. If you hit this api, with a phone number that is already present in our database for your account, a new contact will not be created - however instead of an error, we will send the existing contact details in response.

Sample Request


                                curl -X POST \
                                -H "Accept: application/json" \
                                -H "Authorization: {api_key}:{api_secret}" \
                                --data 
                                    '{
                                    "campaign_id":"1234213",
                                    "first_name":"John",
                                    "last_name":"Smith",
                                    "phone":"+1 256 256 256",
                                    "custom_props": {
                                    "10909":"true",
                                    "10910":"Bathilda Collins",
                                    "10911":"Subscribed",
                                }
                            }' \
                            --url 
                        "https://api.justcall.io/v1/autodialer/campaigns/add"

Sample Response


                        {
                          "id":"21001",
                          "name":"John Smith",
                          "phone":"1256256256",
                      }

Remove Contact

You can use this endpoint, to remove contacts from your existing JustCall AutoDialer campaign using your api_key and api_secret.

POST : https://api.justcall.io/v1/autodialer/contacts/remove

Parameters

Parameters	Type	Details
campaign_id	string	Campaign ID from which you wish to remove this contact.
phone	string	Phone number of the contact, which you wish to remove from the campaign.
all	string	Use all=true for removing all contacts from a AutoDialer campaign. campaign_id is required while using this parameter.

Note : If you only provide the phone number of the contact, then that contact will be removed from all of the campaigns in your AutoDialer account.

Sample Request


                                curl -X POST \
                                -H "Accept: application/json" \
                                -H "Authorization: {api_key}:{api_secret}" \
                                --data 
                                '{
                                "campaign_id":"1234213",
                                "phone":"+1 256 256 256",
                            }' \
                            --url 
                            "https://api.justcall.io/v1/autodialer/contacts/remove"

Sample Response


                            {
                              "status":"success",
                              "message":"The contact has been removed                                                                                       successfully.",
                          }

Contact Fields

You can use this endpoint, to fetch custom contact fields for your AutoDialer using your api_key and api_secret.

POST : https://api.justcall.io/v1/autodialer/contacts/customfields

Sample Request


                                            curl -X POST \
                                            -H "Accept: application/json" \
                                            -H "Authorization: {api_key}:{api_secret}" \
                                            --url 
                                            "https://api.justcall.io/v1/autodialer/contacts/customfields"

Sample Response


                                            {
                                                "status": "success",
                                                "data": [
                                                {
                                                    "label": "membership_status",
                                                    "key": 1090960,
                                                    "type": "string"
                                                },
                                                {
                                                    "label": "Zip Code",
                                                    "key": 1091095,
                                                    "type": "string"
                                                }
                                                ]
                                            }

Users

This endpoint lets you get Users fro your JustCall account.

List all users

You can use this endpoint, to list all your users in JustCall using your api_key and api_secret. This api returns a paginated response that you can use to go through all your users.

POST : https://api.justcall.io/v1/users/list

Parameters

Parameters	Type	Details
page^	string	If it’s a paginated data, the page number you want to read
per_page^	string	The number of results you want to have per page. Defaults to 50. Maximum is 100.

^the response data is paginated with a limit of 100 per page

Sample Request


                                                curl -X POST \
                                                -H "Accept: application/json" \
                                                -H "Authorization: {api_key}:{api_secret}" \
                                                --data
                                                '{
                                                "per_page":"10",
                                                "page":"1"
                                            }' \
                                            --url 
                                            "https://api.justcall.io/v1/users/list"

Sample Response



                                            {
                                              "status": "success",
                                              "count": 10,
                                              "data": 
                                              [
                                              {
                                                  "agent_id": 25363,
                                                  "owner_id": 25363,
                                                  "firstname": "Mike",
                                                  "lastname": "Smith",
                                                  "email": "mike@justcall.io",
                                                  "on_call": "0",
                                                  "last_login": "2020-05-01 17:43:31",
                                                  "availability": 0
                                              },
                                              {
                                                  "agent_id": 25916,
                                                  "owner_id": 25363,
                                                  "firstname": "John",
                                                  "lastname": "Doe",
                                                  "email": "john@justcall.io",
                                                  "on_call": "0",
                                                  "last_login": "2020-05-01 22:15:20",
                                                  "availability": 1
                                              },
                                              {
                                                  "agent_id": 25174,
                                                  "owner_id": 25363,
                                                  "firstname": "David",
                                                  "lastname": "Hahn",
                                                  "email": "David@justcall.io",
                                                  "on_call": "0",
                                                  "last_login": "2020-04-28 15:21:08",
                                                  "availability": 0
                                              },
                                              {
                                                  "agent_id": 29232,
                                                  "owner_id": 25363,
                                                  "firstname": "Linda",
                                                  "lastname": "Smith",
                                                  "email": "linda@justcall.io",
                                                  "on_call": "0",
                                                  "last_login": "2020-05-04 01:16:41",
                                                  "availability": 0
                                              },
                                              {
                                                  "agent_id": 25996,
                                                  "owner_id": 25363,
                                                  "firstname": "Michael",
                                                  "lastname": "Wayne",
                                                  "email": "michael@justcall.io",
                                                  "on_call": "0",
                                                  "last_login": "2020-04-24 01:55:53",
                                                  "availability": 0
                                              },
                                              {
                                                  "agent_id": 27627,
                                                  "owner_id": 25363,
                                                  "firstname": "Jack",
                                                  "lastname": "Reese",
                                                  "email": "jack@justcall.io",
                                                  "on_call": "0",
                                                  "last_login": "2020-04-27 21:24:32",
                                                  "availability": 0
                                              },
                                              {
                                                  "agent_id": 27283,
                                                  "owner_id": 25363,
                                                  "firstname": "Jill",
                                                  "lastname": "Brown",
                                                  "email": "jill@justcall.io",
                                                  "on_call": "0",
                                                  "last_login": "2020-04-27 19:57:20",
                                                  "availability": 0
                                              },
                                              {
                                                  "agent_id": 29263,
                                                  "owner_id": 25363,
                                                  "firstname": "Brian",
                                                  "lastname": "Coster",
                                                  "email": "brian@justcall.io",
                                                  "on_call": "0",
                                                  "last_login": "2020-04-30 20:03:05",
                                                  "availability": 1
                                              },
                                              {
                                                  "agent_id": 29839,
                                                  "owner_id": 25363,
                                                  "firstname": "Eric",
                                                  "lastname": "Marin",
                                                  "email": "eric@justcall.io",
                                                  "on_call": "0",
                                                  "last_login": "2020-04-28 15:13:15",
                                                  "availability": 1
                                              },
                                              {
                                                  "agent_id": 30223,
                                                  "owner_id": 25363,
                                                  "firstname": "Ronnis",
                                                  "lastname": "Ripley",
                                                  "email": "ronnis@justcall.io",
                                                  "on_call": "0",
                                                  "last_login": "2020-04-24 16:29:30",
                                                  "availability": 0
                                              }
                                              ]
                                          }

Get a user

You can use this endpoint, to get information of a single user on JustCall using your api_key and api_secret.

POST : https://api.justcall.io/v1/users/get

Parameters

Parameters	Type	Details
ID (required)	string	User id to get details. Only this particular user will be returned.

Sample Request


                                        curl -X POST \
                                        -H "Accept: application/json" \
                                        -H "Authorization: {api_key}:{api_secret}" \
                                        --data
                                        '{
                                        "id":"27283"
                                    }' \
                                    --url 
                                    "https://api.justcall.io/v1/users/get"

Sample Response

                                  

                                    {
                                      "status": "success",
                                      "data": {
                                      "agent_id": 27283,
                                      "owner_id": 25363,
                                      "firstname": "Jill",
                                      "lastname": "Brown",
                                      "email": "jill@justcall.io",
                                      "on_call": "0",
                                      "last_login": "2020-04-27 19:57:20",
                                      "availability": 0
                                  }
                              }

Error Definition

The Easycalendar API uses HTTP status codes to reflect a successful or unsuccessful request 200 status codes represent a successful request. If you receive any other error status code, check the body for an error code and message.

Error code	Error	Description
200	Successful Request
500	Internal Server Error server error	Contact support if this error persists
401	Unauthorized	Invalid/missing credentials
429	Too Many Requests	API request has exceeded the API hit rate limit
400	Bad Request	Invalid/missing data
404	Not Found	The resource doesn’t exist. Ex. invalid/non-existent meeting-id