Getting Started

The TIGER FORM API lets your server create forms, send or read submissions, download QR images, and receive webhook events. All paths live under https://api.form-qr-code-generator.com/v1. Every account has a monthly API request limit by plan (Freemium 500; Starter 10,000; Business 30,000; Professional 50,000; Enterprise — contact us or [email protected] — see Rate Limits & Retries). When the limit is reached, responses return HTTP 429.

What to read first

Pick one path by goal — you do not need every guide on day one.

Documentation map

Full index — bookmark for later. Day one: Core Concepts + one workflow guide above is enough.

Account setup

1. Register on TIGER FORM (Freemium includes a limited API quota; paid plans include higher limits — Rate Limits & Retries).
2. Copy your API key from Settings → Integration.
   
3. Optional: import public.openapi.json or postman.collection.json into Postman or your HTTP client. Before production, skim Reliability — Before Go-Live Checklist and Typical Latency (POST /forms often 1–2s).

API_KEY="<API_KEY>"

curl -sS -X GET "https://api.form-qr-code-generator.com/v1/forms?page=1&limit=5" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json"

{
  "status": "success",
  "data": {
    "total": 2,
    "page": 1,
    "pageSize": 5,
    "totalPages": 1,
    "items": [
      {
        "id": "507f1f77bcf86cd799439011",
        "qrId": "ABC123",
        "title": "Contact form",
        "shortText": "Contact us",
        "shortUrl": "https://tgr.li/ABC123",
        "scans": 120,
        "submissions": 45,
        "active": true,
        "createdAt": "2025-06-01T10:00:00.000Z",
        "updatedAt": "2025-06-15T08:30:00.000Z"
      }
    ]
  }
}

{
  "status": "failed",
  "message": "Not authorized",
  "code": 401,
  "data": {}
}

API_KEY="<API_KEY>"
QR_ID=$(curl -sS "https://api.form-qr-code-generator.com/v1/forms?page=1&limit=1" \
  -H "Authorization: Bearer ${API_KEY}" \
  | jq -r '.data.items[0].qrId')

FIELD_KEY=$(curl -sS "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/submission-schema" \
  -H "Authorization: Bearer ${API_KEY}" \
  | jq -r '.data.fields | keys[0]')

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/submissions" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: demo-abc123-001" \
  -d "$(jq -n --arg k "$FIELD_KEY" '{answers: {($k): "Jane Doe"}}')"

When a call fails

Check in this order — most issues are URL, key, or payload (not server bugs):

1. Wrong path or method → HTTP 404 (Error Model · 5-minute checklist)
2. Bad or missing API key → HTTP 401
3. Wrong qrId, role, or body → HTTP 400 / 403 (often not 404 for bad form id)
4. Quota exhausted → HTTP 429 (Rate Limits & Retries)

Pitfall list: Common Mistakes. Full step-by-step: Error Model → 5-Minute Troubleshooting Checklist. No free form slots on create → HTTP 400 — use an existing qrId from GET /forms or archive a test form in the web app.

Core Concepts

Read this once before integrating. It explains identifiers, list pagination, permissions, and error semantics used across the API.

On this page: Common Mistakes · Team Roles · Identifiers · Pagination · 400 vs 404

Common Mistakes

Base URL and responses

• Production base URL: https://api.form-qr-code-generator.com/v1 — append paths exactly as documented (/forms, /submissions/..., etc.).
• JSON success: { "status": "success", "data": ... }. JSON errors: { "status": "failed", "message", "code", "data": {} }.
• Exception: GET /forms/{qrId}/download returns a binary image on success (not JSON). See Error Model.

Identifiers

Pagination (GET /forms, GET /forms/{qrId}/submissions)

Query params: page (default 1), limit (page size; submissions default 50, max 100). Response data includes:

• items — forms for this page
• total, page, pageSize, totalPages

Optional sort on forms: 1 newest first, 2 by name, 3 by scan count. On submissions, optional since / until filter by submission createdAt (ISO 8601 or Unix timestamp).

HTTP 400 vs 404

When debugging, check the path first (404), then auth (401), then resource access (400). Full rules and upload exceptions: Error Model.

Exception — form file uploads: unknown or wrong-owner form → HTTP 404 on upload routes (not 400). See Upload APIs Compared for DELETE 400 on invalid qrId format.

Field list shape (array vs map)

GET /forms/{qrId} and create/update responses return fields as an array (each item includes key). GET /forms/{qrId}/submission-schema returns fields as an object keyed by field key — optimized for building answers. Do not assume the same JSON shape on every endpoint.

Team Roles

Most integrations use the account owner API key (full access). Team members have separate keys — permissions follow their role:

Why 403 vs 400? 403 = this role cannot do that action at all (Viewer creating a form). 400 = route exists but this user cannot modify that specific resource (Viewer updating a form).

Per-route HTTP status tables and Team API endpoints: details below · Team API · API Reference → Team tag.

Write vs read (submissions)

Use the same answers map for create, edit, validate, and read. Read responses return answers only.

Typical integration flows

1. Push a response — Create a Submission (submission-schema → optional validate → create with optional Idempotency-Key).
2. Pull submissions — Read Submissions (GET /forms/{qrId}/submissions with since / pagination, or GET /submissions/{submissionId} for one record).
3. Push submissions (webhook) — configure one URL per account — Webhooks guide (GET/PUT /account/webhook).
4. Programmatic form + QR — End-to-End Integration or Create a Form → optional qrConfig → download QR PNG. Optional layout helpers: AI Form Builder, Form Templates API.
5. Analytics — GET /forms/{qrId}/analytics with period and timezone. See Form Analytics.

End-to-End Integration

Five steps from zero to a working integration: create a form, send a response, read it back, download the QR image. Run from a terminal with bash and jq — or port the same flow to your language via SDK Examples.

API_KEY="<API_KEY>"
QR_ID=$(curl -sS "https://api.form-qr-code-generator.com/v1/forms?page=1&limit=1" \
  -H "Authorization: Bearer ${API_KEY}" \
  | jq -r '.data.items[0].qrId')
echo "Using qrId=${QR_ID}"

Step 1 — Create a Form

Captures QR_ID and FIELD_KEY for later steps. If your plan has no free form slots (HTTP 400), use the shortcut above instead.

API_KEY="<API_KEY>"

CREATE_RESP=$(curl -sS -X POST "https://api.form-qr-code-generator.com/v1/forms" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "API demo form",
    "shortText": "Demo",
    "fields": [
      { "type": "shortText", "option": { "label": "Name", "required": true } }
    ]
  }')

QR_ID=$(echo "$CREATE_RESP" | jq -r '.data.qrId')
FIELD_KEY=$(echo "$CREATE_RESP" | jq -r '.data.fields[0].key')
echo "Created qrId=${QR_ID} fieldKey=${FIELD_KEY}"

{
  "status": "success",
  "data": {
    "qrId": "ABC123",
    "title": "API demo form",
    "fields": [
      {
        "type": "shortText",
        "key": "<assigned-on-create>",
        "option": { "label": "Name", "required": true }
      }
    ]
  }
}

Field type values: Form Field Types. Prefer natural language? Draft the layout with AI Form Builder, then pass data to POST /forms.

Step 2 — Discover answer shapes (optional)

Confirms valueType and example per field. Step 3 can reuse FIELD_KEY from Step 1; use this when integrating an existing form or many field types.

