Qwizoo
Try for free

Public API (v1)

Read-only REST API for pulling your quizzes, leads and analytics into your own tools. Authenticated with workspace API keys.

Updated: August 2026

Overview#

The v1 API lets you read data from your workspace: the list of quizzes with their public URLs, leads with filters and pagination, and a current-month analytics overview. It is what the official WordPress plugin uses. The API is read-only — quizzes are created and edited in the builder.

Base URL for all endpoints:

text
https://api.qwizoo.com/api

Authentication#

Every request must include an API key in the header: X-Api-Key: qwz_…

  1. 1Open Settings → API Keys in your dashboard (owner only).
  2. 2Click "Create key", give it a name and copy the key — it is shown only once.
  3. 3Store it in a secret manager. To rotate, create a new key and revoke the old one.
bash
curl https://api.qwizoo.com/api/v1/quizzes \
  -H "X-Api-Key: qwz_your_api_key_here"
💡

A workspace can have up to 10 active keys. A revoked key stops working immediately. Keys are stored hashed — if you lose one, create a new one.

Response envelope

Successful responses are wrapped in { success: true, data }. Errors use { success: false, statusCode, code, message }.

Endpoints#

GET /v1/quizzes — List quizzes

Returns all non-deleted quizzes in the workspace (published first) together with workspace plan and lead-quota usage.

json
{
  "success": true,
  "data": {
    "workspace": { "name": "Acme", "plan": "comfort", "leadsThisMonth": 42, "leadLimit": 300 },
    "quizzes": [
      {
        "id": "cmt2u9b0400a614a9svpjmm48",
        "title": "Which plan fits you?",
        "slug": "which-plan",
        "publicId": "iyXAFBVY",
        "isPublished": true,
        "embedUrl": "https://www.qwizoo.com/q/iyXAFBVY",
        "allowAdvancedEmbed": true,
        "updatedAt": "2026-08-21T11:21:14.852Z"
      }
    ]
  }
}

GET /v1/leads — List leads

Returns leads newest-first with filters and offset pagination.

Query parameters

ParameterTypeDescription
quizIdstringFilter by quiz ID (internal id from /v1/quizzes)
statusstringnew | contacted | qualified | disqualified | converted
aiScorestringhot | warm | cold (Premium lead scoring)
frozenbooleantrue | false — leads over the monthly quota
fromISO dateCreated on or after this date
toISO dateCreated on or before this date
limitnumber1–100, default 50
offsetnumberPagination offset, default 0
bash
curl "https://api.qwizoo.com/api/v1/leads?status=new&from=2026-08-01&limit=20" \
  -H "X-Api-Key: qwz_your_api_key_here"
json
{
  "success": true,
  "data": {
    "total": 3,
    "limit": 20,
    "offset": 0,
    "data": [
      {
        "id": "cmt2vlmlm00fs14a94lgjxcox",
        "name": "Maria",
        "email": "maria@example.com",
        "phone": "+380671234567",
        "status": "new",
        "aiScore": "hot",
        "frozen": false,
        "followUpStatus": "sent",
        "createdAt": "2026-08-21T11:38:27.370Z",
        "quiz": { "id": "cmt2u9b0400a614a9svpjmm48", "title": "Which plan fits you?", "publicId": "iyXAFBVY" }
      }
    ]
  }
}

GET /v1/analytics — Analytics overview

Views, completions, leads and conversion rates for the current calendar month — for the whole workspace or a single quiz.

bash
curl "https://api.qwizoo.com/api/v1/analytics?quizId=cmt2u9b0400a614a9svpjmm48" \
  -H "X-Api-Key: qwz_your_api_key_here"
json
{
  "success": true,
  "data": {
    "period": { "from": "2026-08-01T00:00:00.000Z", "to": "2026-08-21T15:00:00.000Z" },
    "views": 42,
    "completions": 3,
    "leads": 3,
    "frozenLeads": 0,
    "conversionRate": 7.14,
    "leadCaptureRate": 100
  }
}

JavaScript

js
const res = await fetch("https://api.qwizoo.com/api/v1/leads?limit=100", {
  headers: { "X-Api-Key": process.env.QWIZOO_API_KEY },
});
const { data } = await res.json();
console.log(data.total, data.data[0]?.email);

Rate limits#

Limits are per API key. Exceeding them returns 429 TOO_MANY_REQUESTS — back off and retry.

EndpointLimit
GET /v1/quizzes120 / min
GET /v1/leads60 / min
GET /v1/analytics60 / min

Error codes#

CodeMeaning
401 UNAUTHORIZEDMissing, invalid or revoked X-Api-Key
429 TOO_MANY_REQUESTSRate limit exceeded
400 BAD_REQUESTInvalid query parameter (e.g. malformed date)

Notes#

  • Frozen leads (over the monthly quota) are returned with frozen: true; their contacts are masked until you upgrade or buy a lead pack.
  • Leads older than your plan’s retention are still returned — the API reads the same data as the dashboard.
  • Need write endpoints (create lead, trigger webhook)? Use the quiz itself or Zapier/Make — and tell us at hello@qwizoo.com what you’d build.
⚠️

Never ship an API key to the browser or a public repo — it grants read access to all leads in the workspace.

Account Security