Jump to section
Integrate video-enhanced eCards into your platform
Use the Livstick Client API v3 to create digital gift cards with embedded video messages. From simple email delivery to fully embedded widget experiences.
Key Concepts
Core building blocks for the eCard integration.
Container (CRID)
Each video message lives in a container identified by a unique CRID. Create one per gift card order.
API Keys
Private key for server-to-server calls (create, notify, unlock). Public key for client-side widget integration.
Widget
A JavaScript embed that lets buyers record video messages directly on your site. No redirect needed.
Environments
| Environment | Base URL | Purpose |
|---|---|---|
| Demo | https://demo-api.livstick.com | Testing & development |
| Production | https://api.livstick.com | Live environment |
Integration Scenarios
Choose the scenario that best fits your eCard platform needs.
Step-by-Step Guides
Detailed implementation guide for each scenario with code examples.
Simple
Quick email-based delivery with a single API call.
Create a container for the eCard, then trigger an email notification to the buyer with a recording link. The recipient gets the video automatically.
Create a container
Your back-end creates a new video container when the buyer completes a gift card purchase.
/v3/containers{
"sender": {
"email": "buyer@example.com",
"firstName": "Alice"
},
"receiver": {
"email": "recipient@example.com",
"firstName": "Bob"
},
"language": "en",
"metadata": {
"orderId": "ORD-12345",
"amount": "50 EUR"
}
}{
"crid": "abc123-def456",
"editKey": "ek_live_xxxxx",
"status": "created"
}Store the CRID and editKey for subsequent API calls.
Notify the buyer
Trigger an email to the buyer with a branded link to record their video message.
/v3/containers/{crid}/notify{
"type": "sender_invite",
"channel": "email"
}The buyer receives a branded email with a one-click recording link.
Automatic delivery
Once the buyer records their video, Livstick automatically delivers it to the recipient at the scheduled time via email.
Widget-Embedded
Embed the recording widget directly on your checkout page.
Embed the Livstick recording widget directly in your checkout confirmation page. The buyer records without leaving your site.
Create a container
Your back-end creates a container when the order is placed.
/v3/containers{
"sender": {
"email": "buyer@example.com",
"firstName": "Alice"
},
"receiver": {
"email": "recipient@example.com",
"firstName": "Bob"
},
"language": "en"
}{
"crid": "abc123-def456",
"editKey": "ek_live_xxxxx"
}Display the widget
On your order confirmation page, render the Livstick widget using the CRID. The buyer can record their video message inline.
See the Widget Integration section below for embed code and configuration options.
Fallback email
If the buyer doesn't record via the widget, a fallback email is sent automatically after a configurable delay.
Automatic delivery
Livstick delivers the video to the recipient at the scheduled time. No further API calls needed.
The video goes through automatic processing: storage, conversion, moderation, then delivery.
PDF Voucher
Generate a branded PDF card with QR code for physical delivery.
Generate a branded PDF voucher with a QR code that links to the video message. Perfect for printable gift cards.
Create a container
Create a container for the gift card order.
/v3/containers{
"sender": {
"email": "buyer@example.com",
"firstName": "Alice"
},
"receiver": {
"firstName": "Bob"
},
"language": "en",
"metadata": {
"amount": "50 EUR",
"brand": "Amazon"
}
}Notify buyer to record
Send the buyer a recording invitation.
/v3/containers/{crid}/notify{
"type": "sender_invite",
"channel": "email"
}Generate PDF voucher
Once the video is recorded, generate a branded PDF card with the QR code linking to the video.
/v3/containers/{crid}/cardBinary PDF file (application/pdf)The PDF includes a QR code that the recipient can scan to watch the video message.
Deliver the PDF
Attach the PDF to your own delivery email or make it downloadable from your platform.
You control the delivery: email attachment, download link, or printed insert.
Custom Delivery
Full control over the delivery flow with custom notifications.
Take complete control of the container lifecycle: create, update metadata, unlock for viewing, and trigger notifications on your schedule.
Create a container
Create a container with initial data.
/v3/containers{
"sender": {
"email": "buyer@example.com",
"firstName": "Alice"
},
"receiver": {
"email": "recipient@example.com",
"firstName": "Bob"
},
"language": "en",
"locked": true
}Set locked: true to prevent automatic delivery until you explicitly unlock it.
Update container metadata
Update the container with order details, shipping info, or any metadata at any time.
/v3/containers/{crid}{
"metadata": {
"orderId": "ORD-12345",
"shippingDate": "2026-03-15"
},
"receiver": {
"email": "updated@example.com"
}
}Unlock for delivery
When you're ready (e.g., package shipped), unlock the container to allow delivery.
/v3/containers/{crid}/unlockAfter unlocking, Livstick will deliver the video at the next scheduled time.
Trigger notification
Send the final notification to the recipient.
/v3/containers/{crid}/notify{
"type": "receiver_delivery",
"channel": "email"
}You have full control over when and how the recipient is notified.
Widget Integration
Embed the Livstick recording widget directly on your pages.
Domain-based
Widget auto-detects the account based on the domain where it's embedded. Simplest setup.
<div id="livstick-widget" data-crid="YOUR_CRID"></div>
<script src="https://widget.livstick.com/v3/embed.js"></script>API Key
Use your public API key for explicit authentication. Works on any domain.
<div id="livstick-widget"
data-crid="YOUR_CRID"
data-key="pk_live_xxxxx">
</div>
<script src="https://widget.livstick.com/v3/embed.js"></script>Pre-created Container
Pass the CRID from a container you created server-side. Most control over the flow.
<div id="livstick-widget"
data-crid="abc123-def456"
data-edit-key="ek_live_xxxxx"
data-mode="record">
</div>
<script src="https://widget.livstick.com/v3/embed.js"></script>Data Attributes
| Attribute | Required | Description |
|---|---|---|
| data-crid | Yes | Container ID to attach the recording to |
| data-key | No | Public API key (if not using domain-based auth) |
| data-edit-key | No | Edit key for pre-created containers |
| data-mode | No | "record" or "view" (default: "record") |
| data-language | No | UI language (en, fr, de, es, it, nl, pt, pl) |
| data-theme | No | "light" or "dark" (default: "light") |
JavaScript Events
Listen for widget events to react to user actions in your application.
window.addEventListener('livstick:recording-complete', (e) => {
console.log('Video recorded!', e.detail);
// Update your UI, enable next step, etc.
});| Event | Description |
|---|---|
| livstick:ready | Widget has loaded and is ready to use |
| livstick:recording-start | User started recording a video |
| livstick:recording-complete | Video recording is complete and uploaded |
| livstick:error | An error occurred during widget operation |
API Reference
Client API v3 endpoints for eCard container management.
| Method | Path | Key | Docs |
|---|---|---|---|
| POST | /v3/containers | Private | View |
| GET | /v3/containers/{crid} | Private | View |
| PATCH | /v3/containers/{crid} | Private | View |
| POST | /v3/containers/{crid}/notify | Private | View |
| POST | /v3/containers/{crid}/unlock | Private | View |
| GET | /v3/containers/{crid}/qrcode | Public | View |
| GET | /v3/containers/{crid}/card | Private | View |
| GET | /v3/containers/{crid}/url | Public | View |
| GET | /v3/containers/{crid}/redirect | Public | View |
Ready to transform your customer experiences?
Let's discuss your project and discover how LIVSTICK can help you create unforgettable moments.