Campaign API

Introduction

The Campaign API includes a method that allows you to search for completed campaigns that match selected criteria, as well as a method to list account transactions for a campaign.

In the future, many additional methods will be added, to allow full programmatic control over the lifecycle of a campaign, as well as real-time metrics about campaigns.

See the LiveVox API Overview for a general description of how to interact with the API.

Prerequisites

The user must have successfully logged into the LiveVox platform to obtain a valid Session ID. See Session Management for more information.
The user must have an active subscription to the Campaign API, in order to obtain an Access Token for use in all API requests. See Access Tokens for details.
All messages in this API may be subject to rate limits and other restrictions.

Campaign API WADL/Swagger

The Session API WADL/Swagger is publicly available; to obtain the WADL/Swagger for any other API category a user will need to include the LV-Session header with a valid session ID in the WADL/Swagger request.

The Campaign API v17.0 WADL/Swagger is available at the following URL:

The URLs listed below are for the LiveVox NA3 environment and will change slightly if your portal is in a different environment. To know how the URL changes per environment, see the LiveVox Environments and APIs section.

Campaign API Resource	Link
Campaign WADL	https://api.livevox.com/campaign/campaigns/?_wadl
Campaign Swagger	https://api.livevox.com/campaign/campaigns/api-docs?url=https://api.livevox.com/campaign/campaigns/swagger.json#/Campaigns

User Roles

Unless otherwise specified in this documentation, for a user to be able to access any data through the Campaign API, the user must belong to the Sysadmin, Superuser, or Manager role.

Within a session generated by an Agent, the following methods of the Campaign API may be accessed. Attempts to access any other API method of the Campaign API will return a 403 Forbidden response.

Find Matching Campaigns
Find Matching Finished Calls

API Methods

Campaigns

Currently, the Campaign API provides a method enabling you to query the LiveVox platform for a list of completed campaigns that meet a specific set of criteria, find a list of matching finished calls, list the records in a campaign, read a campaigns' properties, and list the campaign templates.

Append Campaign Record

Description: Allows for the addition of records to an existing campaign, that is in either the built, playing, or paused state. Limitations of this method include:

The method can only be called 5 times per minute.
When created, the campaign must have the 'Allow Append' feature enabled.
Campaigns cannot contain more than 500,000 records; this is a platform limitation and although an error will not be returned exceeding this limit will cause latency in the platform.
Appendable campaigns will follow the normal dialing sort rules set at the Service level and will be resorted after each successful append request.
- In U10 and above appended records supersede dialing sort rules and are placed at the top of the dialing list.

For detailed information and limitations when using the Append Campaign Record method, see the Adding/Appending Records to Active Campaigns on the User Hub.

Method: PUT /campaign/campaigns/{id}/transactions

Parameters:

Path/Query Parameter Name	Variable Name	Type	Mandatory?	Description
id	campaignId	Integer (ID)	Yes	The ID of the campaign to append records to.

Body:

Key Type Mandatory? Description

records

Array

Yes

An array of campaign transactions

Key	Type	Mandatory?	Description	Character Limit
account	String	No	The account number for the transaction.	50
firstName	String	No	The first name for the transaction.	50
lastName	String	No	The last name for the transaction.	50
phone1	String	Yes	The primary phone number for the transaction.	32
phone2	Array	No	The secondary phone number(s) for the transaction, this field can be filled with up to 29 additional phone numbers separated by a comma.	450
dob	String	No	The date of birth for the transaction must be stored in MMDD format.	20
email	String	No	Email for the transaction.	50
ssn	String	No	The social security number for the transaction, an SSN must be 4 or 9 characters any other number will cause the record to fail.	9
lastPaymentDate	String	No	Can be used to store additional account information.
minimumPaymentAmount	Decimal	No	The minimum payment amount for the transaction.	24
accountToSpeak	String	No	The account number to be TTS'd in the IVR. In most cases, this is the same as the 'account' field, but can be different as there are two different TTS fields that can be used.	50
amountToSpeak	Decimal	No	The amount to be TTS'd in the IVR.	24
extra1	String	No	Used to store agent login ID.	50
extra2	String	No	Can be used to store additional account information.	50
extra3	String	No	Can be used to store additional account information.	50
extra4	String	No	Can be used to store additional account information.	50
extra5	String	No	Can be used to store additional account information.	50
extra6	String	No	Used to store Agent's extension.	50
extra7	String	No	If messaging is configured, can be used to tts names;	50
extra8	String	No	Can be used to store additional account information.	50
extra9	String	No	Used to store the time for a scheduled call back, must be in HH:MM:SS format. Placing a time in this field does not schedule a callback, that can only be done through ACD or the Schedule Callback API.	50
extra11	String	No	Stores the zip code for the transaction and used for zip area mismatch.
extra12	String	No	Stores the date of service information.
extra13	String	No	Can be used to store values. If coming from the input filter, can be used to generate address-type TTS read back. ex: format for TTS 123 Main St.
extra14	String	No	Can be used to store values; if multiple values need to be stored you can separate them with pipes.
extra15	String	No	Can be used to store values; if multiple values need to be stored you can separate them with pipes.
extra16	String	No	Can be used to store additional account information.	50
extra19	String	No	Can be used to store additional account information.	50
extra20	String	No	Can be used to store additional account information.	150
originalAccountNumber	String	No	The original account number for the transaction.
practiceId	Integer	No	The practice ID for the transaction.	24
clientPracticeId	String	No	The client practice ID for the transaction.	50
templateId	String	No	The template ID that will be used on the call; this must be a valid template id or the call will fail. If no template ID is included the template assigned to the service will be used.	24
practicePhone	String	No	The phone number played in the IVR for outbound calls.	13
practicePhoneAlternate	String	Yes^*	The caller ID displayed for outbound calls. ^*Indicates that the '`practicePhoneAlternate`' property is not mandatory in the API request. But if you do not include this property in the API request, then the caller ID will be null and the appended call records will not launch.	13
operatorNumber	String	No	The operator phone used for the transaction. Used as the caller ID on manual dials.	13
placeOfServiceId	Integer	No	This is generally used in conjunction with client_practice_id, storing information about specific locations for the sub-client.	24
altLanguage1	Integer	No	Alternate language a user can choose from in the IVR.	24
altLanguage2	Integer	No	Alternate language a user can choose from in the IVR.	24
altLanguage3	Integer	No	Alternate language a user can choose from in the IVR.	24
languageCallback1	String	No	The legacy setting, no longer in use.	13
languageCallback2	String	No	The legacy setting, no longer in use.	13
languageCallback3	String	No	The legacy setting, no longer in use.	13
language	Integer	No	The main language the IVR will be offered in, leaving this field blank will default to the voice talent set at the Service level.
totalAmount	Decimal	No	The total amount due.

