Dynamic Video-on-Demand API

The Video-on-Demand (VOD) API enables external platforms to programmatically create personalized videos and deliver them to users via Email, SMS, or WhatsApp. This guide covers authentication, template/persovid lookups, video creation, styled page generation, and delivery orchestration.

ℹ️ Looking for the previous API version? Documentation for the legacy version (v032021) can be found here.

Authentication

To ensure security and integrity, every request must include a valid access token. This token acts as a secure key, confirming that the request is made by an authenticated and authorized user or system.

To obtain an access token, send a POST request to our Authentication Service with your account credentials.

Authentication Request Example:

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

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

Request Body Parameters:

• email (string, required): Your registered account email.
• password (string, required): Your account password.
• expirationDate (number, optional): A Unix timestamp in milliseconds indicating when the token should expire. If omitted, the token will automatically expire after 2 weeks. Adjust this based on your security requirements.

Successful Response Example:

{
   "status": "SUCCESS",
   "accessToken": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
   "expirationDate": 1646794257759
}

Authorization

To ensure secure communication with our API, each request must include proper authorization by attaching your access token to the request headers. Follow these steps to authorize your requests:

1. Obtain an access token using the Authentication Service described above.
2. Add the Authorization header to your HTTP request.
3. Prefix the access token with the word Bearer, followed by a space:

Authorization Header Format:

Authorization: Bearer <your_access_token_here>

⚠️ Important Security Reminder: Keep your access token confidential and secure. It grants full API access on your behalf. If your access token is lost or compromised, please contact support immediately to revoke the token and issue a new one.

1. Retrieving Templates & Persovids

Treepodia offers two ways to structure dynamic videos: Raw Templates (where all parameters must be sent) and Persovids (partially pre-configured templates where static fields are saved in our web portal, and only dynamic variables are provided via API).

Get Available Templates

Retrieves all raw video templates available for your account.

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

Example Response:

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

Get Template Parameters

Retrieves the dynamic parameters required by a raw template.

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

Supported Parameter Types:

Type	Format / Description
text	A plain text string (e.g., recipient names, prices).
image	A publicly accessible image URL.
video	A publicly accessible video URL.
select	A string value that must match one of the items in the values array.
date	A string representing a date.
time	A string representing a time.

Get Available Persovids

Retrieves a list of all pre-configured templates (Persovids) associated with your account. You can match the name returned here with the corresponding Persovid set up in the Treepodia Web Portal.

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

Example 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. Managing Video Pages & Senders

When you create a video, it is usually hosted on a personalized web landing page. To send this page to a user, you need to configure the **Page Template Design** and select a verified **Sender Channel** (Email, SMS, or WhatsApp).

Get Available Page Templates

Retrieves the list of available page templates/designs that can host your video.

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

Get Available Senders

Retrieves the list of configured senders (channels) available on your account to deliver video pages. Senders can be of type Email, SMS, or WhatsApp.

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

Example 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"
      }
   ]
}

3. Video-on-Demand Creation

To create a video, send a POST request. You can create the video based on a raw template or on a pre-configured Persovid.

Option A: Creation from Raw Template

Provide the template ID and define every single required template parameter.

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

{
    "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"
    }
}

Option B: Creation from Persovid (Recommended)

Provide the persovidId instead of template. You only need to pass the remaining dynamic parameters (e.g., recipient name or gender). All other static template parameters are resolved automatically from the Persovid definition.

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

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

Optional Advanced Parameters

• pageTemplateId (number, optional): Pass this attribute in the request body to generate a personalized video landing page utilizing a specific design template.
• temp (boolean, optional): Set to true if generating a short-lived temporary video (e.g., for user editor previews). Temporary videos expire and are deleted within 24 hours. Set to false (default) for production videos.

Successful Video Creation Response

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

Response Fields:

• id: The database primary tracking identifier for this video/delivery transaction.
• status: Creation execution status (e.g., SUCCESS, PENDING).
• videoUUID: The unique raw video asset identifier.
• pageUUID: The unique identifier for the landing page hosting this video.
• pageUrl / shortPageUrl: The web page destinations. Use shortPageUrl to optimize character count in SMS or WhatsApp deliveries.

4. Delivering Video Pages

Once you generate a video page, you can dispatch it to recipients. There are two supported methods:

Method 1: Direct Delivery via Video Creation (All-in-One Call)

You can combine video generation and instant distribution into a single API call by passing a deliveries array directly in the video creation request. Treepodia will render the video and immediately dispatch the link via your selected channels.

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

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

Deliveries Object Parameters:

• senderId (number, required): The ID of the channel sender (from the Senders service).
• email (string, conditional): Required if the sender’s type is EMAIL.
• phone (string, conditional): Required if the sender’s type is WHATSAPP or SMS (use standard international E.164 formats, e.g., +1234567890).

Method 2: Standalone Page Delivery (Two-Step Flow)

If you already have a pageUUID (generated from a previous video creation call), you can trigger delivery later using this separate endpoint.

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

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

Request Body for SMS/WhatsApp Sender:

{
    "phone": "+1234567890"
}

Successful Delivery Response:

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

5. Tracking Delivery Status

To check whether your email, SMS, or WhatsApp has been successfully delivered, query the delivery status endpoint using the deliveryId (or the delivery transaction id) received in the previous step.

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

Example Response:

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