Call Scheduling and Pacing API

- NEW! - Interactive API docs, now live!

Visit api-docs.plumvoice.com 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.vxml.sharpencx.com/api/schedules

• https://scheduler.vxml.sharpencx.com/api/profiles

• https://scheduler.vxml.sharpencx.com/api/campaigns

• https://scheduler.vxml.sharpencx.com/api/campaigns/start

• https://scheduler.vxml.sharpencx.com/api/campaigns/stop

• https://scheduler.vxml.sharpencx.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.vxml.sharpencx.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"

422: Unprocessable Entity Nickname has already been taken.

JSON

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

Schema

200: OK Successful schedule creation.

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"

200: OK Returns all of your existing schedules and the parameters set for each one.

Example Request

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

cURL

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

Success Response

JSON

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

Schema

Update Schedule

PATCH https://scheduler.vxml.sharpencx.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"

200: OK Selected parameters were updated successfully.

Example Request

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

cURL

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

Success Response

JSON

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

Schema

Delete Schedule

DELETE https://scheduler.vxml.sharpencx.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

200: OK Successful schedule deletion.

Example Request

This request deletes the schedule associated with id 4.

cURL

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

Success Response

JSON

{
    "status": "success"
}

Schema

400: Bad Request Schedule was not deleted because it is applied to an existing campaign.

Create Profile

POST https://scheduler.vxml.sharpencx.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

200: OK Successful profile creation.

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

curl --location --request POST 'https://scheduler.vxml.sharpencx.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

JSON

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

Schema

422: Unprocessable Entity Nickname has already been taken.

Get Profiles

GET https://scheduler.vxml.sharpencx.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"

200: OK Returns all of your existing profiles and the parameters set for each one.

Example Request

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

cURL

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

Success Response

JSON

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

Schema

Update Profile

PATCH https://scheduler.vxml.sharpencx.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

200: OK Selected parameters were updated successfully.

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

curl --location --request PATCH 'https://scheduler.vxml.sharpencx.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

JSON

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

Schema

Delete Profile

DELETE https://scheduler.vxml.sharpencx.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

200: OK Successful profile deletion.

Example Request

This request deletes the profile associated with id 7.

cURL

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

Success Response

JSON

{
    "status": "success"
}

Schema

400: Bad Request Profile was not deleted because it is applied to an existing campaign.

Create Campaign

POST https://scheduler.vxml.sharpencx.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:[phone]; ani=7778889999"] With a message_reference value: ["tel:[phone]; 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"

200: OK Successful campaign creation.

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

curl --location --request POST 'https://scheduler.vxml.sharpencx.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

JSON

{
    "status": "success",
    "response": {
        "id": 2,
    }
}

Schema

Get Campaigns

GET https://scheduler.vxml.sharpencx.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"

200: OK Returns all of your existing campaigns and the parameters set for each one.

Example Request

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

cURL

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

Success Response

JSON

[
      {
        "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"
            }
        ]
    }
]

Schema

Start Campaign

POST https://scheduler.vxml.sharpencx.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

200: OK Campaign successfully started.

Example Request

This request starts the campaign associated with campaign_id 6.

cURL

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

Success Response

JSON

{
    "status": "success"
}

Schema

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

200: OK Campaign successfully stopped.

Example Request

This request stops the campaign associated with campaign_id 2.

cURL

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

Success Response

JSON

{
    "status": "success"
}

Schema

Add Calls

POST https://scheduler.vxml.sharpencx.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:[phone]; ani=7778889999","tel:[phone]; 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:[phone]; ani=7778889999"] With a message_reference value: ["tel:[phone]; ani=7778889999, marchcampaign"]
campaign_id	Integer	[Required] The identifier for an existing campaign. Example: 2

200: OK Successful addition of phone numbers to the chosen campaign.

Example Request

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

cURL

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

Success Response

JSON

{
    "status": "success"
}

Schema

Update Campaign

PATCH https://scheduler.vxml.sharpencx.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"

200: OK Selected parameters were updated successfully.

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

curl --location -g --request PATCH 'https://scheduler.vxml.sharpencx.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

JSON

{
    "status": "success",
    "response": {
        "id": 26
    }
}

Schema

Delete Campaign

DELETE https://scheduler.vxml.sharpencx.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

200: OK Successful campaign deletion.

Example Request

This request deletes the campaign associated with id 11.

cURL

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

Success Response

JSON

{
    "status": "success"
}

Schema