> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.tryenvoy.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tryenvoy.ai/_mcp/server. # ELP Tests 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. | # | Competency | What the agent asks | What it tests | | -- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Q1 | Conversational 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. | | Q2 | Instruction 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. | | Q3 | Conversational 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. | | Q4 | Sign & 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. | | Q5 | Verbal Reporting | "You've just delivered freight and the bill of lading needs the truck number. Please say your truck 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") truck numbers are valid. The score reflects dictation clarity, not format. ## What gets scored | Area | Question(s) | What the question asks | | ---------------------------- | ----------- | ------------------------------------------------------------------- | | Conversational Communication | Q1, Q3 | Driver identifies themselves and answers a three-part open question | | Instruction Comprehension | Q2 | Driver responds to a multi-step spoken instruction | | Sign & Signal Recognition | Q4 | Driver reads a road sign and states the required action | | Verbal Reporting | Q5 | Driver 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:** ```mermaid stateDiagram-v2 [*] --> REQUESTED: POST /v1/elp/tests REQUESTED --> COMPLETED: call ended (full or partial test) REQUESTED --> FAILED: call never connected or dropped before any answer ``` **Scoring status:** ```mermaid stateDiagram-v2 [*] --> PENDING: call ends PENDING --> SCORED: scoring succeeds PENDING --> FAILED: scoring exhausted retries ``` The two statuses combine as follows: | `status` | `scoring_status` | Meaning | | ----------- | ---------------- | -------------------------------------------------------------------------------------------------------------- | | `REQUESTED` | `null` | Test created. Call not yet completed. | | `COMPLETED` | `PENDING` | Call finished. Scoring queued. | | `COMPLETED` | `SCORED` | Scores available. `elp_test.scored` fired. Compare `valid_answers` to `total_questions` to spot partial tests. | | `COMPLETED` | `FAILED` | Call finished but post-call analysis could not be completed. `elp_test.failed` fired. | | `FAILED` | `FAILED` | Call 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](/api-reference/api-reference/elp/create-test) 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](https://tryenvoy.ai/app/organization#webhooks). See the [Webhooks guide](/guides/core-concepts/webhooks) for the full setup: signature verification, retries, idempotency. Polling `GET /v1/elp/tests/{test_id}` ([reference](/api-reference/api-reference/elp/get-result)) also works for one-off cases. ![Webhook delivery log showing elp\_test.scored deliveries. Same endpoint detail page covered in the Webhooks guide.](/_fern-img/c176d3bd4d9a9ef1131a1825d104bb9fd7f1326a3f8a2a3daa0ef174e7567f61.webp) ## Step 3: Read the scored test The full response shape lives in the [Get ELP test API reference](/api-reference/api-reference/elp/get-result), including an example payload. The fields below are the ones worth understanding when interpreting a `SCORED` test. ### Field reference | Field | Meaning | | ------------------------------ | ----------------------------------------------------------------------------------------------------- | | `conversational_communication` | 1–10. Average of Q1 and Q3 scores. | | `instruction_comprehension` | 1–10. Score on Q2. | | `sign_recognition` | 1–10. Score on Q4. | | `verbal_reporting` | 1–10. Score on Q5. | | `total_score` | Sum of the four competency scores, scaled to 100. | | `questions_answered` | Count of questions the driver produced any audible response to (0–5). | | `valid_answers` | Subset of `questions_answered` where the response was in English and on-topic enough to assess (0–5). | | `notes` | Observational summary of the call. | | `driver_name` / `carrier_name` | Extracted from the driver's Q1 answer. Either may be `null` if not clearly stated. | ## Failure modes | Scenario | `status` | `scoring_status` | What it means | What to do | | ----------------------- | ----------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Call never connected | `FAILED` | `FAILED` | Busy, no answer, voicemail, or telephony error before the agent could engage | Create a new test ([reference](/api-reference/api-reference/elp/create-test)) once the driver is reachable | | Driver hung up mid-test | `COMPLETED` | `SCORED` | Call still ended cleanly; the scorer marks the unanswered questions as not-responded and the answered ones get their normal 1–10 score | Compare `valid_answers` to `total_questions` — a low ratio is the signal that a retake may be warranted | | Scoring failed | `COMPLETED` | `FAILED` | Call 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 * Set up webhook delivery: see [Webhooks](/guides/core-concepts/webhooks). * [Create an ELP test](/api-reference/api-reference/elp/create-test). Full API reference. * [Get an ELP test](/api-reference/api-reference/elp/get-result). Full API reference.