Response Code: 204 No Content

Body:

None

Append Records to a Campaign

#Request (JSON)
PUT /campaign/campaigns/32383930/transactions
Host: localhost.com
Content-Type: application/json
Accept: application/json
 
{
   "records":    [{
      "phone1": "4155556004",
      "account": "1234567890",
      "firstName": "James",
      "lastName": "Brown",
      "phone2": ["4155553849","4155553785"]
   }]
}

#Response (JSON)
204 No Content
Content-Type: application/json

CODE

Create Campaign

Description: Creates a Campaign on LiveVox.

Method: POST /campaign/campaigns

Attachments:

Name	Type	Mandatory?	Description
campaignFile	Attachment - [octet-stream]	Yes	Campaign file containing the records to be uploaded to the platform. The name of the file will become the name of the campaign so it should match the campaign naming pattern of the input filter you want to use.
campaignConfiguration	Attachment - [json]	Yes	The configuration properties for the campaign.

Configuration Properties:

Key Type Mandatory? Description

serviceId Integer Yes The serviceId the campaign will be assigned to

operatorPhone

String

No*

Operator phone to be set for this campaign, this can be a 10 digit number or 'LOCAL' to use an LCID package.

'LOCAL' can only be used if the Service level setting is set to LOCAL CALLER ID.

voiceId Integer Yes Voice ID for one of the available configured voices

answeringMachineOption

Enum

Yes

Denotes the Answering machine behavior for this campaign

Key	Description
LEAVE_MESSAGES	Detects answering machines and leaves a message.
NO_MESSAGES	If an answering machine is detected, no message is left, and the call is disconnected.
TRANSFER	Answering machine detection is off. All connections are passed to agents.

callerId

String

No*

Caller ID to be set for this campaign, this can be a valid 10 digit caller ID configured at the Service level or 'LOCAL' to use an LCID package.

'LOCAL' can only be used if the Service level setting is set to LOCAL CALLER ID. If 'LOCAL' is used callbackPhone and operatorPhone are not required to create a campaign.

callbackPhone

String

No*

Callback phone to be set for this campaign, this can be a 10 digit number or 'LOCAL' to use an LCID package.

'LOCAL' can only be used if the Service level setting is set to LOCAL CALLER ID.

dialingStrategyId Integer Yes Dialing Strategy ID number assigned for this campaign

appendable Boolean No If set to true a user will be able to add records to a campaign after it started using the append campaign record method. If not present it will default to false.

typeId

Enum

Yes

Type of the campaign. Possible types include:

Campaign Type ID	Campaign Type
1	Outbound
6	SMS
7	HCI
8	10DMT

scheduleTime

Object

No

When this element is present, the campaign will be configured to run at the desired schedule. When this element is not present, LVP's OnDemand behavior applies

Key	Type	Mandatory?	Description
start	DateTime	Yes	The start date/time of the campaign, provided in ms, if not provided the campaign will be scheduled to start "ASAP".
end	DateTime	Yes	The end date/time of the campaign, provided in ms, If not provided the campaign will be scheduled to end at "EOD" (End of Day).
nextDay	Boolean	Yes	If set to `true`, the campaign will be scheduled to run the following day.

LiveVox day starts at 04:00 AM ET and ends at 03:59 AM ET. So anything scheduled between 00:00 AM ET to 03:59 AM ET with nextDay flag as true will run at 4:00 AM ET. Anything scheduled after 4:00 AM ET with nextDay flag set as true will run on the following day.

*These properties may be required based on Service level settings. If required and not included in the request an error will be returned stating which field is missing.

Response Code: 201 Created

Body:

Key or Attribute	Type	Mandatory?	Description
id	Integer (ID)	Yes	The ID of the newly created campaign.

Create Campaign

#Request
POST https://api.livevox.com/campaign/campaigns/ HTTP/1.1
Content-Type: multipart/form-data; boundary="----=_Part_0_249168912.1551295147735"
Lv-Session: 8bff6203-aa6d-4eaf-9861-fe1bed440831

