Dynamic Video On Demand API¶

The Dynamic Video On Demand (VOD) API lets external platforms create personalized videos programmatically and deliver them to users by Email, SMS or WhatsApp. This guide covers authentication, template and Persovid lookups, video creation, video landing pages, and delivery.

API version

This page documents the current version of the API, v012024. Documentation for the previous version is available at Dynamic Video On Demand API (v032021).

How it works¶

Get an access token and send it with every request.
Choose what the video is based on: a raw template or a pre-configured Persovid.
Optionally choose a page template for the video's landing page and a sender to deliver it.
Create the video. You can deliver it in the same call or later.
Track the delivery status.

All endpoints use this base URL:

https://api.treepodia.com/rest/vod/v012024

In the endpoints below, replace {uuid} with your Treepodia account UUID.

Authentication¶

Every request must include a valid access token. The token confirms that the request comes from an authenticated and authorized user or system. To get a token, send your account credentials to the authentication service.

Endpoint

POST https://api.treepodia.com/rest/vod/v012024/auth
Content-Type: application/json

Request body

Field	Type	Required	Description
`email`	string	Yes	Your registered account email.
`password`	string	Yes	Your account password.
`expirationDate`	number	No	When the token should expire, as a Unix timestamp in milliseconds. If omitted, the token expires after 2 weeks. Choose the expiration according to your security requirements.

JSONcURL

{
  "email": "you@example.com",
  "password": "your-password",
  "expirationDate": 1646794257759
}

curl -X POST "https://api.treepodia.com/rest/vod/v012024/auth" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

Successful response

{
  "status": "SUCCESS",
  "accessToken": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "expirationDate": 1646794257759
}

Authorization¶

Send the access token in the Authorization header of every API request, prefixed with the word Bearer and a space:

Authorization: Bearer <your_access_token>

For example:

curl "https://api.treepodia.com/rest/vod/v012024/acc/YOUR-UUID/templates" \
  -H "Authorization: Bearer YOUR-ACCESS-TOKEN"

Keep your token secret

The access token grants full API access on your behalf. Use it only from your server, never in browser code. If your token is lost or compromised, contact support immediately to revoke it and issue a new one.

1. Templates and Persovids¶

A video is created from one of two sources:

