Kudowall

API Reference

Complete reference for integrating with our testimonial management API. Build powerful testimonial workflows with simple HTTP requests.

RESTful API
API Key Auth
HTTPS Only

API Endpoints Overview

Quick navigation to all available endpoints

Testimonials

GET
/testimonialsList all testimonials
GET
/testimonials/:idGet testimonial by ID
POST
/testimonialsCreate testimonial
PATCH
/testimonials/:idUpdate testimonial
DELETE
/testimonials/:idDelete testimonial

Forms

GET
/formsList all forms
GET
/forms/:idGet form by ID
POST
/formsCreate form
PATCH
/forms/:idUpdate form
DELETE
/forms/:idDelete form

Widgets

GET
/widgetsList all widgets
GET
/widgets/:idGet widget by ID
POST
/widgetsCreate widget
PATCH
/widgets/:idUpdate widget
DELETE
/widgets/:idDelete widget

Tags

GET
/tagsList all tags
POST
/tagsCreate tag

Getting Started

Authentication and base configuration

Quick test: Use the cURL examples below to verify your API key works before building your integration.

Base URL

https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy

Authentication

Include your API key in the x-api-key header for all requests:

x-api-key: YOUR_API_KEY

Response Format

All API responses follow this consistent structure:

Success Response
{
  "success": true,
  "data": {
    // Response data here
  },
  "error": null
}
All endpoints require authentication. Make sure to include your API key in every request, or you'll receive a 401 Unauthorized error.

Testimonials

Manage customer testimonials and reviews

GET
/testimonials

List testimonials

Retrieve all testimonials for your workspace with optional filtering and pagination

Start with just the page and limit parameters for basic pagination. Add status filtering once you have testimonials to filter.

Essential Query Parameters
Most developers only need these

ParameterTypeRequiredDescription
pageinteger
Optional
Page number for pagination (default: 1)
limitinteger
Optional
Number of items per page (default: 50, max: 100)
statusstring
Optional
Filter by status: pending, approved, rejected

Example Request

cURL
curl -X GET \
  -H "x-api-key: YOUR_API_KEY"   "https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy/testimonials?status=approved&limit=10"

Example Response

JSON
{
  "success": true,
  "data": {
    "testimonials": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "title": "Amazing product!",
        "content": "This product has completely transformed our workflow. Highly recommended!",
        "rating": 5,
        "author_firstname": "John",
        "author_lastname": "Doe",
        "author_photo_url": "https://example.com/photo.jpg",
        "job_title": "CEO",
        "company": "Acme Corp",
        "company_logo_url": "https://example.com/logo.jpg",
        "company_website_url": "https://acme.com",
        "social_links": {
          "linkedin": "https://linkedin.com/in/johndoe",
          "twitter": "https://twitter.com/johndoe"
        },
        "testimonial_images": ["https://example.com/image1.jpg"],
        "testimonial_video": "https://example.com/video.mp4",
        "testimonial_audio": null,
        "tags": ["customer", "enterprise"],
        "status": "approved",
        "source": "direct_from_customers",
        "featured": true,
        "embed_approved": true,
        "submitted_at": "2024-01-15T10:30:00Z",
        "approved_at": "2024-01-15T11:00:00Z",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T11:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "pages": 3
    }
  }
}
GET
/testimonials/:id

Get testimonial by ID

Retrieve a specific testimonial by its ID

Example Request

cURL
curl -X GET \
  -H "x-api-key: YOUR_API_KEY"   https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy/testimonials/123e4567-e89b-12d3-a456-426614174000

Example Response