------=_Part_0_249168912.1551295147735
Content-Type: application/json; name="new 22.txt"
Content-Transfer-Encoding: binary
Content-Disposition: form-data; name="campaignConfiguration"; filename="new 22.txt"
{
  "typeId": 1,
  "serviceId": 55199,
  "operatorPhone": "4155041922",
  "callerId": "4155041922",
  "voiceId": 1,
  "answeringMachineOption": "NO_MESSAGES",
  "callbackPhone": "4155041922",
  "dialingStrategyId": 49080,
  "appendable": false,
  "scheduleTime": {
    "start": "1551385723000",
    "end": "1551407323000",
    "nextDay": true
  }
}
------=_Part_0_249168912.1551295147735
Content-Type: application/octet-stream; name=Testcampaignfile.txt
Content-Transfer-Encoding: binary
Content-Disposition: form-data; name="campaignFile"; filename="Testcampaignfile.txt"
124659238,4155556004,doe john,
------=_Part_0_249168912.1551295147735--

  
#Response
201 Created
Content-Type: application/json
 
{"id": 3456789}

CODE

Deactivate Campaign

Description: Deactivates a campaign.

Method: POST /campaign/campaigns/{id}/deactivate

Parameters:

Path/Query Parameter Name	Variable Name	Type	Mandatory?	Description
id	campaignId	Integer	Yes	Campaign to be deactivated

Response Code: 204 No Content

Body:

None

Deactivate Campaign

 #Request (JSON)
POST /campaign/campaigns/32383930/deactivate
Host: localhost.com
Content-Type: application/json
Accept: application/json
 
#Response (JSON)
204 No Content
Content-Type: application/json

CODE

Find Matching Campaigns

Description: A query that returns a list of Campaigns for a specified date range and for a specific Campaign Type. Optionally allows the user to filter the list by Service ID(s) and Campaign Type ID(s). The user can also specify one or more campaign statuses that the campaigns must match in order to be returned in the response.

Method: POST /campaign/campaigns/search?[client={clientId}&]count={n}&offset={n}

Parameters:

Path/Query Parameter Name	Variable Name	Type	Mandatory?	Description
client	clientId	Integer (ID)	No	Specifies the Client for which you want to retrieve the list of Campaigns.
count	n	Integer	Yes	Specifies the number of items to return in the list. There is a hard cap of 1000 items.
offset	n	Integer	Yes	Specifies the offset from 0, based on the count, to start listing from.

Body:

Key Type Mandatory? Description

state

Array

No

Array of possible campaign statuses you want to query for. Valid values are:

LOADING
SCHEDULED_UNBUILT
READY_UNBUILT
SCHEDULED
READY
REPORTED
DONE
PLAYING
PAUSED

There is an additional campaign status, BROKEN or DEACTIVATED, but that cannot be used in the state.

dateRange

Object

Yes

Establishes the date/time range for which to search for matching Campaigns. The filter consists of:

Key	Type	Mandatory?	Description
from	dateTime	Yes	Starting date/time of the range in which to search for Campaigns.
to	dateTime	Yes	Ending date/time of the range in which to search for Campaigns.

service

Object

No

Specifies the Service IDs to include in the query. If specified, the results will only include Campaigns associated with one of those Services. The filter consists of:

Key

Type

Mandatory?

Description

service

Array

Yes

An array of Service IDs

Key	Type	Mandatory?
id	Integer (ID)	Yes

type

Object

No

Specifies the Campaign Type IDs to include in the query. If specified, the results will only include Campaigns of one of these types. The filter consists of:

Key

Type

Mandatory?

Description

type

Array

Yes

An array of Campaign Type IDs

Key	Type	Mandatory?
id	Integer	Yes

Valid values are:

Campaign Type ID	Campaign Type
1	Outbound
2	Callback (i.e. for Inbound calls)
4	Scheduled Callback
5	Manual
6	SMS
7	HCI
8	10DMT
9	Manual SMS
10	Inbound SMS
11	Email
12	Manual Email
13	Inbound Email
14	Chat

Response Code: 200 OK

Body:

Key Type Mandatory? Description

next URI No A URI for the next page of entries. If next is not present, or blank, then there are no pages after this one.

campaign

Array

No

A container for a page of Campaign entries. The page size is controlled via count and offset in the request.

Key Type Mandatory? Description

id Integer (ID) Yes The ID of the Campaign

name String Yes Name of the Campaign

typeId

Integer

Yes

The type of Campaign. Possible values are:

Campaign Type ID	Campaign Type
1	Outbound
2	Callback (i.e. for Inbound calls)
4	Scheduled Callback
5	Manual
6	SMS

serviceId Integer (ID) Yes The Service associated with the Campaign

status

Enum

Yes

Status of the campaign. Possible values are:

UNASSIGNED
ACTIVE
PREBUILT
PLAYING
PAUSED
STOPPED
COMPLETED
INVALID

uploadDate DateTime No Timestamp (Unix timestamp format) describing when the campaign was uploaded.

The results will be sorted by the Campaign end date in descending order.

Get a list of Outbound Campaigns for a Client, filtered by date range and Skill IDs

#Request (JSON)
POST /campaign/campaigns/search?count=10&client=37111&offset=0
Host: localhost.com
Content-Type: application/json
Accept: application/json
 
{
"dateRange":{"from":1200700800000,"to":1221868800000},
"state":["ACTIVE","PREBUILT","PLAYING","PAUSED","STOPPED","COMPLETED"],
"service":{"service":[{"id":38211},{"id":35264},{"id":35274},{"id":35276},{"id":35284},{"id":35288},{"id":35343}]},
"type":{"type":[{"id":1},{"id":2}]}
}

#Response (JSON)
200 OK
Content-Type: application/json