Raw template: you send values for all of the template's parameters.
Persovid: a partially pre-configured template. Its static fields are saved in the Treepodia Web Portal, so you only send the dynamic values (for example the recipient's name).

Get available templates¶

Returns all raw video templates available to your account.

GET https://api.treepodia.com/rest/vod/v012024/acc/{uuid}/templates

Successful response

{
  "templates": [
    {
      "id": 1111111111,
      "name": "Template 1",
      "description": "Template 1 description",
      "thumbnailPath": "https://api.treepodia.com/rest/vod/v032021/acc/YOUR-UUID/templates/1111111111/thumbnail"
    }
  ]
}

Field	Description
`id`	The template ID. Use it to get the template's parameters and to create a video.
`name`	The template name.
`description`	The template description.
`thumbnailPath`	The URL of the template's thumbnail image.

Get template parameters¶

Returns a template's details and the parameters it needs.

GET https://api.treepodia.com/rest/vod/v012024/acc/{uuid}/templates/{templateId}

Successful response

{
  "template": {
    "name": "Template 1",
    "description": "Template 1 description",
    "thumbnailPath": "https://api.treepodia.com/rest/vod/v032021/acc/YOUR-UUID/templates/1111111111/thumbnail",
    "parameters": [
      {
        "id": "gender",
        "name": "Gender",
        "description": "Gender",
        "defaultValue": "Male",
        "values": ["Male", "Female"],
        "type": "select"
      },
      {
        "id": "companyName",
        "name": "Company Name",
        "description": "Company Name",
        "type": "text"
      },
      {
        "id": "companyLogo",
        "name": "Company Logo",
        "description": "Company Logo",
        "type": "image"
      }
    ]
  }
}

Parameter fields

Field	Description
`id`	The parameter ID. Use it as the key in the `parameters` object when you create a video.
`name`	The display name of the parameter.
`description`	A description of the parameter.
`type`	The type of value the parameter accepts (see below).
`defaultValue`	The value used if you don't provide one.
`values`	For `select` parameters, the list of allowed values.
`mandatory`	Whether the parameter must be provided.

Parameter types

Type	Value
`text`	A plain text string, for example a recipient name or a price.
`image`	A publicly accessible image URL.
`video`	A publicly accessible video URL.
`select`	A string that must match one of the items in the parameter's `values` array.
`date`	A string representing a date.
`time`	A string representing a time.

Get available Persovids¶

Returns the Persovids (pre-configured templates) on your account. The name matches the Persovid as it appears in the Treepodia Web Portal.

GET https://api.treepodia.com/rest/vod/v012024/acc/{uuid}/persovids

Successful response

{
  "persovids": [
    {
      "id": 14,
      "name": "Customer Birthday Template",
      "description": "Pre-filled birthday video campaign"
    },
    {
      "id": 516,
      "name": "Employee Welcome Template",
      "description": "Pre-filled onboarding campaign"
    }
  ]
}

2. Video pages and senders¶

A created video is usually hosted on a personalized web landing page. To send that page to a user, choose a page template (the page design) and a verified sender (the Email, SMS or WhatsApp channel it is sent from).

Get available page templates¶

Returns the page templates (designs) available to host videos made from a template.

GET https://api.treepodia.com/rest/vod/v012024/acc/{uuid}/templates/{templateId}/pageTemplates

Use a page template's ID as pageTemplateId when you create a video.

Get available senders¶

Returns the senders (delivery channels) configured on your account. A sender's type is EMAIL, SMS or WHATSAPP.

GET https://api.treepodia.com/rest/vod/v012024/acc/{uuid}/senders

Successful response

{
  "senders": [
    {
      "id": 2,
      "name": "Marketing Email Channel",
      "type": "EMAIL",
      "fromAddress": "no-reply@yourdomain.com"
    },
    {
      "id": 3,
      "name": "Customer Support WhatsApp",
      "type": "WHATSAPP",
      "fromNumber": "+1234567890"
    }
  ]
}

Use a sender's id as senderId when you deliver a video page.

3. Video creation¶

To create a video, send a POST request to the videos endpoint. The video can be based on a raw template or on a Persovid.

POST https://api.treepodia.com/rest/vod/v012024/acc/{uuid}/videos
Content-Type: application/json

Option A: Create from a raw template¶

Send the template ID and a value for every required template parameter.

JSONcURL

{
  "sku": "unique-sku-12345",
  "template": 1111111111,
  "temp": false,
  "parameters": {
    "birthDate": "1990-05-12",
    "companyName": "Acme Corp",
    "employeeName": "John Doe",
    "companyLogo": "https://example.com/logo.png"
  }
}

curl -X POST "https://api.treepodia.com/rest/vod/v012024/acc/YOUR-UUID/videos" \
  -H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sku": "unique-sku-12345", "template": 1111111111, "temp": false, "parameters": {"companyName": "Acme Corp", "employeeName": "John Doe"}}'

Option B: Create from a Persovid (recommended)¶

Send the persovidId instead of template. You only need to send the remaining dynamic parameters, such as the recipient's name or gender. All other parameters are taken from the Persovid definition.

JSONcURL

{
  "persovidId": 14,
  "parameters": {
    "firstName": "John",
    "employeeGender": "Male"
  }
}

curl -X POST "https://api.treepodia.com/rest/vod/v012024/acc/YOUR-UUID/videos" \
  -H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"persovidId": 14, "parameters": {"firstName": "John", "employeeGender": "Male"}}'

Request fields¶

Field	Type	Description
`template`	number	The ID of a raw template. Send either `template` or `persovidId`.
`persovidId`	number	The ID of a Persovid. Send either `template` or `persovidId`.
`parameters`	object	Parameter values, keyed by parameter `id`. For a raw template, include every required parameter. For a Persovid, include only the dynamic parameters.
`sku`	string	The SKU (identifier) of the video.
`pageTemplateId`	number	Optional. Creates a personalized video landing page with this page template.
`temp`	boolean	Optional. `true` for a short-lived temporary video, for example an editor preview. Temporary videos expire and are deleted within 24 hours. Defaults to `false` (a production video).
`deliveries`	array	Optional. Deliver the video page as soon as it is created. See Method 1.