JSON
{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Amazing product!",
    "content": "This product has completely transformed our workflow.",
    "rating": 5,
    "author_firstname": "John",
    "author_lastname": "Doe",
    "job_title": "CEO",
    "company": "Acme Corp",
    "status": "approved",
    "source": "direct_from_customers",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
POST
/testimonials

Create testimonial

Add a new testimonial to your collection. Tags that don't exist will be automatically created in your workspace.

Essential Request Body Parameters
Required & commonly used

ParameterTypeRequiredDescription
titlestring
Optional
Testimonial title or headline
contentstring
Optional
Main testimonial content
author_firstnamestring
Required
Author's first name

Example Request

cURL
curl -X POST \
  -H "x-api-key: YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "title": "Game-changing solution",
    "content": "This platform has revolutionized how we collect and manage testimonials.",
    "rating": 5,
    "author_firstname": "Jane",
    "author_lastname": "Smith",
    "job_title": "Marketing Director",
    "company": "TechCorp",
    "company_website_url": "https://techcorp.com",
    "social_links": {
      "linkedin": "https://linkedin.com/in/janesmith"
    },
    "tags": ["marketing", "enterprise", "new-tag"],
    "source": "direct_from_customers",
    "featured": true,
    "embed_approved": true
  }' \
  https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy/testimonials

Example Response

JSON
{
  "success": true,
  "data": {
    "id": "456e7890-e89b-12d3-a456-426614174001",
    "title": "Game-changing solution",
    "content": "This platform has revolutionized how we collect and manage testimonials.",
    "rating": 5,
    "author_firstname": "Jane",
    "author_lastname": "Smith",
    "job_title": "Marketing Director",
    "company": "TechCorp",
    "tags": ["marketing", "enterprise", "new-tag"],
    "status": "pending",
    "featured": true,
    "embed_approved": true,
    "created_at": "2024-01-15T12:00:00Z"
  }
}
PATCH
/testimonials/:id

Update testimonial

Modify an existing testimonial. Only author firstname is required. Only provided fields will be updated. New tags will be automatically created.

Essential Request Body Parameters
Required & commonly used

ParameterTypeRequiredDescription
titlestring
Optional
Testimonial title or headline
contentstring
Optional
Main testimonial content
author_firstnamestring
Required
Author's first name

Example Request

cURL
curl -X PATCH \
  -H "x-api-key: YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "content": "This platform has completely revolutionized how we collect and manage testimonials.",
    "author_firstname": "Jane",
    "status": "approved",
    "featured": true,
    "embed_approved": true,
    "tags": ["customer", "featured", "enterprise"]
  }'   }' \
  https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy/testimonials/123e4567-e89b-12d3-a456-426614174000

Example Response

JSON
{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "content": "This platform has completely revolutionized how we collect and manage testimonials.",
    "author_firstname": "Jane",
    "status": "approved",
    "featured": true,
    "embed_approved": true,
    "tags": ["customer", "featured", "enterprise"],
    "approved_at": "2024-01-15T13:00:00Z",
    "updated_at": "2024-01-15T13:00:00Z"
  }
}
DELETE
/testimonials/:id

Delete testimonial

Permanently remove a testimonial from your workspace

Example Request

cURL
curl -X DELETE \
  -H "x-api-key: YOUR_API_KEY"   https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy/testimonials/123e4567-e89b-12d3-a456-426614174000

Example Response

JSON
{
  "success": true,
  "data": {
    "message": "Testimonial deleted successfully"
  }
}

Forms

Create and manage testimonial collection forms

GET
/forms

List forms

Get all testimonial forms for your workspace

Essential Query Parameters
Most developers only need these

ParameterTypeRequiredDescription
pageinteger
Optional
Page number for pagination
limitinteger
Optional
Number of items per page

Example Request

cURL
curl -X GET \
  -H "x-api-key: YOUR_API_KEY"   https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy/forms

Example Response

JSON
{
  "success": true,
  "data": {
    "forms": [
      {
        "id": "789e0123-e89b-12d3-a456-426614174002",
        "title": "Customer Feedback Form",
        "description": "Share your experience with our product",
        "published": true,
        "submissions": 25,
        "blocks": [
          {
            "id": "block_1",
            "type": "testimonial",
            "title": "Share Your Experience"
          }
        ],
        "settings": {
          "theme": "light",
          "show_progress_bar": true,
          "background_color": "#ffffff"
        },
        "created_at": "2024-01-10T09:00:00Z",
        "updated_at": "2024-01-15T14:00:00Z"
      }
    ]
  }
}
GET
/forms/:id

Get form by ID

Retrieve a specific form configuration

Example Request

cURL
curl -X GET \
  -H "x-api-key: YOUR_API_KEY"   https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy/forms/789e0123-e89b-12d3-a456-426614174002
