Please refer to the detailed API endpoint specification: Update campaign contacts

What you can achieve with the Campaigns API

Campaigns API enables you to obtain a list of campaign IDs from your contact center and add contacts to a live outbound dialer campaign.

Update campaign contacts

The Update campaign contacts method enables you to update multiple contacts in an active Dialer campaign programmatically.

The following attributes are supported for an updated contact:

Phone number: (Mandatory) The contact's phone number in E.164 format.
Contact name: The contact's name is displayed on the agent’s softphone when the call is connected.
Contact source: Where the contact record was obtained.
Contact URL: The URL for the CRM screen pop of the contact's record.
Priority: The contact's priority for calling purposes.
Is Active: An indication of whether or not the contact should be called for this campaign.

Important: To use contact names, sources, and URLs, contact your Voiso representative.

Prerequisites

The Dialer campaign must have the Live campaign setting enabled.
The campaign ID, which can be obtained by using List campaigns API request or from the Outbound > Campaigns page.
A valid phone number for each contact in E.164 format without the preceding '+'. For example: 441234567890.

Making requests

The Update contacts API requires the Base URL (cluster_id) and the contact center API key.

It uses the following parameters to update the contact list:

Parameter	Description	Type	Required	Notes
key	The contact center API key for authentication.	string	Required	Must be included in the request URL.
campaign_id	The identification number associated with the campaign to which the contacts are to be added. It an be obtained by using the List campaigns API request or from the Outbound > Campaigns page.	string	Required	Must be included in the request URL.
contacts	An array of phone numbers and contact information to be added to a Dialer campaign.	array	Required	Must be included in the request Body.

Contacts array

Parameter	Description	Type	Required	Notes
phoneNumber	The recipient's phone number.	string	Required	The number must be specified in E.164 format without the preceding '+'. For example: 447414992548
contactName	The name of the contact.	string	Optional
contactSource	The name of the source of the contact information, such as a trade show, CRM, and so on.	string	Optional
contactURL	The URL of a CRM or other integrated application where the contact’s record can be screen-popped. Refer to CRM integration overview.	string	Optional
priority	A value assigned to the contact to determine the calling order for Dialer.	string	Optional	The range is from 0 to 1000, where 0 is the highest priority.
isActive	An indicator of whether the contact should be dialed as part of the campaign.	number	Optional	Valid values are 0 and 1. 0 means the contact should not be called. 1 means the contact should be called.

With these parameters, you can make a PUT request:

PUT {
  "method": "PUT",
  "url": "https://cluster1.contact_center_name.com/api/v1/ab7a556b6...bb00cc6c3/campaigns/25735/contacts",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "contacts": [
      {
        "phoneNumber": "4407414992548",
        "contactName": "Bill Bringy",
        "contactSource": "CRM",
        "contactURL": "https://myurl.com",
        "priority": "1",
        "isActive": 1
      },
      {
        "phoneNumber": "4407415552548",
        "contactName": "Alicia Gonzales",
        "contactSource": "CRM",
        "contactURL": "https://myurl.com",
        "priority": "2",
        "isActive": 0
      }
    ]
  }
}

Note: You may have multiple contacts parameters.

Response

The following table describes the elements of the response.

Element	Description	Type	Notes
numbers_not_found	Phone numbers that do not exist in the campaign or that you are trying to update more than once.	array	An array of strings.
invalid_numbers	Phone numbers that are not in the E.164 format.	array	An array of strings.
contacts	Phone numbers successfully added to the campaign.	array	An array of strings.

Response sample

{
  "numbers_not_found": [
    “525555013275”,
    "541160905555"
  ],
  "invalid_numbers": [
    “525742360”,
    “1170347521”
  ],
  "contacts": [
    "541123654789",
    “541160908475”,
    “525552489136”
  ]
}

Troubleshooting

The following issues are sometimes encountered:

Invalid Key

The Add Contacts API requires the user API key to validate the request. If you see this error, "error": "Invalid Key", check that you are using the correct user API key. For more information about API keys, refer to Authentication.

Campaign not found

If you see this error, "error": "Campaign not found", the campaign ID that you specified in the request URL does not exist in your contact center or is not accessible to the user.

To verify the campaign ID, use the List campaigns API to request it, or from the Outbound > Campaigns page, find the campaign ID in the Campaigns table.

To verify that the user has access to the specified campaign, check the user profile associated with the API request. The Edit all campaigns or Edit own campaigns permissions must be assigned to the user's profile.

Campaign type should be live

If you see this error, "error": "Campaign type should be live", the Live campaign option is not enabled for the specified campaign. To set this option, from the Voiso main menu bar, navigate to Outbound > Dialer campaigns and select the campaign. On the Edit campaign page, select Live campaign and save the campaign.

Maximum limit of 1000 contacts for each request

If you see this error, "error": "Maximum limit of 1000 contacts for each request", your POST request is attempting to add more than 1000 contacts to the campaign. To add more than 1000 contacts, make multiple requests of up to 1000 contacts each.

Required contact field missing

If you see this error, "error": "Required contact field missing - phoneNumber", there is no phone number available for one or more of the contacts you are trying to add to the campaign. Please ensure that you have a phone number for every contact you add to the campaign.