LogoLogo
  • Go to Docs Center
  • Plum DEV Documentation
  • Overview
  • Developer Reference
    • Tutorial
    • How to...
      • Use Plum's Transcription API
    • Audio Formats and Prompts
    • Grammars and Speech Recognition
    • Available ASR Engines
    • TTS Engine Characteristics
      • Amazon Polly TTS Engine
        • Polly Voice Tag Attribute Details
      • AT&T Natural Voices
      • Cepstral Engine
      • RealSpeak Engine
      • Vocalizer 7
        • Vocalizer 7: <voice> tag and SSML Support
    • Data Exchange
    • Logging
    • Caching
    • Root Documents
  • VoiceXML
    • Tags
      • <assign>
      • <audio>
      • <block>
      • <break>
      • <catch>
      • <choice>
      • <clear>
      • <data>
      • <desc>
      • <disconnect>
      • <else>
      • <elseif>
      • <emphasis>
      • <enumerate>
      • <error>
      • <example>
      • <exit>
      • <field>
      • <filled>
      • <foreach>
      • <form>
      • <goto>
      • <grammar>
      • <help>
      • <if>
      • <initial>
      • <item>
      • <lexicon>
      • <link>
      • <log>
      • <mark>
      • <menu>
      • <meta>
      • <metadata>
      • <noinput>
      • <nomatch>
      • <one-of>
      • <option>
      • <paragraph>
      • <param>
      • <phoneme>
      • <prompt>
      • <property>
      • <prosody>
      • <record>
      • <reprompt>
      • <return>
      • <rule>
      • <ruleref>
      • <say-as>
      • <script>
      • <sentence>
      • <speak>
      • <sub>
      • <subdialog>
      • <submit>
      • <tag>
      • <throw>
      • <token>
      • <transfer>
      • <value>
      • <var>
      • <voice>
      • <vxml>
    • Properties
      • audiofetchhint
      • audiomaxage
      • audiomaxstale
      • bargein
      • bargeintype
      • certverifypeer
      • completetimeout
      • confidencelevel
      • datafetchhint
      • datamaxage
      • datamaxstale
      • documentfetchhint
      • documentmaxage
      • documentmaxstale
      • fetchaudio
      • fetchaudiodelay
      • fetchaudiominimum
      • fetchtimeout
      • grammarfetchhint
      • grammarmaxage
      • grammarmaxstale
      • incompletetimeout
      • inputmodes
      • interdigittimeout
      • logging
      • maxnbest
      • maxspeechtimeout
      • normalizeaudio
      • recordcall
      • recordcallappend
      • recordutterance
      • recordutterancetype
      • scriptfetchhint
      • scriptmaxage
      • scriptmaxstale
      • sensitivity
      • speedvsaccuracy
      • termchar
      • termmaxdigits
      • termtimeout
      • timeout
      • universals
      • voicegender
      • voicename
    • Application and Session Variables
      • application.lastresult$[i].confidence
      • application.lastresult$[i].inputmode
      • application.lastresult$[i].interpretation
      • application.lastresult$[i].recording
      • application.lastresult$[i].recordingduration
      • application.lastresult$[i].recordingsize
      • application.lastresult$[i].utterance
      • session.callrecording
      • session.id
      • session.telephone.ani
      • session.telephone.dnis
    • VoiceXML Resources
  • Plum DEV Guide
    • Using the Plum DEV site
    • Using the File Repository
    • Outbound Calling Guide
      • Using the Outbound Tools in the DEV web UI
      • DEV Outbound Programming Notes
      • Outbound FAQs and Tips
    • Call Reporting
    • Analytics
    • VoiceTrends
    • Debugging
    • Scratchpads
    • Saved URLs
    • Voice Biometrics
    • Call Routing
    • Data Security
      • 'Private' Tags
      • Managing Secure Phone Numbers
      • Sensitive Data Types
    • SMS Guide
      • Standard Short Codes
      • SMS Debugging/Error Logs
      • Additional SMS Info
    • Single Sign On
  • Plum DEV APIs
    • DEV Outbound APIs
      • Contacts CSV Formatting
      • Outbound API Parameter Notes
      • Legacy and Miscellaneous Notes
    • SMS API
    • Call Logs API
    • Call Scheduling and Pacing API
    • Transcription API
    • Application API
    • Blocklist API
