Skip to main content
POST
/
api
/
v1
/
convert
Convert document
curl --request POST \
  --url https://api.example.com/api/v1/convert
Convert a Google Doc or uploaded document into a quiz or form on any of the 30+ supported platforms.

​
Request

​
Headers

HeaderValueRequired
AuthorizationBearer YOUR_API_TOKENYes
Content-Typeapplication/jsonYes

​
Body parameters

ParameterTypeRequiredDescription
documentIdstringYesGoogle Doc ID or full Google Docs URL
formatstringYesTarget format (see supported formats)
documentNamestringNoName for the output file (defaults to "Untitled Document")
documentTypestringNoSource document type (defaults to "google_doc")
asyncbooleanNoSet to true for async processing (returns immediately with a job ID)

​
Document ID

You can pass either a raw Google Doc ID or a full URL: 
// Raw ID
{ "documentId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms" }

// Full URL
{ "documentId": "https://docs.google.com/document/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms/edit" }
The document must be shared with Formswrite (or set to “Anyone with the link can view”) for the conversion to work.

​
Supported formats

​
Live forms

Format valuePlatformDescription
google_formGoogle FormsCreates a Google Form in your Google account
formswrite_formFormswrite FormsCreates a hosted form on Formswrite
google_form requires that you have previously connected your Google account via the Formswrite web app. The form will be created in your Google Drive.

​
Learning Management Systems (LMS)

Format valuePlatformFile type
canvasCanvas LMS.zip (QTI package)
moodleMoodle.xml (Moodle XML)
blackboardBlackboard.txt
brightspaceBrightspace (D2L).zip
schoologySchoology.zip (QTI package)
sakaiSakai.zip (QTI 2.1 package)

​
Quiz and game platforms

Format valuePlatformFile type
kahootKahoot!.csv
quizizzQuizizz.csv
blooketBlooket.csv
gimkitGimkit.csv
socrativeSocrative.csv
wooclapWooclap.csv
quizalizeQuizalize.csv
classmarkerClassMarker.csv
pear_assessmentPear Assessment (formerly Pear Deck).csv

​
Standard formats

Format valueDescriptionFile type
qti_21QTI 2.1 (IMS standard).zip
qti_22QTI 2.2 (IMS standard).zip
giftGIFT format (Moodle-compatible).txt
aikenAiken format (simple text).txt
clozeCloze / Embedded Answers format.txt
wordMicrosoft Word.docx

​
Other platforms

Format valuePlatformFile type
learndashLearnDash (WordPress).txt (GIFT format)
h5pH5P.zip (QTI 2.1 package)

​
Synchronous mode (default)

By default, the API waits for the document to be analyzed and converted before returning the result. This can take up to 5 minutes depending on document size.

​
Request

curl -X POST https://api.formswrite.com/api/v1/convert \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documentId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
    "format": "moodle",
    "documentName": "Chemistry Quiz"
  }'

​
Success response (file formats)

{
  "success": true,
  "format": "moodle",
  "exportId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "downloadUrl": "https://api.formswrite.com/api/forms/exports/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "fileName": "Chemistry Quiz-moodle.xml"
}

​
Success response (Google Forms)

{
  "success": true,
  "format": "google_form",
  "formId": "1AbCdEf2GhIjKlMnOpQrStUvWxYz",
  "formUrl": "https://docs.google.com/forms/d/1AbCdEf2GhIjKlMnOpQrStUvWxYz/viewform"
}

​
Timeout response (408)

If the analysis takes longer than 5 minutes, you will receive a 408 response with a job ID you can use to poll for status: 
{
  "success": false,
  "status": "processing",
  "jobId": "123",
  "message": "Analysis still in progress. Poll for status.",
  "pollUrl": "/api/v1/convert/status/123"
}

​
Asynchronous mode

Set "async": true to return immediately with a job ID. Use the poll status endpoint to check when the conversion is complete.

​
Request

curl -X POST https://api.formswrite.com/api/v1/convert \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documentId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
    "format": "canvas",
    "documentName": "Biology Exam",
    "async": true
  }'

​
Response (202 Accepted)

{
  "success": true,
  "status": "processing",
  "jobId": "456",
  "message": "Document analysis queued. Poll for status.",
  "pollUrl": "/api/v1/convert/status/456"
}
Then poll GET /api/v1/convert/status/456 until the job is complete. See Poll status for details.

​
Error responses

StatusDescription
400Missing or invalid documentId or format
401Invalid or missing API token
402Subscription expired or credit limit reached
408Analysis timed out (sync mode only — use the returned pollUrl)
500Internal server error

​
Example: invalid format

{
  "success": false,
  "message": "Invalid format. Supported formats: google_form, formswrite_form, canvas, moodle, blackboard, brightspace, schoology, sakai, kahoot, quizizz, blooket, gimkit, socrative, wooclap, quizalize, classmarker, pear_assessment, qti_21, qti_22, gift, aiken, cloze, word, learndash, h5p"
}

​
Example: subscription required

{
  "success": false,
  "message": "Your subscription has expired. Please upgrade to continue using the API."
}