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 SmartReach API Overview for a general description of how to interact with the API.

Prerequisites

To obtain a valid Session ID, you must have successfully logged into the SmartReach platform. See Generating a Session ID for more information.
To obtain an Access Token that is used in API requests, you must have an active subscription to the Configuration API. See Access Tokens for details.
All messages in this API may be subject to rate limits and other restrictions.

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

The Campaign API provides a method enabling you to query the SmartReach 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 be called once every 5 seconds per service.
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.
The appended records 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.

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",
      "practicePhoneAlternate": "4155553849"
   }]
}

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

CODE

Create Campaign

Description: Creates a Campaign on SmartReach .

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.

A SmartReach 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 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.
This method returns the first 50,000 matching records.

Method: GET /campaign/campaigns/{campaign}/finishedCalls

Parameters:

None

Body:

None

Response Code: 200 OK

Body:

Key Type Mandatory? Description

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	No	The phone number that was dialed
started	TIme	No	The time when the call was started today (Unix timestamp format)
finished	Time	No	The time when the call was finished today (Unix timestamp format)
id	Number	No	The ID of the campaign.
serviceId	Number	No	The `serviceId` to which the campaign will be assigned.
campaignId	Number	No	Identifier of the campaign you want to query.
interactionType	String	No	The value for the interaction type.
firstName	String	No	The first name for the transaction.
lastName	String	No	The last name for the transaction.
result	String	No	Result code assigned to the account transaction by the SmartReach system.
agentId	Number	No	The agent ID.
zipcode	String	No	Zip code of the consumer.
wireless	Boolean	No	Indicates whether the phone is wireless.
attempts	Number	No	The number of attempts made to the contact.

Get a list of completed call attempts for a campaign

#Request (JSON)
Get /campaign/campaigns/755873189/finishedCalls
Host: localhost.com
Content-Type: application/json
Accept: application/json
  
#Response (JSON)
200 OK
Content-Type: application/json
 
{
  "call": [
    {
      "id": 500097501543101,
      "firstName": "ASDF",
      "attempts": 1,
      "result": "AGENT - CUST RPC 1",
      "interactionType": "INBOUND_CHAT",
      "agentId": 657823921,
      "serviceId": 284393,
      "zipcode": "12345",
      "wireless": false
    },
    {
      "id": 500097501543101,
      "firstName": "ASDF",
      "attempts": 1,
      "result": "Listened",
      "interactionType": "INBOUND_CHAT",
      "agentId": 0,
      "serviceId": 284393,
      "zipcode": "12345",
      "wireless": false
    },
    .
    .
    .
    {
      "id": 500097501556101,
      "firstName": "ASDF",
      "attempts": 1,
      "result": "Listened",
      "interactionType": "INBOUND_CHAT",
      "agentId": 0,
      "serviceId": 284393,
      "zipcode": "12345",
      "wireless": false
    }
  ]
}

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

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 
}

CODE

List Campaign Transactions

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

This method returns the first 5,000 records.

Method: GET /campaign/campaigns/{id}/transactionList

Parameters:

Path/Query Parameter Name	Type	Mandatory?	Description
id	Integer (ID)	Yes	The ID of the active campaign for which you want to return the account transaction list.
orderBy	String	No	Sorting by option. The default value is date_modified. The sorting values are as follows: acct_transaction_id, account, patient_firstname, patient_lastname, queued, date_modified.

Body:

None

Response Code: 200 OK

Body:

Key Type Mandatory? Description

transaction

Array

No

A container for a page of account transaction entries.

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

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.

dateModified

Date

No

The date on which record is modified.

templateId

Number

No

Template ID

messageId

Number

No

Message ID

resultCode

String

No

Result code

Retrieve the account transaction list for a campaign

#Request (JSON)
GET /campaign/campaigns/121142002/transactionList
Host: localhost.com
Content-Type: application/json
Accept: application/json
 
#Response (JSON)
200 OK
Content-Type: application/json
 
