record-assessment-backend

Backend SDK for SmartAI Assessment Portal — create sessions and manage assessments from your server.

Install

pip install record-assessment-backend

Usage

from record_assessment_backend import AssessmentClient

client = AssessmentClient(
    api_key="VFN_LIVE_...",
    secret_key="VFN_SK_LIVE_...",
    base_url="https://your-api.com/api/v1",           # optional
    webhook_base_url="https://your-webhook-api.com",   # optional
    timeout=60.0,                                       # optional — create_campaign calls OpenAI server-side
)

Create a session

result = client.create_session(
    candidate_id="mongo_candidate_id",
    name="Jane Doe",
    email="jane@example.com",
)
token = result["token"]

Create a campaign

Generates the assessment immediately. method must be "programming" or "knowledge" and the workflow must have that verification method enabled — "programming" generates a programming-only assessment, "knowledge" generates a mix of mcq/true-false/short-answer/long-answer per the workflow's configured counts. workflow_id, method, and name+email are required — everything else falls back to the workflow's own defaults:

campaign = client.create_campaign(
    workflow_id="wf_...",
    method="knowledge",
    name="Jane Doe",
    email="jane@example.com",
    job_title="Backend Engineer",  # optional
    experience="3",                 # optional
    level="2-5",                    # optional
)
assessment_link = campaign["assessmentLink"]

List assessments

assessments = client.list_assessments()

Poll for assessment links

Fired by create_campaign — send these to your candidates:

links = client.get_assessment_links()
for event in links["events"]:
    print("send to candidates:", event["assessmentLink"])
if links["events"]:
    client.acknowledge_assessment_links([e["eventId"] for e in links["events"]])

Poll for assessment results

Fired once a candidate submits or is disqualified. Carries score, passed, totalMarks, passMarks, candidateName, candidateEmail, submittedAt, durationMinutes, questionAnswers, proctoring, recording, aiFeedback — plus reportUrl, the shareable link to the candidate's full result report page:

results = client.get_assessment_results()
for event in results["events"]:
    print(event["candidateEmail"], event["score"], "passed" if event["passed"] else "failed")
    print("full report:", event["reportUrl"])
if results["events"]:
    client.acknowledge_assessment_results([e["eventId"] for e in results["events"]])

get_webhook_events / acknowledge_webhook_events still work if you'd rather handle both event types yourself in one poll — the link/result methods above are just filtered, labeled wrappers around the same Redis-backed queue.

Headers sent on every request

x-api-key:   VFN_LIVE_...
x-signature: hmac-sha256(secret_key, "METHOD:/api/v1/path:timestamp:sorted_body")
x-timestamp: 1234567890123

Notes

• secret_key is HMAC-sign-only for signed requests (list_assessments); create_session and create_campaign send it directly as x-secret-key instead, since those endpoints authenticate with x-api-key + x-secret-key rather than a signature.
• There's a single deployed backend for this integration — no separate test/live URLs. base_url and webhook_base_url both default to it, and can each be overridden independently via the constructor params (e.g. for local testing). Webhook events do use a different response envelope though: {status, code, data} on success, {status, code, message} on error — not {success, data} like the rest of this client.

License

MIT