Overview

Introduction

The Career Coach Assessments API provides access to assessment question sets, traits, and scoring functionality. It allows you to generate, score, and store completed assessments to help users understand their occupational interests.

Currently, the assessments are based exclusively on Holland Occupational Themes (RIASEC), the same model used by the U.S. Department of Labor’s O*NET.

Note: If you are a United Kingdom user, skip to the UK Specific Notes. If you are a Canada user, skip to the CA Specific Notes.

Data Overview

The Career Coach Assessments API uses the RIASEC model, developed by using Holland Occupational Themes and used by the U.S. Department of Labor / O*NET to classify occupational interests.

The six RIASEC traits are:

O*NET has conducted interest profiler surveys across all 974 occupations, rating each career on a 1–7 scale for every RIASEC trait. Lightcast extends this dataset to include career categories and pathways by averaging the weights of careers in each category or pathway.

O*NET Information

This API includes information from O*NET OnLine by the U.S. Department of Labor, Employment and Training Administration (USDOL/ETA), used under the CC BY 4.0 license.

O*NET® is a trademark of USDOL/ETA. Lightcast has modified all or some of this information, and USDOL/ETA has not approved, endorsed, or tested these modifications.

Scoring Methodology & Algorithm

The Assessments API provides empirical question sets, where each question is correlated with a specific RIASEC trait. A user’s responses are weighted to calculate their personal RIASEC interest profile, similar to how O*NET’s Interest Profiler operates.

The algorithm then compares the user’s normalized trait weights against normalized weights for careers, categories, and pathways, producing a percent-match score (1–100). Due to normalization (feature scaling), top matches always have a score of 100%, while the lowest possible score is 1%.

Simplified Explanation: The API ranks each career, category, and pathway by how closely its RIASEC trait pattern matches the user’s traits.

UK Specific Notes

• All UK queries should target: https://cc.emsiservices.com/assessments/results/uk instead of the base /results endpoint.
• All methodology remains tied to O*NET codes.
• UK SOC codes are translated to O*NET codes for scoring, then translated back to SOC for final results.
• UK-specific examples can be found in the Reference section.

CA Specific Notes

• All CA queries should target: https://cc.emsiservices.com/assessments/results/ca instead of the base /results endpoint.
• All methodology remains tied to O*NET codes.
• Canadian NOC codes are translated to O*NET codes for scoring, then translated back to NOC for final results.
• CA-specific examples can be found in the Reference section.

Resource Structure

Each route in this API is prefixed by /assessments. The API provides access to the following collections:

1. All Assessment Questions
2. Single Set of Assessment Questions
3. All Assessment Traits
4. Single Assessment Trait
5. Assessment Results
6. Single Assessment Score

Building an Assessment

Here's how to build an assessment similar to the one we use on the Career Coach frontend:

1. Retrieve a question set that will serve as "trait prompts" for your users. For example, the 6-question assessment set is available at /assessments/questions/short.

2. Weight each trait as the user answers questions. The frontend takes the average of each question and normalizes it on a scale of 1–10. Note: If all trait values are identical, the API will return an error. Equally weighted traits would result in every career being a 100% match, which is the same as not taking the assessment at all.

3. Pass the results object with trait IDs and weights to the API at /assessments/results to get an assessment ID with full results.

4. Optionally, display the user's top 3 (+/-) traits with full descriptions available from /assessments/traits.

5. Query the user's assessment ID to get career, career category, and career pathway percent matches. Use this data to query the Careers API for personalized recommendations.

curl --request POST \
  --url 'https://cc.emsiservices.com/assessments/results' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --data '{
    "data": {
      "type": "assessment",
      "attributes": {
        "question-set": "short",
        "results": [
          { "trait-id": "R", "weight": 10 },
          { "trait-id": "I", "weight": 2 },
          { "trait-id": "A", "weight": 4 },
          { "trait-id": "S", "weight": 5 },
          { "trait-id": "E", "weight": 10 },
          { "trait-id": "C", "weight": 3 }
        ]
      }
    }
  }'

{
  "data": {
    "type": "assessment",
    "id": "8d1e132a7b244111bf5d1d4ebb2414df",
    "attributes": {
      "assessment-id": "8d1e132a7b244111bf5d1d4ebb2414df",
      "date": "2025-10-25T19:06:13.097Z"
    }
  }
}

API Endpoint

There are multiple endpoints within this category. Refer to individual API docs under the Career Coach Assessments API section.

Request Headers

Authentication

All endpoints in this category require an OAuth 2.0 Bearer Token for authentication. Tokens are granted through Lightcast’s Authentication API and are valid for 1 hour.

To access the Career Coach Assessment API, the token must include the following scope:

• assessments (for expanded access)

Sample Request

curl --request POST \
  --url https://auth.emsicloud.com/connect/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'client_id=<CLIENT_ID>' \
  --data 'client_secret=<CLIENT_SECRET>' \
  --data grant_type=client_credentials \
  --data scope=assessments

Request Parameters

Sample Response

{
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Note that the Tokens expire after 3600 seconds. To maintain uninterrupted access, refresh the token before it expires. To know more about this, refer to the Authentication guide.

Response Parameters

Status Code Summary

Versioning

The Career Coach Assessment API is currently at version 1.0. New data updates, fields, and minor hotfixes may be added at any time and are not considered breaking changes.

Data is typically refreshed once per quarter, as new economic information becomes available. Clients will be notified when new data or features are released.

In the rare event that a version is deprecated, clients will receive at least 90 days’ notice to update their queries to the new format.