# Application 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 %}

## Overview

Plum offers eight services for its Application REST API:

| Method                  | Service                                       | Description                                                       |
| ----------------------- | --------------------------------------------- | ----------------------------------------------------------------- |
| [GET](#get-asr-value)   | [application/getASR](#get-asr-value)          | [Returns the ASR value of the given phone number](#get-asr-value) |
| [GET](#get-tts-value)   | [application/getTTS](#get-tts-value)          | [Returns the TTS value of the given phone number](#get-tts-value) |
| [GET](#get-url-value)   | [application/getURL](#get-url-value)          | [Returns the URL value of the given phone number](#get-url-value) |
| [GET](#get-asr-options) | [application/getOptionsASR](#get-asr-options) | [Returns a list of ASR options](#get-asr-options)                 |
| [GET](#get-tts-options) | [application/getOptionsTTS](#get-tts-options) | [Returns a list of TTS options](#get-tts-options)                 |
| [POST](#set-asr-value)  | [application/setASR](#set-asr-value)          | [Sets the ASR value on the given phone number](#set-asr-value)    |
| [POST](#set-tts-value)  | [application/setTTS](#set-tts-value)          | [Sets the TTS value on the given phone number](#set-tts-value)    |
| [POST](#set-url-value)  | [application/setURL](#set-url-value)          | [Sets the URL value on the given phone number](#set-url-value)    |

{% hint style="danger" %}
These API methods are designed to work with inbound phone numbers.
{% endhint %}

## **Authentication**

{% hint style="warning" %}
All API requests authenticate using HTTP Basic Authentication. Use the same username and password that you use to login to your Dev account.
{% endhint %}

Most likely, users will be able to use built-in HTTP Basic Authentication, depending on the HTTP libraries available in the programming language they opt to use.

Examples of this for each Method are listed below.

## Get ASR Value

<mark style="color:blue;">`GET`</mark> `https://hosting.vxml.sharpencx.com/ws/application/getASR/{phone_number}`

Returns ASR value currently set to phone number provided.

#### Path Parameters

| Name          | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| phone\_number | string | 10 digit phone number Ex. 3332221111 |

#### Headers

| Name   | Type   | Description                       |
| ------ | ------ | --------------------------------- |
| Accept | string | application/xml, application/json |

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

```javascript
{
    "status": "success",
    "error": "",
    "result": {
        "asr": "Nuance OSR 3.0"
    }
}
```

{% endtab %}
{% endtabs %}

**Sample Request:**

```php
<?php

$login = "<username>";
$password = "<password>";
$phone_number = "<phone number>";
$auth = $login . ":" . $password;
$url = "https://hosting.vxml.sharpencx.com/ws/application/getASR/$phone_number";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_USERPWD, $auth);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec($ch);

curl_close($ch);
?>
```

## Get TTS Value

<mark style="color:blue;">`GET`</mark> `https://hosting.vxml.sharpencx.com/ws/application/getTTS/{phone_number}`

Returns TTS value currently set to phone number provided.

#### Path Parameters

| Name          | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| phone\_number | string | 10 digit phone number Ex. 3332221111 |

#### Headers

| Name   | Type   | Description                       |
| ------ | ------ | --------------------------------- |
| Accept | string | application/xml, application/json |

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

```javascript
{
    "status": "success",
    "error": "",
    "result": {
        "tts": "AT&T Natural Voices 1.4"
    }
}
```

{% endtab %}
{% endtabs %}

**Sample Request:**

```php
<?php

$login = "<username>";
$password = "<password>";
$phone_number = "<phone number>";
$auth = $login . ":" . $password;
$url = "https://hosting.vxml.sharpencx.com/ws/application/getTTS/$phone_number";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_USERPWD, $auth);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec($ch);

curl_close($ch);
?>
```

## Get URL Value

<mark style="color:blue;">`GET`</mark> `https://hosting.vxml.sharpencx.com/ws/application/getURL/{phone_number}`

Returns URL value currently set to phone number provided.

#### Path Parameters

| Name          | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| phone\_number | string | 10 digit phone number Ex. 3332221111 |

#### Headers

| Name   | Type   | Description                       |
| ------ | ------ | --------------------------------- |
| Accept | string | application/xml, application/json |

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

```javascript
{
    "status": "success",
    "error": "",
    "result": {
        "url": "http://google.com"
    }
}
```

{% endtab %}
{% endtabs %}

**Sample Request:**

```php
<?php

$login = "<username>";
$password = "<password>";
$phone_number = "<phone number>";
$auth = $login . ":" . $password;
$url = "https://hosting.vxml.sharpencx.com/ws/application/getURL/$phone_number";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_USERPWD, $auth);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec($ch);

curl_close($ch);
?>
```

## Get ASR Options

<mark style="color:blue;">`GET`</mark> `https://hosting.vxml.sharpencx.com/ws/application/getOptionsASR`

Returns all currently available ASR options.

#### Headers

| Name   | Type   | Description                       |
| ------ | ------ | --------------------------------- |
| Accept | string | application/xml, application/json |

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

```javascript
{
    "status": "success",
    "error": "",
    "result": {
        "asr": [
            "Nuance OSR 3.0",
            "Nuance Recognizer 9",
            "Nuance Recognizer 11"
        ]
    }
}
```

{% endtab %}
{% endtabs %}

**Sample Request:**

```php
<?php

$login = "<username>";
$password = "<password>";
$auth = $login . ":" . $password;
$url = "https://hosting.vxml.sharpencx.com/ws/application/getOptionsASR";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_USERPWD, $auth);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec($ch);

curl_close($ch);
?>
```

## Get TTS Options

<mark style="color:blue;">`GET`</mark> `https://hosting.vxml.sharpencx.com/ws/application/getOptionsTTS`

Returns all currently available TTS options.

#### Headers

| Name   | Type   | Description                       |
| ------ | ------ | --------------------------------- |
| Accept | string | application/xml, application/json |

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

```javascript
{
    "status": "success",
    "error": "",
    "result": {
        "asr": [
            "Nuance RealSpeak 4.0",
            "Cepstral Swift 4.1",
            "AT&T Natural Voices 1.4",
            "Nuance Vocalizer 6.0 Alpha",
            "AWS Polly",
            "Nuance Vocalizer 7"
        ]
    }
}
```

{% endtab %}
{% endtabs %}

**Sample Request:**

```php
<?php

$login = "<username>";
$password = "<password>";
$auth = $login . ":" . $password;
$url = "https://hosting.vxml.sharpencx.com/ws/application/getOptionsTTS";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_USERPWD, $auth);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec($ch);

curl_close($ch);
?>
```

## Set ASR Value

<mark style="color:green;">`POST`</mark> `https://hosting.vxml.sharpencx.com/ws/application/setASR/{phone_number}`

Sets the ASR of the given phone number to the provided ASR value.

#### Path Parameters

| Name          | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| phone\_number | string | 10 digit phone number Ex. 3332221111 |

#### Headers

| Name         | Type   | Description                      |
| ------------ | ------ | -------------------------------- |
| Content-type | string | multipart/form-data              |
| Accept       | string | application/xml, applicaton/json |

#### Request Body

| Name | Type   | Description         |
| ---- | ------ | ------------------- |
| asr  | string | ASR value to be set |

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

```javascript
{
    "status": "success",
    "error": "",
    "result": {
        "asr": "Record updated successfully"
    }
}
```

{% endtab %}
{% endtabs %}

**Sample Request:**

```php
<?php

$username = "<login>";
$password = "<password>";
$phone_number = "<phone number>";
$value = "<ASR to be set>";
$params = array("asr"=>$value);

$auth = $username . ":" . $password;
$url = "https://hosting.vxml.sharpencx.com/ws/application/setASR/$phone_number";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_USERPWD, $auth);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-type: multipart/form-data"));
$result = curl_exec($ch);
curl_close($ch);
?>
```

## Set TTS Value

<mark style="color:green;">`POST`</mark> `https://hosting.vxml.sharpencx.com/ws/application/setTTS/{phone_number}`

Sets the TTS of the given phone number to the TTS value provided.

#### Path Parameters

| Name          | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| phone\_number | string | 10 digit phone number Ex. 3332221111 |

#### Headers

| Name         | Type   | Description                       |
| ------------ | ------ | --------------------------------- |
| Content-type | string | multipart/form-data               |
| Accept       | string | application/xml, application/json |

#### Request Body

| Name | Type   | Description         |
| ---- | ------ | ------------------- |
| tts  | string | TTS value to be set |

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

```javascript
{
    "status": "success",
    "error": "",
    "result": {
        "tts": "Record updated successfully"
    }
}
```

{% endtab %}
{% endtabs %}

**Sample Request:**

```php
<?php

$username = "<login>";
$password = "<password>";
$phone_number = "<phone number>";
$value = "<TTS to be set>";
$params = array("tts"=>$value);

$auth = $username . ":" . $password;
$url = "https://hosting.vxml.sharpencx.com/ws/application/setTTS/$phone_number";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_USERPWD, $auth);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-type: multipart/form-data"));
$result = curl_exec($ch);
curl_close($ch);
?>
```

## Set URL Value

<mark style="color:green;">`POST`</mark> `https://hosting.vxml.sharpencx.com/ws/application/setURL/{phone_number}`

Sets the URL of the given phone number to the provided URL value.

#### Path Parameters

| Name          | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| phone\_number | string | 10 digit phone number Ex. 3332221111 |

#### Headers

| Name         | Type   | Description                       |
| ------------ | ------ | --------------------------------- |
| Content-type | string | multipart/form-data               |
| Accept       | string | application/xml, application/json |

#### Request Body

| Name | Type   | Description         |
| ---- | ------ | ------------------- |
| url  | string | URL value to be set |

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

```javascript
{
    "status": "success",
    "error": "",
    "result": {
        "url": "Record updated successfully"
    }
}
```

{% endtab %}
{% endtabs %}

**Sample Request:**

```php
<?php

$username = "<login>";
$password = "<password>";
$phone_number = "<phone number>";
$value = "<URL to be set>";
$params = array("url"=>$value);

$auth = $username . ":" . $password;
$url = "https://hosting.vxml.sharpencx.com/ws/application/setURL/$phone_number";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_USERPWD, $auth);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-type: multipart/form-data"));
$result = curl_exec($ch);
curl_close($ch);
?>
```