Optional fields¶

pageTemplateId, temp and deliveries can be added to either option above.

Successful response¶

{
  "id": 5,
  "status": "SUCCESS",
  "sku": "n5j2df3snocic3rkjcikpt6ki9",
  "videoUUID": "clau5n1j8pp64b3f1begtjrijrp53h63opv68820a6t7vngdsgk",
  "pageUUID": "o542rvosj1ro9ffe1qabqvpqs8",
  "pageUrl": "https://persovid.treepodia.com/video/page?acc=YOUR-UUID&id=o542rvosj1ro9ffe1qabqvpqs8",
  "shortPageUrl": "https://persovid.treepodia.com/l/1400569cTJRSEgI"
}

Field	Description
`id`	The tracking ID of this video and delivery transaction.
`status`	The creation status, for example `SUCCESS` or `PENDING`.
`sku`	The SKU of the video.
`videoUUID`	The unique ID of the video. Pass it to the Dynamic Video Player to play the video on your own pages.
`pageUUID`	The unique ID of the landing page hosting the video. Use it to deliver the page later.
`pageUrl`	The URL of the landing page.
`shortPageUrl`	A short URL of the landing page. Use it to save characters in SMS and WhatsApp messages.

4. Delivering video pages¶

Once a video page is created, you can send it to recipients in one of two ways.

Method 1: Deliver when creating the video¶

Add a deliveries array to the video creation request. Treepodia creates the video and immediately sends the link through the senders you choose.

JSONcURL

{
  "persovidId": 14,
  "parameters": {
    "firstName": "John",
    "employeeGender": "Male"
  },
  "deliveries": [
    {
      "senderId": 2,
      "email": "recipient@example.com"
    },
    {
      "senderId": 3,
      "phone": "+1234567890"
    }
  ]
}

curl -X POST "https://api.treepodia.com/rest/vod/v012024/acc/YOUR-UUID/videos" \
  -H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"persovidId": 14, "parameters": {"firstName": "John"}, "deliveries": [{"senderId": 2, "email": "recipient@example.com"}]}'

Delivery fields

Field	Type	Required	Description
`senderId`	number	Yes	The ID of the sender, from Get available senders.
`email`	string	If the sender type is `EMAIL`	The recipient's email address.
`phone`	string	If the sender type is `SMS` or `WHATSAPP`	The recipient's phone number in international E.164 format, for example `+1234567890`.

Method 2: Deliver an existing page¶

If you already have a pageUUID from an earlier video creation call, you can send the page later with this endpoint.

POST https://api.treepodia.com/rest/vod/v012024/acc/{uuid}/senders/{senderId}/send/pages/{pageUUID}
Content-Type: application/json

Request body

Email senderSMS or WhatsApp sender

{
  "email": "recipient@example.com"
}

{
  "phone": "+1234567890"
}

Successful response

{
  "deliveryId": 9857,
  "status": "QUEUED"
}

5. Tracking delivery status¶

To check whether an email, SMS or WhatsApp message was delivered, query the delivery status endpoint with the deliveryId from the delivery response (or the transaction id from the video creation response).

GET https://api.treepodia.com/rest/vod/v012024/acc/{uuid}/deliveries/{deliveryId}

Successful response

{
  "deliveryId": 9857,
  "status": "DELIVERED",
  "channel": "WHATSAPP",
  "updatedAt": 1646794300000,
  "errorMessage": null
}

Field	Description
`deliveryId`	The delivery ID.
`status`	The delivery status, for example `QUEUED` or `DELIVERED`.
`channel`	The channel used: `EMAIL`, `SMS` or `WHATSAPP`.
`updatedAt`	When the status last changed, as a Unix timestamp in milliseconds.
`errorMessage`	A description of the problem if the delivery failed, otherwise `null`.