> 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);
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/voicetrends/voicetrends-api/authenticate.md?ask=<question>
```

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.