curl -sS "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/submission-schema" \
  -H "Authorization: Bearer ${API_KEY}"

{
  "status": "success",
  "data": {
    "qrId": "ABC123",
    "title": "API demo form",
    "fields": {
      "<field-key>": {
        "key": "<field-key>",
        "type": "shortText",
        "label": "Name",
        "required": true,
        "valueType": "string",
        "example": "Example value"
      }
    }
  }
}

data.fields is a map keyed by field key (not an array). Refresh FIELD_KEY from schema if needed: FIELD_KEY=$(curl … submission-schema | jq -r '.data.fields | keys[0]').

Step 3 — Validate (optional) and create a submission

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/submissions/validate" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg k "$FIELD_KEY" '{answers: {($k): "Jane Doe"}}')"

CREATE_SUB_RESP=$(curl -sS -X POST "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/submissions" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-abc123-001" \
  -d "$(jq -n --arg k "$FIELD_KEY" '{answers: {($k): "Jane Doe"}}')")

SUBMISSION_ID=$(echo "$CREATE_SUB_RESP" | jq -r '.data.submissionId')
echo "submissionId=${SUBMISSION_ID}"

Retry the same create call with the same Idempotency-Key + body to verify idempotency (no duplicate). See Create a Submission.

Step 4 — Read the submission back

curl -sS "https://api.form-qr-code-generator.com/v1/submissions/${SUBMISSION_ID}" \
  -H "Authorization: Bearer ${API_KEY}"

Success includes data.answers in the same shape as create/edit. See Read Submissions.

Step 5 — Download QR PNG

curl -sS -o qr.png "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/download?format=png&resolution=500" \
  -H "Authorization: Bearer ${API_KEY}"

Optional: set qrConfig on create/update before download — Create a Form, How to Customize Your QR Code, or pick a preset from Built-in QR Design Presets.

Next

• Before production — Before Go-Live Checklist in Reliability
• Pull new responses on a schedule — GET /forms/{qrId}/submissions?since=...
• File fields — upload workflow in Upload APIs Compared
• Errors and retries — Error Model, Rate Limits & Retries

Create a Form

Minimal walkthrough for POST /forms. The server assigns a new qrId and returns the full form including fields[].key for later submissions.

Required body fields

• title, shortText — display strings
• fields — array of field definitions (each needs type and option). Do not send key on create — the server assigns stable keys in the response. See Form Field Types for all type values.

Send only the fields documented in this guide and the OpenAPI schemas — omit properties not listed there.

Minimal example (one text field)

API_KEY="<API_KEY>"

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/forms" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "title": "Contact form",
    "shortText": "Please fill out the form",
    "fields": [
      { "type": "shortText", "option": { "label": "Name", "required": false } }
    ]
  }'

Success response (excerpt)

{
  "status": "success",
  "data": {
    "qrId": "ABC123",
    "title": "Contact form",
    "fields": [
      {
        "type": "shortText",
        "key": "<assigned-on-create>",
        "option": { "label": "Name", "required": false }
      }
    ]
  }
}

Optional: qrConfig (QR appearance)

Include a top-level qrConfig object on POST /forms and PUT /forms/{qrId} to style the downloadable QR image. All properties are optional — omitted keys use product defaults. Matches schema QRConfig in the sidebar. GET /forms/{qrId} and create/update responses return qrConfig as the same object shape.

Full property list and previews: How to Customize Your QR Code, Built-in QR Design Presets, and OpenAPI schema QRConfig.

Example with qrConfig

API_KEY="<API_KEY>"

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/forms" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Contact form",
    "shortText": "Please fill out the form",
    "fields": [
      { "type": "shortText", "option": { "label": "Name", "required": true } }
    ],
    "qrConfig": {
      "colorDark": "#054080",
      "eye_outer": "eyeOuter2",
      "eye_inner": "eyeInner1",
      "qrData": "pattern0",
      "frame": 1,
      "frameText": "SCAN ME",
      "gradient": false
    }
  }'

After create, download the PNG with GET /forms/{qrId}/download?format=png&resolution=500 — see Manage Forms.

Next steps

• Customize QR appearance — qrConfig on create/update, Built-in QR Design Presets, or How to Customize Your QR Code
• Download QR image — GET /forms/{qrId}/download?format=png&resolution=500 (see End-to-End Integration Step 5)
• Collect responses — Create a Submission
• Full schema — FormCreate in API Reference → Schemas
• Draft from a prompt — AI Form Builder

Form Field Types

Public field definitions use exactly two properties: type and option. On read responses the server also returns a stable key for each field (use it in submission answers).

Supported type values

Jump to: shortText · checkbox · picture · checkList · sheet · answer shapes · schema-examples.json

Minimal field object

{
  "type": "shortText",
  "option": {
    "label": "Your name",
    "required": true,
    "hint": "Optional hint text"
  }
}

Choice fields (radio, checkbox, gender) need option.options — see API Reference schemas for radio and checkbox. Full property lists: API Reference → Schemas → Field. From a marketplace template? Use GET /form-templates/{templateId}/form-create — see Form Templates API.

Create a Submission

Push a form response from your integration server with POST /forms/{qrId}/submissions. Requires Authorization: Bearer <API_KEY> — server-to-server only; do not call from browser or mobile app code.

On this page: answers shape · Text workflow · File workflow · Success response · Common errors

Simplified payload — answers

Send a flat map of field key → simple value. File fields need only fileId after upload.

{
  "answers": {
    "<field-key>": "Jane Doe",
    "<checkbox-field-key>": ["Option 1"],
    "<file-field-key>": { "fileId": "507f1f77bcf86cd799439011" }
  }
}

Workflow — text fields

1. GET /forms/{qrId}/submission-schema — read each field key, valueType, and example.
2. POST /forms/{qrId}/submissions/validate — optional dry-run with { "answers": { ... } }.
3. POST /forms/{qrId}/submissions — same body; optional header Idempotency-Key for safe retries.

{
  "status": "success",
  "data": {
    "qrId": "ABC123",
    "title": "Contact form",
    "fields": {
      "<name-field-key>": {
        "key": "<name-field-key>",
        "type": "shortText",
        "label": "Name",
        "required": false,
        "valueType": "string",
        "example": "Example value"
      },
      "<interests-field-key>": {
        "key": "<interests-field-key>",
        "type": "checkbox",
        "label": "Interests",
        "required": false,
        "options": [{ "value": "Option 1", "name": "Option 1" }],
        "valueType": "string[]",
        "example": ["Option 1"]
      },
      "<photo-field-key>": {
        "key": "<photo-field-key>",
        "type": "picture",
        "label": "Photo",
        "required": false,
        "valueType": "fileId[]",
        "example": { "fileId": "<from POST /forms/{qrId}/uploads>" }
      }
    }
  }
}

Assumes API_KEY and QR_ID are set — see Manage Forms → cURL setup (or End-to-End Integration Step 1).

FIELD_KEY=$(curl -sS "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/submission-schema" \
  -H "Authorization: Bearer ${API_KEY}" \
  | jq -r '.data.fields | keys[0]')

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/submissions" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-abc123-001" \
  -d "$(jq -n --arg k "$FIELD_KEY" '{answers: {($k): "Jane Doe"}}')"

Workflow — file fields

