Callingly API Documentation

Generating an API Key

The API requires generating a Bearer Token to be used with every request.


To generate a new token:

  1. Head to the API Keys page under Settings -> API Keys.
  2. Click the blue "Add API Key" button in the top right.
  3. Give the API Key a name. This name is just for your own purposes.
  4. Copy the API key and save it for use later. You cannot view the API key again so make sure you save it somewhere safe.

Authentication Headers

With every API request, please send in the following two headers:

Authorization: Bearer {{YOUR_BEARER_TOKEN_HERE}}


Accept: application/json

Account ID for Clients

If you are an Agency partner and are using the API to make requests for your clients, along with your Bearer Token you can pass in an account_id parameter with the ID number of your client's account.

You can find your client's account ID number either in the Clients endpoint or by clicking Edit on the Client's account in the Clients panel and looking for the ID in the top right corner.

Clients

List Clients

Endpoint

GET https://api.callingly.com/v1/clients

Sample Response

[
	{
		"id": 123,
		"name": "Client Name",
		"email": "client@email.com",
		"billed_users": 12,
		"billed_numbers": 2
	}
]

Create Client

Endpoint

POST https://api.callingly.com/v1/clients

Sample Request

{
	"fname": "John",
	"lname": "Smith",
	"company": "Smith Pools",
	"email": "client@email.com",
	"phone_number": "555-555-5555",
	"password": "password123"
}

Delete Client

Endpoint

DELETE https://api.callingly.com/v1/clients/{{id}}

Activate/Deactivate

Endpoint

POST https://api.callingly.com/v1/clients/{{id}}/active

Sample Request 

{
	"is_active": 0
}

Teams

List Teams

Endpoint

GET https://api.callingly.com/v1/teams

Sample Response

[
	{
		"id": 123,
		"account_id": 1,
		"name": "Main Team"
	}
]

Get Team

Endpoint

GET https://api.callingly.com/v1/teams/{{id}}

Sample Response

{
    "id": 123,
    "account_id": 1,
    "name": "Main Team",
    "is_record": 1,
    "call_mode": "simultaneous",
    "whispertext": "Please press 1 to connect to {first_name} {last_name} from {company} {category}",
    "post_whispertext": "Your call has been completed. Press 1 if you were able to reach the lead. Press 2 if you left a voicemail. Press 3 otherwise to reschedule the call.",
    "language": "en",
    "delay": 0,
    "is_retry": 1,
    "retries": 3,
    "retry_schedule": [
        15,
        60,
        120
    ],
    "is_reschedule": 1,
    "is_retry_lead": 1,
    "lead_retries": 3,
    "lead_retry_schedule": [
        15,
        60,
        120
    ],
    "is_sms": 0,
    "sms_body": ""
}

Create Team

Endpoint

POST https://api.callingly.com/v1/teams

Sample Request

{
    "account_id": 1,
    "name": "New Team",
    "is_record": 1,
    "call_mode": "simultaneous",
    "whispertext": "Please press 1 to connect to {first_name} {last_name} from {company} {category}",
    "language": "en",
    "delay": 0,
    "is_retry": 1,
    "retries": 3,
    "retry_schedule": [
        15,
        60,
        120
    ],
    "is_reschedule": 1,
    "is_retry_lead": 1,
    "lead_retries": 3,
    "lead_retry_schedule": [
        15,
        60,
        120
    ]
}

Update Team

Endpoint

PUT https://api.callingly.com/v1/teams/{{id}}

List Team Users

Endpoint

GET https://api.callingly.com/v1/teams/{{id}}/agents

Sample Request

{
    "agents": [
        {
            "id": 1,
            "name": "John Smith",
            "priority": 1,
            "cap": null
        },
        {
            "id": 2,
            "name": "Test Test",
            "priority": 1,
            "cap": 1000
        },
        {
            "id": 3,
            "name": "Jane Smith",
            "priority": 2,
            "cap": null
        }
    ]
}

Update Users

Endpoint

PUT https://api.callingly.com/v1/teams/{{id}}/agents

Sample Request

{
    "agents": ["1","3","5"]
}

Remove Agent

Endpoint

DELETE https://api.callingly.com/v1/teams/{{id}}/agents/{{agent_id}}

Update Agent Settings

Endpoint

PUT https://api.callingly.com/v1/teams/{{id}}/agents/{{agent_id}}

Sample Request

{
    "priority": 1,
    "cap": 100
}

Users

