Use Cases

ELP Tests

Administer English Language Proficiency tests over the phone, then receive structured scores via webhook.

An ELP test is a phone-based English Language Proficiency assessment for commercial motor vehicle drivers. Our voice agent calls the driver, asks five scripted questions across four communication areas, and reports a per-area score after the call.

Test questions

The agent reads all five questions verbatim, in order, one at a time. The five questions stay fixed across all tests so scores are comparable between drivers.

#CompetencyWhat the agent asksWhat it tests
Q1Conversational Communication”What’s your full name and what company do you drive for?”Driver identifies themselves and their carrier in natural English. Both pieces should be present; phrasing and formality do not matter.
Q2Instruction Comprehension”You arrive at a USPS facility. An employee says: ‘Please back into door fourteen and bring your paperwork to the office window.’ What do you do?”Driver demonstrates comprehension of a two-step spoken instruction (back into a door, then bring paperwork to the office). The exact door number is not required.
Q3Conversational Communication”A DOT inspector asks you: ‘What are you hauling today, where are you coming from, and where are you going?’ Please answer in your own words.”Driver answers a three-part open question (cargo, origin, destination) in their own words. State-level or regional place names are fine.
Q4Sign & Signal Recognition”You see a sign that says: ‘No Idling - Shut Engine Off.’ What should you do?”Driver understands the sign means “turn the engine off / don’t idle” and states that required action. Reading the sign back word-for-word is not required.
Q5Verbal Reporting”You’ve just delivered freight and the bill of lading needs the trailer number. Please say your trailer number out loud like you’re filling in the form.”Driver dictates a record-entry value (numeric or alphanumeric) clearly enough that a listener could write it into a form.

Scoring leniency (what the scorer accepts as a high-band answer):

  • Q1: First name plus carrier is fine (“Joe, Joe’s Trucking”). Full legal name not required.
  • Q2: The exact door number is not required. The competency tested is multi-step comprehension (back into a door, then bring paperwork), not number recall.
  • Q3: State-level, regional, or facility names all count for origin and destination. Exact place names not required.
  • Q4: The required answer is the action (turn the engine off, don’t idle). Reading the sign back word-for-word is not required.
  • Q5: Both numeric (“5327”) and alphanumeric (“ABC1234”) trailer numbers are valid. The score reflects dictation clarity, not format.

What gets scored

AreaQuestion(s)What the question asks
Conversational CommunicationQ1, Q3Driver identifies themselves and answers a three-part open question
Instruction ComprehensionQ2Driver responds to a multi-step spoken instruction
Sign & Signal RecognitionQ4Driver reads a road sign and states the required action
Verbal ReportingQ5Driver dictates a record-entry value out loud

Each area is scored 1–10. Q1 and Q3 are averaged into a single Conversational Communication score.

Lifecycle

An ELP test moves through two parallel statuses. status tracks the call. scoring_status tracks the post-call analysis.

Call status:

Scoring status:

The two statuses combine as follows:

statusscoring_statusMeaning
REQUESTEDnullTest created. Call not yet completed.
COMPLETEDPENDINGCall finished. Scoring queued.
COMPLETEDSCOREDScores available. elp_test.scored fired. Compare valid_answers to total_questions to spot partial tests.
COMPLETEDFAILEDCall finished but post-call analysis could not be completed. elp_test.failed fired.
FAILEDFAILEDCall never connected (busy, no answer, telephony error, or voicemail). elp_test.failed fired.

Scoring is fully automated and typically completes within a minute of call end.

Step 1: Create a test

Call POST /v1/elp/tests with the driver’s phone number (E.164). See the Create ELP test reference for the full request and response schema.

The response returns the test row in the REQUESTED state with its id and a call_id. The voice agent dials the number immediately, so hand the driver the phone before you create the test, or expect a missed-call follow-up.

Step 2: Receive the score via webhook

The recommended pattern is to subscribe to two webhook events:

  • elp_test.scored fires when scoring completes successfully.
  • elp_test.failed fires when the test reaches a terminal failure state (the call never connected, the call ended without scoring, or scoring exhausted its retries).

Each event fires exactly once per test, and its data field carries the same body as GET /v1/elp/tests/{test_id}. Inspect the payload’s status and scoring_status fields to disambiguate the outcome; notes carries the human-readable failure reason on the failed event.

To subscribe, register a webhook endpoint with elp_test.scored and elp_test.failed in event_types. You can do this from the dashboard at Organization → Webhooks. See the Webhooks guide for the full setup: signature verification, retries, idempotency.

Polling GET /v1/elp/tests/{test_id} (reference) also works for one-off cases.

Webhook delivery log showing elp_test.scored deliveries. Same endpoint detail page covered in the Webhooks guide.

Step 3: Read the scored test

The full response shape lives in the Get ELP test API reference, including an example payload. The fields below are the ones worth understanding when interpreting a SCORED test.

Field reference

FieldMeaning
conversational_communication1–10. Average of Q1 and Q3 scores.
instruction_comprehension1–10. Score on Q2.
sign_recognition1–10. Score on Q4.
verbal_reporting1–10. Score on Q5.
total_scoreSum of the four competency scores, scaled to 100.
questions_answeredCount of questions the driver produced any audible response to (0–5).
valid_answersSubset of questions_answered where the response was in English and on-topic enough to assess (0–5).
notesObservational summary of the call.
driver_name / carrier_nameExtracted from the driver’s Q1 answer. Either may be null if not clearly stated.

Failure modes

Scenariostatusscoring_statusWhat it meansWhat to do
Call never connectedFAILEDFAILEDBusy, no answer, voicemail, or telephony error before the agent could engageCreate a new test (reference) once the driver is reachable
Driver hung up mid-testCOMPLETEDSCOREDCall still ended cleanly; the scorer marks the unanswered questions as not-responded and the answered ones get their normal 1–10 scoreCompare valid_answers to total_questions — a low ratio is the signal that a retake may be warranted
Scoring failedCOMPLETEDFAILEDCall succeeded but post-call analysis could not be completed (no transcript, retries exhausted)notes carries the reason; contact support for a manual rescore

elp_test.scored fires on SCORED outcomes; elp_test.failed fires on every terminal failure (call never connected, call ended without scoring, or scoring exhausted retries). Subscribe to both event types to get full lifecycle coverage. The failure reason is on the notes field of the payload.

Reading the data

  • valid_answers vs. questions_answered. If valid_answers < questions_answered, the driver responded but the response was off-topic, non-English, or otherwise unscorable. The competency score reflects that.
  • STT mishear disclosure. When the scorer extends leniency for a probable speech-to-text artifact (heavy accent on a short or jargon-heavy phrase), it discloses this in notes along with what it inferred the driver actually said. For example: “Q3 contained ‘Holly Mayo’ where the cargo word would go; treated as a probable STT mishear of ‘hauling mail’.”
  • Anomaly notes. Edge cases (a substantive answer scoring 1, an empty segmenter window) are flagged in notes for review.

Next steps