# DEV Outbound APIs

{% 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 %}

## Outbound API Methods

| Method                        | Service                                            | Description                                                  |
| ----------------------------- | -------------------------------------------------- | ------------------------------------------------------------ |
| [POST](#queue-a-single-call)  | [webservice/queuecall.php](#queue-a-single-call)   | [Queues a single outbound phone call](#queue-a-single-call)  |
| [POST](#queue-multiple-calls) | [webservice/queuecalls.php](#queue-multiple-calls) | [Queues multiple outbound phone call](#queue-multiple-calls) |

#### Queue a Single Call with the queuecall web service

This default campaign and the calls within it are visible in and controlled from your campaign management interface after you login with your login name and PIN.‌ If you do not already have a PIN for outbound calling, contact Plum's [Account Management](mailto:accountmanagement@plumgroup.com) team.

{% hint style="danger" %}
If you plan to queue **more than one** call at a time, use the [Queue Multiple Calls](#queue-multiple-calls) API Method. Looping the Single Call API for individual calls can cause DDoS, which will result in all calls failing.
{% endhint %}

## Queue A Single Call

<mark style="color:green;">`POST`</mark> `http://outbound.vxml.sharpencx.com/webservice/queuecall.php‌`

The **queuecall** API method allows users to initiate a call to a specific phone number. Initiating an outbound call in this manner places the call into the default calling campaign for your account.&#x20;

#### Request Body

| Name                  | Type    | Description                                                                                                                                                                                          |
| --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| login                 | string  | Sender login name (max length 128)                                                                                                                                                                   |
| pin                   | string  | Sender PIN code (max length 16)                                                                                                                                                                      |
| phone\_number         | string  | Phone number to be dialed (include a 1 before the area code) (max length 128)                                                                                                                        |
| start\_url            | string  | URL for the VoiceXML script used for the call (max length 255)                                                                                                                                       |
| result\_url           | string  | URL for post-call processing (max length 255)                                                                                                                                                        |
| message\_reference    | string  | The message\_reference string is POSTed to the URL specified by start\_url (max length 255)                                                                                                          |
| call\_parameters      | string  | The call\_parameters string is POSTed to the URL specified by start\_url (max length 255)                                                                                                            |
| max\_retry            | integer | An integer between 0 and 10 for the number of failed call attempts before giving up                                                                                                                  |
| retry\_interval       | integer | An integer from 60 to 172800 indicating the number of seconds between retries                                                                                                                        |
| scheduled\_timestamp  | integer | (Optional) 0 to start immediately or a UNIX-time integer indicating when to start attempting the call                                                                                                |
| expiration\_timestamp | integer | (Optional) 0 to never expire or a UNIX-time integer indicating when the outbound system should give up attempting to complete an uncompleted call                                                    |
| scheduled\_time       | string  | Alternative option to `scheduled_timestamp`. See call control settings below. (max length 80)                                                                                                        |
| expiration\_time      | string  | Alternative option to `expiration_timestamp`. See call control settings below. (max length 80)                                                                                                       |
| is\_pci               | integer | 0 or 1. For customers who have been granted access to our HIPAA-/PCI-compliant secure environment, setting this flag to 1 causes connected outbound calls to execute within that secure environment. |

{% tabs %}
{% tab title="200 " %}
{% tabs %}
{% tab title="Required Parameters" %}

```javascript
<?xml version="1.0"?>
<queuecall status="queued" call_id="112850593">
    <login>user</login>
    <pin>98765432</pin>
    <phone_number>+1234567890;ani=8001234567</phone_number>
    <start_url>http://charles.plumgroup.com/~schan/src/charles/vxml/start.php</start_url>
</queuecall>
```

{% endtab %}

{% tab title="Required & Optional Parameters" %}

```javascript
<?xml version="1.0"?>
<queuecall status="queued" call_id="112852724">
    <login>user</login>
    <pin>98765432</pin>
    <phone_number>+1234567890;ani=8001234567</phone_number>
    <start_url>http://charles.plumgroup.com/~schan/src/charles/vxml/start.php</start_url>
    <max_retries>1</max_retries>
    <retry_interval>70</retry_interval>
    <scheduled_timestamp>1596832808</scheduled_timestamp>
    <scheduled_time>Fri, 07 Aug 2020 16:40:08 -0400</scheduled_time>
</queuecall>
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
See the [Outbound API parameter notes](https://docs.plumvoice.com/dev/plum-dev-apis/outbound-api-parameter-notes#single-outbound-call) for additional information on these single call API parameters.
{% endhint %}

#### Queue Multiple Calls with the queuecalls web service

The campaign manager interface allows users to assign campaigns a unique name and to manage various aspects of the campaign. Use your login name and PIN to access the campaign manager.‌ If you do not already have a PIN for outbound calling, contact Plum's [Account Management](mailto:accountmanagement@plumgroup.com) team.

## Queue Multiple Calls

<mark style="color:green;">`POST`</mark> `http://outbound.vxml.sharpencx.com/webservice/queuecalls.php‌`

The **queuecalls** API method allows users to initiate calls to any number of callers listed in an uploaded text file. Initiating a group of outbound calls in this manner creates a calling campaign.&#x20;

#### Headers

| Name         | Type   | Description         |
| ------------ | ------ | ------------------- |
| content-type | string | multipart/form-data |

#### Request Body

| Name                  | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| login                 | string  | Sender login name (max length 128)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| pin                   | string  | Sender PIN code (max length 16)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| campaign\_name        | string  | Unique name for the new calling campaign                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| phone\_list           | object  | <p>CSV file containing the list of phone numbers to be dialed, and optionally the <em>message\_reference</em> and <em>call\_parameter</em>.<br><br>Each line will include the following items, delimited by a comma:<br><strong>1</strong>) Phone number destination, include "1" before the area code (<em>required</em>)<br><strong>2</strong>) <em>message\_reference</em> - string posted to start\_url and result\_url (max length 128, <em>optional</em>)<br><strong>3</strong>) <em>call\_parameter</em> - string posted to start\_url (max length 255, <em>optional</em>)</p> |
| start\_url            | string  | URL for the VoiceXML script used for the call (max length 255)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| result\_url           | string  | URL for post-call processing (max length 255)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| message\_reference    | string  | The message\_reference string is POSTed to the URL specified by start\_url (max length 255)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| call\_parameters      | string  | The call\_parameters string is POSTed to the URL specified by start\_url (max length 255)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| max\_retry            | integer | An integer between 0 and 10 for the number of failed call attempts before giving up                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| retry\_interval       | integer | An integer from 60 to 172800 indicating the number of seconds between retries                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| scheduled\_timestamp  | integer | (Optional) 0 to start immediately or a UNIX-time integer indicating when to start attempting the call                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| expiration\_timestamp | integer | (Optional) 0 to never expire or a UNIX-time integer indicating when the outbound system should give up attempting to complete an uncompleted call                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| scheduled\_time       | string  | Alternative option to `scheduled_timestamp`. See call control settings below. (max length 80)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| expiration\_time      | string  | Alternative option to `expiration_timestamp`. See call control settings below. (max length 80)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| is\_pci               | integer | 0 or 1. For customers who have been granted access to our HIPAA-/PCI-compliant secure environment, setting this flag to 1 causes connected outbound calls to execute within that secure environment.                                                                                                                                                                                                                                                                                                                                                                                  |