{
   "campaign":    [
            {
         "id": 8124075,
         "name": "July_110508_12pm.txt",
		 "typeId": 1,
		 "serviceId": 35264,
		 "status": "ACTIVE",
		 "uploadDate": 1383755215000
      },
            {
         "id": 8125731,
         "name": "Securityhm_110208_320pm.txt",
		 "typeId": 1,
		 "serviceId": 35264,
		 "status": "COMPLETED",
		 "uploadDate": 1383636721000
      },
            {
         "id": 8134019,
         "name": "Mischm_110208_1030am.txt",
		 "typeId": 1,
		 "serviceId": 35288,
		 "status": "ACTIVE",
		 "uploadDate": 1384109502000
      },
...
            {
         "id": 8259394,
         "name": "Independencepoe_092308_945am.txt",
		 "typeId": 2,
		 "serviceId": 35343,
		 "status": "COMPLETED",
		 "uploadDate": 1383636721000
      }
   ],
   "next": "campaign/campaigns/search?count=10&client=37111&offset=10"
}

CODE

Find Matching Finished Calls

Description: A query that returns a list of completed call attempts for a campaign, where each call's finish time falls within a specified time window, for the current day.

The Find Matching Finished Calls method will not return records for campaigns that have been deactivated.
This method works only for the current day in the UTC timezone. The'windowStart' and'windowEnd'properties should be adjusted accordingly. For example, for UTC-5 timezone, the'windowStart'time is 5 AM and anything before 5 AM will be considered as the prior day and the result will not be available.

Method: POST /campaign/campaigns/{campaign}/finishedCalls?count={n}&offset={n}

Parameters:

Path/Query Parameter Name	Variable Name	Type	Mandatory?	Description
id	campaignId	Integer (ID)	Yes	Identifier of the campaign you want to query.
count	n	Integer	Yes	Specifies the number of items to return in the list. There is a hard cap of 1000 items.
offset	n	Integer	Yes	Specifies the offset from 0, based on the count, to start listing from.

Body:

Key	Type	Mandatory?	Description
windowStart	Time	Yes	Start time of the window in which to search for completed calls. For a call to be returned, its finish time must fall between the `windowStart` time and the `windowEnd` time. The API method currently searches within the current day only.
windowEnd	Time	Yes	The end time of the window in which to search for completed calls. For a call to be returned, its finish time must fall between the `windowStart` time and the `windowEnd` time. The API method currently searches within the current day only.

Response Code: 200 OK

Body:

Key

Type

Mandatory?

Description

No

A URI for the next page of entries. If next is not present, or blank, then there are no pages after this one.

call

Array

No

A container for a page of call entries. The page size is controlled via count and offset in the request.

Key	Type	Mandatory?	Description
account	String	Yes	The account associated with the phone number that was dialed.
phoneDialed	String	Yes	The phone number that was dialed
started	TIme	Yes	The time when the call was started today (Unix timestamp format)
finished	Time	Yes	The time when the call was finished today (Unix timestamp format)
livevoxResultId	Integer (ID)	Yes	Indicates the result of the call.

Get a list of completed call attempts for a campaign when sending in Time Zone Format

#Request (JSON)
POST /campaign/campaigns/28702845/finishedCalls?count=100&offset=0
Host: localhost.com
Content-Type: application/json
Accept: application/json
  
{
  "windowStart": "2021-02-15T02:00:00-08:00",
  "windowEnd": "2021-02-15T04:30:00-08:00"
}
 
#Response (JSON)
200 OK
Content-Type: application/json
 
{
  "call": [
    {
      "account": "Apps_Test",
      "phoneDialed": "6503517451",
      "started": 1613387433000,
      "finished": 1613387436000,
      "liveVoxResultId": 316
    },
    ...
    {
      "account": "Apps_Test",
      "phoneDialed": "9176754178",
      "started": 1613387452000,
      "finished": 1613387465000,
      "liveVoxResultId": 326
    }
  ],"next":null
}

CODE

Get a list of completed call attempts for a campaign when sending Parameters in Unix Epoch format

#Request (JSON)
POST /campaign/campaigns/28702845/finishedCalls?count=100&offset=0
Host: localhost.com
Content-Type: application/json
Accept: application/json
  
{
  "windowStart": "1613383200000",
  "windowEnd": "1613392200000"
}
 
#Response (JSON)
200 OK
Content-Type: application/json
 
{
  "call": [
    {
      "account": "Apps_Test",
      "phoneDialed": "6503517451",
      "started": 1613387433000,
      "finished": 1613387436000,
      "liveVoxResultId": 316
    },
    ...
    {
      "account": "Apps_Test",
      "phoneDialed": "9176754178",
      "started": 1613387452000,
      "finished": 1613387465000,
      "liveVoxResultId": 326
    }
  ],"next":null
}

CODE

Get Campaign List Info

Description: Returns metadata for a campaign list.

Method: GET /campaign/campaigns/info

Parameters:

None

Response Code: 200 OK

Body:

Key	Type	Mandatory?	Description
size	Integer	Yes	Number of campaigns currently loaded for this client
lastModified	Timestamp	Yes	Most recently modified campaign's timestamp (Unix timestamp format)

Get Campaign List Info

 #Request (JSON)
GET /campaign/campaigns/info
Host: localhost.com
Content-Type: application/json
Accept: application/json
 
#Response
200 OK
Content-Type: application/json

{
   "size": 100,
   "lastModified": "1384252114000"  
}

CODE

List Campaigns

Description: Lists Campaigns loaded for a Client.

User Roles: Sysadmin, Superuser, or Manager

Method: GET /campaign/campaigns?count={n}&offset={n}

Parameters:

Path/Query Parameter Name	Variable Name	Type	Mandatory?	Description
count	n	Integer	Yes	Specifies the number of items to return in the list. There is a hard cap of 1000 items.
offset	n	Integer	Yes	Specifies the offset from 0, based on the count, to start listing from.

