Questionnaires API: Upload, Status, Results

Upload a file

URL: POST https://api.wolfia.com/v1/questionnaire/upload/file Authentication: API key required (see API overview for setup) A restricted key needs the Questionnaires: write scope to upload, and Questionnaires: read for the list, search, and overview endpoints. This endpoint accepts multipart form data.

curl -X POST https://api.wolfia.com/v1/questionnaire/upload/file \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE" \
  -F "file=@questionnaire.xlsx;type=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" \
  -F "company_name=Acme Corp" \
  -F "deal_value=50000" \
  -F "deadline=2025-03-15" \
  -F "instructions=Focus on SOC 2 and ISO 27001 compliance"

You must set the correct MIME type for the file using the ;type= syntax in curl (or the equivalent Content-Type in your HTTP client). Uploads with an incorrect MIME type will fail to process.

Request parameters

Parameter	Type	Required	Description
`file`	file	Yes	The questionnaire file
`company_name`	string	Yes	Company that sent the questionnaire
`deal_value`	decimal	No	Associated deal value
`deadline`	date (YYYY-MM-DD)	No	Completion deadline
`instructions`	string	No	Instructions to guide AI processing
`tag_ids`	array of strings	No	Tag IDs to categorize the questionnaire (see Content tags)
`assignee_ids`	array of strings	No	User IDs to assign to
`assignee_types`	array of strings	No	Type per assignee (`USER` or `GROUP`)

Supported file types

Extension	MIME type
`.xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
`.xlsm`	`application/vnd.ms-excel.sheet.macroenabled.12`
`.xls`	`application/vnd.ms-excel`
`.csv`	`text/csv`
`.docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
`.pdf`	`application/pdf`

Response (200 OK)

{
  "questionnaire_id": "da891171-9293-4218-a74a-c53c55673beb",
  "message": "File 'questionnaire.xlsx' uploaded successfully and queued for processing"
}

Upload text content

URL: POST https://api.wolfia.com/v1/questionnaire/upload/text Authentication: API key required (see API overview for setup) Use this when you have questions as text rather than a file, for example, pasted from an email or extracted from a web form.

curl -X POST https://api.wolfia.com/v1/questionnaire/upload/text \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "text_content": "1. Describe your data encryption standards.\n2. How do you handle incident response?\n3. What certifications do you hold?",
    "company_name": "Acme Corp"
  }'

Request parameters

Parameter	Type	Required	Description
`text_content`	string	Yes	Questions as text (50 to 200,000 characters)
`company_name`	string	No	Company that sent the questionnaire
`source_type`	string	No	Defaults to `TEXT`
`deal_value`	decimal	No	Associated deal value
`deadline`	date (YYYY-MM-DD)	No	Completion deadline
`instructions`	string	No	Instructions to guide AI processing
`tag_ids`	array of strings	No	Tag IDs to categorize the questionnaire (see Content tags)
`assignees`	array of objects	No	Each with `id` (string) and `type` (`USER` or `GROUP`)

Response (200 OK)

{
  "questionnaire_id": "da891171-9293-4218-a74a-c53c55673beb",
  "message": "Text content uploaded successfully and queued for processing"
}

List questionnaires

URL: GET https://api.wolfia.com/v1/questionnaire/list Authentication: API key required Returns a paginated list of all questionnaires in your organization, ordered by creation date (newest first).

Request

curl -X GET 'https://api.wolfia.com/v1/questionnaire/list?limit=20&offset=0' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"

Query parameters

Parameter	Type	Required	Default	Description
`limit`	integer (1-1000)	No	10	Number of questionnaires to return
`offset`	integer	No	0	Number of questionnaires to skip (for pagination)

Response (200 OK)