List Users

Endpoint

GET https://api.callingly.com/v1/agents?account_id=1

Sample response

[
    {
        "id": 123,
        "account_id": 1,
        "fname": "John",
        "lname": "Smith",
        "phone_number": "+16024819661",
        "ext": "",
        "donotdisturb": 0,
        "priority": 1,
        "timezone": "America/Phoenix",
        "is_available": true
    }
]

Get Agent Schedule

Endpoint

GET https://api.callingly.com/v1/agents/{{id}}/schedule

Sample response

[
    {
        "label": "Sunday",
        "day": 0,
        "is_available": false,
        "times": [
            {
                "start": "allday",
                "end": "20:00:00"
            }
        ]
    },
    {
        "label": "Monday",
        "day": 1,
        "is_available": true,
        "times": [
            {
                "start": "06:00:00",
                "end": "20:00:00"
            }
        ]
    },
    {
        "label": "Tuesday",
        "day": 2,
        "is_available": true,
        "times": [
            {
                "start": "06:00:00",
                "end": "12:00:00"
            },
            {
                "start": "12:00:00",
                "end": "23:45:00"
            }
        ]
    },
    {
        "label": "Wednesday",
        "day": 3,
        "is_available": true,
        "times": [
            {
                "start": "06:00:00",
                "end": "20:00:00"
            }
        ]
    },
    {
        "label": "Thursday",
        "day": 4,
        "is_available": true,
        "times": [
            {
                "start": "06:00:00",
                "end": "22:00:00"
            }
        ]
    },
    {
        "label": "Friday",
        "day": 5,
        "is_available": true,
        "times": [
            {
                "start": "allday",
                "end": "20:00:00"
            }
        ]
    },
    {
        "label": "Saturday",
        "day": 6,
        "is_available": true,
        "times": [
            {
                "start": "allday",
                "end": "20:00:00"
            }
        ]
    }
]

Create Agent

Endpoint

POST https://api.callingly.com/v1/agents

Sample response

{
	"account_id": 1,
	"fname": "John",
        "lname": "Smith",
	"phone_number": "555-555-5555",
	"ext": "100",
	"timezone: "America/Phoenix"
}

Update Agent

Endpoint

PUT https://api.callingly.com/v1/agents/{{id}}

Sample request

{
	"account_id": 1,
	"fname": "John",
        "lname": "Smith",
	"phone_number": "555-555-5555",
	"ext": "100",
	"timezone: "America/Phoenix",
	"donotdisturb": 1,
        "donotdisturb_until" "2021-01-25 22:00:00"
}

Delete Agent

Endpoint

DELETE https://api.callingly.com/v1/agents/{{id}}

Update Schedule

Endpoint

PUT https://api.callingly.com/v1/agents/{{id}}/schedule

Sample Request

[
    {
        "label": "Sunday",
        "day": 0,
        "is_available": false,
        "times": [
            {
                "start": "allday",
                "end": "20:00:00"
            }
        ]
    },
    {
        "label": "Monday",
        "day": 1,
        "is_available": true,
        "times": [
            {
                "start": "06:00:00",
                "end": "20:00:00"
            }
        ]
    },
    {
        "label": "Tuesday",
        "day": 2,
        "is_available": true,
        "times": [
            {
                "start": "06:00:00",
                "end": "12:00:00"
            },
            {
                "start": "12:00:00",
                "end": "23:45:00"
            }
        ]
    },
    {
        "label": "Wednesday",
        "day": 3,
        "is_available": true,
        "times": [
            {
                "start": "06:00:00",
                "end": "20:00:00"
            }
        ]
    },
    {
        "label": "Thursday",
        "day": 4,
        "is_available": true,
        "times": [
            {
                "start": "06:00:00",
                "end": "22:00:00"
            }
        ]
    },
    {
        "label": "Friday",
        "day": 5,
        "is_available": true,
        "times": [
            {
                "start": "allday",
                "end": "20:00:00"
            }
        ]
    },
    {
        "label": "Saturday",
        "day": 6,
        "is_available": true,
        "times": [
            {
                "start": "allday",
                "end": "20:00:00"
            }
        ]
    }
]

Calls

Get Call

Endpoint

GET https://api.callingly.com/v1/calls/{{call_id}}

Sample Response