Body:

None

Response Code: 200 OK

Body:

Key

Type

Mandatory?

Description

No

A URI for the next page of entries. If next is not present, or blank, then there are no pages after this one.

campaignDetails

Array

No

A container for a page of Campaign entries. The page size is controlled via count and offset in the request.

Key

Type

Mandatory?

Description

id

Integer (ID)

Yes

The ID of the campaign.

name

String

Yes

The original filename that was used to upload this campaign

serviceId

Integer

Yes

The Service ID the campaign is assigned to

uploadDate

Date

Yes

Date campaign was uploaded

typeId

Integer

Yes

Type of campaign.

Value	Campaign Type
OUTBOUND	1
SMS	6
HCI	7
10DMT	8

status

String

Yes

The current state of the campaign.

Deactivated campaigns will be returned in the list method.

Get a list of Campaigns for a Client

#Request (JSON)
GET /campaign/campaigns?count=5&offset=0
Host: localhost.com
Content-Type: application/json
Accept: application/json

#Response
200 OK
Content-Type: application/json

{
   "campaignDetails":    [
            {
         "id": 28518963,
         "name": "62199_MANUAL_CALLS_09-12-2017",
         "typeId": 5,
         "serviceId": 62199,
         "status": "PLAYING",
         "uploadDate": 1505224100000
      },
            {
         "id": 28518962,
         "name": "47419_MANUAL_CALLS_09-12-2017",
         "typeId": 5,
         "serviceId": 47419,
         "status": "PLAYING",
         "uploadDate": 1505223821000
      },
...
            {
         "id": 28518943,
         "name": "47416_MANUAL_EMAILS_09_12_2017",
         "typeId": 12,
         "serviceId": 47416,
         "status": "PLAYING",
         "uploadDate": 1505205106000
      }
   ],
   "next": "campaign/campaigns?offset=4&count=4"
}

CODE

List Campaign Transactions

Description: Returns the account transaction records for an active Campaign.

Method: GET campaign/campaigns/{id}/transactionList?count={n}&offset={n}[&extra={true|false}&validOnly={true|false}]

Parameters:

Path/Query Parameter Name	Variable Name	Type	Mandatory?	Description
id	campaignId	Integer (ID)	Yes	The ID of the active campaign for which you want to return the account transaction list
count	n	Integer	Yes	Specifies the number of items to return in the list. There is a hard cap of 1000 items.
offset	n	Integer	Yes	Specifies the offset from 0, based on the count, to start listing from.
extra	true or false	Boolean	Yes	If set to `true`, indicates that you want the response to include values from the account's EXTRA fields. The EXTRA fields will be populated with Client-specific data elements, as configured when the campaign is created or uploaded into the LiveVox system.
daysDue	true or false	Boolean	Yes	If set to `true`, indicates that you want the response to include values from the account's DAYS_DUE fields. Fields will be populated with Client-specific data elements, as configured when the campaign is created or uploaded into the LiveVox system.
validOnly	true or false	Boolean	Yes	If set to `true`, indicates that you want the response to include only valid account transactions. Invalid account transactions are ones that have a LiveVox Result that is classified as "Not Made". This includes accounts without a valid phone number, accounts where all the phone numbers are on the Do Not Call list, accounts with missing or bad data, etc.

Body:

None

Response Code: 200 OK

Body:

Key Type Mandatory? Description

next URI No A URI for the next page of entries. If next is not present, or blank, then there are no pages after this one.

transaction

Array

No

A container for a page of account transaction entries. The page size is controlled via count and offset in the request.

Key Type Mandatory? Description

consumer

Object

Yes

Each consumer object includes the following attributes (when non-null):

Key	Type	Mandatory?	Description
firstName	String	Yes	First name of the consumer
lastName	String	Yes	Last name of the consumer
dateOfBirth	Date	No	Date of birth of the consumer
email	String	No	The email address of the consumer
ssn	String	No	Social Security number of the consumer
zipCode	String	No	Zip code of the consumer

phone

Array

No

Array of phone entries for the account. Each object in the phone array includes the following attributes:

Key	Type	Mandatory?	Description
phone	String	Yes	One of the phone numbers to dial associated with the account.
ordinal	Integer	Yes	Indicates the position (e.g. 1, 2, 3...) associated with the phone number. This position is relevant for the campaign's dialing rules, which are defined in the Dialing Strategy assigned to the campaign.

extra

Array

No

Array of extra entries from the account transaction record's EXTRA_* fields. Each object in the extra array includes the following attributes:

Key	Type	Mandatory?	Description
key	String	Yes	Name of the EXTRA field (e.g. EXTRA_14). The possible extra values that can be returned are: EXTRA_7 EXTRA_12 (as dateOfService) EXTRA_13 EXTRA_14 EXTRA_15 The field EXTRA_12 is normally used to store the date of service provided to the consumer, so the key for EXTRA_12 is `dateOfService`.
value	String	Yes	Value populating the EXTRA field in the account transaction record.

daysDue

Array

No

Array of DAYS_DUE entries from the account transaction record's DAYS_DUE_*. Each object in the DAYS_DUE array includes the following attributes:

Key	Type	Mandatory?	Description
key	String	Yes	Name of the DAYS_DUE field.
value	String	Yes	Value populating the DAYS_DUE field in the account transaction record.

accountTransactionId

Integer (ID)

Yes

Unique account transaction identifier for the account, within the campaign.

account String Yes Account identifier, normally coming from the Client's system of record

balance Decimal Yes The amount owed by the consumer.

