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 — see Notes below
)

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 results

Fired by record-assessment-backend when a candidate submits or is disqualified — event types assessment.completed / assessment.disqualified:

result = client.get_webhook_events()
for event in result["events"]:
    print(event["event"], event["assessmentId"], event.get("score"))
if result["events"]:
    client.acknowledge_webhook_events([e["eventId"] for e in result["events"]])

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.
• Webhook events are served by a different backend (record-assessment-backend, not the assessment-portal backend that everything else in this client talks to) — that's the service that actually runs candidate exam sessions and fires assessment.completed once one is submitted or disqualified. Its response envelope is also different: {status, code, data} on success, {status, code, message} on error — not {success, data} like the rest of this client.

License

MIT