Document to Quiz Conversion API: Complete Developer Guide

API Overview

Authentication

Getting Your API Token

1. Sign in to Formswrite
2. Navigate to your account settings
3. Generate an API token

Using Your Token

bash# Recommended: Authorization header
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.formswrite.com/api/v1/convert

# Alternative: X-Access-Token header
curl -H "X-Access-Token: YOUR_TOKEN" \
  https://api.formswrite.com/api/v1/convert

# Alternative: Query parameter
curl "https://api.formswrite.com/api/v1/convert?token=YOUR_TOKEN"

Endpoints

POST /api/v1/convert

json{
  "documentId": "string (required)",
  "format": "string (required)",
  "documentName": "string (optional)",
  "async": false
}

Supported Output Formats

Sync Mode (Default)

bashcurl -X POST https://api.formswrite.com/api/v1/convert \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documentId": "1abc123xyz",
    "format": "moodle",
    "documentName": "Chapter 5 Quiz"
  }'

json{
  "success": true,
  "exportId": "export-uuid",
  "downloadUrl": "https://api.formswrite.com/api/forms/exports/export-uuid",
  "fileName": "Chapter 5 Quiz-moodle.xml",
  "format": "moodle",
  "expiresAt": "2026-03-17T00:00:00.000Z"
}

Async Mode

bashcurl -X POST https://api.formswrite.com/api/v1/convert \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documentId": "1abc123xyz",
    "format": "canvas",
    "async": true
  }'

json{
  "success": true,
  "status": "processing",
  "jobId": "12345",
  "message": "Document analysis queued. Poll for status.",
  "pollUrl": "/api/v1/convert/status/12345"
}

GET /api/v1/convert/status/:jobId

bashcurl https://api.formswrite.com/api/v1/convert/status/12345 \
  -H "Authorization: Bearer YOUR_TOKEN"

json{
  "success": true,
  "jobId": "12345",
  "state": "completed",
  "progress": 100,
  "result": {
    "success": true,
    "documentName": "Chapter 5 Quiz",
    "isQuiz": true,
    "mergedContent": {
      "title": "Chapter 5 Quiz",
      "introduction": "Answer the following questions",
      "questions": [...]
    }
  }
}

Error Handling

json{
  "success": false,
  "message": "Invalid format. Supported formats: google_form, moodle, canvas, ..."
}

Code Examples

Python — Convert and Download

pythonimport requests

API_TOKEN = "your_token"

def convert_doc(doc_id, format, name):
    response = requests.post(
        "https://api.formswrite.com/api/v1/convert",
        headers={
            "Authorization": f"Bearer {API_TOKEN}",
            "Content-Type": "application/json"
        },
        json={
            "documentId": doc_id,
            "format": format,
            "documentName": name
        }
    )
    result = response.json()

    if result.get("success"):
        file_response = requests.get(result["downloadUrl"])
        with open(result["fileName"], "wb") as f:
            f.write(file_response.content)
        return result["fileName"]
    else:
        raise Exception(result.get("message", "Conversion failed"))

# Usage
convert_doc("1abc123xyz", "moodle", "Biology Quiz")
convert_doc("1abc123xyz", "canvas", "Biology Quiz")
convert_doc("1abc123xyz", "kahoot", "Biology Quiz")

Node.js — Async with Polling

javascriptasync function convertDocument(docId, format, name) {
  // Start async conversion
  const response = await fetch('https://api.formswrite.com/api/v1/convert', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FORMSWRITE_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      documentId: docId,
      format,
      documentName: name,
      async: true
    })
  });

  const { jobId } = await response.json();

  // Poll for completion
  while (true) {
    const status = await fetch(
      `https://api.formswrite.com/api/v1/convert/status/${jobId}`,
      { headers: { 'Authorization': `Bearer ${process.env.FORMSWRITE_TOKEN}` } }
    );
    const result = await status.json();

    if (result.state === 'completed') return result;
    if (result.state === 'failed') throw new Error(result.error);

    await new Promise(r => setTimeout(r, 3000)); // Wait 3s
  }
}

Zapier Webhook

javascript// In a Zapier "Code by Zapier" step:
const response = await fetch('https://api.formswrite.com/api/v1/convert', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + inputData.api_token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    documentId: inputData.google_doc_id,
    format: 'moodle',
    documentName: inputData.quiz_name
  })
});

output = await response.json();

AI-Powered Question Extraction

• Natural language question formatting
• Numbered and bulleted answer options
• Correct answers marked with bold, asterisks, or other conventions
• Section headers and introductions
• Images embedded in questions
• Point values and grading rubrics

Integration Patterns

Webhook-Based Automation

1. Trigger: New file added to a Google Drive folder
2. Action: Call Formswrite API to convert to Moodle XML
3. Action: Upload the XML to your Moodle instance

CI/CD Pipeline

1. Store quiz documents in a shared Google Drive
2. Run a conversion script as part of your deployment
3. Upload generated files to your LMS automatically

SaaS Integration

1. User uploads or selects a Google Doc
2. Your backend calls the Formswrite API
3. Return the download URL to your user

FAQ

What document formats can I use as input?

How does the AI detect question types?

Can I convert the same document to multiple formats?

How long are download URLs valid?

Is the API available in all regions?

Can I use this for commercial purposes?

What happens if my document has no questions?

Get Started