livevoxResultId Integer (ID) No Result code assigned to the account transaction by the LiveVox system (aka TFH Result)

serviceId Integer (ID) Yes Service associated with the account transaction's campaign

Retrieve the account transaction list for a campaign

#Request (JSON)
GET campaign/campaigns/8955087/transactionList?count=20&extra=true&daysDue=true&offset=0&validOnly=true
Host: localhost.com
Content-Type: application/json
Accept: application/json
 
#Response (JSON)
200 OK
Content-Type: application/json
 
{
   "transaction":    [
            {
         "consumer":          {
            "firstName": "Kenneth",
            "lastName": "Lahoma",
            "dateOfBirth": null,
            "email": null,
            "ssn": null,
            "zipCode": "84758"
         },
         "phone": [         {
            "phone": "7072541670",
            "ordinal": 1,
            "type": null
         }],
         "extra":          [
						{
               "key": "dateOfService",
               "value": "12/04/12"
            },                        
						{
               "key": "EXTRA_13",
               "value": "330 CHAMBERS COURT||PENSACOLA|FL|1||2|25327531|0"
            },
                        {
               "key": "EXTRA_14",
               "value": "3|||||||||"
            },
                        {
               "key": "EXTRA_15",
               "value": "7072541670||7072541670|||||||||"
            }
      	],
      	"daysDue":       	[
                  		{
       		   "key": "DAYS_DUE_5",
               "value": "21\t1\t56790719\t3405\t72\tDirecTV Early Defaul\...tWells\t1213\tTelephoneReside\t33584421\t\t\t\t\t588\t1393\t\t\t"
         	},
                  		{
               "key": "DAYS_DUE_6",
               "value": "-1"
         	}
     	 ],
         "accountTransactionId": 21179819048,
         "account": "12161464",
         "balance": 320.09,
         "livevoxResultId": 320,
		 "serviceId": 67422
      },
            {
         "consumer":          {
            "firstName": "Jermaine",
            "lastName": "Frey",
            "dateOfBirth": null,
            "email": null,
            "ssn": null,
            "zipCode": "38131"
         },
         "phone":          [
                        {
               "phone": "7044976529",
               "ordinal": 1,
               "type": null
            },
                        {
               "phone": "8668478366",
               "ordinal": 2,
               "type": null
            }
         ],
         "extra":          [
						{
               "key": "dateOfService",
               "value": "11/04/13"
            },
                        {
               "key": "EXTRA_13",
               "value": "15823 Dixon Landing Rd||Dundee|NE|1||2|25510921|0"
            },
                        {
               "key": "EXTRA_14",
               "value": "3|||||||||"
            },
                        {
               "key": "EXTRA_15",
               "value": "7044976529|8668478366|7044976529|||||||||"
            }
      	],
      	"daysDue":       	[
                  		{
               "key": "DAYS_DUE_5",
               "value": "21\t1\t56790605\t1248\...\t\t\t\t732\t1456\t\t\t"
         	},
                  		{
               "key": "DAYS_DUE_6",
               "value": "-1"
         	}
      ],
      "accountTransactionId": 21190250867,
      "account": "12344",
      "balance": 0,
      "livevoxResultId": 339,
      "serviceId": 41428
   }],
...
            {
         "consumer":          {
            "firstName": "Randy",
            "lastName": "Hutton",
            "dateOfBirth": null,
            "email": null,
            "ssn": null,
            "zipCode": "91292"
         },
         "phone": [         {
            "phone": "9192730439",
            "ordinal": 1,
            "type": null
         }],
         "extra":          [
						{
               "key": "dateOfService",
               "value": "05/04/13"
            },
                        {
               "key": "EXTRA_13",
               "value": "145 GEORGE ST||WEST ADAMS|CA|1||2|25427784|0"
            },
                        {
               "key": "EXTRA_14",
               "value": "|||||||||"
            },
                        {
               "key": "EXTRA_15",
               "value": "9192730439|||||||||||"
            }
      	],
      	"daysDue":       [
                  		{
               "key": "DAYS_DUE_5",
               "value": "120"
         	},
                  		{
               "key": "DAYS_DUE_6",
               "value": "21\t1\t56784502\t6418\t72\ t\t\t\t\t8708381650\...\t32437127\t\t9012460118\tTelephoneReside\t32437128t\t\t\t\t\t597\t1357\t\t\t"
         	}
      	],
         "accountTransactionId": 21179819278,
         "account": "139228103",
         "balance": 3333.3,
         "livevoxResultId": 320,
		 "serviceId": 67422
      }
   ],
   "next": "campaign/campaigns/8955087/transactionList?count=20&extra=true&offset=20&validOnly-=true"
}

CODE

Read Campaign

Description: Reads the properties of a campaign, based on Campaign ID.

Method: GET /campaign/campaigns/{id}

Parameters:

Path/Query Parameter Name	Variable Name	Type	Mandatory?	Description
id	campaignId	Integer (ID)	Yes	The ID of the campaign for which you want to read the properties

Body:

None

Response Code: 200 OK

Body:

Key Type Mandatory? Description

name String Yes Name of the campaign

typeId

Integer

Yes

Type of the campaign. Possible types include:

Campaign Type ID	Campaign Type
1	Outbound
2	Callback (i.e. for Inbound calls)
4	Scheduled Callback
5	Manual
6	SMS
7	HCI
10	10 DMT

serviceId Integer (ID) No The ID of the Service to which the campaign is assigned

operatorPhone String No The phone number first dialed by LiveVox when extension-based agents are called by LiveVox to tether them to the system. It is also the number used as the default caller ID of manual dials. If an LCID package was used then 'LOCAL' will be returned, and LVP will display [Local, rotated].

