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.
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 GET, POST, PUT, PATCH, 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”.
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.
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.
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.
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.
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.
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
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 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.
An example of the lead JSON object may look like this:
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