How to use Vocal Video's Subscription API

For most use cases, integration with our Zapier API is the easiest way to go. Zapier offers a free plan for basic use cases and no coding is required. However, if you'd like to build something custom, you can access our Subscription API directly.

Note: Your subscription must include API access.

Functionally, the Subscription API is identical to our Zapier integration. Using your API keys, you can register a callback to be sent to your requested endpoint when a response is received or a video is published.

Testing Your API Key

You can find your individual API key inside the Vocal Video application by navigating to Settings -> Zapier Integration. Your API key is unique to your account and user. If you have access to multiple Vocal Video accounts, 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 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 Callback

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.

To register your callback, 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.

Replies API Definition

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.

Storyboards API Definition

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

{
  "id": 1,
  "app_url": "https://vocalvideo.com/app/prints/slug",
  "creator": {
    "id": 1,
    "name": "Jane Doe"
  },
  "description": "A new video",
  "height": 1080,
  "internal_title": "An internal title",
  "public_url": "https://vocalvideo.com/v/slug",
  "published_at": "2019-08-01T06:50:30-0500",
  "render_count": 1,
  "slug": "slug",
  "title": "Public title",
  "width": 1080,
  "video_original": {
    "url": "https://vocalvideo.com/rails/private"
  },
  "visibility": "public",
  "replies": [
    {
      "id": 1,
      "collector": {
        "id": 2,
        "nickname": "Nickname",
        "slug": "collector-slug"
      },
      "company_name": "Company",
      "created_at": "2019-08-01T06:50:30-0500",
      "custom_1": "Custom Field 1",
      "custom_2": "Custom Field 2",
      "custom_3": "Custom Field 3",
      "email": "test@email.co",
      "job_title": "CEO",
      "name": "Jane Doe",
      "url": "https://vocalvideo.com/app/token"
    }
  ]
}

Terminating Your Callback

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.