Creating a Custom Integration With Our Subscription API and Webhooks

For the vast majority of Vocal Video users, our point & click integrations provide all the functionality they need. But, if you want to create a custom integration, we offer a Subscription API that lets you register webhooks that will be triggered when new videos are published or new collector responses are received.

Note: to use our Subscription API, you'll need a paid Vocal Video subscription.

Getting your API Key

Each request sent to our Subscription API is authorized by an API key. You can find your API key by going to Settings > API Key. 

Your API key is unique to your user account and a Vocal Video workspace. If you have access to multiple workspaces, each one will have a different API key.

To begin, you can test your API key by sending a GET request to https://vocalvideo.com/api/v1/account using an API client such as curl or Postman, and including your API key as the api_key parameter.

curl -X GET https://vocalvideo.com/api/v1/account -d api_key=YOUR_KEY  

In response, you should receive a JSON payload confirming your account and user.

{"account":"Your Account","user":"Your Name"}  

Once you've confirmed your API key is correct, you can also test each of our endpoints. v1 of our API supports two: when a response is received and when a video is published. The URLs are:

curl -X GET https://vocalvideo.com/api/v1/replies -d api_key=YOUR_KEY  

for responses and

curl -X GET https://vocalvideo.com/api/v1/storyboards -d api_key=YOUR_KEY  

for video publication. Each request returns sample data from your account (up to the three most recent matching items), allowing you to verify that your API key and request are working correctly.

Response Webhooks

Use response webhooks for callbacks when someone submits a collector response. Include optional collector_id   to scope callbacks to one collector.

Published Video Webhooks

Use published video webhooks for callbacks when a video is published.

Payload Fields

Payloads can include optional fields such as first_name  , last_name  , transcript  , thumbnail  , width  , height  , and media URL fields. Build integrations to tolerate missing optional fields.

Registering your Webhooks

If all of the above tests are working, you're ready to move to the next step. Our subscription API works by registering endpoints for us to notify when either a response is received or a video is published -- aka "webhooks".

To register your callbacks, you will send a POST request to the  /subscribe   action of either resource (either replies   or storyboards  ). Include your callback URL in the zap[url]  parameter.

For example:

curl -X POST https://vocalvideo.com/api/v1/replies/subscribe -d api_key=YOUR_KEY -d 'zap[url]=https://yourdomain.com/some/path'  

On a successful request, you'll receive a response with a callback ID:

{"id":123}  

Your callback is now successfully registered. In the above example, whenever a new response is received, we will send a callback to  https://yourdomain.com/some/path  . Note your callback ID, as it will come in handy if you ever need to unsubscribe.

Responses API Definition

When a new video collector response is received, your callback will contain a JSON payload with the following data:

{

"id": 1,

"collector": {

"id": 1,

"nickname": "Customer Evidence",

"slug": "customer-evidence"

},

"company_name": "Doe, Co.",

"created_at": "2019-08-01T06:50:30-0500",

"custom_1": "Custom Field 1",

"custom_2": "Custom Field 2",

"custom_3": "Custom Field 3",

"email": "jane@doe.com",

"job_title": "Marketing Manager",

"name": "Jane Doe",

"release_agreed": true,

"responses": [

{

"id": 1,

"clips": [

{

"id": 1,

"format": "video"

}

],

"prompt": "Question 1"

}

],

"url": "http://vocalvideo.com/app/token"

}

Note that all date fields are in ISO8601 format.

Videos API Definition

Published videos (known as the API resource Storyboards) have the following format:

Terminating your Webhooks

You can end a callback by sending a DELETE request to the  /unsubscribe   action at any time. You must include the ID (provided during the subscription call) as a parameter named zap_id  . For example:

curl -X DELETE https://vocalvideo.com/api/v1/replies/unsubscribe -d api_key=YOUR_KEY -d zap_id=123  

On a successful request, you will receive a HTTP 200 response with no response body.

Alternatively, when we send a callback, if your endpoint returns a 410 status code, we will also unsubscribe your callback immediately.