API Reference

API Reference

Programmatic access to your Convertly quizzes and leads.

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from your Account settings.

Authorization: Bearer cvt_live_YOUR_API_KEY

Manage your API keys from the API section in your dashboard.

Plan access

Pro
Read-only API

GET endpoints — pull quiz data and leads into your CRM, Zapier, Airtable, or BI tools.

Business
Full API (Read + Write)

All GET endpoints plus POST/PUT — create quizzes programmatically, headless quiz submission.

Rate limits

API requests are rate-limited per user, across all API keys.

Limit1,000 requests / hourResponse headerX-RateLimit-Remaining

Endpoints

GET
/api/v1/quizzes
Pro+

List all quizzes (paginated). Includes team quizzes.

curl -H "Authorization: Bearer cvt_live_YOUR_KEY" \
  "https://convertly.buzz/api/v1/quizzes?page=1&limit=20"
GET
/api/v1/quizzes/:id
Pro+

Get a single quiz with all questions, options, and score ranges.

curl -H "Authorization: Bearer cvt_live_YOUR_KEY" \
  "https://convertly.buzz/api/v1/quizzes/QUIZ_ID"
GET
/api/v1/quizzes/:id/leads
Pro+

List leads for a specific quiz (paginated).

curl -H "Authorization: Bearer cvt_live_YOUR_KEY" \
  "https://convertly.buzz/api/v1/quizzes/QUIZ_ID/leads?page=1&limit=20"
GET
/api/v1/leads/:id
Pro+

Get a single lead with score range details.

curl -H "Authorization: Bearer cvt_live_YOUR_KEY" \
  "https://convertly.buzz/api/v1/leads/LEAD_ID"
POST
/api/v1/quizzes
Business

Create a new quiz (draft). Requires Business plan.

curl -X POST \
  -H "Authorization: Bearer cvt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Quiz", "description": "Optional description", "language": "en"}' \
  "https://convertly.buzz/api/v1/quizzes"
PUT
/api/v1/quizzes/:id
Business

Update quiz metadata (title, published, webhook, etc.). Requires Business plan.

curl -X PUT \
  -H "Authorization: Bearer cvt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Title", "published": true}' \
  "https://convertly.buzz/api/v1/quizzes/QUIZ_ID"
POST
/api/v1/quizzes/:id/submit
Business

Headless quiz submission — submit answers, get score and result. Requires Business plan.

curl -X POST \
  -H "Authorization: Bearer cvt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "answers": [
      {"question_id": "q1", "option_id": "o2"},
      {"question_id": "q2", "option_id": "o5"}
    ]
  }' \
  "https://convertly.buzz/api/v1/quizzes/QUIZ_ID/submit"

Pagination

List endpoints support pagination with page and limit query parameters. Default: page=1, limit=20. Max limit: 100.

GET /api/v1/quizzes?page=2&limit=10

Responses include a pagination object:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 10,
    "total": 45,
    "total_pages": 5
  }
}
Convertly - Create Lead Generation Quizzes