1. POST /forms/{qrId}/uploads — category=submission, one request per file.
2. Copy data.fileId from the upload response into answers (server resolves fileUrl).
3. POST /forms/{qrId}/submissions with the full answers map.

Upload limits and curl: Upload APIs Compared.

Success response

All forms — HTTP 200 with the standard success envelope. Non-quiz:

{ "status": "success", "data": { "submissionId": "507f1f77bcf86cd799439011" } }

Quiz Forms add score fields in the same data object (uses points, matching quizData.points on read). Visibility depends on form quizConfig:

• When showFinalScore is false — omit points, totalMarks, percentage, and per-question points / earnedPoints.
• When showAnswersResults is false — omit correctAnswer on each quizResult item.

{
  "status": "success",
  "data": {
    "submissionId": "507f1f77bcf86cd799439011",
    "points": 80,
    "totalMarks": 100,
    "percentage": 80,
    "passed": true,
    "passingScore": 70,
    "quizResult": [ { "question": "Question 1", "correct": true, "answer": "Yes" } ]
  }
}

Quiz and validate (optional)

{
  "answers": { "<field-key>": "Yes" },
  "timeSpentSeconds": 95,
  "timeExpired": false
}

POST /forms/{qrId}/submissions/validate

Common errors

• 401 — missing or invalid API key.
• 400 — unknown qrId, wrong account, plan limit, or invalid answers (data.fieldErrors lists each field problem).
• 409 — same Idempotency-Key reused with a different JSON body.
• 429 — submission file upload rate limit (upload step only).

Related

• Read Submissions — quizData on list/get when the form is a quiz
• Webhooks — submission.quizData in push payloads
• Optional: Quiz Forms (API authoring)
• OpenAPI — POST /forms/{qrId}/submissions, schema SubmissionCreateBody

Quiz Forms (optional)

If a quiz was built in the web app, you do not need this guide — handle submissions like any other form. See Create a Submission (quiz response shape), Read Submissions (quizData), and Webhooks.

When to use the API

• Automated provisioning of assessment forms (LMS, training portals).
• Syncing quiz definitions from an external content system.

Authoring via POST /forms

Send isQuiz: true, form-level quizConfig (e.g. passingScore, showFinalScore), and question fields with option.disableQuiz: false plus per-field quizConfig (points, correctAnswers). Scored field types: radio, checkbox, shortText, number. Requires plan quiz features — HTTP 400 if a setting is not allowed.

GET /forms/{qrId} returns isQuiz and form-level quizConfig but not per-field correct answers.

Minimal create example

API_KEY="<API_KEY>"

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/forms" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Safety quiz",
    "shortText": "Answer all questions",
    "isQuiz": true,
    "quizConfig": { "passingScore": 70, "showFinalScore": true },
    "fields": [{
      "type": "radio",
      "option": {
        "label": "Question 1",
        "disableQuiz": false,
        "options": [
          { "name": "Yes", "value": "Yes", "key": 1 },
          { "name": "No", "value": "No", "key": 2 }
        ]
      },
      "quizConfig": { "points": 100, "correctAnswers": "Yes" }
    }]
  }'

Plan-gated quiz settings

On POST /forms and PUT /forms/{qrId}, the server validates quizConfig and per-field quizConfig against your plan. Disallowed settings return HTTP 400 with the standard error envelope (Error Model), for example:

{
  "status": "failed",
  "message": "Quiz time limit is not allowed on your plan",
  "code": 400,
  "data": {}
}

Exact limits depend on your active plan. Upgrade in the web app if a setting is rejected.

Related (core path)

• Create a Submission — same answers map; quiz returns points and related fields in data
• Read Submissions — quizData on each item
• OpenAPI — FormCreate, SubmissionCreateQuizData, POST /forms

Manage Submissions

Update or delete responses. To list or map payload fields, see Read Submissions. To create, see Create a Submission.

On this page: Actions table · cURL examples (list, get, update, delete, batch delete)

GET /forms/{qrId}/submissions?page=1&limit=50

curl -sS "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/submissions?page=1&limit=50&since=2025-01-01T00:00:00Z" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json"

GET /submissions/{submissionId}

SUBMISSION_ID=$(curl -sS "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/submissions?page=1&limit=1" \
  -H "Authorization: Bearer ${API_KEY}" \
  | jq -r '.data.items[0].id')

curl -sS "https://api.form-qr-code-generator.com/v1/submissions/${SUBMISSION_ID}" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json"

SUBMISSION_ID=$(curl -sS "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/submissions?page=1&limit=1" \
  -H "Authorization: Bearer ${API_KEY}" \
  | jq -r '.data.items[0].id')

FIELD_KEY=$(curl -sS "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/submission-schema" \
  -H "Authorization: Bearer ${API_KEY}" \
  | jq -r '.data.fields | keys[0]')

curl -sS -X PUT "https://api.form-qr-code-generator.com/v1/submissions/${SUBMISSION_ID}" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg k "$FIELD_KEY" '{answers: {($k): "Updated name"}}')"

SUBMISSION_ID=$(curl -sS "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/submissions?page=1&limit=1" \
  -H "Authorization: Bearer ${API_KEY}" \
  | jq -r '.data.items[0].id')

curl -sS -X DELETE "https://api.form-qr-code-generator.com/v1/submissions/${SUBMISSION_ID}" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json"

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/submissions/batch-delete" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg id "$SUBMISSION_ID" '{submissionIds: [$id]}')"

Read Submissions

Pull form responses into your system. Edit or delete: Manage Submissions. Real-time push: Webhooks.

On this page: Response examples · Map payload · Incremental pull

Response examples

{
  "status": "success",
  "data": {
    "total": 1,
    "page": 1,
    "pageSize": 50,
    "totalPages": 1,
    "items": [
      {
        "id": "507f1f77bcf86cd799439011",
        "qrId": "ABC123",
        "createdAt": "2025-06-01T10:00:00.000Z",
        "answers": {
          "<name-field-key>": "Jane Doe",
          "<interests-field-key>": ["Option 1", "Option 2"],
          "<photo-field-key>": {
            "fileId": "507f1f77bcf86cd799439011",
            "fileUrl": "https://cdn.example.com/files/abc.png"
          }
        }
      }
    ]
  },
  "form": {
    "title": "Contact form",
    "fields": [
      { "key": "<name-field-key>", "type": "shortText", "option": { "label": "Name" } },
      { "key": "<interests-field-key>", "type": "checkbox", "option": { "label": "Interests" } },
      { "key": "<photo-field-key>", "type": "picture", "option": { "label": "Photo" } }
    ]
  }
}

{
  "status": "success",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "qrId": "ABC123",
    "createdAt": "2025-06-01T10:00:00.000Z",
    "answers": {
      "<name-field-key>": "Jane Doe",
      "<interests-field-key>": ["Option 1", "Option 2"],
      "<photo-field-key>": {
        "fileId": "507f1f77bcf86cd799439011",
        "fileUrl": "https://cdn.example.com/files/abc.png"
      }
    }
  },
  "form": {
    "title": "Contact form",
    "fields": [
      { "key": "<name-field-key>", "type": "shortText", "option": { "label": "Name" } },
      { "key": "<interests-field-key>", "type": "checkbox", "option": { "label": "Interests" } },
      { "key": "<photo-field-key>", "type": "picture", "option": { "label": "Photo" } }
    ]
  }
}

