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.

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 NameVariable NameTypeMandatory?Description
idcampaignIdInteger (ID)YesThe ID of the campaign to append records to.

Body:

KeyTypeMandatory?Description
recordsArrayYes

An array of campaign transactions

KeyTypeMandatory?Description

Character Limit

accountStringNoThe account number for the transaction.50
firstNameStringNoThe first name for the transaction.50
lastNameStringNoThe last name for the transaction.50
phone1StringYesThe primary phone number for the transaction.32
phone2ArrayNoThe secondary phone number(s) for the transaction, this field can be filled with up to 29 additional phone numbers separated by a comma.450
dobStringNoThe date of birth for the transaction must be stored in MMDD format.20
emailStringNoEmail for the transaction.50
ssnStringNoThe social security number for the transaction, an SSN must be 4 or 9 characters any other number will cause the record to fail.9
lastPaymentDateStringNoCan be used to store additional account information.
minimumPaymentAmountDecimalNoThe minimum payment amount for the transaction.24
accountToSpeakStringNoThe 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
amountToSpeakDecimalNoThe amount to be TTS'd in the IVR.24
extra1StringNoUsed to store agent login ID.50
extra2StringNoCan be used to store additional account information.50
extra3StringNoCan be used to store additional account information.50
extra4StringNoCan be used to store additional account information.50
extra5StringNoCan be used to store additional account information.50
extra6StringNoUsed to store Agent's extension.50
extra7StringNoIf messaging is configured, can be used to tts names;50
extra8StringNoCan be used to store additional account information.50
extra9StringNo

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
extra11StringNoStores the zip code for the transaction and used for zip area mismatch.
extra12StringNoStores the date of service information.
extra13StringNoCan 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.
extra14StringNoCan be used to store values; if multiple values need to be stored you can separate them with pipes.
extra15StringNoCan be used to store values; if multiple values need to be stored you can separate them with pipes.
extra16StringNoCan be used to store additional account information.50
extra19StringNoCan be used to store additional account information.50
extra20StringNoCan be used to store additional account information.150
originalAccountNumberStringNoThe original account number for the transaction.
practiceIdIntegerNoThe practice ID for the transaction.24
clientPracticeIdStringNo

The client practice ID for the transaction.

50
templateIdStringNoThe 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
practicePhoneStringNoThe phone number played in the IVR for outbound calls.13
practicePhoneAlternateStringYes*

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
operatorNumberStringNoThe operator phone used for the transaction. Used as the caller ID on manual dials.13
placeOfServiceIdIntegerNoThis is generally used in conjunction with client_practice_id, storing information about specific locations for the sub-client.24
altLanguage1IntegerNoAlternate language a user can choose from in the IVR.24
altLanguage2IntegerNoAlternate language a user can choose from in the IVR.24
altLanguage3IntegerNoAlternate language a user can choose from in the IVR.24
languageCallback1StringNoThe legacy setting, no longer in use.13
languageCallback2StringNoThe legacy setting, no longer in use.13

languageCallback3

StringNoThe legacy setting, no longer in use.13
languageIntegerNoThe main language the IVR will be offered in, leaving this field blank will default to the voice talent set at the Service level.
totalAmountDecimalNoThe 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:

