Personalized Video API

Legacy Feature: please note that Personalized Video is no longer available as a feature except for some Vidyard accounts with existing contracts prior to January 2022.

What is Vidyard's Personalized Video API?

Vidyard's personalized video API allows you to render and embed personalized videos.

With the help of Vidyard's Professional Services Team, the API can be used to POST personalized details (such as name, company, email address, etc) to Vidyard's API endpoint. Vidyard will then return a custom_id that can be used to render a personalized video experience to your audience through the Vidyard player.

There are two contexts in which the API can be used. These depend upon the nature of the video project, how it was produced and edited, and it's intended use.

1. Create pre-rendered personalized videos upon receipt of a callback notification.
   • The API may be used in this context for videos that have been made using our production guidelines that allow for personalized images, audio, or other editing effects that cannot be immediately rendered.
2. Render on-demand (aka. real time) personalized videos immediately upon receipt of a custom_id in the response.
   • The API may be used in this context for videos that have been produced using our on-demand personalization guidelines.

API Prerequisites

Before you begin, create a video that can be personalized with an individual or audiences' details. You'll need to work with Vidyard's Professional Services Team to set up the project and ensure your video meets our personalization guidelines.

Vidyard will then also provide you with: 

1. Vidyard's personalization API endpoint URL
   • The endpoint will be in the format of an HTML form that lists the data fields (in the form of input placeholder or id) to be passed through the API
   • This endpoint can be used to send personalization data via JSON POST-request
2. A player UUID that can be used to pull the generic version of your personalized video
   • You'll also need the UUID to generate the embed code or sharing link used to deliver your video

Supported formats

JSON

Response codes

• 200 OK Request: The data fields in the body were successfully submitted to the personalization engine
• 400 Bad Request: Body has the wrong syntax or is unable to handle request
• 404 Not Found: The requested resource could not be found
• 406 Not Acceptable: Accept or Content-Type headers must be application/json
• 422 Unprocessable Entity: Body has the wrong attributes
• 500 Internal Server Error: Required fields are missing from the body

Example request

"Accept": "application/json",
"Content-Type": "application/json"
{
 "fields": {
  //<<Examples of fields that you might use to personalize a video>>
  "companyname": "Vidyard",
  "email": "vbot@vidyard.com",
  "fullname": "Vidyard Bot"
 },
 "meta": {
    //<<Examples of additional metadata that you might want to associate with data in the fields object>>
  "player_UUID": "7rkDqvoX2xbMUQzNGCT5QA",
  "session_id": "1"
 }
}

The above data fields can be submitted to the form via POST request by adding the /submit.json to end of the form URL: https://yourendpoint.com/forms/<<form_UUID>>/submit.json

Request Parameters

Example response

{
"unit": {
  "batch_id": null,
  "camapign_uuid": "5ny6T4hqsUeTG5bYvGgrHF",
  "campaign_id": 369,
  "created_at": "2017-07-11T14:26:52.000Z",
  "id": 3804526,
  "meta": {
    "notification_email_address": "vbot@vidyard.com",
    "player_UUID": "7rkDqvoX2xbMUQzNGCT5QA",
    "session_id": "1"
  },
  "notification_url": "http://testingcallback.ca/projects/sf/api/callback.php",
  "personalized_data": {
    "companyname": "Vidyard",
    "email": "vbot@vidyard.com",
    "fullname": "Vidyard Bot"
  },
  "status": "waiting",
  "updated_at": "2017-07-11T14:26:52.000Z",
  "uuid": "fZAsCdUb9vkpqw8dFNSWDy",
  "video_id": 2113272,
  "video_status": "initialized"
  }
}

A custom_id can be found in the response as unit.uuid. The custom_id is used to generate the personalized video with an embed code or sharing page link.

Set up a callback/notification URL

The callback URL will provide you with a notification when a personalized video has finished rendering. Contact the Vidyard Professional Services Team to have a callback URL set up for your personalized video. 

Note: A callback notification is only required for projects that have been set up using our classic personalized video engine. The majority of projects will use our real-time engine and do not require a callback.

If you are unsure which version of the personalized video engine you are using, reach out to the Vidyard Professional Services Team.

{
"unit": {
  "camapign_uuid": "EY6A21r9Z8QCw35xJs44TY",
  "created_at": "2016-09-14T16:57:49.000Z",
  "meta": {
    "notification_email_address": "vbot@vidyard.com",
    "player_UUID": "7rkDqvoX2xbMUQzNGCT5QA",
    "session_id": "1"
  },
  "notification_url": "http://notification.myurl.com/notifications/video/JKDFJG638KDKFYUE83KKEK",
  "personalized_data": {
    "companyname": "Vidyard",
    "email": "vbot@vidyard.com",
    "fullname": "Vidyard Bot"
  },
  "status": "notifying",
  "updated_at": "2016-09-14T16:57:49.000Z",
  "uuid": "W6gdbD3PZC6V3XHKNvkfHw",
  "video_status": "ready"
  }
}

Create an embed code or sharing page link

Use the unit.uuid (custom_id) from the response to generate an embed code or sharing page link for your personalized video

Example embed code (v4)

<img style="max-width: 100%;"
class="vidyard-player-embed"
src="https://play.vidyard.com/{player_UUID}.jpg?custom_id={custom_id}"
data-uuid="6D1Nzj3PXVdGQoQx19ci6T"
data-v="4" data-type="inline" data-width="640" data-height="360" data-vydata=""
data-custom_id="{custom_id}"/>

Example embed code (v3)

<script type="text/javascript" id="vidyard_embed_code_${player_UUID}" src="//play.vidyard.com/${player_UUID}.js?custom_id=${custom_id}&v=3.1.1&type=inline"></script>

Example sharing page link

http://embed.vidyard.com/share/${player_UUID}?custom_id=${custom_id}

Query string parameters

See our documentation for a more comprehensive list of query string parameters.

Access personalized thumbnail

If you want to access the personalized thumbnail, append the custom_id query to the following URL: 

play.vidyard.com/{playerUUID}.jpg?custom_id={custom_id}

Query String Parameters

See our documentation for a more comprehensive list of thumbnail query string parameters.