{
  "id": "507f1f77bcf86cd799439011",
  "qrId": "QUIZ01",
  "answers": { "<field-key>": "Yes" },
  "quizData": {
    "points": 100,
    "totalMarks": 100,
    "percentage": 100,
    "passed": true,
    "passingScore": 70
  }
}

Map read payload → your integration

Quiz Forms also return quizData on each item — see samples in Response examples above and Quiz Forms (optional).

Incremental pull

Assumes API_KEY and QR_ID are set (see Manage Forms → cURL setup).

curl -sS "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/submissions?page=1&limit=50&since=2025-06-01T00:00:00Z" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json"

Store the latest createdAt (or submission id) in your system and pass since on the next poll. Alternatively, configure an account-level webhook — see Webhooks.

Manage Forms

Read, update, archive, clone, share, and delete forms after creation.

On this page: Goals table · cURL setup (API_KEY + QR_ID) · list · update · delete · share · download

Viewer role: cannot create (403 on POST /forms) or update (400 on writes). Role details: Core Concepts.

API_KEY="<API_KEY>"
QR_ID=$(curl -sS "https://api.form-qr-code-generator.com/v1/forms?page=1&limit=1" \
  -H "Authorization: Bearer ${API_KEY}" \
  | jq -r '.data.items[0].qrId')
echo "Using qrId=${QR_ID}"

curl -sS "https://api.form-qr-code-generator.com/v1/forms?page=1&limit=5&sort=1" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json"

{
  "status": "success",
  "data": {
    "total": 2,
    "page": 1,
    "pageSize": 5,
    "totalPages": 1,
    "items": [
      {
        "qrId": "ABC123",
        "title": "Contact form",
        "shortText": "Contact us",
        "scans": 120,
        "submissions": 45,
        "active": true,
        "createdAt": "2025-06-01T10:00:00.000Z"
      }
    ]
  }
}

curl -sS -X PUT "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"title":"Updated title","submissionNotification":false}'

OTHER_QR_ID="DEF456"
curl -sS -X DELETE "https://api.form-qr-code-generator.com/v1/forms?ids=${QR_ID}&ids=${OTHER_QR_ID}" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json"

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/share" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "recipients": "[email protected],[email protected]" }'

curl -sS -o qr.png "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/download?format=png&resolution=500" \
  -H "Authorization: Bearer ${API_KEY}"

Team API

Manage team members under your account. Role summary: Core Concepts.

Editor and Viewer accounts receive HTTP 403 on list, create, delete, and rename routes above. PUT /team/members/{memberId} also returns 403 for Editor and Viewer accounts.

API_KEY="<API_KEY>"

curl -sS "https://api.form-qr-code-generator.com/v1/team/members" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json"

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/team/members" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Integration Bot",
    "email": "[email protected]",
    "password": "SecurePass123!",
    "userType": "Editor"
  }'

curl -sS -X PATCH "https://api.form-qr-code-generator.com/v1/team" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "teamName": "Acme Integrations",
    "password": "YourAccountPassword"
  }'

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/team/members/674a…/reset-password" \
  -H "Authorization: Bearer <MEMBER_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "oldPass": "OldPass123!",
    "newPass": "NewSecurePass456!",
    "confirmPass": "NewSecurePass456!"
  }'

{
  "status": "success",
  "data": {
    "message": "Team member created.",
    "member": {
      "id": "674a…",
      "name": "Integration Bot",
      "email": "[email protected]",
      "userType": "Editor",
      "blocked": false
    }
  }
}

Account API

Account-level logo uploads for QR branding. For push notifications on new submissions, see the dedicated Webhooks guide. Not for form page assets or submission files — use Upload APIs Compared for those.

Webhook configuration (GET/PUT /account/webhook) is documented in Webhooks.

API_KEY="<API_KEY>"

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/account/uploads" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json" \
  -F "[email protected];type=image/png" \
  -F "category=logo"

curl -sS "https://api.form-qr-code-generator.com/v1/account/uploads" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json"

Webhooks

Receive a signed HTTP POST to your server whenever a new submission is created on any form owned by your account. One webhook URL per account — filter by qrId in your handler. Configure via API or the Integrations page in the web app (same place as your API key).

On this page: Setup (curl) · Signing secret · Delivery · Payload · Verify signature

API_KEY="<API_KEY>"

curl -sS -X PUT "https://api.form-qr-code-generator.com/v1/account/webhook" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "url": "https://hooks.example.com/tigerform"}'

curl -sS "https://api.form-qr-code-generator.com/v1/account/webhook" \
  -H "Authorization: Bearer ${API_KEY}"

Signing secret lifecycle

• First save — PUT with a non-empty url generates secret if none exists.
• Change URL only — secret stays the same (update your handler config only if the URL changes).
• Disable — { "enabled": false, "url": "" } clears url and secret.
• Rotate after compromise — PUT with { "enabled": true, "url": "https://…", "rotateSecret": true } (same URL is fine) to receive a new secret in the response. Update your server before relying on the new value.

Delivery

On each new submission, TIGER FORM POSTs JSON to your URL:

• Timeout: 10 seconds — respond with HTTP 2xx promptly.
• Retries: TIGER FORM does not automatically retry failed deliveries. Use polling as a backup if your endpoint was unavailable.
• Recommended pattern: Verify signatures, handle duplicates idempotently (by submissionId), and use polling (GET /forms/{qrId}/submissions?since=…) as a backup — especially after outages or if your endpoint was down.
• User-Agent: TigerForm-Webhook/1.0

Request headers

Payload (submission.created)

Schema: WebhookSubmissionCreatedEvent in the sidebar. TIGER FORM sends HTTP POST with Content-Type: application/json and the JSON body below (sign the exact raw bytes for verification).

{
  "event": "submission.created",
  "qrId": "ABC123",
  "formTitle": "Contact form",
  "submission": {
    "id": "507f1f77bcf86cd799439011",
    "createdAt": "2026-06-01T12:00:00.000Z",
    "updatedAt": "2026-06-01T12:00:00.000Z",
    "answers": {
      "<name-field-key>": "Jane Doe",
      "<interests-field-key>": ["Option 1"],
      "<photo-field-key>": { "fileId": "507f1f77bcf86cd799439012" }
    }
  }
}

{
  "event": "submission.created",
  "qrId": "QUIZ01",
  "formTitle": "Safety quiz",
  "submission": {
    "id": "507f1f77bcf86cd799439011",
    "createdAt": "2026-06-01T12:00:00.000Z",
    "updatedAt": "2026-06-01T12:00:00.000Z",
    "answers": {
      "<question-1-key>": "Yes",
      "<question-2-key>": "B"
    },
    "quizData": {
      "points": 80,
      "totalMarks": 100,
      "percentage": 80,
      "passed": true,
      "passingScore": 70,
      "quizResult": [
        { "question": "Is PPE required?", "answer": "Yes", "correct": true, "points": 50, "earnedPoints": 50, "correctAnswer": "Yes" },
        { "question": "Max speed?", "answer": "B", "correct": false, "points": 50, "earnedPoints": 0, "correctAnswer": "A" }
      ]
    }
  }
}