{
  "questionnaires": [
    {
      "id": "da891171-9293-4218-a74a-c53c55673beb",
      "title": "SOC 2 Security Questionnaire",
      "company_name": "Acme Corp",
      "status": "ANSWERING_COMPLETED",
      "status_display_name": "Ready for review",
      "total_questions": 150,
      "answered_questions": 148,
      "created_at": 1735689600000000,
      "deadline": "2025-03-15",
      "deal_value": 50000,
      "tags": [
        {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "name": "SOC 2",
          "description": "SOC 2 compliance questionnaires",
          "is_ai_generated": false,
          "status": "ACTIVE"
        }
      ],
      "should_poll": false
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  },
  "should_poll": false
}

The should_poll field (at both the list level and individual questionnaire level) indicates whether any questionnaires are still being processed. If true, poll the endpoint periodically to get updated statuses.

Processing status values

After uploading, a questionnaire moves through these statuses:

Status	Display name	Meaning
`UPLOADED`	Uploaded	File received, processing not started
`QUEUED_PENDING_REVIEW`	Pre-validation	Queued for initial validation before processing
`QUEUED_FOR_EXTRACTION`	Queued	Validated and queued for question extraction
`ANALYSIS_IN_PROGRESS`	Analyzing	AI is analyzing the document structure
`QUESTION_EXTRACTION_IN_PROGRESS`	Extracting	AI is extracting individual questions
`ANSWERING_IN_PROGRESS`	Answering	AI is generating answers
`ANSWERING_COMPLETED`	Ready for review	All answers generated, ready for human review
`READY_FOR_APPROVAL`	Ready for approval	Reviewed and pending final approval
`COMPLETED`	Completed	Fully completed

Failed statuses (ANALYSIS_FAILED, QUESTION_EXTRACTION_FAILED, ANSWERING_FAILED) indicate a processing error. Contact support@wolfia.com if failures persist.

Search questionnaires

URL: GET https://api.wolfia.com/v1/questionnaire/search Authentication: API key required Search questionnaires by text or filter by specific fields using the @field:value syntax.

Request

# Text search
curl -X GET 'https://api.wolfia.com/v1/questionnaire/search?query=security+review' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"

# Filter by status
curl -X GET 'https://api.wolfia.com/v1/questionnaire/search?query=@status:ANSWERING_COMPLETED' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"

# Filter by account name
curl -X GET 'https://api.wolfia.com/v1/questionnaire/search?query=@account:Acme' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"

# Combine filters
curl -X GET 'https://api.wolfia.com/v1/questionnaire/search?query=@status:ANSWERING_IN_PROGRESS+@account:Acme' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"

Query parameters

Parameter	Type	Required	Default	Description
`query`	string	No	`""`	Search query (see filter syntax below)
`limit`	integer (1-1000)	No	10	Number of results to return
`offset`	integer	No	0	Pagination offset

Filter syntax

Use @field:value to filter by specific fields. Multiple filters can be combined in a single query.

Filter	Example	Description
`@title:`	`@title:security review`	Match questionnaire title
`@status:`	`@status:ANSWERING_COMPLETED`	Match processing status (see status values)
`@account:`	`@account:Acme`	Match company name

Plain text without the @ prefix searches across all fields.

Response (200 OK)

The response format matches List questionnaires, with an additional matched_questions array on each item showing which questions matched the search query.

Get questionnaire details

URL: GET https://api.wolfia.com/v1/questionnaire/{questionnaire_id}/overview Authentication: API key required Returns detailed information about a specific questionnaire, including per-sheet statistics, processing logs, and completion metrics.

Request

curl -X GET 'https://api.wolfia.com/v1/questionnaire/da891171-9293-4218-a74a-c53c55673beb/overview' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"

Response (200 OK)

{
  "id": "da891171-9293-4218-a74a-c53c55673beb",
  "title": "SOC 2 Security Questionnaire",
  "company_name": "Acme Corp",
  "status": "ANSWERING_COMPLETED",
  "status_display_name": "Ready for review",
  "total_questions": 150,
  "answered_questions": 148,
  "statistics": {
    "total_questions": 150,
    "answered_questions": 148,
    "approved_questions": 0,
    "ai_answered_questions": 145,
    "manual_answered_questions": 3,
    "not_answered_questions": 2,
    "completion_percentage": 98.67,
    "approval_percentage": 0.0
  },
  "created_at": 1735689600000000,
  "deadline": "2025-03-15",
  "deal_value": 50000,
  "tags": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "SOC 2",
      "description": "SOC 2 compliance questionnaires",
      "is_ai_generated": false,
      "status": "ACTIVE"
    }
  ],
  "sheets": [
    {
      "id": "sheet-uuid",
      "name": "Security Controls",
      "status": "ANSWERING_COMPLETED",
      "should_poll": false
    }
  ],
  "sheet_stats": [
    {
      "id": "sheet-uuid",
      "name": "Security Controls",
      "status": "ANSWERING_COMPLETED",
      "total_questions": 150,
      "answered_questions": 148,
      "completion_percentage": 98.67
    }
  ],
  "should_poll": false
}

