# Queuing an Outbound Call

## Queuing an Outbound Call

<mark style="color:green;">`POST`</mark> `https://insight.plumvoice.com/api/surveys/{survey_id}/{instance_id}/queue`

Queue an outbound call for an Insight survey.

#### Path Parameters

| Name         | Type   | Description                           |
| ------------ | ------ | ------------------------------------- |
| survey\_id   | string | Insight ID number                     |
| instance\_id | string | Instance number for an Insight survey |

#### Headers

| Name         | Type   | Description                       |
| ------------ | ------ | --------------------------------- |
| content-type | string | application/x-www-form-urlencoded |

#### Request Body

| Name             | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| phone\_number    | string  | The phone number to which the outbound call should be placed. There are multiple ways to format phone numbers. They can include the 'tel:' prefix. ANI and postd suffixes are also valid, e.g. ani=1234567890 and/or postd=1234. Examples of valid numbers include: 6175551234, tel:+16175551234, tel:16175551234;ani=2125551234 (this determines the number the recipient sees), tel:16175551234;ani=2125551234;postd=2 (this determines the number the recipient sees and enters the dtmf tone “2” after the call connects). |
| start\_timestamp | string  | Unix timestamp for when to make the outbound call.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| end\_timestamp   | string  | Unix timestamp for when to stop attempting to make the outbound call                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| max\_attempts    | integer | Number of attempts to be made (if previous attempts are not completed successfully). Integer between 1-10.                                                                                                                                                                                                                                                                                                                                                                                                                     |
| reattempt\_wait  | integer | Interval (in seconds) to wait before retrying the outbound call after a failure. This is only required when you set an max\_attempts value greater than one, indicating additional retry attempts.                                                                                                                                                                                                                                                                                                                             |
| metadata         | array   | Array of key⇒value pairs of metadatabase columns and their associated values.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| result\_url      | string  | Callback URL to your REST service that processes the call status results when the call is completed, canceled, or all attempts have been exhausted. The POST body will match the format of the 'call\_details' attribute from the outbound call status API response, shown here.                                                                                                                                                                                                                                               |

{% tabs %}
{% tab title="200 Note the 'Link' header. This URI can be used to check the status of the outbound call." %}
{% tabs %}
{% tab title="JSON" %}

```javascript
//Headers

HTTP/1.1 200 OK
Date: Wed, 06 May 2015 18:19:13 GMT
Server: Apache/2.2.29 (Unix) mod_ssl/2.2.29 OpenSSL/0.9.8e-fips-rhel5 PHP/5.4.40
X-Powered-By: PHP/5.4.40
Link: https://insight.plumvoice.com/api/outbound/155761
Content-Length: 33
Content-Type: application/json

//Response body

{'success':true,'call_id':155761}
```

{% endtab %}

{% tab title="XML" %}

```markup
<!-- Headers -->

HTTP/1.1 200 OK
Date: Wed, 06 May 2015 18:24:41 GMT
Server: Apache/2.2.29 (Unix) mod_ssl/2.2.29 OpenSSL/0.9.8e-fips-rhel5 PHP/5.4.40
X-Powered-By: PHP/5.4.40
Link: https://insight.plumvoice.com/api/outbound/155761
Content-Length: 88
Content-Type: application/xml

<!-- Response body -->

<result>
  <success>true</success>
  <call_id>155761</call_id>
</result>
```

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

{% tab title="400 Example: too many attempts were supplied. " %}
{% tabs %}
{% tab title="JSON" %}

```javascript
{'success':false,'error':'attempts can only be an integer between 1 and 10.'}
```

{% endtab %}

{% tab title="XML" %}

```markup
<result>
  <success>false</success>
  <error>attempts can only be an integer between 1 and 10.</error>
</result>
```

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

### **Possible Response Codes**

* **200**: success
* **400**: supplied data improperly formatted or invalid
* **401**: authentication headers invalid or the account is inactive
* **403**: the account attempting to queue the outbound call for the survey does not have appropriate permissions
* **404**: deployment, user or survey was not found
* **405**: invalid HTTP method supplied (only POST allowed)
* **409**: survey has been marked as deleted, survey deployment has expired, no TTS engine or metadatbase set for the survey, instance\_id supplied did not match the current deployment, the number of survey responses has exceeded the max responses set in the survey's deployment settings
* **415**: unsupported media type (Content-Type value in request)
* **500**: database error

{% hint style="info" %}
**Note**: The returned 'Link' header provides the URI for checking the status of the most recent outbound call.
{% endhint %}

The return structure will contain the following item(s):

| Name     | Data Type | Always Present | Description                                                                                                                                                                                         |
| -------- | --------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| success  | boolean   | yes            | Indicates the outcome of the request                                                                                                                                                                |
| error    | string    | no             | If the success value is false this provides a message indicating what error(s) occurred                                                                                                             |
| call\_id | int       | no             | The unique identifier for the outbound call when the request is successful. This is the 'call id' value that can be used to look up the call details in the call details API method outlined below. |

### **Sample Code**

This sample PHP code makes a request to queue a new outbound call. This triggers an outbound call that goes out immediately and makes a single attempt to connect:

```php
<?php
$ch = curl_init();
$url = 'https://insight.plumvoice.com/api/surveys/{survey_id}/{instance_id}/queue';
$params = array(
	'phone_number'=>'desintation_phone_number',
	);
$username = 'you@yourdomain.com';
$password = 'your_developer_key';
curl_setopt($ch, CURLOPT_USERPWD, $username.":".$password);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-type: application/x-www-form-urlencoded"));
$result = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($result);
var_dump($http_code);
```