Powered by GitBook
On this page
  • Overview
  • Authentication
  • List of methods
  • Create Schedule
  • Get Schedules
  • Update Schedule
  • Delete Schedule
  • Create Profile
  • Get Profiles
  • Update Profile
  • Delete Profile
  • Create Campaign
  • Get Campaigns
  • Start Campaign
  • Stop Campaign
  • Add Calls
  • Update Campaign
  • Delete Campaign
  1. Plum DEV APIs

Call Scheduling and Pacing API

PreviousCall Logs APINextTranscription API

Last updated 2 years ago

- NEW! - Interactive API docs, now live!

Visit to read Plum API documentation, build and test requests in our interactive API sandbox, review the responses, and share it all with your team.

IMPORTANT: Development on this API is ongoing – please bear in mind that additional, unforeseen changes may occur between the time of this writing and product release.

Overview

The Outbound Call Scheduling and Pacing API allows you to create outbound calling campaigns as well as reusable resources to define schedules and call pacing for each campaign. This API consists of three main resources:

  • Schedules: Sets the days of the week that your campaign will run. Once created, a schedule can be reused across one or more campaigns.

  • Profiles: Sets call pacing for your campaign. Once created, a profile can be reused across one or more campaigns. One or multiple profiles can be used in a single campaign if desired.

  • Campaigns: Creates outbound calling campaigns linked to your chosen VXML application. Also controls existing campaign activity. Existing schedules and profiles are linked to campaigns during campaign creation.

This API contains the following endpoints (6 total):

  • https://scheduler.plumvoice.com/api/schedules

  • https://scheduler.plumvoice.com/api/profiles

  • https://scheduler.plumvoice.com/api/campaigns

  • https://scheduler.plumvoice.com/api/campaigns/start

  • https://scheduler.plumvoice.com/api/campaigns/stop

  • https://scheduler.plumvoice.com/api/campaigns/add-calls

Authentication

API requests are authenticated using a bearer token. Currently, this token will be generated for you. In the future, users will be able to generate their own bearer tokens as needed.

List of methods

NOTE: In each of the following methods, you can view an example request and success response by expanding the Responses section and viewing the 200: OK response.