Use should_poll to determine if the questionnaire is still being processed. If true, poll this endpoint at reasonable intervals (e.g., every 10-30 seconds) until processing completes.

Key response fields

Field	Type	Description
`id`	string (UUID)	Questionnaire identifier
`status`	string	Current processing status (see status values)
`status_display_name`	string	Human-readable status
`total_questions`	integer	Total extracted questions
`answered_questions`	integer	Questions with AI or manual answers
`statistics`	object	Detailed completion and quality metrics
`sheets`	array	Individual sheets/tabs with their processing status
`sheet_stats`	array	Per-sheet question and completion statistics
`tags`	array	Content tags applied to this questionnaire
`should_poll`	boolean	`true` if processing is still in progress
`created_at`	integer	Creation timestamp (microseconds)

Get question-level data

URL: GET https://api.wolfia.com/v1/questionnaire/{questionnaire_id}/questions Authentication: API key required, with the Questionnaires: read scope Returns every question in a questionnaire with its full answer data as structured JSON: question text, section, status, and each response field’s answer. Built for analysis and reporting, for example measuring what topics your customers ask about most, without downloading and parsing exported documents. Combine it with List questionnaires to run an analysis across your whole questionnaire history: list the questionnaire IDs, then fetch question-level data for each.

Request

curl -X GET 'https://api.wolfia.com/v1/questionnaire/da891171-9293-4218-a74a-c53c55673beb/questions?limit=500&offset=0' \
  -H "X-API-Key: wolfia-api-YOUR_KEY_HERE"

Query parameters

Parameter	Type	Required	Default	Description
`limit`	integer (1-1000)	No	500	Number of questions to return
`offset`	integer	No	0	Number of questions to skip (for pagination)

Response (200 OK)

{
  "items": [
    {
      "question_id": "8a411f72-1d3c-4a0e-9b2f-6a1c2d3e9f02",
      "questionnaire_id": "da891171-9293-4218-a74a-c53c55673beb",
      "section_name": "Data Residency",
      "question_order": 12,
      "question_text": "Where is customer data stored at rest?",
      "status": "ANSWERED_AI",
      "confidence_score": 92,
      "is_approved": true,
      "is_out_of_scope": false,
      "created_at": 1735689600000000,
      "updated_at": 1735776000000000,
      "responses": [
        {
          "response_name": "Response",
          "response_type": "TEXT",
          "is_required": true,
          "answer": "Customer data is stored at rest in...",
          "ai_generated_answer": "Customer data is stored at rest in...",
          "is_pre_approved_answer": false,
          "answer_origin": "ai_generated",
          "response_order": 0,
          "created_at": 1735689600000000,
          "updated_at": 1735776000000000
        }
      ]
    }
  ],
  "total": 150,
  "offset": 0,
  "limit": 500
}

Keys with no value are omitted from the response. An unanswered question has no answer key rather than a null one.

Key response fields