curl -sS -X POST "https://hooks.example.com/tigerform" \
  -H "Content-Type: application/json" \
  -H "User-Agent: TigerForm-Webhook/1.0" \
  -H "X-TigerForm-Event: submission.created" \
  -H "X-TigerForm-Delivery-Id: test-delivery-001" \
  -H "X-TigerForm-Signature: sha256=<computed-hmac-of-raw-body>" \
  -d '{
    "event": "submission.created",
    "qrId": "ABC123",
    "formTitle": "Contact form",
    "submission": {
      "id": "507f1f77bcf86cd799439011",
      "createdAt": "2026-06-01T12:00:00.000Z",
      "updatedAt": "2026-06-01T12:00:00.000Z",
      "answers": { "<name-field-key>": "Jane Doe" }
    }
  }'

const crypto = require('crypto');

function verifyTigerFormWebhook(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
  const received = signatureHeader || '';
  if (expected.length !== received.length) return false;
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

import hmac
import hashlib

def verify_tigerform_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"), raw_body, hashlib.sha256
    ).hexdigest()
    received = signature_header or ""
    if len(expected) != len(received):
        return False
    return hmac.compare_digest(expected, received)

Related

• Read Submissions — polling fallback with since; quizData on quiz forms
• Reliability — idempotency and operational notes
• OpenAPI — Account tag, GET/PUT /account/webhook, schema AccountWebhook

Form Templates API

Browse public templates in the marketplace, manage favorites, share by email, or save private templates on your account. Categories are listed under Form Template Categories. API requests create private templates only — the public gallery is managed by TIGER FORM.

Create a Form from a template

1. GET /form-templates/categories — list categories (get id for each category). Optional ?items=1 embeds up to six public templates per root category.
2. GET /form-templates?categoryId=...&limit=10 — list public templates in a category; save id from a row.
3. GET /form-templates/{templateId}/form-create — returns a POST /forms body (title, shortText, fields[]).
4. POST /forms — send the data object from step 3 (see Create a Form).

API_KEY="<API_KEY>"

curl -sS "https://api.form-qr-code-generator.com/v1/form-templates/TEMPLATE_ID/form-create" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json"

{
  "status": "success",
  "data": {
    "title": "Contact form",
    "shortText": "Get in touch",
    "fields": [
      { "type": "shortText", "option": { "label": "Name", "required": true } },
      { "type": "email", "option": { "label": "Email", "required": true } }
    ]
  }
}

Pass data to POST /forms as-is (after review). Optional fields such as qrConfig or quiz settings are included when present on the template. Cannot call form-create? See Manual convert (fallback). Use GET /form-templates/{templateId} when you need full template metadata (SEO fields, preview image, raw form object).

Other template endpoints

curl -sS "https://api.form-qr-code-generator.com/v1/form-templates/categories" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json"

{
  "status": "success",
  "data": [
    { "id": "507f1f77bcf86cd799439012", "name": "Business" }
  ]
}

curl -sS "https://api.form-qr-code-generator.com/v1/form-templates?categoryId=CATEGORY_ID&limit=10" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json"

{
  "status": "success",
  "data": [
    {
      "id": "507f1f77bcf86cd799439013",
      "title": "Contact form basic",
      "categoryName": "Business"
    }
  ]
}

curl -sS "https://api.form-qr-code-generator.com/v1/form-templates/507f1f77bcf86cd799439013" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json"

curl -sS -X PUT "https://api.form-qr-code-generator.com/v1/form-templates/507f1f77bcf86cd799439013/favorite" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json"

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/form-templates" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "categoryId": "507f1f77bcf86cd799439012",
    "title": "My reusable layout",
    "form": { "title": "Contact", "shortText": "Get in touch", "fields": { "...": { "name": "…ShortText", "option": { "label": "Name", "required": true } } } }
  }'

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/form-templates/507f1f77bcf86cd799439013/share" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "recipients": "[email protected],[email protected]" }'

{
  "form": {
    "title": "Contact form",
    "shortText": "Get in touch",
    "fields": {
      "<template-field-key-0>": {
        "name": "…ShortText",
        "option": { "label": "Name", "required": true }
      },
      "<template-field-key-1>": {
        "name": "…Email",
        "option": { "label": "Email", "required": true }
      }
    }
  }
}

{
  "title": "Contact form",
  "shortText": "Get in touch",
  "fields": [
    { "type": "shortText", "option": { "label": "Name", "required": true } },
    { "type": "email", "option": { "label": "Email", "required": true } }
  ]
}

AI Form Builder

Send a detailed prompt (minimum 10 characters). Optionally include currentForm to refine an existing draft. The response data uses the same field contract as Create a Form: title, shortText, optional locale, and fields[] where each item has type and option.

Endpoint

Workflow

1. POST /form-ai-builder/generate with { "prompt": "..." }.
2. Review data — same shape as FormCreate (title, shortText, fields with type + option).
3. Send the draft (or a subset) on Create a Form — POST /forms.
4. Quiz drafts may include isQuiz and per-field quizConfig — see Quiz Forms.

Example: generate draft

API_KEY="<API_KEY>"

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/form-ai-builder/generate" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a simple contact form with name, email, and message fields."
  }'

{
  "status": "success",
  "data": {
    "title": "Contact us",
    "shortText": "Please fill out the form below.",
    "locale": "en",
    "fields": [
      { "type": "shortText", "option": { "label": "Name", "required": true } },
      { "type": "email", "option": { "label": "Email", "required": true } },
      { "type": "longText", "option": { "label": "Message", "required": false } }
    ]
  }
}

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/form-ai-builder/generate" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Add a required phone number field and make email optional.",
    "currentForm": {
      "title": "Contact us",
      "shortText": "Please fill out the form below.",
      "fields": [
        { "type": "shortText", "option": { "label": "Name", "required": true } },
        { "type": "email", "option": { "label": "Email", "required": true } }
      ]
    }
  }'

Errors

• 401 — missing or invalid API key.
• 400 — missing prompt, prompt shorter than 10 characters, or invalid AI response.
• 429 — monthly API quota exhausted (same message as other v1 routes). See Rate Limits & Retries.
• 500 — AI service or server error after a valid request.

currentForm accepts the same draft shape as the response (title, shortText, fields) — not a live form with qrId or qrConfig.

Authentication

Every v1 request needs Authorization: Bearer <API_KEY>. Copy the key from Settings → Integration (owner account) or from a team member's account settings.

Test your key

