Overview

This article contains basic information on where to find your API Authorization Token and how to use the menu options in the API Main Menu. 

Each page and tab in the API menu includes the HTTP Method, and Example PHP and JSON Responses, and a Test Request function.

Contents:

• Authorization Tokens
• API URLs
• Leads API
  • Insert Lead Tab
  • Update Lead Tab
  • Delete Lead Tab
  • Search Leads Tab
  • Get Lead Recordings Tab
• Agent Performance API
• Call Logs API
  • Search Call Log
  • Update Call Logs Tab
• Callbacks API
  • Insert Callbacks
• Campaigns API
  • Campaign Status Tab
  • Search Campaign Tab
• Lists API
  • Insert List Tab
  • Update List Tab
  • Delete List Tab
  • Search List Tab
• Users API
  • Get Recordings Tab
  • Search Tab

Authorization Tokens

• Click the API main menu.
• Click the Authorization Token menu option.

The Manage Authorization Token page will open.

• Click the blue Add Authorization Token button to add a token.

The Add Token modal window will open.

• Select tokens by clicking the checkboxes in the Access column.
• Click the Create button.

API URLs

• Leads API
  • Lead Insert API URL: https://api.convoso.com/v1/leads/insert
  • Update Leads API URL: https://api.convoso.com/v1/leads/update
  • Delete Leads API URL: https://api.convoso.com/v1/leads/delete
  • Leads Search API URL: https://api.convoso.com/v1/leads/search
  • Lead Get Recordings API URL: https://api.convoso.com/v1/leads/get-recordings
• Agent Performance API URL: https://api.convoso.com/v1/agent-performance/search
• Call Logs API
  • Search Call logs API URL: https://api.convoso.com/v1/log/retrieve
• Callbacks API
  • CallbacksAPI URL: https://api.convoso.com/v1/callbacks/search
• Campaigns API
  • Campaign Status API URL: https://api.convoso.com/v1/campaigns/status
  • Search Campaign API URL: https://api.convoso.com/v1/campaigns/search
• List API
  • Insert List API URL: https://api.convoso.com/v1/lists/insert
  • Update List API URL: https://api.convoso.com/v1/lists/update
  • Delete List API URL: https://api.convoso.com/v1/lists/delete
  • Search List API URL: https://api.convoso.com/v1/lists/search
• Users API
  • User Get Recordings API URL: https://api.convoso.com/v1/users/recordings
  • Search Users API URL: https://api.convoso.com/v1/users/search

Leads API

API menu > Leads option

The Leads menu option will open Leads API on the Insert Lead tab.

Insert Lead Tab

Required Argument:

On the page you can see more optional Arguments that can be used.

At the bottom of the Arguments list are the HTTP Method, Example PHP Usage, and Example JSON Response.

Example PHP Usage
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/leads/insert');
curl_setopt($ch, CURLOPT_POST, 1);

curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
'auth_token' => 'd2e422d1311c72c408344465fe2258c2a7356061',
'list_id' => 10,
'phone_number' => '8181234560',
'status' => 'CALLBK',
'phone_code' => 1,
'user' => 'john1',
'FirstName' => 'John',
'LastName' => 'Test',
)));

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$result = curl_exec($ch);

Example JSON Response
curl_close($ch);{
"success": true,
"data": {
"lead_id": "65007347"
}
}

Update Lead Tab

• While in Leads API, click the Update Lead tab.

Required Arguments

Example PHP usage
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/leads/update');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
'auth_token' => 'd2e422d1311c72c408344465fe2258c2a7356061',
'lead_id' => '65007347',
'list_id' => 10,
'PhoneNumber' => '8181234561',
'phone_code' => 44,
'status' => 'CALLBK',
'FirstName' => 'John',
'LastName' => 'Test',
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

curl_close($ch);

Example JSON Response
{
"success": true,
"data": {
"lead_id": "65007347"
 }
}

Delete Lead Tab