POST
/forms

Create form

Create a new testimonial collection form with customizable blocks and settings

Essential Request Body Parameters
Required & commonly used

ParameterTypeRequiredDescription
titlestring
Required
Form title
blocksarray
Required
Array of form blocks (see Form Block Types section for detailed configuration)

Example Request

cURL
curl -X POST \
  -H "x-api-key: YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "title": "Customer Experience Survey",
    "description": "Help us improve by sharing your experience",
    "blocks": [
      {
        "id": "block_1",
        "type": "testimonial",
        "title": "Share Your Experience",
        "rating": {
          "enabled": true,
          "question": "Rate your experience",
          "scale": 5,
          "required": true
        },
        "testimonial_text": {
          "enabled": true,
          "question": "Tell us about your experience",
          "placeholder": "Your feedback helps us improve...",
          "required": true
        },
        "testimonial_video": {
          "enabled": true,
          "question": "Record a video testimonial (optional)",
          "max_duration": 90,
          "allow_upload": true,
          "required": false
        }
      },
      {
        "id": "block_2",
        "type": "profile_info",
        "title": "About You",
        "first_name": {
          "label": "First Name",
          "placeholder": "Enter your first name",
          "required": true,
          "visible": true
        },
        "last_name": {
          "label": "Last Name",
          "placeholder": "Enter your last name",
          "required": true,
          "visible": true
        },
        "job_title": {
          "label": "Job Title",
          "placeholder": "Your role",
          "required": true,
          "visible": true
        },
        "photo": {
          "label": "Profile Photo",
          "placeholder": "Upload your photo",
          "required": false,
          "visible": true
        }
      },
      {
        "id": "block_3",
        "type": "company_info",
        "title": "Company Information",
        "company_name": {
          "label": "Company",
          "placeholder": "Your company name",
          "required": true,
          "visible": true
        },
        "company_logo": {
          "label": "Company Logo",
          "placeholder": "Upload company logo",
          "required": false,
          "visible": true
        },
        "website_url": {
          "label": "Website",
          "placeholder": "https://yourcompany.com",
          "required": false,
          "visible": true
        }
      }
    ],
    "settings": {
      "theme": "light",
      "show_progress_bar": true,
      "navigation_arrows": true,
      "background_color": "#ffffff",
      "text_color": "#333333",
      "buttons_color": "#2563eb",
      "button_text_color": "#ffffff"
    },
    "thank_you_block": {
      "type": "thank_you",
      "title": "Thank You!",
      "message": "Your testimonial has been submitted successfully.",
      "button_text": "Visit Our Website",
      "redirect_url": "https://yourcompany.com"
    },
    "published": false
  }' \
  https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy/forms
PATCH
/forms/:id

Update form

Update an existing form configuration

Essential Request Body Parameters
Required & commonly used

ParameterTypeRequiredDescription
titlestring
Optional
Form title

Example Request

cURL
curl -X PATCH \
  -H "x-api-key: YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "published": true,
    "title": "Updated Product Review Form"
  }' \
  https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy/forms/789e0123-e89b-12d3-a456-426614174002
DELETE
/forms/:id

Delete form

Permanently delete a form and all its responses

Example Request

cURL
curl -X DELETE \
  -H "x-api-key: YOUR_API_KEY"   https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy/forms/789e0123-e89b-12d3-a456-426614174002

Widgets

Manage testimonial display widgets

GET
/widgets

List widgets

Get all widgets for your workspace

Example Request

cURL
curl -X GET \
  -H "x-api-key: YOUR_API_KEY"   https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy/widgets

Example Response

JSON
{
  "success": true,
  "data": {
    "widgets": [
      {
        "id": "abc12345-e89b-12d3-a456-426614174003",
        "name": "Homepage Reviews",
        "widget_type": "wall",
        "layout_type": "grid",
        "design_theme": "showcase",
        "published": true,
        "public_url": "xyz789",
        "embed_code": "<iframe src='https://kudowall.com/w/xyz789'></iframe>",
        "display_settings": {
          "showRating": true,
          "showAuthorName": true,
          "showCompany": true
        },
        "layout_settings": {
          "columns": 3,
          "gap": 16
        },
        "brand_settings": {
          "background_color": "#ffffff",
          "accent_color": "#000000"
        },
        "view_count": 1250,
        "click_count": 89,
        "created_at": "2024-01-12T15:30:00Z"
      }
    ]
  }
}
GET
/widgets/:id

