Using the Vidyard Video Agent API

The Video Agent API lets you integrate Vidyard's AI-powered video generation into your systems and workflows. Instead of relying on pre-built integrations with platforms like HubSpot, Salesforce, or Marketo, the API gives you complete flexibility to trigger the personalized video creation of Vidyard campaigns from any application or custom workflow.

Get your webhook endpoint URL

To use the Video Agent API in your campaign workflow, you'll first need to add API for Video Agent to your account so that you can access your webhook endpoint URL.

1. Sign in to your Vidyard account
2. Select Admin > Integrations from the main menu
3. Select Add next to API for Video Agent
4. Copy the Webhook Endpoint URL into your notepad for future use, then select Finish

Access your API variable names

To create AI videos for your viewers, you need the correct names for each dynamic variable in your campaign scripts (eg. {{firstName}}) for use in your API calls.

You can access these variable names from any campaign by selecting the Workflow tab, choosing API for Video Agent from the dropdown menu, and selecting View.

Video Agent API call details

Below, you'll find the endpoint, inputs, and output for your Video Agent API calls.

Video Agent API endpoint

URL: The Webhook Endpoint URL you copied from the API for Video Agent integration setup

Method: POST

Content-Type: application/json

Sample input body:

"auth_token": "vidyard_api_token"
  "email": "bob@dennit.com",
  "lead_owner_email": "user@vidyard.com",
  "campaign_id": "66b37431-8f5c-4168-b58f-275a83246756025",
  "firstName": "Bob",
  "lastName": "Richardson",
  "jobTitle": "Senior Director",
  "companyName": "Dennit Textiles",
  "vy_custom_id": "optional-url-encoded-string",
  "use_stock_avatar": "true",
  "webhook_url": "https://endpoint.domain.com"

Required inputs

• Lead Details - Any data about the lead that is relevant to the personalization of the video script (eg. first name, company, other details).
  • You can also pass the entire script as a single variable (scripts limited to 1000 characters).
     
• auth_token - The admin authentication token for the Vidyard account. To get this token, follow the steps in "How to access your Vidyard API tokens."
   
• lead_owner_email - The email address you use will determine which user's avatar the workflow uses when generating a video. If they've created multiple avatars, their most recently created avatar will be used.
  • The user must have an AI Avatar seat and have created a custom avatar.
     
• campaign_id - Each Vidyard campaign you create has a different script, with different dynamic variable fields (eg. "Hello {{first.name}}, etc.) that are populated using information from your lead details. You can use different campaign IDs to customize your video's message depending on the scenario. You can find the campaign ID at the end of that campaign's URL in Vidyard.
  • Please note that updating the script for a campaign in Vidyard does not change any previously generated videos.
  • As mentioned in Lead Details above, you can optionally specify {{script}} as the entire script in the template. Using this passes a fully-formed, generated script in the JSON payload.
     
• email - The email address is required to map the video's UUID to the correct lead so the right person receives the right personalized video.

Optional inputs

• vy_custom_id - This URL-encoded string will be sent back in the callback once the video has been successfully generated.
   
• webhook_url - The endpoint URL Vidyard should POST a callback to when the video has finished generating.
   
• use_stock_avatar - This input will use the default stock avatar, rather than the avatar of the user specified in lead_owner_email. You should still enter the email address of a user with an avatar license for the lead_owner_email field.

API call output

The output of a workflow contains the campaign ID and video UUID, which can be written as custom fields in your application or posted back to a webhook URL. These IDs help retrieve relevant details about the video for use wherever necessary, such as the video thumbnail image or share URL.

The campaign ID is used to pull the personalized video and thumbnail from a campaign, so that the viewer receives content tailor-made for them.

• https://share.vidyard.com/match/campaign_id?vyemail=contact@domain.com
• https://share.vidyard.com/match/campaign_id/thumbnail?vyemail=contact@domain.com

You can also find these links under the Workflow tab of your campaign.

Depending on how or where you're sharing videos, the video UUID can also be used to pull both the video sharing link and thumbnail image.

• https://share.vidyard.com/watch/video_uuid
• https://play.vidyard.com/video_uuid.jpg?email=1

You can see an example of what an output could look like below.

{
"lead_owner_email": "user@vidyard.com",
"email": "bob@domain.com",
"campaign_id": "66b37431-8f5e-4168-b58f-275a456789086",
"approval_status": "approved",
"video_uuid": "ePGB4bQuESTP8sDPwpHng7",
"vy_custom_id": "optional-url-encoded-string",
"thumbnail_url": "https://play.vidyard.com/ePGB4bQuESTP8sDPwpHng7.jpg?email=1"
}

API Limits

There is a limit on the number of Video Agent API calls that can be processed in certain time periods.

• Per day - 25,000
• Per minute - 1,000

Video approval process (optional)

If you'd like users to approve videos before they're passed to your workflow platform, you can set up a video approval process. To enable this, you'll have to contact Vidyard Support/your CSM to have it turned on for your account.

When a video is created, the owner of the video's AI Avatar will receive the video in their personal folder and be notified by email that a video was generated on their behalf. The notification includes a link that lets the user review individual videos, delete them, or approve all videos in the queue (if multiple videos require approval).

If the user approves a video, the process is complete, and the video UUID is sent to your workflow platform. 

If the user rejects a video, it is deleted, and nothing is sent to the workflow platform.