Screening from Template

Create a screening by uploading a questionnaire template file. Briink automatically extracts questions from your document and runs a screening against your uploaded files — no need to manually create a questionnaire first.

How It Works

Upload a template file (your questionnaire document) along with the files to screen
Briink extracts questions from the template automatically (PDF, Excel, CSV, DOCX, PPTX, TXT, Markdown, HTML)
A screening is created and AI-generated responses start processing in the background
Poll for results using the template ID

Creating a Screening from Template

Endpoint: POST /workspaces/{workspace_id}/screenings/template

Authentication: Platform auth or API key required

This endpoint accepts multipart/form-data with the following fields:

Field	Type	Required	Description
`questionnaire_template`	file	Yes	The questionnaire document to extract questions from
`file_ids`	list of UUIDs	Yes	IDs of files to screen against (must be uploaded first)
`name`	string	No	Name for the screening
`description`	string	No	Description for the screening
`due_date`	ISO datetime	No	Due date for the screening
`entity`	JSON string	No	Entity to associate (company_id or data with name/type/industry/location)

Response

{
  "id": "template-file-uuid",
  "screening": null
}

The id is your template ID — use it to poll for the screening result. The screening field is null initially because question extraction and screening creation happen asynchronously.

Polling for Results

Endpoint: GET /workspaces/{workspace_id}/screenings/template/{template_id}

Authentication: Platform auth or API key required

Poll this endpoint to check if the screening has been created.

While processing:

{
  "id": "template-file-uuid",
  "screening": null
}

After processing completes:

{
  "id": "template-file-uuid",
  "screening": {
    "id": "screening-uuid",
    "workspace_id": "workspace-uuid",
    "name": "My Screening",
    "description": null,
    "due_date": null,
    "creator_id": "user-uuid",
    "created_at": "2026-02-25T12:00:00Z",
    "total_credit_cost": 0,
    "questionnaire": { ... },
    "executions": [
      {
        "id": "execution-uuid",
        "status": "PROCESSING",
        "questionnaire_id": "questionnaire-uuid",
        ...
      }
    ],
    "entity": null
  }
}

Once screening is populated, you can use the standard screening endpoints to track execution progress and retrieve responses:

GET /workspaces/{workspace_id}/screenings/{screening_id} — Get screening details
GET /workspaces/{workspace_id}/screenings/{screening_id}/responses — Get AI-generated responses

Execution Status Values

Status	Meaning
`CREATED`	Screening created, execution starting
`AWAITING_FILES_PROCESSED`	Waiting for file preprocessing
`PROCESSING`	AI is generating responses
`PROCESSING_DONE`	All responses generated
`PROCESSING_FAILED`	Execution failed

Python Example

import requests
import time

BASE_URL = "https://api.platform.briink.com"
API_KEY = "your-api-key"
WORKSPACE_ID = "your-workspace-id"

headers = {"X-API-Key": API_KEY}

# Step 1: Upload the template and create the screening
with open("questionnaire.xlsx", "rb") as template_file:
    response = requests.post(
        f"{BASE_URL}/workspaces/{WORKSPACE_ID}/screenings/template",
        headers=headers,
        files={"questionnaire_template": ("questionnaire.xlsx", template_file, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")},
        data={
            "file_ids": ["file-uuid-1", "file-uuid-2"],
            "name": "Q1 ESG Assessment",
        },
    )

result = response.json()
template_id = result["id"]
print(f"Template uploaded: {template_id}")

# Step 2: Poll until the screening is created
while True:
    poll = requests.get(
        f"{BASE_URL}/workspaces/{WORKSPACE_ID}/screenings/template/{template_id}",
        headers=headers,
    )
    data = poll.json()

    if data["screening"] is not None:
        screening_id = data["screening"]["id"]
        print(f"Screening created: {screening_id}")
        break

    print("Processing template... waiting 5s")
    time.sleep(5)

# Step 3: Wait for execution to finish, then fetch responses
screening = data["screening"]
execution_status = screening["executions"][0]["status"]

while execution_status not in ("PROCESSING_DONE", "PROCESSING_FAILED"):
    time.sleep(5)
    resp = requests.get(
        f"{BASE_URL}/workspaces/{WORKSPACE_ID}/screenings/{screening_id}",
        headers=headers,
    )
    execution_status = resp.json()["executions"][0]["status"]
    print(f"Execution status: {execution_status}")

# Step 4: Get the responses
responses = requests.get(
    f"{BASE_URL}/workspaces/{WORKSPACE_ID}/screenings/{screening_id}/responses",
    headers=headers,
).json()

for r in responses:
    print(f"Q: {r['question']['text']}")
    print(f"A: {r['response_text']}")
    print()

Note: Files must be uploaded to the workspace before creating the screening. Use the files upload endpoint to get file IDs.

Best Practices

Supported formats: PDF, Excel (.xls/.xlsx/.xlsm), CSV, DOCX, PPTX, plain text, Markdown, and HTML
Poll interval: 10-30 seconds is recommended when waiting for template processing
Template quality: Well-structured documents with clear question numbering yield the best extraction results
File preprocessing: If files haven't been preprocessed yet, the execution will wait (AWAITING_FILES_PROCESSED) until they're ready before starting