NameTypeMandatory?Description
campaignFileAttachment - [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.

campaignConfigurationAttachment - [json]YesThe configuration properties for the campaign.

Configuration Properties:

KeyTypeMandatory?Description
serviceIdIntegerYesThe serviceId the campaign will be assigned to
operatorPhoneStringNo*

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.

voiceIdIntegerYesVoice ID for one of the available configured voices
answeringMachineOptionEnumYes

Denotes the Answering machine behavior for this campaign

KeyDescription
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.
TRANSFERAnswering machine detection is off. All connections are passed to agents.
callerIdStringNo*

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.

callbackPhoneStringNo*

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.

dialingStrategyIdIntegerYesDialing Strategy ID number assigned for this campaign
appendableBooleanNoIf 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.
typeIdEnumYes

Type of the campaign. Possible types include:

Campaign Type IDCampaign Type
1Outbound
6SMS
7HCI
810DMT
scheduleTimeObjectNo

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

KeyTypeMandatory?Description
startDateTimeYesThe start date/time of the campaign, provided in ms, if not provided the campaign will be scheduled to start "ASAP".
endDateTimeYesThe end date/time of the campaign, provided in ms, If not provided the campaign will be scheduled to end at "EOD" (End of Day).
nextDayBooleanYesIf 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

idInteger (ID)YesThe 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

campaignIdIntegerYesCampaign 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 NameVariable NameTypeMandatory?Description
clientclientIdInteger (ID)NoSpecifies the Client for which you want to retrieve the list of Campaigns.
countnIntegerYesSpecifies the number of items to return in the list. There is a hard cap of 1000 items.
offsetnIntegerYesSpecifies the offset from 0, based on the count, to start listing from.

Body:

KeyTypeMandatory?Description
stateArrayNo

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.

dateRangeObjectYes

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

KeyTypeMandatory?Description
fromdateTimeYesStarting date/time of the range in which to search for Campaigns.
todateTimeYesEnding date/time of the range in which to search for Campaigns.
serviceObjectNo

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:

KeyTypeMandatory?Description
serviceArrayYes

An array of Service IDs

KeyTypeMandatory?
idInteger (ID)Yes
typeObjectNo

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:

KeyTypeMandatory?Description
typeArrayYes

An array of Campaign Type IDs

KeyTypeMandatory?
idIntegerYes

Valid values are:

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



Response Code: 200 OK

Body:

KeyTypeMandatory?Description
nextURINoA URI for the next page of entries. If next is not present, or blank, then there are no pages after this one.
campaignArrayNo

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

KeyTypeMandatory?Description
idInteger (ID)YesThe ID of the Campaign
nameStringYesName of the Campaign
typeIdIntegerYes

The type of Campaign. Possible values are:

Campaign Type IDCampaign Type
1Outbound
2Callback (i.e. for Inbound calls)
4Scheduled Callback
5Manual
6SMS
serviceIdInteger (ID)YesThe Service associated with the Campaign
statusEnumYes

Status of the campaign. Possible values are:

  • UNASSIGNED
  • ACTIVE
  • PREBUILT
  • PLAYING
  • PAUSED
  • STOPPED
  • COMPLETED
  • INVALID
uploadDateDateTimeNoTimestamp (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 NameVariable NameTypeMandatory?Description
idcampaignIdInteger (ID)YesIdentifier of the campaign you want to query.
countnIntegerYesSpecifies the number of items to return in the list. There is a hard cap of 1000 items.
offsetnIntegerYesSpecifies the offset from 0, based on the count, to start listing from.

Body:

KeyTypeMandatory?Description
windowStartTimeYes

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.

windowEndTimeYes

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:

KeyTypeMandatory?Description
nextURINoA URI for the next page of entries. If next is not present, or blank, then there are no pages after this one.
callArrayNo

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

KeyTypeMandatory?Description
accountStringYesThe account associated with the phone number that was dialed.
phoneDialedStringYesThe phone number that was dialed
startedTImeYes

The time when the call was started today (Unix timestamp format)

finishedTimeYesThe time when the call was finished today (Unix timestamp format)
livevoxResultIdInteger (ID)YesIndicates 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:

KeyTypeMandatory?Description
sizeIntegerYesNumber of campaigns currently loaded for this client
lastModifiedTimestampYes

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 NameVariable NameTypeMandatory?Description
countnIntegerYesSpecifies the number of items to return in the list. There is a hard cap of 1000 items.
offsetnIntegerYesSpecifies the offset from 0, based on the count, to start listing from.

Body:

None

Response Code: 200 OK

Body:

KeyTypeMandatory?Description
nextURINoA URI for the next page of entries. If next is not present, or blank, then there are no pages after this one.
campaignDetailsArrayNo

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

KeyTypeMandatory?Description
idInteger (ID)YesThe ID of the campaign.
nameStringYesThe original filename that was used to upload this campaign
serviceIdIntegerYesThe Service ID the campaign is assigned to
uploadDateDateYesDate campaign was uploaded
typeIdIntegerYes

Type of campaign.

ValueCampaign Type
OUTBOUND1
SMS6
HCI7
10DMT8
statusStringYes

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 NameVariable NameTypeMandatory?Description
idcampaignIdInteger (ID)YesThe ID of the active campaign for which you want to return the account transaction list
countnIntegerYesSpecifies the number of items to return in the list. There is a hard cap of 1000 items.
offsetnIntegerYesSpecifies the offset from 0, based on the count, to start listing from.
extratrue or falseBooleanYesIf 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.
daysDuetrue or falseBooleanYesIf 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.
validOnlytrue or falseBooleanYesIf 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:

KeyTypeMandatory?Description
nextURINoA URI for the next page of entries. If next is not present, or blank, then there are no pages after this one.
transactionArrayNo

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

KeyTypeMandatory?Description
consumerObjectYes

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

KeyTypeMandatory?Description
firstNameStringYesFirst name of the consumer
lastNameStringYesLast name of the consumer
dateOfBirthDateNoDate of birth of the consumer
emailStringNoThe email address of the consumer
ssnStringNo

Social Security number of the consumer

zipCodeStringNo

Zip code of the consumer

phoneArrayNo

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

KeyTypeMandatory?Description
phoneStringYes

One of the phone numbers to dial associated with the account.

ordinalIntegerYes

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.

extraArrayNo

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

KeyTypeMandatory?Description
keyStringYesName 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.

valueStringYesValue populating the EXTRA field in the account transaction record.
daysDueArrayNo

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

KeyTypeMandatory?Description
keyStringYesName of the DAYS_DUE field.
valueStringYesValue populating the DAYS_DUE field in the account transaction record.
accountTransactionIdInteger (ID)Yes

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

accountStringYesAccount identifier, normally coming from the Client's system of record
balanceDecimalYesThe amount owed by the consumer.
livevoxResultIdInteger (ID)NoResult code assigned to the account transaction by the LiveVox system (aka TFH Result)
serviceIdInteger (ID)YesService 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 NameVariable NameTypeMandatory?Description
idcampaignIdInteger (ID)YesThe ID of the campaign for which you want to read the properties

Body:

None

Response Code: 200 OK

Body:

KeyTypeMandatory?Description
nameStringYesName of the campaign
typeIdIntegerYes

Type of the campaign. Possible types include:

Campaign Type IDCampaign Type
1Outbound
2Callback (i.e. for Inbound calls)
4Scheduled Callback
5Manual
6SMS
7HCI
1010 DMT
serviceIdInteger (ID)NoThe ID of the Service to which the campaign is assigned
operatorPhoneStringNoThe 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].
callbackPhoneStringNoThe 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].
localCallerIdPackageBooleanNoIf 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.
callerIdStringNo

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].

