> For the complete documentation index, see [llms.txt](https://docs.plumvoice.com/voicetrends/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.plumvoice.com/voicetrends/voicetrends-api/authenticate.md).

# Authenticate

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

## Authenticate

<mark style="color:green;">`POST`</mark> `https://voicetrends.plumvoice.com/api/auth`

This service is used to perform initial account authentication. Provide your tool-specific login and password as well as the tool you are attempting to authenticate against. This API is rate-limited to 15 requests per 15-minute window.

#### Query Parameters

| Name     | Type   | Description                                                                                   |
| -------- | ------ | --------------------------------------------------------------------------------------------- |
| tool     | string | The tool you are authenticating against. Allowed values are: “dev”, “insight”, or “fuseplus”. |
| login    | string | The login credential associated with the provided tool.                                       |
| password | string | The password credential associated with the provided tool.                                    |

#### Headers

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

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

```javascript
HTTP/1.1 200 OK
X-RateLimit-Limit: 15
X-RateLimit-Remaining: 14
X-RateLimit-Reset: 1519442100
Content-Length: 90
Content-Type: application/json

{"login":"57b264aa1b794ff89d4effaafdf5e4b0","password":"25d421b1ee6c44daa2d34808e9466f5c"}
```

{% endtab %}

{% tab title="XML" %}

```markup
HTTP/1.1 200 OK
X-RateLimit-Limit: 15
X-RateLimit-Remaining: 14
X-RateLimit-Reset: 1519442100
Content-Length: 140
Content-Type: application/xml

<?xml version="1.0"?>
<result>
  <login>57b264aa1b794ff89d4effaafdf5e4b0</login>
  <password>25d421b1ee6c44daa2d34808e9466f5c</password>
</result>
```

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

{% tab title="400 " %}
{% tabs %}
{% tab title="JSON" %}

```javascript
{ "error": "Invalid tool parameter.  Allowed values: dev, fuse, insight and fuseplus." }
```

{% endtab %}

{% tab title="XML" %}

```markup
<?xml version="1.0"?>
<result>
    <error>Invalid tool parameter.  Allowed values: dev, fuse, insight and fuseplus.</error>
</result>
```

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

### **Possible Response Codes**

* **200**: Success, account successfully authenticated.
* **400**: Supplied data improperly formatted or invalid
* **401**: Authentication parameters invalid or the account is inactive
* **405**: Invalid HTTP method supplied (only POST allowed)
* **429**: Rate limit exceeded
* **500**: Unknown error

The return structure will contain the following items:

| Name     | Data Type | Always Present | Description                                                                                                                  |
| -------- | --------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| error    | string    | no             | This indicates which error occurred if the HTTP code is not 200.                                                             |
| login    | string    | no             | A 200 HTTP code returns this value, which will be used as the login for data access APIs using HTTP Basic Authentication.    |
| password | string    | no             | A 200 HTTP code returns this value, which will be used as the password for data access APIs using HTTP Basic Authentication. |

### **Sample Code**

This sample code makes a request to authenticate an account using PHP, but any language capable of integrating with a REST API works for this type of request:

```php
<?php
// account settings
$tool = '<your_desired_tool>';
$login = '<your_account_login>';
$password = '<your_account_password>';

// build the URL and POST parameters
$url = 'https://voicetrends.plumvoice.com/api/auth';
$params = array('tool'=>$tool, 'login'=>$login, 'password'=>$password);

$ch = curl_init();
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_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);
```