Evalingo - AI Language Assessment

API Documentation

Integrate Evalingo assessments into your ATS or hiring workflow.

Base URL

https://evalingo.ai/api/v1

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

curl -X GET "https://evalingo.ai/api/v1/assessments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Demo API Key

For testing, use: demo_api_key_12345

Endpoints

POST/api/v1/assessments

Create a new assessment for a candidate

Parameters

Name	Type	Required	Description
candidate.email	string	Yes	Candidate email address
candidate.firstName	string	No	Candidate first name
candidate.lastName	string	No	Candidate last name
candidate.externalId	string	No	Your internal ID for the candidate
assessmentType	enum	No	FULL, SPEAKING, or WRITING (default: FULL)
language	string	No	Language code: en, es, fr, de, etc. (default: en)
externalRef	string	No	Your reference ID (e.g., job posting ID)
webhookUrl	string	No	URL to receive completion notifications

Request Body

{
  "candidate": {
    "email": "john@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "externalId": "your-ats-id-123"
  },
  "assessmentType": "FULL",
  "language": "en",
  "externalRef": "job-posting-456",
  "webhookUrl": "https://your-server.com/webhook"
}

Response Example

{
  "id": "clx1234567890",
  "token": "abc123xyz",
  "assessmentUrl": "https://evalingo.ai/assessment/abc123xyz",
  "status": "PENDING",
  "expiresAt": "2024-01-15T00:00:00.000Z"
}

Webhooks

Receive real-time notifications when assessments are completed.

When creating an assessment, provide a webhookUrl to receive a POST request when the assessment is completed and scored.

Webhook Payload

{
  "event": "assessment.completed",
  "timestamp": "2024-01-10T10:25:00.000Z",
  "data": {
    "assessmentId": "clx1234567890",
    "externalRef": "job-posting-456",
    "candidate": {
      "email": "john@example.com",
      "externalId": "your-ats-id-123"
    },
    "result": {
      "overallLevel": "B2",
      "overallScore": 68,
      "speakingLevel": "B2",
      "speakingScore": 72,
      "writingLevel": "B1",
      "writingScore": 64
    }
  }
}

CEFR Levels

Understanding the Common European Framework of Reference for Languages.

A1(0-20)

Beginner

Can understand and use familiar everyday expressions.

A2(21-40)

Elementary

Can communicate in simple and routine tasks.

B1(41-55)

Intermediate

Can deal with most situations while traveling.

B2(56-70)

Upper Intermediate

Can interact with fluency and spontaneity.

C1(71-85)

Advanced

Can express ideas fluently and spontaneously.

C2(86-100)

Proficient

Can understand virtually everything heard or read.