NOTE: The example cURL commands in each API method below use a back slash (\) as a line continuation character. The back slash may be removed or replaced based on your operating system (e.g., replace with (^) for Windows cmd, (`) for Powershell).

Create Schedule

POST https://scheduler.plumvoice.com/api/schedules

Creates a rule set that controls which day(s) in a week a campaign will be active. A schedule can be reused across one or more campaigns.

To affect a campaign, an existing schedule must be added when the campaign is created.

Request Body

Name
Type
Description

days

Array

[Required]

The day(s) in a week when a campaign may place calls. Enter each chosen day as a 3-letter abbreviation. (mon, tue, wed, thu, fri, sat, sun)

Example: ["mon","wed","fri"]

nickname

String

[Optional] | 64 character maximum

A custom name for the schedule.

Example: "3wkdays"

{
    "nickname": [
        "The nickname has already been taken."
    ]
}
Name
Type
Description

nickname

String

The name you entered when creating the schedule.

Example Request

This request creates a schedule named 3wkdays. If this schedule were applied to a new campaign, that campaign would run on Mondays, Wednesdays, and Fridays only.

curl --location --request POST 'https://scheduler.plumvoice.com/api/schedules' \
--header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812' \
--form 'days="[\"mon\", \"wed\", \"fri\"]"' \
--form 'nickname="3wkdays"'

Success Response

{
    "status": "success",
    "response": {
        "id": 6,
        "nickname": "3wkdays"
    }
}
Name
Type
Description

status

String

Returns "success" or "error".

response

Array

Includes the following:

  • id

  • nickname

id

Integer

Identifies a schedule. Automatically added to each schedule upon creation.

nickname

String

The name you entered when creating the schedule.

Get Schedules

GET https://scheduler.plumvoice.com/api/schedules

Returns all existing schedules created by you.

Headers

Name
Type
Description

Content-Type

String

[Optional]

Indicates the content type of the request. Any content type relevant to a form-data POST request will likely work. Default is text/plain.

Example / Suggested values:

"application/json"

"application/xml"

Example Request

This request returns all existing schedules that you have created and their associated parameters.

curl --location --request GET 'https://scheduler.plumvoice.com/api/schedules' \
--header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812' code

Success Response

[
    {
        "schedule_id": 6,
        "nickname": "3wkdays",
        "days": [
            "mon",
            "wed",
            "fri"
        ]
    }
]
Name
Type
Description

schedule_id

Integer

Identifies a schedule. Automatically added to each schedule upon creation.

The Create Schedule endpoint returns this identifier as response.id when you create a schedule.

nickname

String

The name you entered when creating the schedule.

days

Array

The day(s) in a week when a campaign may place calls.

Returns each selected day as a string value.

Update Schedule

PATCH https://scheduler.plumvoice.com/api/schedules/{id}

Update one or more specific parameters for the selected schedule.

Note: The API is designed to accept this request with either the PATCH or PUT method and produce the same results. Only parameters specified in the request will be updated.

Path Parameters

Name
Type
Description

id

Integer

[Required]

The identifier for an existing schedule.

The Create Schedule endpoint returns this identifier as response.id when you create a schedule. The Get Schedules endpoint returns this identifier as id for any existing schedule.

Example: 4

Query Parameters

Name
Type
Description

days

Array

[Required]

The day(s) in a week when a campaign may place calls. Enter each chosen day as a 3-letter abbreviation. (mon, tue, wed, thu, fri, sat, sun)

Example: ["mon","wed","fri"]

name

String

[Optional] | 64 character minimum

A custom name for the schedule.

Example: "3wkdays"

Example Request

This request updates the days parameter to Mondays and Wednesdays for the schedule with id 15.

curl --location -g --request PATCH 'https://scheduler.plumvoice.com/api/schedules/15?days=["mon","wed"]' \
--header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812'

Success Response

{
    "status": "success",
    "response": {
        "id": 15,
        "days": "[\"mon\",\"wed\"]",
        "nickname": "MonWedOnly"
    }
}
Name
Type
Description

status

String

Returns "success" or "error".

response

Array

Includes the following:

  • id

  • days

  • nickname

id

Integer

Identifies a schedule. Automatically added to each schedule upon creation.

days

Array

The day(s) in a week when a campaign may place calls. Returns each selected day as a string value. Note: Backslashes (\) in the response only appear here and are not included in the updated days value.

nickname

String

The name you entered when creating the schedule.

Delete Schedule

DELETE https://scheduler.plumvoice.com/api/schedules/{id}

Removes an existing schedule using the id number entered.

Note: A schedule cannot be deleted while applied to a campaign.

Path Parameters

Name
Type
Description

id

Integer

[Required]

The identifier for an existing schedule.

The Create Schedule endpoint returns this identifier as response.id when you create a schedule. The Get Schedules endpoint returns this identifier as id for any existing schedule.

Example: 4

Example Request

This request deletes the schedule associated with id 4.

curl --location --request DELETE 'https://scheduler.plumvoice.com/api/schedules/4' \
--header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812'

Success Response

{
    "status": "success"
}
Name
Type
Description

status

String

Returns "success" or "error".

Note: The response lists only one campaign at a time. If the selected schedule is associated with multiple campaigns, the campaign with the highest ID number will be given.

{
    "status": "error",
    "error": "Schedule 3wkdays(id 6) is being used with campaign id 3."
}
Name
Type
Description

status

String

Returns "success" or "error".

error

String

Describes the reason for the error response.

Create Profile

POST https://scheduler.plumvoice.com/api/profiles

Creates a rule set that controls call pacing for campaigns. A profile can be reused across one or more campaigns.

To affect a campaign, an existing profile must be added when the campaign is created.

Request Body

Name
Type
Description

period

Integer

[Required] | 11 digit maximum

The interval for placing calls, in minutes.

Example: 30

time_between_periods

Integer

[Required] | 11 digit maximum

An interval of downtime between each period, in minutes.

Example: 10

nickname

String

[Optional] | 64 character maximum

A custom name for the profile. Used to reference the profile when using the Create Campaign endpoint.

Example: "MorningCalls"

amount_per_period

Integer

[Required] | 11 digit maximum

The number of calls to place within a period.

Example: 100

Example Request

This request creates a profile named MorningPace. If this profile were applied to a new campaign, that campaign would run for 30 minutes at a time (period), make 100 calls during that time (amount_per_period), and have 10 minutes of downtime between each 30 minute period (time_between_periods).

curl --location --request POST 'https://scheduler.plumvoice.com/api/profiles' \
--header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812' \
--form 'period="30"' \
--form 'amount_per_period="100"' \
--form 'nickname="MorningPace"' \
--form 'time_between_periods="10"'

Success Response

{
    "status": "success",
    "response": {
        "id": 6,
        "nickname": "3wkdays"
    }
}
Name
Type
Description

status

String

Returns "success" or "error".

response

Array

Includes the following:

  • id

  • nickname

id

Integer

Identifies a profile. Automatically added to each profile upon creation.

nickname

String

The name you entered when creating the profile.

{
    "nickname": [
        "The nickname has already been taken."
    ]
}
Name
Type
Description

nickname

String

The name you entered when creating the schedule.

Get Profiles

GET https://scheduler.plumvoice.com/api/profiles

Returns all existing profiles created by you.

Headers

Name
Type
Description

Content-Type

String

[Optional]

Indicates the content type of the request. Any content type relevant to a form-data POST request will likely work. Default is text/plain.

Example / Suggested values:

"application/json"

"application/xml"

Example Request

This request returns all existing profiles that you have created and their associated parameters.

curl --location --request GET 'https://scheduler.plumvoice.com/api/profiles' \
--header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812'

Success Response

[
    {
        "profile_id": 5,
        "nickname": "MorningPace"
    },
    {
        "profile_id": 6,
        "nickname": "MorningCalls"
    }
]
Name
Type
Description

profile_id

Integer

Identifies a profile. Automatically added to each profile upon creation.

The Create Profile endpoint returns this identifier as response.id when you create a profile.

nickname

String

The name you entered when creating the profile.

Update Profile

PATCH https://scheduler.plumvoice.com/api/profiles/{id}

Update one or more specific parameters for the selected profile.

Note: The API is designed to accept this request with either the PATCH or PUT method and produce the same results. Only parameters specified in the request will be updated.

Path Parameters

Name
Type
Description

id

Integer

[Required]

The identifier for an existing profile.

The Create Profile endpoint returns this identifier as response.id when you create a profile. The Get Profiles endpoint returns this identifier as id for any existing profile.

Example: 7

Query Parameters

Name
Type
Description

period

Integer

[Optional] | 11 digit maximum

The interval for placing calls, in minutes.

Example: 30

amount_per_period

Integer

[Optional] | 11 digit maximum

The number of calls to place within a period.

Example: 100

nickname

String

[Optional] | 64 character maximum

A custom name for the profile. Used to reference the profile when using the Create Campaign endpoint.

Example: "MorningCalls"

time_between_periods

Integer

[Optional] | 11 digit maximum

An interval of downtime between each period, in minutes.

Example: 10

Example Request

This request updates all parameters available for the profile with id 17.

Note that the response only returns the profile's id and nickname. To confirm all specified parameters have the desired values, use the Get Profiles endpoint and review the updated profile in the response.

curl --location --request PATCH 'https://scheduler.plumvoice.com/api/profiles/17?period=31&amount_per_period=101&time_between_periods=11&nickname=30-100-10' \
--header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812'

Success Response

{
    "status": "success",
    "response": {
        "id": 17,
        "nickname": "30-100-10"
    }
}
Name
Type
Description

status

String

Returns "success" or "error".

response

Array

Includes the following:

  • id

  • nickname

id

Integer

Identifies a schedule. Automatically added to each schedule upon creation.

nickname

String

The name you entered when creating the schedule.

Delete Profile

DELETE https://scheduler.plumvoice.com/api/profiles/{id}

Removes an existing profile using the id number entered.

Note: A profile cannot be deleted while applied to a campaign.

Path Parameters

Name
Type
Description

id

Integer

[Required]

The identifier for an existing profile.

The Create Profile endpoint returns this identifier as response.id when you create a profile. The Get Profiles endpoint returns this identifier as id for any existing profile.

Example: 7

Example Request

This request deletes the profile associated with id 7.

curl --location --request DELETE 'https://scheduler.plumvoice.com/api/profiles/7' \
--header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812'

Success Response

{
    "status": "success"
}
Name
Type
Description

status

String

Returns "success" or "error".

Note: The response lists only one campaign at a time. If the selected profile is associated with multiple campaigns, the campaign with the highest ID number given.

{
    "status": "error",
    "error": "Profile MorningPace(id 5) is being used with campaign id 4."
}
Name
Type
Description

status

String

Returns "success" or "error".

error

String

Describes the reason for the error response.

Create Campaign

POST https://scheduler.plumvoice.com/api/campaigns

Creates a new campaign.

Headers

Name
Type
Description

Content-Type

String

[Optional]

Indicates the content type of the request. Any content type relevant to a form-data POST request will likely work. Default is text/plain.

Example / Suggested values:

"application/json"

"application/xml"

Request Body

Name
Type
Description

start_date

String

[Required]

The start date for the campaign.

Format: YYYY-MM-DD

Example: "2022-01-01"

end_date

String

[Required]

The end date for the campaign.

Format: YYYY-MM-DD

Example: "2022-01-31"

schedule

String

[Required]

The schedule to apply to the campaign. Accepts one (1) schedule's schedule_id number or nickname, whichever you choose.

Example:

6

"3wkdays"

profiles

Array

[Required]

The profile(s) to apply to the campaign. You can enter one or multiple profiles.

For each profile, enter an array containing the following key/value pairs:

profile (String): The nickname set for your chosen profile.

start_time (String): The time campaign calls will start. Eastern timezone.

Format: HH:MM (24-hour clock)

end_time (String): The time campaign calls will end. Eastern timezone.

Format: HH:MM (24-hour clock)

Examples:

1 profile:

[{"profile":"JanuaryMornings", "start_time":"08:00", "end_time":"21:00"}]

2 profiles:

[{"profile":"MorningPace", "start_time":"08:00", "end_time":"11:00"},{"profile":"AfternoonPace", "start_time":"12:00", "end_time":"16:00"}]

phone_numbers

Object

[Optional]

The .CSV or .TXT file containing phone numbers to be called. Enter the filepath to the .CSV or .TXT file.

Example:

"/C:/Users/My Account/Desktop/PhoneNumbers.csv"

Note: Phone number entries can also include a message_reference value. Once submitted in an API request, this value will be posted to the URLs referemced in thestart_url and result_url parameters. Adding message_reference values can help with identifying calls and API requests within your internal systems.

Format: Any string that does not contain a comma. Add this string at the end of any phone number entry, separated with a comma.

Examples:

Without a message_reference value: ["tel:+12223334444; ani=7778889999"]

With a message_reference value:

["tel:+12223334444; ani=7778889999, marchcampaign"]

start_url

String

[Required]

The URL of the VXML application to use in each call.

Example:

"http://charles.plumgroup.com/~schan/src/charles/vxml/start.php"

result_url

String

[Optional]

The URL for post-call processing.

Example:

"http://myserver.com/storesmsresults.php"

Example Request

This request creates a campaign that will run from January 1, 2022 (start_date) to January 5, 2022 (end_date). The campaign will run on the days set in the schedule associated with the schedule_id 6. On each scheduled day, the campaign will begin running at 8:00 A.M. and stop running at 11:00 A.M. (Eastern) using the call-pacing profile MorningPace. Each call will use the VXML application linked in start_url and post-call processing linked in result_url.

curl --location --request POST 'https://scheduler.plumvoice.com/api/campaigns' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812' \
--form 'start_date="2022-01-01"' \
--form 'end_date="2022-01-05"' \
--form 'phone_numbers=@"/C:/Users/jrobe/Desktop/api-test-1.csv"' \
--form 'profiles="[{\"profile\":\"MorningPace\",\"start_time\":\"08:00\",\"end_time\":\"11:00\"}]"' \
--form 'schedule_id="6"' \
--form 'start_url="http://charles.plumgroup.com/~schan/src/charles/vxml/start.php"' \
--form 'result_url="http://myserver.com/storesmsresults.php"'

Success Response

{
    "status": "success",
    "response": {
        "id": 2,
    }
}
Name
Type
Description

status

String

Returns "success" or "error".

response

Array

Includes the following:

  • id

id

Integer

Identifies a campaign. Automatically added to each campaign upon creation.

Get Campaigns

GET https://scheduler.plumvoice.com/api/campaigns

Returns all existing campaigns created by you.

Headers

Name
Type
Description

Content-Type

String

[Optional]

Indicates the content type of the request. Any content type relevant to a form-data POST request will likely work. Default is text/plain.

Example / Suggested values:

"application/json"

"application/xml"

Example Request

This request returns all existing campaigns that you have created and their associated parameters.

curl --location --request GET 'https://scheduler.plumvoice.com/api/campaigns' \
--header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812'

Success Response

[
      {
        "campaign_id": 12,
        "start_date": "2022-01-01 00:00:00",
        "end_date": "2022-01-05 00:00:00",
        "start_url": "http://charles.plumgroup.com/~schan/src/charles/vxml/start.php",
        "result_url": "http://myserver.com/storesmsresults.php",
        "schedule_nickname": "3wkdays",
        "profiles": [
            {
                "profile_id": 5,
                "nickname": "MorningPace",
                "start_time": "08:00",
                "end_time": "23:00"
            }
        ]
    }
]
Name
Type
Description

campaign_id

Integer

Identifies a campaign. Automatically added to each campaign upon creation.

This is the same value returned as response.id by the Create Campaign endpoint response.

start_date

String

The start date entered for the campaign.

end_date

String

The end date entered for the campaign.

start_url

String

The URL entered for the VXML application that will be used in each call.

result_url

String

The URL entered for post-call processing.

schedule_nickname

String

The schedule ID or nickname entered when the campaign was created.

profiles

Array

Includes the following:

  • profile_id

  • nickname

  • start_time

  • end_time

profile_id

Integer

Identifies a profile. Automatically added to each profile upon creation.

nickname

String

The name you entered when creating the profile.

start_time

String

The time campaign calls will start. Eastern timezone.

end_time

String

The time campaign calls will end. Eastern timezone.

Start Campaign

POST https://scheduler.plumvoice.com/api/campaigns/start

Starts an existing campaign.

Request Body

Name
Type
Description

campaign_id

Integer

[Required]

The identifier for the campaign to start.

The Create Campaign endpoint returns this identifier as response.id when you create a campaign. The Get Campaigns endpoint returns this identifier as id for any existing campaign.

Example: 2

Example Request

This request starts the campaign associated with campaign_id 6.

curl --location --request POST 'https://scheduler.plumvoice.com/api/campaigns/start' \
--header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812' \
--form 'campaign_id="6"'

Success Response

{
    "status": "success"
}
Name
Type
Description

status

String

Returns "success" or "error".

Stop Campaign

POST https://scheduler.plumvoice.com/api/campaigns/stop

Stops an active campaign.

Request Body

Name
Type
Description

campaign_id

Integer

[Required]

The identifier for an existing campaign.

Example: 2

Example Request

This request stops the campaign associated with campaign_id 2.

curl --location --request POST 'https://scheduler.plumvoice.com/api/campaigns/stop' \
--header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812' \
--form 'campaign_id="2"'

Success Response

{
    "status": "success"
}
Name
Type
Description

status

String

Returns "success" or "error".

Add Calls

POST https://scheduler.plumvoice.com/api/campaigns/add-calls

Appends additional phone numbers to an existing campaign.

If the campaign is already running, the new phone numbers will be added to the end of the queue.

Request Body

Name
Type
Description

phone_numbers

Array / Object

[Required]

The phone numbers to be added to an existing campaign. Can be submitted as either a JSON array, or a .CSV or .TXT file.

For JSON: Enter each number as a string in the array, including both the long code number and the ANI.

Format:

["tel:[(phone number); ani=(ANI)"]

Example (Array):

["tel:+12223334444; ani=7778889999","tel:+14443332222; ani=9998887777"]

For .CSV/.TXT files: Enter the filepath to the .CSV or .TXT file.

Example:

"/C:/Users/My Account/Desktop/PhoneNumbers.csv"

Note: Phone number entries can also include a message_reference value. Once submitted in an API request, this value will be posted to the URLs referemced in thestart_url and result_url parameters. Adding message_reference values can help with identifying calls and API requests within your internal systems.

Format: Any string that does not contain a comma. Add this string at the end of any phone number entry, separated with a comma.

Examples:

Without a message_reference value: ["tel:+12223334444; ani=7778889999"]

With a message_reference value:

["tel:+12223334444; ani=7778889999, marchcampaign"]

campaign_id

Integer

[Required]

The identifier for an existing campaign.

Example: 2

Example Request

This request adds the submitted phone numbers to the campaign associated with campaign_id 2.

curl --location --request POST 'https://scheduler.plumvoice.com/api/campaigns/add-calls' \
--header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812' \
--form 'phone_numbers="[\"tel:+12223334444;ani=7778889999\",\"tel:+14443332222;ani=9998887777\"]"' \
--form 'campaign_id="2"'

Success Response

{
    "status": "success"
}
Name
Type
Description

status

String

Returns "success" or "error".

Update Campaign

PATCH https://scheduler.plumvoice.com/api/campaigns/{id}

Update one or more specific parameters for the selected campaign.

Notes:

The API is designed to accept this request with either the PATCH or PUT method and produce the same results. Only parameters specified in the request will be updated.

A campaign's phone numbers cannot be updated through this method. Use the Add Calls method for this instead.

Path Parameters

Name
Type
Description

id

Integer

[Required]

The identifier for an existing campaign.

The Create Campaign endpoint returns this identifier as response.id when you create a campaign. The Get Campaigns endpoint returns this identifier as id for any existing campaign.

Example: 11

Note: The id parameter is required for this method to function properly, but requests without a value set for id will still return a response.

However, in this case, the request will simply return all existing campaigns, similar to the Get Campaigns method. No changes to any other specified parameters will be applied to any campaign.

Query Parameters

Name
Type
Description

start_date

String

[Optional]

The start date for the campaign.

Format: YYYY-MM-DD

Example: "2022-01-01"

end_date

String

[Optional]

The end date for the campaign.

Format: YYYY-MM-DD

Example: "2022-01-31"

start_url

String

[Optional]

The URL of the VXML application to use in each call.

Example:

"http://charles.plumgroup.com/~schan/src/charles/vxml/start.php"

result_url

String

[Optional]

The URL for post-call processing.

Example:

"http://myserver.com/storesmsresults.php"

profiles

Array

[Optional]

The profile(s) to apply to the campaign. You can enter one or multiple profiles.

For each profile, enter an array containing the following key/value pairs:

profile (String): The nickname set for your chosen profile.

start_time (String): The time campaign calls will start. Eastern timezone.

Format: HH:MM (24-hour clock)

end_time (String): The time campaign calls will end. Eastern timezone.

Format: HH:MM (24-hour clock)

Examples:

1 profile:

[{"profile":"JanuaryMornings", "start_time":"08:00", "end_time":"21:00"}]

2 profiles:

[{"profile":"MorningPace", "start_time":"08:00", "end_time":"11:00"},{"profile":"AfternoonPace", "start_time":"12:00", "end_time":"16:00"}]

IMPORTANT – PLEASE READ!

The profile(s) submitted here will overwrite ALL of the selected campaign's attached profiles.

If the selected campaign has multiple profiles, you must enter ALL of the profiles that the campaign should have once updated. This includes both the profiles being added/changed AND the ones that should stay the same.

schedule

String

[Optional]

The schedule to apply to the campaign. Accepts one (1) schedule's schedule_id number or nickname, whichever you choose.

Example:

6

"3wkdays"

Example Request

This request updates the applied schedule, starting date, ending date, and applied profile for the campaign with id 26.

Note that the response only returns the campaign's id. To confirm all specified parameters have the desired values, use the Get Campaigns endpoint and review the updated campaign in the response.

curl --location -g --request PATCH 'https://scheduler.plumvoice.com/api/campaigns/26?schedule=11&start_date=2022-04-15&end_date=2022-04-30&profiles=[{"profile":"MorningPace","start_time":"08:00","end_time":"23:00"}]' \
--header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812'

Success Response

{
    "status": "success",
    "response": {
        "id": 26
    }
}
Name
Type
Description

status

String

Returns "success" or "error".

response

Array

Includes the following:

  • id

id

Integer

Identifies a schedule. Automatically added to each schedule upon creation.

Delete Campaign

DELETE https://scheduler.plumvoice.com/api/campaigns/{id}

Removes an existing campaign using the id number entered.

Note: Deleting a campaign will not delete any schedule or profile(s) applied to that campaign.

Path Parameters

Name
Type
Description

id

Integer

[Required]

The identifier for an existing campaign.

The Create Campaign endpoint returns this identifier as response.id when you create a campaign. The Get Campaigns endpoint returns this identifier as id for any existing campaign.

Example: 11

Example Request

This request deletes the campaign associated with id 11.

curl --location --request DELETE 'https://scheduler.plumvoice.com/api/campaigns/11' \
--header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812'

Success Response

{
    "status": "success"
}
Name
Type
Description

status

String

Returns "success" or "error".

api-docs.plumvoice.com