callbackPhone String No The phone number left by the LiveVox system on voicemail or live person messages. If an LCID package was used then 'LOCAL' will be returned, and LVP will display [Local, rotated].

localCallerIdPackage Boolean No If true, the campaign is configured to use a local caller ID package as the callbackPhone, callerId, or operatorPhone so that consumers receiving calls will see a local caller ID.

callerId

String

No

The caller ID would be visible on a consumer's phone, or included in the envelope of a voicemail message. If localCallerIdPackage is true, then callerId will be 'LOCAL' , and LVP will display [Local, rotated].

dialingStrategyId

Integer (ID)

No

The ID of the Dialing Strategy the LiveVox system will use when dialing account records for the campaign.

On the original campaign pass, the Dialing Strategy defines the phone fields to be dialed and the dialing outcomes that are final for the account should be re-attempted for the same number or should result in dialing the account’s next number. On a requeue campaign pass, the Dialing Strategy also defines the outcomes from the prior pass which should be included or excluded from dialing.

voiceId

Integer (ID)

No

The ID of the voice talent that will be used for the campaign. Possible voice talents are:

Voice ID	Name
1	Julie
2	Juanita
3	Kate
4	Gisele
5	Bob
6	Gruff-M
8	Gruff-F
9	Lee
10	Scarlet
11	Claudine

answeringMachineOption

Enum

No

Controls the behavior of the system when an answering machine (voicemail) is detected. Possible values are:

LEAVE_MESSAGES: Detects answering machines and leaves a message
NO_MESSAGES: If an answering machine is detected, no message is left, and the call is disconnected.
TRANSFER: Answering machine detection is off. All connections are passed to agents.

dialCellPhones Boolean No When set to true, cell phones will be dialed as part of the campaign. When set to false, cell phone numbers will be scrubbed from the campaign.

status

Enum

Yes

Describes the status of the campaign. Possible values are:

UNASSIGNED
ACTIVE
PREBUILT
PLAYING
PAUSED
STOPPED
COMPLETED
INVALID

When a new campaign has been initialized, but the uploading of campaign records has either not started yet or is still in progress, the status will be returned as INVALID.

uploadDate DateTime No Timestamp (Unix timestamp format) describing when the campaign was uploaded to LiveVox.

buildDate DateTime No Timestamp (Unix timestamp format) describing when the campaign was built.

actualStartDate DateTime No Timestamp (Unix timestamp format) describing the date and time of the record from the campaign that had the earliest call start time (call launch time).

actualEndDate DateTime No Timestamp (Unix timestamp format) describing the date and time of the record from the campaign that had the latest call finish time (call end time).

onDemand Boolean No Is null when the campaign schedule is configured. When set to true, it indicates that no campaign schedule has been configured, and the campaign will be built and played on-demand.

scheduleTime

Object

No

If included, the campaign will be configured to run on the desired schedule; otherwise, LVP on demand behavior applies.

Key Type Mandatory? Description

nextDay Boolean Yes If set to true, the campaign will be scheduled to run the following day.

start

DateTime

Yes

The start date/time of the campaign, provided in ms (Unix timestamp format), if not provided the campaign will be scheduled to start "ASAP".

The time that this campaign will build and start dialing. If this time is prior to the current time, dialing will not occur today - instead it will wait until next week at the selected time. If the start time returns 00:00:00.000 (XML) or 1381464000000 (JSON), it means that the start time is set to "ASAP". This instructs the system to start dialing the campaign as soon as possible.

end

DateTime

Yes

The end date/time of the campaign, provided in ms (Unix timestamp format), If not provided the campaign will be scheduled to end at "EOD" (End of Day).

The time that this campaign will end. If the end time returns 23:59:00.000 (XML) or 1381550340000 (JSON), it indicates "End of Day". This means that there is no scheduled time for the system to stop dialing. The campaign will end by curfew, depletion when a manager presses Stop on the campaign GUI in LVP.

scrubOption

String

Yes

The scrubOption returns the value configured for the segmentation option at the Services and Client editor Settings section for the selected service. Below are the available values:

NONE - This is the default option and if selected no scrub occurs.
WIRELESS - Scrubs all wireless phone numbers so that all landline numbers can be dialed.
LANDLINE - Scrubs all landline numbers so that all wireless phone numbers can be dialed.
SEGMENTED_WIRELESS- Scrubs all wireless phone numbers from positions 1-15 and place them starting at position 16.

When loading the campaign, the configured service level Scrub option is automatically taken for the selected service. If the service level Scrub option is selected as null for the particular service, then the client level Scrub option will be taken for that particular service.

Read the properties of a campaign that includes a schedule

#Request (JSON)
GET /campaign/campaigns/106427749
Host: localhost.com
Content-Type: application/json
Accept: application/json
  
#Response (JSON)
200 OK
Content-Type: application/json
  
{
  "onDemand": false,
  "scheduleTime": {
    "start": 1599120000000,
    "end": 1599163200000,
    "nextDay": false
  },
  "operatorPhone": "6174889880",
  "callbackPhone": "6174889880",
  "localCallerIdPackage": false,
  "callerId": "6174889880",
  "dialingStrategyId": 1002212,
  "answeringMachineOption": "LEAVE_MESSAGES",
  "serviceId": 1008351,
  "typeId": 1,
  "dialMode": "AUTOMATIC",
  "voiceId": 1,
  "appendable": false,
  "name": "test4_PDMgnt.txt",
  "clientId": 1005018,
  "status": "DEACTIVATED",
  "uploadDate": 1599160914000,
  "buildDate": 1599160935000,
  "actualStartDate": 0,
  "actualEndDate": 0,
  "scrubOption": "NONE"
}