HTTP 200 with status: success means the key works. HTTP 401 = wrong or missing key. HTTP 429 = monthly API request limit reached (including Freemium's 500 requests). Inactive or expired paid subscription (not downgraded to Freemium) → most operations return 400 until renewal.

API_KEY="<API_KEY>"

curl -sS "https://api.form-qr-code-generator.com/v1/forms?page=1&limit=1" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json"

Rules

1. Account owner — one key with full access (forms, webhook, team if plan allows).
2. Team members — separate key per member; permissions follow role — see Core Concepts. To test Viewer/Editor restrictions, use that member's key, not the owner key.
3. Do not share keys or embed them in client-side code. No self-service revoke — contact support to reset a compromised key.

Key rotation. API keys are long-lived until support resets them. Plan integrations to store keys in secrets management and rotate by requesting a new key from support, updating your servers, then confirming the old key is disabled — not by calling a documented v1 endpoint.

Security tips

1. Never commit API keys to public repositories.
2. Contact support to request a key reset if you suspect compromise.
3. Use HTTPS only. All production requests must use TLS.

Versioning (API v1)

• This site documents API v1. All paths are relative to https://api.form-qr-code-generator.com/v1.
• OpenAPI info.version is 1.0.0 — the first public release (2026-06-15).
• Undocumented routes (for example those used only by the TIGER FORM web app) are not supported and may change without notice.
• Breaking changes to documented behavior are announced in the release history below (and mirrored in CHANGELOG.md) at least 90 days before removal, except urgent security fixes.
• There is no separate sandbox environment. Use a dedicated test account and test forms on the production server with non-production data.

Release history

[1.0.0] — 2026-06-15

Initial public release of the TIGER FORM HTTP API v1, OpenAPI specification, and integrator documentation. Includes forms, submissions (answers map), uploads, webhooks, analytics, quiz forms, team API, and optional templates/AI endpoints. See CHANGELOG.md for the full list.

You do not need to download a file to check release notes — read this section or CHANGELOG.md for automation and bookmarks.

Rate Limits & Retries

Documented limits

• Plan API quota — each request to a documented endpoint counts against your account's monthly API request limit. This includes read/list calls and POST /forms/{qrId}/submissions/validate (validate does not create a submission but still consumes quota). When the limit is reached, responses return HTTP 429 with message Sorry, your API request limit has been reached. The limit resets each month. (Enforced server-side as monthly apiLimit.)
• Submission file uploads — POST /forms/{qrId}/uploads with category=submission is limited to 200 requests per 5 minutes per client IP and qrId. Excess requests return HTTP 429.
• Other documented routes do not publish separate per-endpoint quotas; use reasonable request rates and implement backoff on HTTP 429 when returned.

Typical monthly API request limits (reference)

Exact limit depends on your active plan. Values below are the standard limits per tier — confirm in your account dashboard or with support if unsure. Enforced server-side as monthly apiLimit on your account.

Every documented endpoint counts once per request, including GET list/read and POST .../submissions/validate.

HTTP 429 examples

Plan API quota (any v1 route when your monthly API request limit is exhausted):

{
  "status": "failed",
  "message": "Sorry, your API request limit has been reached",
  "code": 429,
  "data": {}
}

Submission file uploads (POST /forms/{qrId}/uploads, category=submission, over 200 requests per 5 minutes per IP + qrId):

{
  "status": "failed",
  "message": "Too many requests. Please try again later.",
  "code": 429,
  "data": {}
}

Retry guidance

• On 429 or transient 5xx, retry with exponential backoff (e.g. 1s, 2s, 4s). Respect Retry-After when present.
• Do not retry 400, 401, 403, or 409 without fixing the request.
• For create/update calls, use the Idempotency-Key header on submission create — see Create a Submission and Reliability.

Error Model

5-minute troubleshooting checklist

Run through this before opening a support ticket or rewriting integration code.

1. Confirm the URL — base https://api.form-qr-code-generator.com/v1 + documented path (no trailing slash). Wrong path → 404, not a JSON business error.
2. Confirm the key — Authorization: Bearer <API_KEY> from Settings → Integration (owner key unless testing team roles). Missing/invalid → 401.
3. Confirm the form id — qrId from GET /forms or create response, uppercase alphanumerics. Wrong id on a valid route → usually 400, not 404.
4. Confirm submission keys — field map keys from GET /forms/{qrId}/submission-schema, not doc examples. Wrong keys → 400 with fieldErrors below.
5. Confirm plan quota — monthly API request limit exhausted → 429 on v1 calls. Freemium accounts have a lower limit (500 requests per month). Inactive or expired paid subscription (not downgraded to Freemium) → most operations return 400 until renewal.
6. Confirm role — Viewer cannot create forms (403 on POST /forms); Editor/Viewer cannot manage webhooks or team (403). See Core Concepts → Team Roles.
7. Log one failing request — method, path, HTTP status, JSON code + message (never paste the API key). Full checklist: 5-Minute Troubleshooting Checklist below; quick version on Getting Started → When a call fails.

All documented JSON API errors use the same envelope. Binary routes (for example GET /forms/{qrId}/download) return raw file bytes on success, not JSON.

{
  "status": "failed",
  "message": "Human-readable error text",
  "code": 400,
  "data": {}
}

Common status codes

• 400: Validation or business-rule error (for example invalid input, unknown `qrId` on a valid route).
• 401: Missing/invalid API key in Authorization: Bearer ....
• 403: Authenticated but not allowed (for example viewer-role restrictions).
• 404: Route/method does not exist in this documented API.
• 409: Idempotency-Key reused with a different request body on POST /forms/{qrId}/submissions.
• 429: Rate limit — monthly API quota (Rate Limits & Retries) or submission upload throttling; see guide for two different messages.
• 500: Unexpected server error on a documented route.

Plan and API quota errors

Two checks apply on each API request. The monthly API quota is evaluated first. Subscription and feature limits (form slots, quiz settings, submission capacity) return HTTP 400 only after the quota gate passes. Expired or cancelled paid plans are not downgraded to Freemium — with an inactive subscription, most operations return 400 until renewal.

Exact wording may vary by account locale. These are not retryable without upgrading or renewing the plan. Do not treat them as transient 5xx errors. See also Rate Limits & Retries.

Submission validation (fieldErrors)

On public v1, invalid submission payloads on POST /forms/{qrId}/submissions, PUT /submissions/{submissionId}, and POST /forms/{qrId}/submissions/validate return HTTP 400 with structured field errors. Keys in fieldErrors match field key values; request-level errors use the key _form.

{
  "status": "failed",
  "message": "Submission validation failed.",
  "code": 400,
  "data": {
    "valid": false,
    "fieldErrors": {
      "<field-key>": {
        "code": "invalid_option",
        "message": "Value \"foo\" is not a valid option for this field.",
        "type": "checkbox"
      }
    }
  }
}

Common code values:

• unknown_field — property key not in the form schema
• invalid_shape — answer value has the wrong shape for the field (string vs array, etc.)
• component_mismatch — answer value is incompatible with the field type (same meaning as a type mismatch)
• required — required field missing or empty
• invalid_option — checkbox/radio value not in form options
• missing_file_ref — file field without a valid fileId
• file_not_found — fileId not found or not owned by this form/account
• missing_entry — required answer missing for a field
• invalid_body — top-level request body is invalid
• invalid_email — malformed email on type: "email" fields

Use POST /forms/{qrId}/submissions/validate to test payloads without creating a submission. Each validate call still counts toward your monthly API quota (Rate Limits & Retries).

SDK Examples

List forms — JavaScript (Node 18+)

const apiKey = process.env.TIGER_FORM_API_KEY;
const res = await fetch("https://api.form-qr-code-generator.com/v1/forms?page=1&limit=5", {
  headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" }
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.message}`);
console.log(body.data);

Python

import os, requests
api_key = os.environ["TIGER_FORM_API_KEY"]
resp = requests.get(
    "https://api.form-qr-code-generator.com/v1/forms",
    params={"page": 1, "limit": 5},
    headers={"Authorization": f"Bearer {api_key}", "Accept": "application/json"},
    timeout=30,
)
data = resp.json()
if resp.status_code >= 400:
    raise RuntimeError(f"{data.get('code')}: {data.get('message')}")
print(data.get("data"))

const apiKey = process.env.TIGER_FORM_API_KEY;
const base = "https://api.form-qr-code-generator.com/v1";
const headers = { Authorization: `Bearer ${apiKey}`, Accept: "application/json" };
const formsRes = await fetch(`${base}/forms?page=1&limit=1`, { headers });
const forms = await formsRes.json();
if (!formsRes.ok) throw new Error(`${forms.code}: ${forms.message}`);
const qrId = forms.data?.items?.[0]?.qrId;
if (!qrId) throw new Error("No forms on account — create one first or set qrId manually");
const schemaRes = await fetch(`${base}/forms/${qrId}/submission-schema`, { headers });
const schema = await schemaRes.json();
if (!schemaRes.ok) throw new Error(`${schema.code}: ${schema.message}`);
const nameField = Object.values(schema.data.fields).find((f) => f.type === "shortText");
if (!nameField?.key) throw new Error("No shortText field on this form");
const res = await fetch(`${base}/forms/${qrId}/submissions`, {
  method: "POST",
  headers: {
    ...headers,
    "Content-Type": "application/json",
    "Idempotency-Key": `create-${qrId}-${Date.now()}`,
  },
  body: JSON.stringify({
    answers: { [nameField.key]: "Jane Doe" },
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.message}`);

import fs from "node:fs";
const apiKey = process.env.TIGER_FORM_API_KEY;
const base = "https://api.form-qr-code-generator.com/v1";
const headers = { Authorization: `Bearer ${apiKey}`, Accept: "application/json" };
const formsRes = await fetch(`${base}/forms?page=1&limit=1`, { headers });
const forms = await formsRes.json();
if (!formsRes.ok) throw new Error(`${forms.code}: ${forms.message}`);
const qrId = forms.data?.items?.[0]?.qrId;
if (!qrId) throw new Error("No forms on account — create one first");
const fileBuffer = await fs.promises.readFile("receipt.pdf");
const formData = new FormData();
formData.append("category", "submission");
formData.append("userFile", new Blob([fileBuffer], { type: "application/pdf" }), "receipt.pdf");
const uploadRes = await fetch(`${base}/forms/${qrId}/uploads`, {
  method: "POST",
  headers: { Authorization: headers.Authorization, Accept: headers.Accept },
  body: formData,
});
const upload = await uploadRes.json();
if (!uploadRes.ok) throw new Error(`${upload.code}: ${upload.message}`);
const fileId = upload.data.fileId;
// Pass fileId in answers when creating the submission

import os, time, requests
api_key = os.environ["TIGER_FORM_API_KEY"]
base = "https://api.form-qr-code-generator.com/v1"
headers = {"Authorization": f"Bearer {api_key}", "Accept": "application/json"}
forms = requests.get(f"{base}/forms", params={"page": 1, "limit": 1}, headers=headers, timeout=30).json()
if forms.get("status") != "success" or not forms.get("data", {}).get("items"):
    raise RuntimeError("No forms on account — create one first or set qr_id manually")
qr_id = forms["data"]["items"][0]["qrId"]
schema = requests.get(
    f"{base}/forms/{qr_id}/submission-schema",
    headers=headers,
    timeout=30,
).json()
if schema.get("status") != "success":
    raise RuntimeError(f"{schema.get('code')}: {schema.get('message')}")
fields = schema["data"]["fields"]
name_field = next((f for f in fields.values() if f.get("type") == "shortText"), None)
if not name_field or not name_field.get("key"):
    raise RuntimeError("No shortText field on this form")
resp = requests.post(
    f"{base}/forms/{qr_id}/submissions",
    headers={
        **headers,
        "Content-Type": "application/json",
        "Idempotency-Key": f"create-{qr_id}-{int(time.time())}",
    },
    json={"answers": {name_field["key"]: "Jane Doe"}},
    timeout=30,
)
body = resp.json()
if resp.status_code >= 400:
    raise RuntimeError(f"{body.get('code')}: {body.get('message')}")

import os, requests
api_key = os.environ["TIGER_FORM_API_KEY"]
base = "https://api.form-qr-code-generator.com/v1"
headers = {"Authorization": f"Bearer {api_key}", "Accept": "application/json"}
forms = requests.get(f"{base}/forms", params={"page": 1, "limit": 1}, headers=headers, timeout=30).json()
if forms.get("status") != "success" or not forms.get("data", {}).get("items"):
    raise RuntimeError("No forms on account — create one first")
qr_id = forms["data"]["items"][0]["qrId"]
with open("receipt.pdf", "rb") as f:
    resp = requests.post(
        f"{base}/forms/{qr_id}/uploads",
        headers=headers,
        files={"userFile": ("receipt.pdf", f, "application/pdf")},
        data={"category": "submission"},
        timeout=60,
    )
upload = resp.json()
if resp.status_code >= 400:
    raise RuntimeError(f"{upload.get('code')}: {upload.get('message')}")
file_id = upload["data"]["fileId"]
# Pass file_id in answers when creating the submission

Webhook signature verification (Node + Python): Webhooks. Key schemas: FormCreate, SubmissionCreateBody, QRConfig, WebhookSubmissionCreatedEvent (pinned in the Schemas sidebar). Download public.openapi.json, postman.collection.json, or schema-examples.json (field type samples). Submission shapes: Submission Field Reference.

Upload APIs Compared

TIGER FORM documents two upload endpoints under /v1 for server-side integrations. Both require Authorization: Bearer <API_KEY>. Choose based on whether the file belongs to your account or a specific form.

On this page: Decision guide · Comparison table · Limits & errors · cURL workflows

Decision guide

1. Is it an account or QR-code logo (not a form page asset)? → POST /account/uploads with category=logo.
2. Is it tied to a form (qrId) — branding or a submission file? → POST /forms/{qrId}/uploads with category=form or category=submission.

Comparison

Shared request format

Both endpoints accept multipart/form-data with a binary part named userFile and a category field. Successful responses return fileId and fileUrl (wrapped in { "status": "success", "data": ... }).

File limits and types

• Max size: 20 MB per file. Files over 20 MB may return HTTP 500 with message: uploaded file is too large (not HTTP 400).
• POST /account/uploads (category=logo) — images only (JPEG, PNG, SVG, GIF, WebP, and other common image MIME types).
• POST /forms/{qrId}/uploads — images plus PDF, office documents, audio, video, archives, and plain text/CSV (see operation description in API Reference).
• Rate limit: category=submission uploads are limited to 200 requests / 5 minutes per client IP and qrId. See Rate Limits & Retries.

Upload errors (400 vs 404)

• Unknown form or wrong account — POST /forms/{qrId}/uploads and DELETE /forms/{qrId}/uploads/{fileId} return HTTP 404 (not 400).
• Invalid qrId format on DELETE — DELETE /forms/{qrId}/uploads/{fileId} returns HTTP 400 when qrId does not match ^[A-Z0-9]+$.
• Invalid qrId format on POST — no pattern check before lookup; a malformed id typically returns HTTP 404 (form not found).
• Unknown fileId on DELETE — HTTP 404.

cURL workflow examples

API_KEY="<API_KEY>"

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/account/uploads" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json" \
  -F "[email protected];type=image/png" \
  -F "category=logo"

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/uploads" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json" \
  -F "[email protected];type=image/jpeg" \
  -F "category=form"

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/uploads" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json" \
  -F "[email protected];type=application/pdf" \
  -F "category=submission"

FILE_ID="<from-upload-response>"

FILE_FIELD_KEY=$(curl -sS "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/submission-schema" \
  -H "Authorization: Bearer ${API_KEY}" \
  | jq -r '.data.fields | to_entries[] | select(.value.valueType | test("fileId")) | .key' | head -1)

curl -sS -X POST "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/submissions" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "$(jq -n --arg k "$FILE_FIELD_KEY" --arg f "$FILE_ID" '{answers: {($k): {fileId: $f}}}')"

Common integration mistakes

• Using /account/uploads for form background or page logo — use /forms/{qrId}/uploads with category=form.
• Uploading submission files without embedding refs in POST /forms/{qrId}/submissions.
• More pitfalls: Common Mistakes in Core Concepts.

OpenAPI reference

• Account tag — GET / PUT /account/webhook, GET / POST /account/uploads
• Forms tag — POST / DELETE /forms/{qrId}/uploads/…
• Submissions tag — POST /forms/{qrId}/submissions
• Schema SubmissionCreateBody — answers object keyed by field key
• Guide Submission Field Reference — answers shapes for every field type

Submission Field Reference

Values for the answers object on POST /forms/{qrId}/submissions, POST /forms/{qrId}/submissions/validate, and PUT /submissions/{submissionId}. Prefer GET /forms/{qrId}/submission-schema for live shapes and examples per form.

Jump to: object (name, address) · string · string[] · array (checkList, sheet) · fileId · file workflow

Payload shape

{
  "answers": {
    "<fieldKey>": /* see table below */
  }
}

Field types and valueType

Combined example

{
  "answers": {
    "<name-field-key>": { "firstName": "Jane", "lastName": "Doe" },
    "<address-field-key>": { "addressLine": "1 Main St", "city": "Austin", "state": "TX", "zipcode": "78701", "country": "US" },
    "<checkbox-field-key>": ["Marketing", "Sales"],
    "<checklist-field-key>": [
      { "itemName": "Safety briefing", "selectedValue": "_d1" },
      { "itemName": "Equipment check", "selectedValue": "_d2" }
    ],
    "<sheet-field-key>": [
      { "itemName": "Row A", "value": "42" },
      { "itemName": "Row B", "value": "OK" }
    ]
  }
}

File fields workflow

For file field types:

1. POST /forms/{qrId}/uploads with category=submission and part userFile
2. Copy data.fileId from the upload response into the matching answers field
3. After a successful create, delete orphan uploads with DELETE /forms/{qrId}/uploads/{fileId} if needed

Full curl examples: Upload APIs Compared. OpenAPI examples on POST /forms/{qrId}/submissions show picture and signature payloads.

Form Analytics

Query scan counts, device breakdown, and geography for a form with GET /forms/{qrId}/analytics. Add export=1 for a CSV download link instead of JSON.

On this page: Quick period picker (table below) · Query parameters · Example request

Endpoint

GET https://api.form-qr-code-generator.com/v1/forms/{qrId}/analytics?period={period}&tz={timezone}

Requires Authorization: Bearer <API_KEY>. The form must belong to your account. Invalid or unknown qrId returns HTTP 400.

Example request

Assumes API_KEY and QR_ID are set — see Manage Forms → cURL setup.

curl -sS -X GET "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/analytics?period=month&tz=Asia/Bangkok" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json"

{
  "status": "success",
  "data": {
    "form": { "qrId": "ABC123", "title": "Contact form" },
    "period": "month",
    "submissionFilter": false,
    "scans": 42,
    "uniqueScans": 38,
    "timeseries": {
      "all": [
        { "count": 12, "bucket": { "year": 2025, "month": 6, "day": 1 }, "date": "2025-06-01" }
      ],
      "unique": [
        { "count": 10, "bucket": { "year": 2025, "month": 6, "day": 1 }, "date": "2025-06-01" }
      ]
    },
    "devices": [{ "device": "mobile", "count": 30 }],
    "countries": [{ "country": "US", "count": 20 }],
    "cities": [{ "city": "Bangkok", "count": 15 }],
    "geoBreakdown": [{ "device": "mobile", "country": "US", "city": "Bangkok", "count": 5 }],
    "topLocations": [{ "city": "Bangkok", "device": "mobile", "count": 10 }],
    "socialButtons": []
  }
}

curl -sS -X GET "https://api.form-qr-code-generator.com/v1/forms/${QR_ID}/analytics?period=month&tz=Asia/Bangkok&export=1" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Accept: application/json"

{
  "status": "success",
  "data": {
    "csvUrl": "https://api.form-qr-code-generator.com/uploads/csv/ABC123-1717234567890.csv"
  }
}

See also the Form Analytics tag in the API Reference sidebar for the full OpenAPI operation (GET /forms/{qrId}/analytics) — query parameters, response schema, and CSV export (export=1).

Reliability & Operational Guidance

Before Go-Live Checklist

Idempotency

On POST /forms/{qrId}/submissions, send an optional Idempotency-Key header (max 128 chars). Replays with the same key and identical JSON body within 24 hours return the original success response without creating a duplicate submission. Reusing the same key with a different body (including changed timeSpentSeconds or timeExpired on quiz forms) returns HTTP 409. See Create a Submission.

Testing without a sandbox

There is no separate staging URL. Use a dedicated test account, test forms, and non-production data on https://api.form-qr-code-generator.com/v1. Disable submissionNotification on test forms if you bulk-create submissions. See Before Go-Live Checklist.

Webhooks

Push notifications for new submissions are documented in the dedicated Webhooks guide (setup, payload, signature verification, and delivery behavior).

Typical Latency

Most read endpoints respond in tens of milliseconds. A few write paths are slower — set client timeouts accordingly (30s is a safe default):

• POST /forms — often 1–2 seconds (form validation, QR provisioning, persistence).
• POST /forms/{qrId}/uploads — often 2–5+ seconds depending on file size and storage.
• POST /forms/{qrId}/submissions — usually under a few hundred milliseconds; validate is similar.

Figures are indicative for production. Do not treat slow creates as errors unless they exceed your timeout or return 5xx.

General guidance

• Use a dedicated API key for server-to-server integration (never from browser/mobile client code).
• Set request timeouts (recommended: 30s) and retry only on 429/5xx with exponential backoff. Respect Retry-After when the server sends it.
• Monitor the status page during incidents.
• Record method, path, timestamp (UTC), and response code/message in your integration logs.
• Test new integrations with dedicated test forms and non-production data before go-live.

Support targets

• Integration support hours: Monday-Friday, business hours (UTC+7).
• Initial human response target: within 1 business day.
• Production outage reports are prioritized when request details are complete.

Support

• Email: [email protected]
• Status page: docs.form-qr-code-generator.com/v1/status.html
• SLA policy: docs.form-qr-code-generator.com/v1/sla.html
• Terms: General Terms and Conditions
• Release history: Versioning (in docs). Plain text: CHANGELOG.md
• OpenAPI download: public.openapi.json
• Postman collection: postman.collection.json
• Field type samples: schema-examples.json
• Alternative OpenAPI viewer: redoc.html (read-only; primary docs use Swagger UI on index.htm)
• Stoplight (Try It & mock): tiger-form.stoplight.io/docs/tiger-form-api-v1-0 — sample responses only; use production for real integration testing

When reporting an issue, include

1. HTTP method and path (e.g. GET /forms)
2. Approximate time (UTC)
3. Response HTTP status and JSON code / message (never send your API key)