Get widget by ID

Retrieve a specific widget configuration

Example Request

cURL
curl -X GET \
  -H "x-api-key: YOUR_API_KEY"   https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy/widgets/abc12345-e89b-12d3-a456-426614174003
POST
/widgets

Create widget

Create a new testimonial display widget

Essential Request Body Parameters
Required & commonly used

ParameterTypeRequiredDescription
namestring
Required
Widget name

Example Request

cURL
curl -X POST \
  -H "x-api-key: YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "name": "Website Testimonials",
    "widget_type": "wall",
    "layout_type": "grid",
    "display_settings": {
      "showRating": true,
      "showAuthorName": true,
      "showCompany": true,
      "showJobTitle": true
    },
    "layout_settings": {
      "columns": 3,
      "gap": 16
    },
    "brand_settings": {
      "background_color": "#ffffff",
      "accent_color": "#2563eb"
    },
    "auto_include_new": true
  }' \
  https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy/widgets
PATCH
/widgets/:id

Update widget

Update widget configuration and settings

Essential Request Body Parameters
Required & commonly used

ParameterTypeRequiredDescription
namestring
Optional
Widget name

Example Request

cURL
curl -X PATCH \
  -H "x-api-key: YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "published": true,
    "layout_settings": {
      "columns": 4
    }
  }' \
  https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy/widgets/abc12345-e89b-12d3-a456-426614174003
DELETE
/widgets/:id

Delete widget

Permanently delete a widget

Example Request

cURL
curl -X DELETE \
  -H "x-api-key: YOUR_API_KEY"   https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy/widgets/abc12345-e89b-12d3-a456-426614174003

Tags

Organize testimonials with tags

GET
/tags

List tags

Get all tags in your workspace with usage statistics

Example Request

cURL
curl -X GET \
  -H "x-api-key: YOUR_API_KEY"   https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy/tags

Example Response

JSON
{
  "success": true,
  "data": {
    "tags": [
      {
        "id": "tag_001",
        "name": "enterprise",
        "testimonial_count": 15,
        "created_at": "2024-01-10T10:00:00Z"
      },
      {
        "id": "tag_002", 
        "name": "customer-support",
        "testimonial_count": 8,
        "created_at": "2024-01-12T14:30:00Z"
      }
    ]
  }
}
POST
/tags

Create tag

Create a new tag for organizing testimonials. Note: Tags are automatically created when used in testimonial creation/updates, so this endpoint is mainly for pre-creating tags.

Essential Request Body Parameters
Required & commonly used

ParameterTypeRequiredDescription
namestring
Required
Tag name (must be unique within your workspace)

Example Request

cURL
curl -X POST \
  -H "x-api-key: YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "name": "product-feature"
  }' \
  https://ufjhlsryemazcfitzewn.supabase.co/functions/v1/api-proxy/tags

Example Response

JSON
{
  "success": true,
  "data": {
    "id": "tag_003",
    "name": "product-feature",
    "testimonial_count": 0,
    "created_at": "2024-01-15T14:00:00Z"
  }
}

Tag Management Behavior

Automatic Tag Creation

When creating or updating testimonials, any tags that don't exist in your workspace will be automatically created. This means you don't need to pre-create tags before using them.

Example: Auto-creating tags
// When you create a testimonial with new tags:
{
  "content": "Great service!",
  "tags": ["existing-tag", "brand-new-tag", "another-new-tag"]
}

// The API will:
// 1. Use "existing-tag" if it already exists
// 2. Create "brand-new-tag" in your workspace
// 3. Create "another-new-tag" in your workspace
// 4. Associate all tags with the testimonial

Workspace Isolation

Tags are scoped to your workspace. Each workspace maintains its own set of tags, so tag names only need to be unique within your workspace, not globally.