{
    "id": 1234,
    "started_at": "2020-11-11 12:08:13",
    "direction": "outbound",
    "status": "completed",
    "status_formatted": "Completed",
    "lead_status": "contacted",
    "lead_status_formatted": "Contacted",
    "ring_status": "completed",
    "seconds": 5,
    "duration": "5s",
    "retry": 0,
    "lead_retry": 0,
    "time_formatted": "11/11/20 12:08pm",
    "from_formatted": "(123) 456-7890",
    "source": "App",
    "recording_url": "https://cdn.callingly.com/recordings/example.mp3",
    "waveform_url": "https://cdn.callingly.com/waveforms/example.png",
    "error_message": null,
    "phone_number_formatted": "(123) 456-7890",
    "human_result": "contacted",
    "user": {
        "id": 1,
        "name": "Michael Scott",
        "fname": "Michael",
        "lname": "Scott",
        "email": "michael@dundermifflin.com",
        "phone_number": "+11234567890",
    },
    "lead": {
        "id": 1234567,
        "name": "Example Lead",
        "label": "Example Lead",
        "fname": "Example",
        "lname": "Lead",
        "email": "example@lead.com",
        "phone_number": "+11234567890",
        "phone_number_formatted": "(123) 456-7890",
        "source": null,
        "crm": null,
        "source_id": null,
        "deleted_at": null
    },
    "number": null,
    "tag": null,
    "notes": [],
    "profile": {
        "id": 12345,
        "name": "Example Team"
    },
    "is_voicemail": 0,
    "is_queue": 0,
    "is_team_offline": 0,
    "scheduled_call_type": null,
    "old_lead_owner_id": null,
    "transcript": "Speaker A: Hello this is a call...",
    "sales_advice": null,
    "is_error": 0,
    "error_code": ""
}

List Calls

Endpoint

GET https://api.callingly.com/v1/calls?start=2020-01-01&end=2020-02-01&team_id=123&limit=10&page=1

Sample Response

{
    data: [
        {
            id: 12343,
            started_at: "2020-11-30 10:54:01",
            direction: "outbound",
            status: "completed",
            lead_status: null,
            seconds: 37,
            duration: "37s",
            retry: 0,
            lead_retry: 0,
            time_formatted: "11/30/20 10:54am",
            source: "Dashboard",
            member: [],
            lead: [],
            profile: [],
            recording_url:
                 "https://cdn.callingly.com/recordings/da3c0bf.mp3",
        }
    ]
}

Create Call

Endpoint

POST https://api.callingly.com/v1/calls

Sample Request

{
    "account_id": 1,
    "team_id": 123,    
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "555-555-5555",
    "email": "john@doe.com",
    "company": "John's Pools",
    "category": "Pools",
    "source": "HubSpot",
    "crm_id": 123
}


Leads

List Leads

Endpoint

GET https://api.callingly.com/v1/leads?start=2020-01-01&end=2020-02-01&phone_number=+14801234567

Sample Response

[
  {
    "id": 1,
    "account_id": 1,
    "lead_owner_id": 4,
    "fname": "Test",
    "lname": "Lead",
    "email": "test@lead.com",
    "phone_number": "+14801234567",
    "source": "Webhook",
    "source_id": null,
    "created_at": "2024-05-21 23:37:54",
    "company": "Callingly",
    "category": null,
    "status": "missed",
    "result": null,
    "team": {
      "id": 1,
      "name": "Team 1"
    },
    "tags": [],
    "stage": null,
    "calls": [
      {
        "id": 1,
        "source": null,
        "seconds": 0,
        "direction": "outbound",
        "status": null,
        "result": null,
        "agent_retry": 0,
        "lead_retry": 0,
        "started_at": "2024-06-03 23:57:04",
        "recording_url": null
      }
    ],
    "scheduled_call_at": "06/13/24 3:48pm MST",
    "lead_owner": {
      "name": "Bartholome Wilkinson",
      "phone_number": "+14801239876",
      "custom_id": null
    }
  }
]

Get Lead

Endpoint

GET https://api.callingly.com/v1/leads/{{id}}

Sample Response

{
  "id": 1,
  "account_id": 1,
  "lead_owner_id": 4,
  "fname": "Test",
  "lname": "Lead",
  "email": "test@lead.com",
  "phone_number": "+14801234567",
  "source": "Webhook",
  "source_id": null,
  "created_at": "2024-05-21 23:37:54",
  "company": "Callingly",
  "category": null,
  "status": "missed",
  "result": null,
  "team": {
    "id": 1,
    "name": "Team 1"
  },
  "tags": [],
  "stage": null,
  "scheduled_call_at": "06/13/24 3:48pm MST"
}