Delete a Lead for an authenticated user.

• While in Leads API, click the Delete Lead tab.

Required Arguments

Example PHP Usage
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/leads/delete');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
'auth_token' => 'd2e422d1311c72c408344465fe2258c2a7356061',
'lead_id' => '65007347',
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

curl_close($ch);

Example JSON Response
{
"success": true
}

Search Leads Tab

Globally search through all the account Leads.

• While in Leads API, click the Search Leads tab.

Searchable fields are marked in Green in the Required/Optional column.

Required Arguments

Example PHP Usage
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/leads/search');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
'auth_token' => 'd2e422d1311c72c408344465fe2258c2a7356061',
'FirstName' => 'John',
'LastName' => 'Test',
'offset' => 0,
'limit' => 10,
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

curl_close($ch);

Example JSON Response
{
 "success": true,
 "data": {
  "offset": "0",
  "limit": "10",
  "total": 1,
  "entries": [
    {
       "id": 38002,
       "created_at": "2015-01-29T14:09:57-0800",
       "status": "CALLBK",
       "phone_number": "8181234561"
      },
      {
        "...": "..."
      }
    ]
  }
}

Get Lead Recordings

Returns a list of all Lead recordings.

• While in Leads API, click the Get Recordings tab.

Required Arguments

Example PHP Usage
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/leads/get-recordings');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
'auth_token' => 'd2e422d1311c72c408344465fe2258c2a7356061',
'lead_id' => '65007347',
'start_time' => '2010-01-01 00:00:00',
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

Example JSON Response
{
"success": true,
"data": {
"offset": 0,
"limit": 10,
"total": 1,
"entries": [
{
"recording_id": 8,
"lead_id": 270,
"start_time": "2014-06-19 21:11:36",
"end_time": "",
"seconds": 10,
"url": "1403237496-all.wav"
}
]
}
}

Agent Performance API

API menu > Agent Performance option

Retrieving Agent Performance records.

• Click the API main menu.
• Click the Agent Performance menu option.

The Agent Performance page will open.

Required Arguments

On the page you can see more optional Arguments that can be used.

At the bottom of the Arguments list are the HTTP Method, Example PHP Usage, and Example JSON Response.

