API Reference
Log InRequest Live Demo

Common and Useful API Examples

Here, you can find common API request logic to help you understand the logic workflow.

Add leads in batch

Allow you to insert batch of lead in a single requst.

EndpointMethodBody Structure:
/api/leadsPOSTleads: array of objects.
allowed fields:
first_name, last_name, phone,phone2, address1, address2, country, state, city, zip, timezone, original_identifier, support_site, purchase_site, purchase_date, purchase_amount, purchase_product_name, purchase_card_name, purchase_card_type, purchase_card_digits, email, birthdate, loan_amount.
special fields:
customFields: an array of additional custom lead fields.

Example:

curl --location 'https://example.td.commpeak.com/api/leads' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic *** \
--data-raw '[
    {
        "first_name": "Alfred",
        "last_name": "Smith",
        "phone": "447700001234",
        "address1": "150 Albert Road",
        "city": "London",
        "country": "UK",
        "original_identifier": "",
        "support_site": null,
        "purchase_site": null,
        "purchase_date": null,
        "purchase_amount": null,
        "purchase_product_name": null,
        "purchase_card_name": null,
        "purchase_card_type": null,
        "purchase_card_digits": null,
        "email": "[email protected]",
        "birthdate": "2000-01-23",
        "loan_amount": null,
        "customFields": {
                   "affiliate": "BZ15",
                   "deposit_date": "2022-01-23 12:50:00"
        }
    }
]'

Success response returns a JSON payload with a list of inserted leads. Each lead includes the field "id," which is the unique lead ID.


Assign leads in batch

Allow you to assign existing leads to campaign, success assign will create campaign lead entity.

EndpointMethodBody Structure:
/api/campaign-leads/mass-assignPUTremove_from_others: remove from other campaigns (true - remove, false - skip).
campaign_id: campaign to add lead to.
where: array of conditions, can have any of the following fields: id, first_name, last_name, phone, phone2, address1, address2, country, state, city, zip, timezone, original_identifier, support_site, purchase_site, purchase_date, purchase_amount, purchase_product_name, purchase_card_name, purchase_card_type, purchase_card_digits, email, birthdate, loan_amount.

In this example, we assign lead id 49969 to campaign 12:

curl --location --request PUT 'https://example.td.commpeak.com/api/campaign-leads/mass-assign' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ***' \
--data '{
"where": {
"id": ["49969"]
},
"campaign_id": 12,
"remove_from_others": false
}'

In this example, we notify that lead ID 49969 was assigned to campaign 12 successfully, and campaign lead ID 78057 was created.

{
    "leads": {
        "78057": {
            "id": "49969",
            "first_name": "Alfred",
            "last_name": "Smith",
            "phone": "447700001234",
            "phone_normalized": "447700001234",
            "original_identifier": ""
        }
    }
}

Creating campaign (cloning from existing)

Allow you to copy or duplicate existing campaign with all campaign related settings (statuses, rules, lead lifecycle).

EndpointMethodBody Structure:
/api/campaigns/cloneGET

In this example, we create a new campaign by cloning from existing campaign ID 12:

curl --location 'https://example.td.commpeak.com/api/campaigns/clone' \
--header 'Authorization: Basic ***' \
--data '{
  "campaign_id": 12,
  "default_caller_id": 123456789
}'

In this example, we notify that new campaign ID 16 was created with all the campaign settings:

{
    "campaigns": [
        {
            "id": "16",
            "name": "[clone of] Campaign 12",
            "description": "[clone of] Campaign 12",
            "creator_user_id": "2",
            "is_active": "1",
            "agent_callerid_name": "AgentId",
            "agent_callerid_number": "11223344",
            "client_callerid_name": "Client",
            "client_callerid_number": "777777777777",
            "default_weight": "0",
            "auto_dial": "0",
            "auto_dial_delay": "0",
            "feedback_timeout": "3000",
            "feedback_default_status": "2",
            "created_at": "2012-04-22 11:16:22",
            "updated_at": "2014-08-18 11:28:08",
            "is_deleted": "0",
            "default_permanent_expiration_days": "5",
            "campaign_type": "predictive",
            "predictive_call_ratio": "3",
            "predictive_call_timeout": "30",
            "default_busy_status": "45",
            "default_voice_mail_status": "42",
            "default_fax_status": "44",
            "default_timeout_status": "43",
            "default_not_exists_status": "46",
            "predictive_fallback_action": "playback",
            "predictive_fallback_action_options": "test.wav",
            "default_error_status": "0",
            "default_answer_status": "2",
            "predictive_fallback_action_timeout": "0",
            "remote_data_url": "http://your_crm_url.com/lead_{original_identifier}.php",
            "remote_call_screen_enabled": "0",
            "predictive_ringing_preservation_ratio": "1",
            "predictive_preservation_min_ringing_duration": "40",
            "default_direct_dial_status": "0",
            "highest_priority_weight": "10000",
            "voicemail_time_options": "once",
            "fetch_leads_type": "priority",
            "parent_id": null,
            "permanent_callback_keepalive": "1",
            "permanent_agent_offline_keepalive": "3",
            "permanent_daily_limit": "0",
            "permanent_total_limit": "0",
            "available_agent_search_timeout": "10",
            "custom_call_fields": "[\"original_identifier\",\"first_name\",\"last_name\",\"country_name\",\"timezone_name\"]",
            "min_weight": "0",
            "advanced_call_fields": "",
            "iframe_call_fields": "",
            "remote_javascript_code": "",
            "default_remote_adapter_channel_id": "0",
            "redial_limit": "0",
            "hide_voicemail_for_no_ratio_permanents": "0",
            "voicemail_button_hide_timeout": "40",
            "end_call_show_timeout": "5",
            "notify_user_about_online_lead": "0",
            "permanent_expiration_active": "0",
            "no_ratio_leads_fetching_method": "queue",
            "highest_priority_weight_ratio_level": "0",
            "is_caller_id_random": "1",
            "is_hold_enabled": "0",
            "show_phone_symbols": "-1",
            "amd_enabled": "0",
            "amd_max_duration": "5",
            "amd_settings": "",
            "phone_mask_mode": "last",
            "voice_mail_button_status": "9",
            "override_dropped_call_action": "1"
        }
    ]
}

📘

We recomends to create campaign from exist one

Campaign entity relared to other entities in related on 1 to many: statuses, lead lifecycle workflows, automation rules, SIP URIs, dialing caller IDs.
This endpoint creates new campaign with the exist related entities logic data without the need to setup this setting manually.


Update mass leads / campaign leads data

Allow you to update a lot of campaign leads and thier related leads data according to search filters.
This powerful endpoint helps you to made changes on your data with a single request.

EndpointMethodBody Structure:
/api/campaign-leads/update-campaign-leadsPUTwhere: array of campaign lead IDs that were affected.
update: array separate to lead and campaignLead. Each of them includes data that needs to be updated.

In this example, we change the status to campaign lead 78057 and update the phone number to his related lead:

curl --location --request PUT 'https://example.td.commpeak.com/api/campaign-leads/update-campaign-leads' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ***' \
--data '{
  "where": {
    "id": [78057]
  },
  "update": {
    "lead": {
        "phone": "447700001235"
     },
    "campaignLead": {
        "status_id": 69
    }
  }
}'

📘

Updating lead fields?

We recommend using this endpoint if you wish to perform a massive and permanent update on a large number of leads in one request, such as updating a specific affiliate for a bunch of leads.

🚧

Updating status?

Remember that updating campaign lead status will initiate the campaign automation rules that can take cupple of minutes until lead will be available to call according to your rules logic.


Removing duplicates (keeping a specific lead only in 1 campaign)

Allow you to delete duplicate campaign leads in same campaigns.

  1. First, let's find the lead IDs that you need to handle. you can use./api/leads/ endpoint to search leads according to various filters.

In this example, we fetch all leads with the same phone number: 

curl --location 'https://example.td.commpeak.com/api/leads/phone/447700001235/' \
--header 'Authorization: Basic ***'

In this example, we fetch all leads that field "purchas_card_name" include affiliate BZ150:

curl --location 'https://example.td.commpeak.com/api/leads/purchase_card_name/affiliate_bz150/' \
--header 'Authorization: Basic ***'

