The .href parameter adds clickable hyperlinks to text and image elements in PDF outputs. When users click on these elements in the generated PDF, they'll be redirected to the specified URL.
PDF Only Feature: Links only work in PDF format outputs. They are ignored for PNG, JPEG, and WebP formats.
When you add .href to a parameterized text or image element, Orshot:
parameterID.hrefFor multi-page templates:
pageN@parameterID.href{
"modifications": {
"cta_button.href": "https://example.com/signup"
},
"response": {
"format": "pdf"
}
}The text element cta_button becomes clickable, redirecting to the signup page.
{
"modifications": {
"logo.href": "https://company.com",
"banner.href": "https://company.com/products"
},
"response": {
"format": "pdf"
}
}Both image elements become clickable in the PDF.
Add different links to elements across pages:
{
"modifications": {
"page1@cta.href": "https://example.com/page1",
"page2@cta.href": "https://example.com/page2",
"page3@cta.href": "https://example.com/page3"
},
"response": {
"format": "pdf"
}
}You can combine .href with regular parameters and styling:
{
"modifications": {
"button": "Learn More",
"button.href": "https://example.com/learn",
"button.fontSize": "24px",
"button.color": "#0066cc",
"button.backgroundColor": "#f0f0f0"
},
"response": {
"format": "pdf"
}
}The button shows "Learn More" text, styled with custom colors and font size, and links to the specified URL.
Orshot validates URLs to ensure they're properly formatted:
✅ Valid URLs:
{
"link.href": "https://example.com",
"link.href": "http://example.com",
"link.href": "https://example.com/path/to/page",
"link.href": "https://example.com?param=value",
"link.href": "https://subdomain.example.com"
}❌ Invalid URLs (ignored):
{
"link.href": "", // Empty string
"link.href": " ", // Whitespace only
"link.href": "not-a-url", // Missing protocol
"link.href": "ftp://example.com" // Unsupported protocol
}http:// or https://If a URL fails validation:
The .href parameter only works with text and image elements:
✅ Supported:
{
"textElement.href": "https://example.com", // ✓ Text element
"imageElement.href": "https://example.com" // ✓ Image element
}❌ Not Supported:
{
"rectangle.href": "https://example.com", // ✗ Shape element - ignored
"circle.href": "https://example.com" // ✗ Shape element - ignored
}Attempting to use .href on unsupported elements will:
All href values are automatically sanitized to prevent XSS attacks:
// Dangerous characters are escaped
"<script>alert('xss')</script>" → "<script>alert('xss')</script>"Malformed URLs are caught and logged without breaking the render:
{
"link.href": "ht!tp://bad-url" // Invalid - logged and skipped
}The PDF generates successfully, but this particular link is not applied.
{
"modifications": {
"headline": "Limited Time Offer!",
"cta_text": "Shop Now",
"cta_text.href": "https://store.example.com/sale",
"cta_text.fontSize": "28px",
"cta_text.color": "#ffffff",
"cta_text.backgroundColor": "#ff6600"
},
"response": {
"format": "pdf",
"type": "url"
}
}{
"modifications": {
"product1_image.href": "https://shop.com/products/item-1",
"product1_name": "Wireless Headphones",
"product1_name.href": "https://shop.com/products/item-1",
"product2_image.href": "https://shop.com/products/item-2",
"product2_name": "Smart Watch",
"product2_name.href": "https://shop.com/products/item-2"
},
"response": {
"format": "pdf"
}
}{
"modifications": {
"page1@source1.href": "https://research.com/paper/123",
"page1@source1": "[1] Latest AI Research",
"page2@source2.href": "https://research.com/paper/456",
"page2@source2": "[2] Machine Learning Advances",
"page3@source3.href": "https://research.com/paper/789",
"page3@source3": "[3] Neural Networks Study"
},
"response": {
"format": "pdf"
}
}{
"modifications": {
"event_name": "Annual Tech Conference 2024",
"register_button": "Register Now",
"register_button.href": "https://events.com/register/tech-2024",
"register_button.fontSize": "32px",
"register_button.backgroundColor": "#0066cc",
"website_link": "Visit Website",
"website_link.href": "https://events.com",
"website_link.fontSize": "16px"
},
"response": {
"format": "pdf",
"type": "binary"
}
}curl -X POST https://api.orshot.com/v1/studio/render \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"templateId": "your-template-id",
"modifications": {
"cta_button": "Get Started",
"cta_button.href": "https://example.com/signup",
"cta_button.fontSize": "24px",
"cta_button.color": "#ffffff",
"cta_button.backgroundColor": "#0066cc"
},
"response": {
"format": "pdf",
"type": "url"
}
}'https://api.orshot.com/v1/studio/dynamic-url/product-card.pdf?
product_name=Premium%20Headphones&
product_name.href=https%3A%2F%2Fshop.com%2Fproduct%2F123&
product_name.fontSize=28px&
product_image.href=https%3A%2F%2Fshop.com%2Fproduct%2F123You can use .href together with .prompt for dynamic linked content:
{
"modifications": {
"title.prompt": "Create a call-to-action for a fitness app",
"title.href": "https://fitness-app.com/download",
"title.fontSize": "36px",
"title.color": "#00cc66"
},
"response": {
"format": "pdf"
}
}The AI generates appropriate CTA text, which then becomes clickable.
.href parameters in the Dynamic Parameters sectionhttps:// for security{
"cta.href": "https://example.com?utm_source=pdf&utm_campaign=summer"
}Issue: Generated PDF doesn't have clickable links
Solutions:
"pdf" (not "png" or "jpeg")Issue: Link redirects to unexpected URL
Solutions:
.href parametersIssue: Special characters break the link
Solutions:
// Properly encode URLs with special characters
const encodedUrl = encodeURIComponent(
"https://example.com?param=value&other=123",
);
// Use in modifications
modifications["link.href"] = decodeURIComponent(encodedUrl);