Tag Usage Statistics

The testimonial_count field shows how many testimonials are currently using each tag. This count updates automatically when testimonials are tagged or untagged.

Object Structures Reference

Detailed breakdown of complex object types used in the API endpoints above

Social Links Object

Structure for storing social media profile links in testimonials:

Social Links Structure
{
  "linkedin": "https://linkedin.com/in/username",
  "twitter": "https://twitter.com/username", 
  "facebook": "https://facebook.com/username",
  "instagram": "https://instagram.com/username",
  "youtube": "https://youtube.com/@username",
  "tiktok": "https://tiktok.com/@username"
}

Widget Settings Objects

Display Settings
Display Settings Structure
{
  "showRating": true,
  "showAuthorName": true,
  "showAuthorPhoto": true,
  "showCompany": true,
  "showJobTitle": false,
  "showDate": false,
  "showSource": false,
  "truncateText": true,
  "maxTextLength": 200
}
Layout Settings
Layout Settings Structure
{
  "columns": 3,
  "gap": 16,
  "cardStyle": "default",
  "borderRadius": 8,
  "shadowLevel": 1,
  "spacing": "comfortable"
}
Brand Settings
Brand Settings Structure
{
  "background_color": "#ffffff",
  "accent_color": "#2563eb",
  "text_color": "#1f2937",
  "border_color": "#e5e7eb",
  "font_family": "Inter",
  "custom_css": ""
}
Embed Settings
Embed Settings Structure
{
  "auto_refresh": true,
  "refresh_interval": 300,
  "filter_tags": ["featured"],
  "filter_rating": 4,
  "max_testimonials": 50,
  "sort_by": "created_at",
  "sort_order": "desc"
}

Form Settings Object

Configuration options for form behavior and appearance:

Form Settings Structure
{
  "theme": "light",
  "show_progress_bar": true,
  "navigation_arrows": true,
  "allow_navigation_back": true,
  "background_color": "#ffffff",
  "text_color": "#333333",
  "buttons_color": "#2563eb",
  "button_text_color": "#ffffff",
  "custom_css": "",
  "auto_save": true,
  "require_consent": false,
  "consent_text": "I agree to the terms and conditions"
}

Form Block Types Reference

Complete guide to configuring form blocks used in the Forms endpoints above

Overview

Forms are built using blocks. Each block represents a section of the form and can be configured with specific parameters to collect different types of information.

Testimonial Block

The main block for collecting testimonial content, ratings, and media.

ParameterTypeRequiredDescription
typestring
Required
Must be 'testimonial'
idstring
Required
Unique identifier for the block
titlestring
Optional
Block title displayed to users
rating.enabledboolean
Optional
Enable star rating input
rating.questionstring
Optional
Question text for rating
rating.scalenumber
Optional
Rating scale (1-10, default: 5)
rating.requiredboolean
Optional
Make rating required
testimonial_text.enabledboolean
Optional
Enable text testimonial input
testimonial_text.questionstring
Optional
Question text for testimonial
testimonial_text.placeholderstring
Optional
Placeholder text
testimonial_text.requiredboolean
Optional
Make testimonial text required
testimonial_text.max_lengthnumber
Optional
Maximum character limit
testimonial_video.enabledboolean
Optional
Enable video testimonial upload
testimonial_video.questionstring
Optional
Question text for video
testimonial_video.max_durationnumber
Optional
Max video duration in seconds
testimonial_video.allow_uploadboolean
Optional
Allow video file uploads
testimonial_video.requiredboolean
Optional
Make video required

Profile Info Block

Collects personal information from the testimonial author.

ParameterTypeRequiredDescription
typestring
Required
Must be 'profile_info'
idstring
Required
Unique identifier for the block
titlestring
Optional
Block title displayed to users
first_name.labelstring
Optional
Label for first name field
first_name.placeholderstring
Optional
Placeholder text
first_name.requiredboolean
Optional
Make first name required
first_name.visibleboolean
Optional
Show/hide field
last_name.labelstring
Optional
Label for last name field
last_name.placeholderstring
Optional
Placeholder text
last_name.requiredboolean
Optional
Make last name required
last_name.visibleboolean
Optional
Show/hide field
job_title.labelstring
Optional
Label for job title field
job_title.placeholderstring
Optional
Placeholder text
job_title.requiredboolean
Optional
Make job title required
job_title.visibleboolean
Optional
Show/hide field
photo.labelstring
Optional
Label for photo upload
photo.placeholderstring
Optional
Placeholder text
photo.requiredboolean
Optional
Make photo required
photo.visibleboolean
Optional
Show/hide field