The response returns the full lead data, including lead ID.

  1. Remove your lead ID duplications via the/api/campaign-leads/mass-assign endpoint with the _remove_from_others_ option.

In this example, we remove all campaign leads related to leads 1,2,3 from all campaigns that are not campaign 12:

curl --location --request PUT 'https://example.td.commpeak.com/api/campaign-leads/mass-assign' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ***' \
--data '{
"where": {
"id": [1, 2, 3]
},
"campaign_id": 12,
"remove_from_others": true
}'

This means that if lead ID 3 has 2 campaign leads, one in campaign 12 and the other in campaign 13, the related campaign lead from campaign 13 will deleted.


📘

Why do I need to ensure the same lead does not exist in more than 1 campaign?

We recommend assigning a lead to one campaign concurrently. A lead can be considered like a person, and a campaign lead is considered as an entity that holds the status workflow.

Having the same lead in several campaigns requires extra attention since any update to this lead will affect all the campaigns it is assigned to.


Move To Campaign with preserved data

Allow you to move lead from campaign to another with preserving importand assigned campaign lead data.

EndpointMethodBody Structure:
/api/campaign-leads/move-to-campaignPUTid: array of lead IDs.
source_campaign_id: campaign ID to move lead from.
destination_campaign_id: campaign ID to move lead to.
with_preserve_data: preserve data (true / false)

In this example, we move lead ID 49969 from campaign 12 to campaign 13.

curl --location --request PUT 'https://example.td.commpeak.com/api/campaign-leads/move-to-campaign' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ***' \
--data '{
  "id": [
    "49969"
  ],
  "source_campaign_id": 12,
  "with_preserve_data": true,
  "destination_campaign_id": 13
}'

📘

Which data will be preserved while I'm moving the lead?

Preserved data will move with the campaign lead from one campaign to another, while regular moving will delete the campaign lead and assign the related lead to the new campaign.

Preserved data includes: calls counter, assigned user, log history, and status.

🚧

Status attention:

Moving with preserved data is allowed only if the current campaign lead status name exists in the destination new campaign.


Get CDRs

Allow you to fetch Call Detail Records (CDR) according to filters.

EndpointBody Structure:
/api/cdrsfields: allow to choose response fields separate with semicolon.
limit: results per page with offset. 100;0 next first 100 results, 100;100 next 100 results.
Allow to filter by any field that is available on the results

In this example, we are fetching CDRs that were made between 2025-01-01 and 2025-01-06, q850 > 0 (means we want only not ongoing calls), ordered by call end time. Filtered by fields status, q850 and end_at.

fields=status;q850;end_at&start_at=2025-01-01 00:00:00;>&end_at=2025-01-06 00:00:00;<&q850=0;>&order=end_at;asc&limit=1;0


curl --location 'https://xpro-ph.td.commpeak.com/api/cdrs?fields=status%3Bq850%3Bend_at&start_at=2025-01-01%2000%3A00%3A00%3B%3E&end_at=2025-01-06%2000%3A00%3A00%3B%3C&q850=0%3B%3E&order=end_at%3Basc&limit=1%3B0' \
--header 'Authorization: Basic ***='

Get call with recording file

Allow you to get call recording file

EndpointBody Structure:
/api/cdrsfields: allow to choose response fields separate with semicolon.
limit: results per page.
offset: pagination interval.
Allow to filter by any field that is available on the results

In this example, we searched after all calls that started from 2024-10-22 and duration greater than 60 seconds: 

curl --location 'https://example.td.commpeak.com/api/calls/?start_at=2024-10-01%3B%3E&call_bill_duration=60%3B%3E' \
--header 'Authorization: Basic ***'

To retrieve only call ID in response insert to request fields param according to example:

curl --location 'https://example.td.commpeak.com/api/calls/?start_at=2024-10-01%3B%3E&call_bill_duration=60%3B%3E&fields=id' \
--header 'Authorization: Basic ***'

Now, after we have the require call IDs, we can request the call recording file:

curl --location 'https://example.td.commpeak.com/api/calls/45475/record' \
--header 'Authorization: Basic ***'

Reponse return binary file content in .flac foramt.