Skip to navigation

Initiate an ELP assessment call

Place an outbound call to a driver and run the FMCSA-aligned English Language Proficiency assessment. Creates an ELP test record in REQUESTED state, places the call, and links the two. Poll GET /v1/elp/tests/{test_id} to follow the test through to scoring.

Authentication: Supports API key and bearer token authentication.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

X-Organization-IDstring or nullOptional
Idempotency-KeystringOptional<=255 characters

A unique key (up to 255 printable ASCII characters, e.g. a UUID) that makes a retry of this request safe. Envoy stores the response for 24 hours; a retry with the same key and the same request returns it again with Idempotent-Replayed: true instead of running twice. The same key with a different request returns 422 idempotency_key_reused; while the first request is still running, 409 idempotency_key_in_progress. 5xx and 429 responses are not stored.

Request

This endpoint expects an object.
phone_numberstringRequired

Driver phone number to call (E.164 format)

Response

Successful Response
idstringformat: "^elp_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
statusenum

Lifecycle state of an ELP test.

Tracks whether the test ran, not its outcome quality. Outcome quality lives in the per-competency scores and the question counters (questions_answered, valid_answers). The system never renders a pass/fail verdict.

Allowed values:
created_atdatetime
call_idstring or nullOptionalformat: "^call_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
carrier_idstring or nullOptionalformat: "^car_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
phone_numberstring or nullOptional
driver_namestring or nullOptional
carrier_namestring or nullOptional
mc_numberstring or nullOptional
scoring_statusenum or nullOptional

Status of the post-call scoring pipeline.

Allowed values:
conversational_communicationinteger or nullOptional
instruction_comprehensioninteger or nullOptional
sign_recognitioninteger or nullOptional
verbal_reportinginteger or nullOptional
total_scoreinteger or nullOptional
total_questionsinteger or nullOptional
questions_answeredinteger or nullOptional
valid_answersinteger or nullOptional
notesstring or nullOptional
callobject or nullOptional
Associated phone call with transcript

Errors

401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error