Example PHP Usage
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/agent-performance/search'); 
curl_setopt($ch, CURLOPT_POST, 1); 
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array( 
'auth_token' => 'd2e422d1311c72c408344465fe2258c2a7356061',
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

curl_close($ch);

Example JSON Response
{
"success": true,
"code": 200,
"total": 6,
"data": {
"1000479": {
"name": "Bob Smith",
"talk_sec_pt": 3.31,
"wait_sec_pt": 87.13,
"pause_sec_pt": 8.82,
"wrap_sec_pt": 0.74,
"talk_sec": "00:00:09",
"wait_sec": "00:03:57",
"pause_sec": "00:00:24",
"wrap_sec": "00:00:02",
"total_time": "00:04:32",
"am": 0,
"others": 2,
"calls": 2,
"am_pt": 0,
"others_pt": 100,
"call_type": "",
"user_id": "1000479"
}
}
}

Call Logs API

API menu > Call Logs option

Search Call Log Tab

Retrieving call log records.

• Click the API main menu.
• Click the Call Logs menu option.

Call Logs API will open on the Search Call Log tab.

Required Arguments

Example PHP Usage
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/log/retrieve'); 
curl_setopt($ch, CURLOPT_POST, 1); 
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array( 
'auth_token' => 'd2e422d1311c72c408344465fe2258c2a7356061',
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

curl_close($ch);

Example JSON Response
{
"success": true
}

Update Call Log Tab

Update Call Log records.

• While in Call Logs API click the Update Call Log tab.

Required Arguments

On the page you can see more optional Arguments that can be used.

At the bottom of the Arguments list are the HTTP Method, Example PHP Usage, and Example JSON Response.

Example PHP Usage
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/log/update'); 
curl_setopt($ch, CURLOPT_POST, 1); 
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array( 
'auth_token' => 'd2e422d1311c72c408344465fe2258c2a7356061',
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

curl_close($ch);

Example JSON Response
{
"success": true
}

Callbacks API

API menu > Callbacks option

Insert Callback Tab

• Click the API main menu.
• Click the Callbacks menu option.

Callbacks API will open on the Insert Callbacks tab.

Required Arguments

On the page you can see more optional Arguments that can be used.

At the bottom of the Arguments list are the HTTP Method, Example PHP Usage, and Example JSON Response.

Example PHP Usage
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/callbacks/insert'); 
curl_setopt($ch, CURLOPT_POST, 1); 
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array( 
'auth_token' => 'd2e422d1311c72c408344465fe2258c2a7356061',
'lead_id' => '546006',
'recipient' => 'system',
'callback_time_zone' => '-7.00',
'callback_time' => '2020-05-19 09:10 AM'
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

curl_close($ch);

Example JSON Response
{
"success": true,
"data": {
"callback_id": "657"
}
}

Campaigns API

API menu > Campaigns option

Campaign Status Tab

• Click the API main menu.
• Click the Campaigns menu option.

Campaigns API will open on the Campaign Status tab.

Required Arguments

At the bottom of the Arguments list are the HTTP Method, Example PHP Usage, and Example JSON Response.

Example PHP usage
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/campaigns/status'); 
curl_setopt($ch, CURLOPT_POST, 1); 
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array( 
'auth_token' => 'd2e422d1311c72c408344465fe2258c2a7356061',
'campaign_id' => 8,
'status' => true,
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

curl_close($ch);

Example JSON Response
{
"success": true
}

Search Campaign Tab

• While in Campaigns API, click the Search Campaign tab.

Required Arguments

At the bottom of the Arguments list are the HTTP Method, Example PHP Usage, and Example JSON Response.

Example PHP Usage
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/campaigns/search'); 
curl_setopt($ch, CURLOPT_POST, 1); 'auth_token' => 'd2e422d1311c72c408344465fe2258c2a7356061')));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

curl_close($ch);

Example JSON Response
{
"success": true,
"data": []
}

Lists API

API menu > Lists option

Insert List Tab

• Click the API main menu.
• Click the Lists option.

Lists API will open on the Insert List tab.

Required Arguments

On the page you can see more optional Arguments that can be used.

At the bottom of the Arguments list are the HTTP Method, Example PHP Usage, and Example JSON Response.

Example PHP Usage
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/lists/insert');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
'auth_token' => 'd2e422d1311c72c408344465fe2258c2a7356061',
'name' => 'List Name',
'campaign_id' => '80',
'description' => 'List Description',
'status' => 1
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

curl_close($ch);

Example JSON Response
{
"success": true,
"data": {
"list_id": "17257"
}
}

Update List Tab

• While in Lists API, click the Update List tab.

Required Arguments

On the page you can see more optional Arguments that can be used.

At the bottom of the Arguments list are the HTTP Method, Example PHP Usage, and Example JSON Response.

Example PHP Usage
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/lists/update');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
'auth_token' => 'd2e422d1311c72c408344465fe2258c2a7356061',
'list_id' => 17257,
'name' => 'List Name',
'campaign_id' => '81',
'status' => 0
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

curl_close($ch);

Example JSON Response
{
"success": true,
"data": {
"list_id": "17257"
}
}

Delete List Tab

• While in Lists API, click the Delete List tab.

Required Arguments

At the bottom of the Arguments list are the HTTP Method, Example PHP Usage, and Example JSON Response.

Example PHP Usage
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/lists/delete');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
'auth_token' => 'd2e422d1311c72c408344465fe2258c2a7356061',
'list_id' => '17257',
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

curl_close($ch);

Example JSON Response
{
"success": true
}

Search List Tab

• While in Lists API, click the Search List tab.

Required Arguments

On the page you can see more optional Arguments that can be used.

At the bottom of the Arguments list are the HTTP Method, Example PHP Usage, and Example JSON Response.

Example PHP Usage
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/lists/search');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
'auth_token' => 'd2e422d1311c72c408344465fe2258c2a7356061',
'status' => '1',
'campaign_id' => '80'
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

curl_close($ch);

Example JSON Response
{
"success": true,
"data": [
{
"id": 48,
"campaign_id": "64",
"status": "Y",
"last_called_at": {
"date": "2016-03-01 16:51:33.000000",
"timezone_type": 3,
"timezone": "America/Los_Angeles"
}
}
]
}

Users API

API menu > Users option

Get Recordings Tab

• Click the API main menu.
• Click the Users option.

Users API will open on the Get Recordings tab.

Required Arguments

On the page you can see more optional Arguments that can be used.

At the bottom of the Arguments list are the HTTP Method, Example PHP Usage, and Example JSON Response.

Example PHP Usage
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/users/recordings');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
'auth_token' => 'd2e422d1311c72c408344465fe2258c2a7356061',
'start_time' => '2015-01-01 00:00:00',
'end_time' => '2015-02-01 00:00:00',
'user' => 'john1@gmail.com',
'limit' => 20,
'offset' => 40
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

curl_close($ch);

Example JSON Response
{
"success": true,
"data": {
"offset": 0,
"limit": 10,
"total": 10,
"entries": [
{
"recording_id": 8,
"lead_id": 270,
"start_time": "2014-06-19 21:11:36",
"end_time": "",
"seconds": null,
"url": "convoso_8183376356_8_1403237496-all.wav"
},
{
"...": "..."
}
]
}
}

User Search Tab

Returns a list of all user information.

• While in Users API, click the Search tab.

Required Arguments

On the page you can see more optional Arguments that can be used.

At the bottom of the Arguments list are the HTTP Method, Example PHP Usage, and Example JSON Response.

Example PHP Usage
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.convoso.com/v1/users/search');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array(
'auth_token' => 'd2e422d1311c72c408344465fe2258c2a7356061',
'user' => 'john1@gmail.com',
'limit' => 20,
'offset' => 40
)));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