{% tabs %}
{% tab title="200 " %}

```javascript
<?xml version="1.0"?>
<queuecalls status="success">
    <login>user</login>
    <pin>98765432</pin>
    <campaign_name>SunnyCamp</campaign_name>
    <start_url>http://charles.plumgroup.com/~schan/src/charles/vxml/start.php</start_url>
    <phone_list>
        <call call_id="112897970">
            <phone_number>tel:+19492222222;ani=8009957586</phone_number>
        </call>
        <call call_id="112897971">
            <phone_number>tel:+19492222223;ani=8009957586</phone_number>
        </call>
    </phone_list>
</queuecalls>
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
You must **POST** with multipart/form-data encoding in order for the `queuecalls` webservice to properly receive and process the uploaded file .‌
{% endhint %}

All settings are applied to all calls in the campaign. However, **`message_reference`** and **`call_parameters`** (see below) are set on a per-call basis and are specified in the uploaded text file with each phone number.‌

### **Required Settings** <a href="#queuecalls-required-settings-notes" id="queuecalls-required-settings-notes"></a>

Calls are listed in the phone number list file on comma-delimited lines where the first field is the phone number and the second and third fields contain a **`message_reference`** string and **`call_parameters`** string, respectively, for the call as described here. The second and third fields are optional.‌

{% hint style="info" %}
See the [Outbound API parameter notes](https://docs.plumvoice.com/dev/plum-dev-apis/outbound-api-parameter-notes#multiple-outbound-calls) for additional information on these multi-call API parameters.
{% endhint %}