Creating a Custom Integration With Our Subscription API and Webhooks

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.

Testing your API Key

To begin, you can test your API key by sending a GET request to https://vocalvideo.com/api/v1/account with your API key:

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 should return an example payload of your last three matching responses or videos.

Registering your Webhooks

If all of the above tests are working, you're ready to move 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). Your callback url should be in a parameter named zap[url].

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 200 responses with no body.

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