curl_close($ch);

Example JSON Response
{
"success": true,
"data": {
"offset": 0,
"limit": "2",
"total": "641",
"results": {
"11004055": {
"id": 1104055,
"acl_access_profile": 1,
"email": "add_user@example",
"first_name": "add user",
"last_name": "add user",
"user_level": 1,
"queue_override": "USE_CAMPAIGN",
"allow_queue_selection": "1",
"allow_callbacks": "1",
"callback_types_allowed": "1",
"allow_transfers": "1",
"default_blended_selection": "0",
"alter_custdata_override": "Y",
"allow_task_assign": "YES",
"status": "Y",
"local_gmt": "-8.00",
"allow_blended_campaign": "1",
"notification": "0",
"created_at": "2016-11-17T10:54:21-0800",
"connection_type": "BROWSER",
"extension": [
313777
],
"last_login": "2017-10-12 10:09:30"
},
"11005758": {
"id": 1105758,
"acl_access_profile": 1,
"email": "11111111111111@gmail.com",
"first_name": "3333333",
"last_name": "4444444",
"user_level": 1,
"queue_override": "USE_CAMPAIGN",
"allow_queue_selection": "1",
"allow_callbacks": "1",
"callback_types_allowed": "1",
"allow_transfers": "1",
"default_blended_selection": "0",
"alter_custdata_override": "Y",
"allow_task_assign": "YES",
"status": "Y",
"local_gmt": "-8.00",
"allow_blended_campaign": "1",
"notification": "0",
"created_at": "2017-03-28T09:42:28-0700",
"connection_type": "BROWSER",
"extension": [
404377
],
"last_login": null
}
}
}
}