Delete Lead

Endpoint

DELETE https://api.callingly.com/v1/leads/{{id}}

Sample Response

{
  "success": true
}

Webhooks

List All Webhooks

Endpoint

GET https://api.callingly.com/v1/webhooks

Sample Response

[
    {
        "id": 1122,
        "account_id": 1,
        "name": "My Webhook 1",
        "event": "lead_updated",
        "target_url": "http://example.com/",
        "call_status": null,
        "call_lead_status": null,
        "team_id": 1,
        "number_id": 1,
        "field": null,
        "filter": null
    },
    {
        "id": 1123,
        "account_id": 1,
        "name": "My Webhook 2",
        "event": "call_completed",
        "target_url": "http://example.com/",
        "call_status": null,
        "call_lead_status": null,
        "team_id": 1,
        "number_id": 1,
        "field": null,
        "filter": null
    },
]

Get a Webhook

Endpoint

GET https://api.callingly.com/v1/webhooks/{{id}}

Sample Response

{
    "id": 1123,
    "name": "My Webhook",
    "account_id": 1,
    "event": "call_completed",
    "target_url": "http://example.com/",
    "call_status": null,
    "call_lead_status": null,
    "team_id": 1,
    "number_id": 1,
    "field": null,
    "filter": null
}

Create a Webhook

Endpoint

POST https://api.callingly.com/v1/webhooks

Fields

Field Type Required Example
name

string


 Yes My Webhook
event

string

  • call_completed
  • lead_created
  • lead_updated

 Yes call_completed
target_url string (url) Yes http://www.example.com/

call_direction


call_completed event only

string | null

  • outbound
  • inbound
 No null

call_status


call_completed event only

string | null

  • completed
  • missed
  • offline
 No completed

call_lead_status


call_completed event only

string | null

  • contacted
  • missed
  • removed
  • voicemail
 No contacted

team_id


call_direction outbound only

call_completed event only

 int | null No 123

number_id


call_direction inbound only

call_completed event only

 int | null No 456

field - only trigger the webhook when the selected lead field has changed .


lead_updated, lead_created events only

string | null

  • lead_owner
  • result
  • stage
  • status
  • tags
 No stage

filter - only leads with the matching value in the field will trigger the webhook


lead_updated, lead_created events only

 string | null No called

Sample Body

{
    "name": "My Webhook",
    "event": "call_completed",
    "target_url": "http://example.com/",
    "team_id": 1
}

Sample Response

{
    "id": 1124,
    "name": "My Webhook,
    "account_id": 1,
    "event": "call_completed",
    "target_url": "http://example.com/",
    "call_status": null,
    "call_lead_status": null,
    "team_id": 1,
    "number_id": 1,
    "field": null,
    "filter": null
}

Update a Webhook

This endpoint supports partial updates.

Endpoint

PUT https://api.callingly.com/v1/webhooks

Fields

Field Type Required Example
name

string


 Yes My Webhook
event

string

  • call_completed
  • lead_created
  • lead_updated

 Yes call_completed
target_url string (url) Yes http://www.example.com/

call_direction


call_completed event only

string | null

  • outbound
  • inbound
 No null

call_status


call_completed event only

string | null

  • completed
  • missed
  • offline
 No completed

call_lead_status


call_completed event only

string | null

  • contacted
  • missed
  • removed
  • voicemail
 No contacted

team_id


call_direction outbound only

call_completed event only

 int | null No 123

number_id


call_direction inbound only

call_completed event only

 int | null No 456

field - only trigger the webhook when the selected lead field has changed .


lead_updated, lead_created events only

string | null

  • lead_owner
  • result
  • stage
  • status
  • tags
 No stage

filter - only leads with the matching value in the field will trigger the webhook


lead_updated, lead_created events only

 string | null No called

Sample Body

{
    "target_url": "http://example.com/new_url",
    "number_id": 1
}

Sample Response

{
    "id": 1124,
    "name": "My Webhook",
    "account_id": 1,
    "event": "call_completed",
    "target_url": "http://example.com/new_url",
    "call_status": null,
    "call_lead_status": null,
    "team_id": 1,
    "number_id": 1,
    "field": null,
    "filter": null
}

Delete a Webhook

Endpoint

DELETE https://api.callingly.com/v1/webhooks/{{id}}

Sample Response

{
    "message": "Webhook deleted."
}
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us