# Call Scheduling and Pacing API {% hint style="success" %} **- NEW! - Interactive API docs, now live!** Visit [api-docs.plumvoice.com](https://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. {% endhint %} {% hint style="warning" %} **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. {% endhint %} ## 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): * * * * * * ### 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 {% hint style="success" %} **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. {% endhint %} {% hint style="info" %} **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). {% endhint %} ## 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"

| {% tabs %} {% tab title="422: Unprocessable Entity Nickname has already been taken." %} {% tabs %} {% tab title="JSON" %} ``` { "nickname": [ "The nickname has already been taken." ] } ``` {% endtab %} {% tab title="Schema" %} | Name | Type | Description | | ------------- | ------ | ------------------------------------------------ | | `nickname` | String | The name you entered when creating the schedule. | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | {% tab title="200: OK Successful schedule creation." %} **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. {% tabs %} {% tab title="cURL" %} ``` curl --location --request POST 'https://scheduler.vxml.sharpencx.com/api/schedules' \ --header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812' \ --form 'days="[\"mon\", \"wed\", \"fri\"]"' \ --form 'nickname="3wkdays"' ``` {% endtab %} {% endtabs %} **Success Response** {% tabs %} {% tab title="JSON" %} ``` { "status": "success", "response": { "id": 6, "nickname": "3wkdays" } } ``` {% endtab %} {% tab title="Schema" %} | 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. | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | | {% endtabs %} | | | ## 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"