Company Info Block

Collects company-related information from the testimonial author.

ParameterTypeRequiredDescription
typestring
Required
Must be 'company_info'
idstring
Required
Unique identifier for the block
titlestring
Optional
Block title displayed to users
company_name.labelstring
Optional
Label for company name field
company_name.placeholderstring
Optional
Placeholder text
company_name.requiredboolean
Optional
Make company name required
company_name.visibleboolean
Optional
Show/hide field
company_logo.labelstring
Optional
Label for logo upload
company_logo.placeholderstring
Optional
Placeholder text
company_logo.requiredboolean
Optional
Make logo required
company_logo.visibleboolean
Optional
Show/hide field
website_url.labelstring
Optional
Label for website field
website_url.placeholderstring
Optional
Placeholder text
website_url.requiredboolean
Optional
Make website required
website_url.visibleboolean
Optional
Show/hide field

Social Links Block

Collects social media profile links from the testimonial author.

ParameterTypeRequiredDescription
typestring
Required
Must be 'social_links'
idstring
Required
Unique identifier for the block
titlestring
Optional
Block title displayed to users
linkedin.labelstring
Optional
Label for LinkedIn field
linkedin.placeholderstring
Optional
Placeholder text
linkedin.requiredboolean
Optional
Make LinkedIn required
linkedin.visibleboolean
Optional
Show/hide field
twitter.labelstring
Optional
Label for Twitter/X field
twitter.placeholderstring
Optional
Placeholder text
twitter.requiredboolean
Optional
Make Twitter required
twitter.visibleboolean
Optional
Show/hide field
facebook.labelstring
Optional
Label for Facebook field
facebook.placeholderstring
Optional
Placeholder text
facebook.requiredboolean
Optional
Make Facebook required
facebook.visibleboolean
Optional
Show/hide field
instagram.labelstring
Optional
Label for Instagram field
instagram.placeholderstring
Optional
Placeholder text
instagram.requiredboolean
Optional
Make Instagram required
instagram.visibleboolean
Optional
Show/hide field
youtube.labelstring
Optional
Label for YouTube field
youtube.placeholderstring
Optional
Placeholder text
youtube.requiredboolean
Optional
Make YouTube required
youtube.visibleboolean
Optional
Show/hide field
tiktok.labelstring
Optional
Label for TikTok field
tiktok.placeholderstring
Optional
Placeholder text
tiktok.requiredboolean
Optional
Make TikTok required
tiktok.visibleboolean
Optional
Show/hide field

Additional Block Types

The following block types are available for creating more complex forms:

Statement Block

Display informational text or instructions to users.

type: "statement"
Multiple Choice Block

Allow users to select one option from multiple choices.

type: "multiple_choice"
Multi Select Block

Allow users to select multiple options from a list.

type: "multi_select"
Number Block

Collect numeric input from users.

type: "number"
Phone Number Block

Collect formatted phone numbers with country codes.

type: "phone_number"
Date Block

Allow users to select dates using a date picker.

type: "date"
File Upload Block

Enable file uploads with customizable file type restrictions.

type: "file_upload"

Error Handling

Understanding API error responses and status codes

Error Response Format

When an error occurs, the API returns a consistent error format with appropriate HTTP status codes:

Error Response
{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "rating",
      "issue": "Must be between 1 and 5"
    }
  }
}

HTTP Status Codes

Status CodeDescription
200OK - Request successful
201Created - Resource created successfully
400Bad Request - Invalid request parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server-side issue

Rate Limiting

API requests are rate limited to ensure fair usage. Default limits are:

  • • 1000 requests per hour per API key
  • • Rate limit headers are included in all responses
  • • Upgrade your plan for higher rate limits