Authenticate

- NEW! - Interactive API docs, now live!

Visit 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.

Authenticate

POST 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

200

JSON

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"}

XML

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>

400

JSON

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

XML

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

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