Field	Type	Description
`question_text`	string	The question as extracted from the source document
`section_name`	string	Section the question belongs to
`status`	string	Question status, for example `ANSWERED_AI`, `ANSWERED_MANUAL`, `EXTRACTED`
`confidence_score`	integer	Answer confidence from 0 to 100, when available
`is_approved`	boolean	Whether the answer has been approved by a reviewer
`responses[].answer`	string	The current answer, including any human edits
`responses[].ai_generated_answer`	string	The original AI-generated answer, before any edits
`responses[].response_type`	string	`TEXT`, `SELECT`, `MULTI_SELECT`, and other field types
`responses[].options`	array	Available choices for select-type questions
`responses[].answer_origin`	string	How the answer was produced, for example `ai_generated`

Questions in multiple languages include question_text_english and answer_english translations alongside the original text. Timestamps are in microseconds.

Comparing answer against ai_generated_answer shows where your team edited AI answers, which is useful for measuring answer quality and adoption.

Integration example

Python: Upload and poll until complete

import os
import time

import requests

API_KEY = os.environ['WOLFIA_API_KEY']
BASE_URL = 'https://api.wolfia.com/v1'


def upload_and_wait(file_path, company_name, timeout_seconds=600):
    """Upload a questionnaire and poll until processing completes."""
    headers = {'X-API-Key': API_KEY}

    # Upload the file
    with open(file_path, 'rb') as f:
        resp = requests.post(
            f'{BASE_URL}/questionnaire/upload/file',
            headers=headers,
            files={'file': (os.path.basename(file_path), f, 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet')},
            data={'company_name': company_name},
            timeout=60,
        )
    resp.raise_for_status()
    qid = resp.json()['questionnaire_id']
    print(f'Uploaded: {qid}')

    # Poll for completion
    start = time.time()
    while time.time() - start < timeout_seconds:
        overview = requests.get(
            f'{BASE_URL}/questionnaire/{qid}/overview',
            headers=headers,
            timeout=30,
        )
        overview.raise_for_status()
        data = overview.json()

        status = data['status']
        display = data['status_display_name']
        print(f'  Status: {display} ({status})')

        if not data['should_poll']:
            return data

        time.sleep(15)

    raise TimeoutError(f'Questionnaire {qid} did not complete within {timeout_seconds}s')


if __name__ == '__main__':
    result = upload_and_wait('questionnaire.xlsx', 'Acme Corp')
    stats = result['statistics']
    print(f"Done: {stats['answered_questions']}/{stats['total_questions']} answered ({stats['completion_percentage']:.1f}%)")

Python: Ingest questionnaires from JIRA

import mimetypes
import os

import requests
from jira import JIRA

WOLFIA_API_KEY = os.environ["WOLFIA_API_KEY"]
BASE_URL = "https://api.wolfia.com/v1"

MIME_TYPES = {
    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    ".xlsm": "application/vnd.ms-excel.sheet.macroenabled.12",
    ".xls": "application/vnd.ms-excel",
    ".csv": "text/csv",
    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    ".pdf": "application/pdf",
}


def get_mime_type(filename):
    ext = os.path.splitext(filename)[1].lower()
    return MIME_TYPES.get(ext, mimetypes.guess_type(filename)[0])


def process_questionnaire_tickets():
    jira = JIRA(server=os.environ["JIRA_SERVER"], token_auth=os.environ["JIRA_TOKEN"])
    issues = jira.search_issues('project = SEC AND type = "Security Questionnaire" AND status = "To Do"', maxResults=50)

    for issue in issues:
        company = issue.fields.summary.split(" - ")[0] if " - " in issue.fields.summary else issue.fields.summary

        if issue.fields.attachment:
            att = issue.fields.attachment[0]
            mime_type = get_mime_type(att.filename)
            resp = requests.post(
                f"{BASE_URL}/questionnaire/upload/file",
                headers={"X-API-Key": WOLFIA_API_KEY},
                files={"file": (att.filename, att.get(), mime_type)},
                data={"company_name": company, "instructions": issue.fields.description or ""},
                timeout=60,
            )
        elif issue.fields.description and len(issue.fields.description) >= 50:
            resp = requests.post(
                f"{BASE_URL}/questionnaire/upload/text",
                headers={"X-API-Key": WOLFIA_API_KEY, "Content-Type": "application/json"},
                json={"text_content": issue.fields.description, "company_name": company},
                timeout=30,
            )
        else:
            print(f"Skipping {issue.key}: no attachment or usable description")
            continue

        if resp.status_code == 200:
            qid = resp.json()["questionnaire_id"]
            jira.add_comment(issue, f"Uploaded to Wolfia (ID: {qid})")
            jira.transition_issue(issue, "In Progress")
            print(f"  {issue.key} -> {qid}")
        else:
            print(f"  {issue.key} failed: {resp.text}")


if __name__ == "__main__":
    process_questionnaire_tickets()

Error responses

Status Code	What it means	How to fix
400	Unsupported file type	Use a supported format: `.xlsx`, `.xlsm`, `.xls`, `.csv`, `.docx`, `.pdf`
401	Invalid or expired API key	Verify your API key
403	Insufficient permissions	Check the API key owner’s role
404	Questionnaire not found	Verify the questionnaire ID exists
422	Missing required fields or invalid input	Check required fields. Text must be 50-200,000 characters.
500	Internal error	Retry with exponential backoff

Best practices

File vs text upload

Use file upload when you have the original document (XLSX, PDF, DOCX). Wolfia preserves the document structure.Use text upload for plain text questions from emails, web forms, or chat messages.

Use instructions to guide AI

The instructions field shapes how Wolfia fills in answers:

{
  "instructions": "This is a SOC 2 questionnaire. Reference our latest audit report."
}

Set metadata for better tracking

Include company_name, deal_value, and deadline when available. This metadata appears in the Wolfia dashboard for prioritization.

Poll efficiently after upload

After uploading, use the get questionnaire details endpoint to track progress. Check the should_poll field; when it’s false, processing is complete. A polling interval of 15-30 seconds is recommended.

Getting help

Check file types: .xlsx, .xlsm, .xls, .csv, .docx, .pdf
Check text length: 50 to 200,000 characters
Contact support: Email support@wolfia.com

Next steps

Content tags

List available tags to categorize questionnaires on upload

API overview

Authentication, rate limits, and error handling

Knowledge base upload

Add documents to your knowledge base

Trust portal analytics

Track engagement metrics and account activity

​Upload a file

​Request parameters

​Supported file types

​Response (200 OK)

​Upload text content

​Request parameters

​Response (200 OK)

​List questionnaires

​Request

​Query parameters

​Response (200 OK)

​Processing status values

​Search questionnaires

​Request

​Query parameters

​Filter syntax

​Response (200 OK)

​Get questionnaire details

​Request

​Response (200 OK)

​Key response fields

​Get question-level data

​Request

​Query parameters

​Response (200 OK)

​Key response fields

​Integration example

​Python: Upload and poll until complete

​Python: Ingest questionnaires from JIRA

​Error responses

​Best practices

​Getting help

​Next steps

Content tags

API overview

Knowledge base upload

Trust portal analytics

Upload a file

Request parameters

Supported file types

Response (200 OK)

Upload text content

Request parameters

Response (200 OK)

List questionnaires

Request

Query parameters

Response (200 OK)

Processing status values

Search questionnaires

Request

Query parameters

Filter syntax

Response (200 OK)

Get questionnaire details

Request

Response (200 OK)

Key response fields

Get question-level data

Request

Query parameters

Response (200 OK)

Key response fields

Integration example

Python: Upload and poll until complete

Python: Ingest questionnaires from JIRA

Error responses

Best practices

Getting help

Next steps