CODE

Read the properties of a Campaign that is "On Demand" (no schedule)

#Request (JSON)
GET /campaign/campaigns/8975202
Host: localhost.com
Content-Type: application/json
Accept: application/json
 
#Response (JSON)
200 OK
Content-Type: application/json
 
{
   "onDemand": true,
   "scheduleTime": null,
   "name": "outbound_campaign1",
   "clientId": 4199,
   "typeId": 1,
   "serviceId": 17643,
   "operatorPhone": null,
   "callbackPhone": "8884773448",
   "localCallerIdPackage": false,
   "callerId": "4156599170",
   "dialingStrategyId": 20536,
   "voiceId": 2,
   "answeringMachineOption": "NO_MESSAGES",
   "dialCellPhones": true,
   "status": "COMPLETED",
   "uploadDate": 1384623227000,
   "buildDate": 1384256051000,
   "actualStartDate": 1384257172000,
   "actualEndDate": 1384272192000
}

CODE

Update Campaign

Description: Updates the campaign dial characteristics.

Method: PUT /campaign/campaigns/{id}

Parameters:

Path/Query Parameter Name	Variable Name	Type	Mandatory?	Description
id	id	Integer (ID)	Yes	Campaign to be updated

Body:

Key

Type

Mandatory?

Description

serviceId Integer No The serviceId this campaign will be assigned to

operatorPhone

String

No

Operator phone to be set for this campaign, this can be a 10 digit number or 'LOCAL' to use an LCID package.

'LOCAL' can only be used if the Service level setting is set to LOCAL CALLER ID.

voiceId Integer No Voice ID to be assigned for this campaign

answeringMachineOption

Enum

No

Denotes the Answering machine behavior for this campaign

Key	Description
LEAVE_MESSAGES	Detects answering machines and leaves a message.
NO_MESSAGES	If an answering machine is detected, no message is left, and the call is disconnected.
TRANSFER	Answering machine detection is off. All connections are passed to agents.

callerId

String

No

Caller ID to be set for this campaign, this can be a valid 10 digit caller ID configured at the Service level or 'LOCAL' to use an LCID package.

'LOCAL' can only be used if the Service level setting is set to LOCAL CALLER ID.

callbackPhone

String

No

Callback phone to be set for this campaign, this can be a 10 digit number or 'LOCAL' to use an LCID package.

'LOCAL' can only be used if the Service level setting is set to LOCAL CALLER ID.

dialingStrategyId Integer No Dialing Strategy Id number assigned for this campaign

typeId

Enum

No

Type of campaign.

Campaign Type ID	Campaign Type
1	Outbound
6	SMS
7	HCI
8	10DMT

scheduleTime

Object

No

When this element is present, the campaign will be configured to run on the desired schedule.

Key	Type	Mandatory?	Description
start	Time	No	The scheduled start time of the campaign. If not provided, ASAP (As Soon As Possible) will be set.
end	TIme	No	The scheduled end time of the campaign. If not provided, EOD (End of Day) will be set.
nextDay	Boolean	Yes	The campaign is set up to run tomorrow

Response Code: 204 No Content

Body:

None

Update a Campaign

#Request (JSON)
PUT /campaign/campaigns/8975202/
Host: localhost.com
Content-Type: application/json
Accept: application/json
 
{
   "operatorPhone": "5558149720",
   "callbackPhone":"5558149720"
}
 
#Response (JSON)
204 No Content
Content-Type: application/json

CODE

Update Campaign State

Description: Changes the campaign state (i.e. from play to pause, play to stop, etc.).

Method: PUT /campaign/campaigns/{id}/state

Parameters:

Path/Query Parameter Name	Variable Name	Type	Mandatory?	Description
id	campaignId	Integer (ID)	Yes	ID of the campaign which will have its state updated.

Body:

Key Type Mandatory? Description

state

Enum

Yes

Desired state of the campaign. Possible values include:

STOP
PLAY
PAUSE
BUILD

Response Code: 204 No Content

Body:

None

Change the state of a Campaign

#Request (JSON)
PUT /campaign/campaigns/8975202/state
Host: localhost.com
Content-Type: application/json
Accept: application/json
 
{
   "state": "STOP"
}
 
#Response (JSON)
204 No Content
Content-Type: application/json

CODE

Change the state of a Campaign that does not exist

#Request (JSON)
PUT /campaign/campaigns/8975202/state
Host: localhost.com
Content-Type: application/json
Accept: application/json
 
{
   "state": "STOP"
}
 
#Response (JSON)
404 Not Found
Content-Type: application/json
 
{
   "code": 104,
   "message": "Campaign doesn't exist"
}

CODE

Try to Update the Campaign State to the Current State

#Request (JSON)
PUT /campaign/campaigns/8975202/state
Host: localhost.com
Content-Type: application/json
Accept: application/json
 
{
   "state": "PLAY"
}
 
#Response (JSON)
202 Accepted
Content-Type: application/json
 
{
   "code": 105,
   "message": "'PLAY' not a valid operation for this campaign"
}

CODE

Errors

For more information, see the Errors topic on the REST APIs Page.

Top of Page

Download PDF

Campaign API

Introduction

Campaign API WADL/Swagger

User Roles

API Methods

Campaigns

Append Campaign Record

Create Campaign

Deactivate Campaign

Find Matching Campaigns

Find Matching Finished Calls

Get Campaign List Info

List Campaigns

List Campaign Transactions

Read Campaign

Update Campaign

Update Campaign State

Errors

Cookie Notice