{
  "transaction": [
    {
      "consumer": {
        "firstName": "James",
        "lastName": "Bond"
      },
      "phone": [
        {
          "phone": "7603131371",
          "ordinal": 0
        },
        {
          "phone": "7603131372|7603131373|7603131374",
          "ordinal": 1
        }
      ],
      "extra": [
        {
          "key": "extra11",
          "value": "12345"
        },
        {
          "key": "extra17",
          "value": "760"
        },
        {
          "key": "extra18",
          "value": "ACD"
        }
      ],
      "daysDue": [],
      "accountTransactionId": 56654614846,
      "account": "qa123",
      "balance": 0.0,
      "dateModified": 1736934945000,
      "templateId": 0,
      "messageId": 10194
    }
  ]
}

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 SmartReach when extension-based agents are called by SmartReach 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 SmartReach 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 SmartReach 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 SmartReach .

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

Search 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 Call Center ID(s).

Method: POST /campaign/campaigns

Parameters:

None

Body:

Key	Type	Mandatory?	Description
active	Boolean	No	If the `active` value is `true`, method returns only active campaigns. If the `active` value is `false`, method returns all possible campaigns.
name	String	No	Searches campaign by name.
start	Date	No	Starting date of the range to search for Campaigns. Date cannot be more than 90 days from today, and if set, the end date is required.
end	Date	No	Ending date/time of the range in which to search for Campaigns. Date cannot be more than 90 days from today, and if set, the start date is required.
callCenterIds	List	No	Numeric list of call center IDs to search campaigns.
serviceIds	List	No	Numeric list of service IDs to search campaigns.
page	Number	No	Number of pages going forward.
pageSize	Number	No	Number of records to be returned per requested page. The accepted range is 1 to 5000.

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

Name of the Campaign

clientId

Number

No

Client ID

status

UUID

No

Last known status of the campaign

uploadDate

Date

No

Date when the campaign data uploaded

buildDate

Date

No

Date when the campaign compiled

actualStartDate

Date

No

Date when the campaign execution started

actualEndDate

Date

No

Date when the campaign execution ended

scrubOption

String

No

Campaign scrub option. Allowed values are: NONE, WIRELESS, LANDLINE, SEGMENTED_WIRELESS.

scheduleTime

Date

No

start	Date	No	Campaign start time
end	Date	No	Campaign end time
nextDate	Boolean	No	Campaign next day flag

serviceId

Number

No

Campaign service ID

typeId

Number

No

Campaign type ID.

dialMode

String

No

Dialing mode of the campaign. Allowed values: AUTOMATIC, MANUAL.

voiceId

Number

No

ID of the selected voice.

appendable

Boolean

No

Flag showing if the campaign can be appended in real time.

operatorPhone

String

No

Operator phone value

callBackPhone

String

No

Call back phone value

localCallerIdPackage

Boolean

No

Flag showing if a local caller ID package is selected.

callerId

String

No

Caller ID to be displayed.

dialingStrategyId

Number

No

ID of the selected dialing strategy.

answeringMachineOption

String

No

Answering machine option. Allowed values are: NO_MESSAGES, LEAVE_MESSAGES, TRANSFER, NONE.

Search Campaigns

#Request (JSON)
POST /campaign/campaigns
Host: localhost.com
Content-Type: application/json
Accept: application/json
 
{
  "active": false
}

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

{
  "campaignDetails": [
    {
      "id": 755873192,
      "name": "284393_CALLBACK_CALLS_09-01-2025",
      "status": "PLAYING",
      "uploadDate": 1756793025000,
      "serviceId": 284393,
      "typeId": 2
    },
    {
      "id": 755871400,
      "name": "dsi_10_lvinternal_invalid.txt",
      "status": "DEACTIVATED",
      "uploadDate": 1756734119000,
      "serviceId": 284402,
      "typeId": 1
    },
    {
      "id": 755871028,
      "name": "scheduled_campaign_job_11_2_p5",
      "status": "READY_UNBUILT",
      "uploadDate": 1756726644000,
      "serviceId": 284255,
      "typeId": 1
    },
    .
	.
	.
    {
      "id": 755870867,
      "name": "DSI_lvinternal.csv",
      "status": "DEACTIVATED",
      "uploadDate": 1756723196000,
      "serviceId": 284153,
      "typeId": 7
    }
  ]
}

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

User Roles

API Methods

Campaigns

Append Campaign Record

Create Campaign

Deactivate Campaign

Find Matching Finished Calls

Get Campaign List Info

List Campaign Transactions

Read Campaign

Search Campaigns

Update Campaign

Update Campaign State

Errors

Cookie Notice