| {% tabs %} {% tab title="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. {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://scheduler.vxml.sharpencx.com/api/schedules' \ --header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812' code ``` {% endtab %} {% endtabs %} **Success Response** {% tabs %} {% tab title="JSON" %} ``` [ { "schedule_id": 6, "nickname": "3wkdays", "days": [ "mon", "wed", "fri" ] } ] ``` {% endtab %} {% tab title="Schema" %} | 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.

| | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | | {% endtabs %} | | | ## 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"

| {% tabs %} {% tab title="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. {% tabs %} {% tab title="cURL" %} ```json curl --location -g --request PATCH 'https://scheduler.vxml.sharpencx.com/api/schedules/15?days=["mon","wed"]' \ --header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812' ``` {% endtab %} {% endtabs %} **Success Response** {% tabs %} {% tab title="JSON" %} ```json { "status": "success", "response": { "id": 15, "days": "[\"mon\",\"wed\"]", "nickname": "MonWedOnly" } } ``` {% endtab %} {% tab title="Schema" %} | 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. | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | | {% endtabs %} | | | ## 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

| {% tabs %} {% tab title="200: OK Successful schedule deletion." %} **Example Request** This request deletes the schedule associated with `id` 4. {% tabs %} {% tab title="cURL" %} ``` curl --location --request DELETE 'https://scheduler.vxml.sharpencx.com/api/schedules/4' \ --header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812' ``` {% endtab %} {% endtabs %} **Success Response** {% tabs %} {% tab title="JSON" %} ```json { "status": "success" } ``` {% endtab %} {% tab title="Schema" %} | Name | Type | Description | | ------------- | ------ | ----------------------------- | | `status` | String | Returns "success" or "error". | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | {% tab title="400: Bad Request Schedule was not deleted because it is applied to an existing campaign." %} **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. {% tabs %} {% tab title="JSON" %} ```json { "status": "error", "error": "Schedule 3wkdays(id 6) is being used with campaign id 3." } ``` {% endtab %} {% tab title="Schema" %} | Name | Type | Description | | ------------- | ------ | -------------------------------------------- | | `status` | String | Returns "success" or "error". | | `error` | String | Describes the reason for the error response. | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | | {% endtabs %} | | | ## 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

| {% tabs %} {% tab title="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`). {% tabs %} {% tab title="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"' ``` {% endtab %} {% endtabs %} **Success Response** {% tabs %} {% tab title="JSON" %} ``` { "status": "success", "response": { "id": 6, "nickname": "3wkdays" } } ``` {% endtab %} {% tab title="Schema" %} | 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. | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | {% tab title="422: Unprocessable Entity Nickname has already been taken." %} {% tabs %} {% tab title="JSON" %} ``` { "nickname": [ "The nickname has already been taken." ] } ``` {% endtab %} {% tab title="Schema" %} | Name | Type | Description | | ------------- | ------ | ------------------------------------------------ | | `nickname` | String | The name you entered when creating the schedule. | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | | {% endtabs %} | | | ## 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"

| {% tabs %} {% tab title="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. {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://scheduler.vxml.sharpencx.com/api/profiles' \ --header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812' ``` {% endtab %} {% endtabs %} **Success Response** {% tabs %} {% tab title="JSON" %} ``` [ { "profile_id": 5, "nickname": "MorningPace" }, { "profile_id": 6, "nickname": "MorningCalls" } ] ``` {% endtab %} {% tab title="Schema" %} | 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. | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | | {% endtabs %} | | | ## 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

| {% tabs %} {% tab title="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. {% tabs %} {% tab title="cURL" %} ```json 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' ``` {% endtab %} {% endtabs %} **Success Response** {% tabs %} {% tab title="JSON" %} ```json { "status": "success", "response": { "id": 17, "nickname": "30-100-10" } } ``` {% endtab %} {% tab title="Schema" %} | 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. | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | | {% endtabs %} | | | ## 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

| {% tabs %} {% tab title="200: OK Successful profile deletion." %} Example Request This request deletes the profile associated with `id` 7. {% tabs %} {% tab title="cURL" %} ``` curl --location --request DELETE 'https://scheduler.vxml.sharpencx.com/api/profiles/7' \ --header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812' ``` {% endtab %} {% endtabs %} **Success Response** {% tabs %} {% tab title="JSON" %} ``` { "status": "success" } ``` {% endtab %} {% tab title="Schema" %} | Name | Type | Description | | ------------- | ------ | ----------------------------- | | `status` | String | Returns "success" or "error". | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | {% tab title="400: Bad Request Profile was not deleted because it is applied to an existing campaign." %} **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. {% tabs %} {% tab title="JSON" %} ```json { "status": "error", "error": "Profile MorningPace(id 5) is being used with campaign id 4." } ``` {% endtab %} {% tab title="Schema" %} | Name | Type | Description | | ------------- | ------ | -------------------------------------------- | | `status` | String | Returns "success" or "error". | | `error` | String | Describes the reason for the error response. | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | | {% endtabs %} | | | ## 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:+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:

""

| | result\_url | String |

\[Optional]

The URL for post-call processing.

Example:

""

| {% tabs %} {% tab title="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`. {% tabs %} {% tab title="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"' ``` {% endtab %} {% endtabs %} **Success Response** {% tabs %} {% tab title="JSON" %} ``` { "status": "success", "response": { "id": 2, } } ``` {% endtab %} {% tab title="Schema" %} | 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. | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | | {% endtabs %} | | | ## 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"

| {% tabs %} {% tab title="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. {% tabs %} {% tab title="cURL" %} ``` curl --location --request GET 'https://scheduler.vxml.sharpencx.com/api/campaigns' \ --header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812' ``` {% endtab %} {% endtabs %} **Success Response** {% tabs %} {% tab title="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" } ] } ] ``` {% endtab %} {% tab title="Schema" %} | 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. | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | | {% endtabs %} | | | ## 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

| {% tabs %} {% tab title="200: OK Campaign successfully started." %} **Example Request** This request starts the campaign associated with `campaign_id` 6. {% tabs %} {% tab title="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"' ``` {% endtab %} {% endtabs %} **Success Response** {% tabs %} {% tab title="JSON" %} ``` { "status": "success" } ``` {% endtab %} {% tab title="Schema" %} | Name | Type | Description | | ------------- | ------ | ----------------------------- | | `status` | String | Returns "success" or "error". | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | | {% endtabs %} | | | ## 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

| {% tabs %} {% tab title="200: OK Campaign successfully stopped." %} **Example Request** This request stops the campaign associated with `campaign_id` 2. {% tabs %} {% tab title="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"' ``` {% endtab %} {% endtabs %} **Success Response** {% tabs %} {% tab title="JSON" %} ``` { "status": "success" } ``` {% endtab %} {% tab title="Schema" %} | Name | Type | Description | | ------------- | ------ | ----------------------------- | | `status` | String | Returns "success" or "error". | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | | {% endtabs %} | | | ## 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:+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

| {% tabs %} {% tab title="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. {% tabs %} {% tab title="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:+12223334444;ani=7778889999\",\"tel:+14443332222;ani=9998887777\"]"' \ --form 'campaign_id="2"' ``` {% endtab %} {% endtabs %} **Success Response** {% tabs %} {% tab title="JSON" %} ``` { "status": "success" } ``` {% endtab %} {% tab title="Schema" %} | Name | Type | Description | | ------------- | ------ | ----------------------------- | | `status` | String | Returns "success" or "error". | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | | {% endtabs %} | | | ## 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:

""

| | result\_url | String |

\[Optional]

The URL for post-call processing.

Example:

""

| | 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"

| {% tabs %} {% tab title="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. {% tabs %} {% tab title="cURL" %} ```json 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' ``` {% endtab %} {% endtabs %} **Success Response** {% tabs %} {% tab title="JSON" %} ```json { "status": "success", "response": { "id": 26 } } ``` {% endtab %} {% tab title="Schema" %} | 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. | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | | {% endtabs %} | | | ## 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

| {% tabs %} {% tab title="200: OK Successful campaign deletion." %} **Example Request** This request deletes the campaign associated with `id` 11. {% tabs %} {% tab title="cURL" %} ``` curl --location --request DELETE 'https://scheduler.vxml.sharpencx.com/api/campaigns/11' \ --header 'Authorization: Bearer 3cbde128-32b6-47aa-9e62-6353f8b06812' ``` {% endtab %} {% endtabs %} **Success Response** {% tabs %} {% tab title="JSON" %} ```json { "status": "success" } ``` {% endtab %} {% tab title="Schema" %} | Name | Type | Description | | ------------- | ------ | ----------------------------- | | `status` | String | Returns "success" or "error". | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | | {% endtabs %} | | | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.plumvoice.com/dev/plum-dev-apis/call-scheduling-and-pacing-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.