dialingStrategyIdInteger (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. 

voiceIdInteger (ID)No

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

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

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.
dialCellPhonesBooleanNoWhen 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.
statusEnumYes

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.

uploadDateDateTimeNoTimestamp (Unix timestamp format) describing when the campaign was uploaded to LiveVox.
buildDateDateTimeNoTimestamp (Unix timestamp format) describing when the campaign was built.
actualStartDateDateTimeNoTimestamp (Unix timestamp format) describing the date and time of the record from the campaign that had the earliest call start time (call launch time).
actualEndDateDateTimeNoTimestamp (Unix timestamp format) describing the date and time of the record from the campaign that had the latest call finish time (call end time).
onDemandBooleanNoIs 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.
scheduleTimeObjectNo

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

KeyTypeMandatory?Description
nextDayBooleanYesIf set to true, the campaign will be scheduled to run the following day.
startDateTimeYes

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.

endDateTimeYes

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.

scrubOptionStringYes
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

ididInteger (ID)YesCampaign to be updated

Body:

Key

Type

Mandatory?

Description

serviceIdIntegerNoThe serviceId this campaign will be assigned to
operatorPhoneStringNo

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.

voiceIdIntegerNoVoice ID to be assigned for this campaign
answeringMachineOptionEnumNo

Denotes the Answering machine behavior for this campaign

KeyDescription
LEAVE_MESSAGES Detects answering machines and leaves a message.
NO_MESSAGESIf an answering machine is detected, no message is left, and the call is disconnected.
TRANSFERAnswering machine detection is off. All connections are passed to agents.
callerIdStringNo

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.

callbackPhoneStringNo

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.

dialingStrategyIdIntegerNoDialing Strategy Id number assigned for this campaign
typeIdEnumNo

Type of campaign.

Campaign Type IDCampaign Type

1

Outbound
6SMS
7HCI
810DMT
scheduleTimeObjectNo

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

KeyTypeMandatory?Description
startTimeNoThe scheduled start time of the campaign. If not provided, ASAP (As Soon As Possible) will be set.
endTImeNoThe scheduled end time of the campaign. If not provided, EOD (End of Day) will be set.
nextDayBooleanYesThe 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 NameVariable NameTypeMandatory?Description
idcampaignIdInteger (ID)YesID of the campaign which will have its state updated.

Body:

KeyTypeMandatory?Description
stateEnumYes

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