API Integration Instruction:

Full featured set of APIs that allow for seamless integration with your existing or new projects. Whether you are building a mobile app to allow your customers to contact clients, adding our voice services to your existing product, our APIs enable you to get up and running quickly.

Please note – our fulfillment and support team are not able to support API integration on third party systems. Below is all the information you need to set up an API integration, but no further support or assistance from the Voice Drops team is available.

Exception: We will secure and provide for you upon request a Webhook Static Key upon request.

REST API

A description of REST

This API is built off of a token-based REST API. If you’re familiar with REST, you can move onto the next section. If you’re unfamiliar with REST, you can google it, read its Wikipedia page, or even try something like the restapitutorial. If you don’t want to do any of those though, here’s a brief explanation that should help explain how to interact with this (and any REST) API.

The first factoid in understanding REST is that it uses the native HTTP request types to determine the type of request (heh, “request types”, go figure) you’re submitting. For example, if you wanted to “get” a report, you call a GET request. Similarly, you wanted to “delete” an object, you submit a DELETE request. The available request types are GETPOSTPUTPATCH, and DELETE. There are a few others, but you won't ever need those here so I won't cover them. The second major factoid in understanding REST is that REST uses the URL to represent the object you’re attempting to access. For example, accessing something like: /api/campaigns would mean that you’re attempting to request the campaigns object of the API. If you combine that knowledge with the first factoid then you can understand the majority of how REST works.

For example, submitting a GET request to /api/campaigns (removing the domain name for brevity, it never changes so no need to keep showing it) should yield you a list of all the campaign objects. But, submitting a POST request to /api/campaigns would create a new campaign object, provided that you gave it the proper HTTP POST variables in the request. In the example, both the GET and POST request access /api/campaigns, but the API knows what to do because of the request type. This is all within the realm of the HTTP standard thus not only making it clean and efficient, but also, well, standard. To access a particular object instead of all of them, you would simply go to that individual object's url, such as a GET request to /api/campaigns/12345 would retrieve the single campaign object with the ID number of “12345”.

*************

JSON Objects

A description of the request and response objects for our API

When you make a request, the data is returned in the form of a JavaScript Object Notation (JSON) object. Most languages nowadays have JSON libraries that will take this output (as a string) and convert it to a native object for you. This convenience makes working with our API really easy. Make the request, and JSON decode the response body, and then you have a native object ready to work with. The format of the JSON objects returned will be explained in each of the output sections of each endpoint.

Most of the requests will expect data to be submitted as JSON objects as well. Any endpoint that does not expect JSON data will explicitly state it and describe what it does expect.

************

Supported Methods

The Voice Drops Developers API uses general HTTP verbs for its methods. GET, PUT, DELETE, POST are the default methods used and each endpoint will show the required method to the left of the endpoint title.

******************

Response Codes

An explanation of the response codes returned by the API endpoints

The Voice Drops Networks Developers API uses standard HTTP response codes for responses. These HTTP codes indicate whether or not an API operation is successful. Explanation of the response codes are shown in the table to the right.

Status Codes in the 2XX range are the desired response codes. They indicate a successful operation.

Codes in the 4XX range detail all of the errors a Voice Drops Networks API customer could encounter while using the API. Bad Request and Unauthorized are some of the sorts of responses in the 4XX block.

 
******************

 

Webhooks

Introduction to Webhooks

An overview of Voice Drops webhooks

We are adding the ability to interact with Voice Drops Networks via webhooks. The benefit of using a webhook is that a webhook will be authenticated using a static key rather than requesting an authorization token that expires. The negative to this is that a static key can be lost or stolen. If your key was stolen then anyone who made a webhook request using your key would be authorized as if it was you.

So why would you use a webhook rather than a regular API call? Good question! The answer is you wouldn't if you can help it, but there are certain situations where you will have no choice.

Take, for instance, an example that you are using call center software that recognizes when a recipient selects to be added to your DNC list. If you are using third party software to manage that interaction you may not have the ability to tell the software how to connect to the Voice Drops API, much less program it to request an authorization token. Lots of software, however, provides the ability to trigger a webhook on a certain event. You could, then, set your software to call the Voice Drops Webhook for adding a DNC without having to program anything in the third party software.

While certainly not for everything, and they really should be used as a second choice to the API, webhooks can provide a great way to interact with your Voice Drops account. Please take a minute to read the docs on Webhook Authorization.

 

 
 ************

Authorization

An overview of using webhook static keys

Webhooks, unlike the rest of the Voice Drops API, are authorized using a static key. The static key is generated for you by Voice Drops on request. This key does not expire and gives a webhook request automatic authorization as the key owner. This means keeping your key secret and safe is CRITICAL as anyone who gains access to your webhook key could access webhooks as you.

Keep your webhook key SECRET and SAFE

Anyone who gains access to your webhook key could access webhooks as you.

To access a Voice Drops Webhook, please contact VoiceDrops Support at www.getsupport.biz to get a Webhook Key generated for you. You will then need to include the Webhook Key in every webhook request as a request parameter called “webhook_key”. This will authenticate and authorize your user on any webhook request. Please see the specific webhook documentation for the required parameters.

 

**************

 

Add DNC

Add a number to your account DNC list via webhooks

This webhook allows you to add a number to your account DNC list. This webhook is processed as a POST request so be sure to set your caller function to send a POST request type.

Remember, you must include your static key as part of your webhook request parameters. If you do not have a static key please contact Voice Drops Support at www.getsupport.biz to have one generated for you. To learn more about the static key please read Webhooks Authorization.

Add DNC Webhook Address

 
************

 

RVM On-Demand

Execute a single RVM drop to a lead

This endpoint allows you to deliver a RVM campaign to a single lead without having to create or upload a phone list. This does require the RVM campaign to have been created previously. This webhook is processed as a POST request so be sure to set your caller function to send a POST request type.

Remember, you must include your static key as part of your webhook request parameters. If you do not have a static key please contact Voice Drops Support at www.getsupport.biz to have one generated for you. To learn more about the static key please read Webhooks Authorization (above).

 

RVM On-Demand Webhook Parameters

 
 

Lead Info

lead is a JSON object that contains the information about the lead to deliver the RVM to. A lead object will have a minimum of one field: lead_phone. How many of the other available fields you include is up to you. lead_phone is the number of the lead to deliver the RVM to and should include only digits. For example: 2552342345.

Lead Columns

lead_phone
extern_id
title
first_name
mid_name
last_name
suffix
address1
address2
city
state
zip
email
gate_keeper
aux_data1
aux_data2
aux_data3
aux_data4
aux_data5

An example of the lead JSON object may look like this:

Optional Parameters

delay is a integer of the number of seconds to delay delivering the RVM drop. If delay is not specified to be greater than 0, the RVM will be delivered at the next available opportunity.

scrub_nat_dnc is a Boolean flag to specify if you want the lead to be scrubbed against the National DNC list. All leads will automatically be scrubbed against your account DNC list.

respect_schedule is a Boolean flag to specify if the designated campaign schedule should be respected. If respect_schedule is set to True, a drop will only be executed if the campaign is already in schedule. If it is not in schedule, the lead will be loaded and queued until the campaign comes in schedule at which time the drop will be executed. If respect_schedule is set to False, the drop will be executed as soon as possible while still respecting legal timeframes. Specifically, the drop will be executed as soon as possible between the hours of 8:00am and 9:00pm local to the lead.

include_landlines is a Boolean flag to specify if the designated campaign should deliver drops to RVM compatible landlines. If it is set to True, those numbers will be included. If omitted, or set to False, they will not be included.

 

Example POST Request Data