SkillsEngine

SkillsEngine API Developer Hub

Welcome to the SkillsEngine API Developer Hub. You'll find comprehensive guides and documentation to help you start working with the SkillsEngine API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Getting Started    Support
Suggest Edits

/api/token

Provides a standard token-retrieval endpoint. A valid access token is required for all subsequent requests of the API's endpoints.

 
posthttps://api.skillsengine.com/api/token
response = RestClient.post 'https://api.skillsengine.com/api/token', {
  grant_type: 'client_credentials',
  client_id: client_id,
  client_secret: client_secret
}
A binary file was returned

You couldn't be authenticated

{"access_token":"2aa1c12f3a6c17bf832d57c7ea6244071777dd64d6a489a1fe0654dfabe7a44a","token_type":"bearer","expires_in":3600,"created_at":1441141199}
{"message":"Unauthorized, expired, or incorrect token request syntax"}

Body Params

grant_type
string
required
client_id
string
required

your assigned Client ID

client_secret
string
required

your assigned Client Secret

 
Suggest Edits

/api/test

Provides a simple endpoint for testing if your code and access token are valid for making requests of any of the API's other endpoints. This test endpoint does not consume a request for paying customers.

 
gethttps://api.skillsengine.com/api/test
access_token = "2aa1c12f3a6c17bf832d57c7ea6244071777dd64d6a489a1fe0654dfabe7a44a"
RestClient.get 'https://api.skillsengine.com/api/test',
  { 'Authorization' => "Bearer #{access_token}" }
A binary file was returned

You couldn't be authenticated

{"message":"Token is authorized"}
{"message":"Unauthorized, expired, or incorrect token request syntax"}
 

Authorization Header Required

Like all endpoints (except the oauth/token endpoint), this endpoint requires an Authorization header attribute with a valid Bearer <access-token>.

Suggest Edits

/v2/skills/freshness

Provides a simple endpoint for retrieving a "freshness tag." Similar to HTTP Etags, you should request this tag periodically and store it in your app's datastore. This can be used to determine if any skills data has been updated on the SkillsEngine side since the last time you checked. If it hasn't, and you know that YOUR request data has not changed, then there's no need to make that same request, potentially saving you (and us!) many computationally-expensive requests that would just return the same data as last time.

 
gethttps://api.skillsengine.com/v2/skills/freshness
GET /v2/skills/freshness
A binary file was returned

You couldn't be authenticated

{"result":{"freshness_tag":"2a12aba8dcabc23f250c78dff46b5661"}}
 
Suggest Edits

/v2/competencies/analyze/flatten

This endpoint parses unstructured text, evaluates that text, and produces a detailed competencies profile in a flattened structure with relevancy scores. If you'd rather have work activities arranged in a hierarchical tree, see the /v2/competencies/analyze endpoint.

 
posthttps://api.skillsengine.com/v2/competencies/analyze/flatten
POST /v2/competencies/analyze/flatten

{"text":"Provide substance abuse education and counseling for at-risk individuals.","bias":0.4}
A binary file was returned

You couldn't be authenticated

{
  "result": {
    "competencies_analysis": {
      "metadata": {},
      "occupations": [],
      "general_work_activities": [],
      "intermediate_work_activities": [],
      "detailed_work_activities": [],
      "workplace_essentials": [],
      "knowledges": [],
      "knowledge_subdomains": [],
      "skills": [],      
      "abilities": [],     
      "tools": [],      
    }
  }
}
// see Analysis Elements for details

Body Params

text
string
required

unstructured text to analyze

bias
string

decimal between 0.1 and 1.0; biases the analysis algorithms towards more granular or more general results

exclude
string

comma-separated list of element types to exclude from the analysis (see Excluding Elements)

 

Why "Flattened"?

While we believe the original hierarchical view of work activities holds tremendous value in showing how more granular activities relate to parent, higher-level groupings of activities, it became clear to us in talking with consumers of the API that there was often a greater desire to receive a simplified flat list of each type of work activity with corresponding scoring that shows how relevant a single work activity is to all of its siblings, regardless of parentage.

Analysis Elements

See the original, hierarchical Profiler for detailed information on the other available elements...

Flattened Work Activities

      "general_work_activities": [
        {
          "version": 2,
          "title": "Training and Teaching Others",
          "guid": "073cc097-39c5-4384-b410-2195e609634e",
          "score": 45.52
        },
        {
          "version": 2,
          "title": "Provide Consultation and Advice to Others",
          "guid": "abe6cddd-0679-4491-ad7a-a672d72ceffb",
          "score": 43.5
        },
        ...
      ],
      "intermediate_work_activities": [
        {
          "version": 2,
          "title": "Counsel others about personal matters",
          "guid": "4b5db412-c1b8-47e4-9606-03244fdd7880",
          "score": 33.82
        },
        {
          "version": 2,
          "title": "Evaluate patient or client condition or treatment options",
          "guid": "a7f7d765-c8ca-42bd-b7a6-8ac184cfefc1",
          "score": 28.82
        },
        ...
      ],
      "detailed_work_activities": [
        {
          "version": 2,
          "title": "Assist clients with understanding personal problems",
          "guid": "c1ccb7e1-2ff2-4a3a-b442-ef3b9d264a51",
          "score": 16.47
        },
        {
          "version": 2,
          "title": "Counsel clients or patients regarding personal issues or problems",
          "guid": "663e4b83-9fdb-4170-9888-e00c0731bd59",
          "score": 15.61
        },
        ...
      ]

Suggest Edits

/v2/competencies/analyze

This endpoint parses unstructured text, evaluates that text, and produces a detailed competencies profile, with work activities arranged in a hierarchical tree where relevancy scores are contextualized to branches of the tree.

 
posthttps://api.skillsengine.com/v2/competencies/analyze
POST /v2/competencies/analyze

{"text":"i am a welder and used welding equipment and acetylene torches","bias":0.4}
A binary file was returned

You couldn't be authenticated

{
  "result": {
    "competencies_analysis": {
      "metadata": {},
      "occupations": [],
      "general_work_activities": [],
      "workplace_essentials": [],
      "knowledges": [],
      "knowledge_subdomains": [],
      "skills": [],      
      "abilities": [],     
      "tools": [],      
    }
  }
}
// see Analysis Elements for details

Body Params

text
string
required

unstructured text to analyze

bias
string

decimal between 0.1 and 1.0; biases the analysis algorithms towards more granular or more general results

exclude
string

comma-separated list of element types to exclude from the analysis (see Excluding Elements)

 

Explanation

Profiler's response JSON includes a variety of arrays, each containing information Profiler has derived from the provided text. The analysis includes:

  • Occupations (ranked and ordered)
  • General Work Activities (as a hierarchy, ranked and ordered)
    • Intermediate Work Activities
      • Detailed Work Activities
  • Workplace Basics (ranked and ordered)
  • Knowledges (ranked and ordered)
    • Knowledge Subdomains (ranked and ordered)
  • Skills (ranked and ordered)
  • Abilities (ranked and ordered)
  • Tools and Technologies (ranked and ordered)

Note that the work activities are presented as a hierarchy of nested arrays, each containing many hashes. This is because General, Intermediate, and Detailed work activities are associated in a hierarchical structure and the analysis is intended to preserve those valuable relationships. Developers can, of course, extract information from this structure and aggregate, roll-up, re-sort, etc. as they see fit for use in their own application.

Analysis Elements

Profiler's response JSON includes several elements:

Metadata

Notes some basic metadata about this specific analysis...

"metadata": {
  "text_size": 12345,
  "state_code": "TX",
  "parse_time": 0.243965
}

Occupations

O*NET Standard Occupational Classification codes, titles, and relevancy scores.

"occupations": [
  {
    "code": "51-4121",
    "title": "Welders, Cutters, Solderers, and Brazers",
    "score": 63.12
  },
  {
    "code": "51-4122",
    "title": "Welding, Soldering, and Brazing Machine Setters, Operators, and Tenders",
    "score": 36.88
  }
]

Work Activities Tree

A work activity describes how major units of time are organized on the job. Every statement theoretically has distinctive starting and ending points. Each is observable and produces results susceptible to being measured. Each array includes a General high-level statement, more specific Intermediate statement and, finally, the Detailed Work Activity. Each Detailed Work Activity includes an action verb (required), object (required), and contextual modifiers.

"general_work_activities": [
  {
    "score": 36.35,
    "title": "Handling and Moving Objects",
    "intermediate_work_activities": [
      {
        "score": 49.57,
        "title": "Assemble equipment or components.",
        "detailed_work_activities": [
          {
            "score": 43.64,
            "title": "Construct patterns or templates for welding projects"
          },
          {
            "score": 37.22,
            "title": "Adjust equipment or instruments to specification"
          },
          ...
        ]
      },
      ...
    ]
  },
  ...
]

Workplace Essentials

Workplace Essentials (aka “soft skills”) are specific behaviors and characteristics that demonstrate general strengths in areas such as teamwork, attention to detail, communication and customer service. SkillsEngine uses 30 statements to describe the most important social and behavioral characteristics.

"workplace_essentials": [
  [ "Attention to Detail", 93.74 ],
  [ "Work Ethic", 28.68 ],
  [ "Information Gathering", 10.06 ],
  [ "Following Directions", 8.29 ],
  ...
]

Knowledges, Knowledge Subdomains, Skills, and Abilities

Knowledges, Skills and Abilities can be assigned both to people and to jobs making them valuable indicators in the job matching process. Knowledges are principles, bodies of content and facts generally applied within academic domains. Knowledge Subdomains are a more granular breakout of Knowledges into topics of greater detail within the context of the parent Knowledge. A Skill is a developed capacity like time management or information gathering that facilitates performance of various tasks and activities across occupations or the rapid acquisition of relevant knowledge. An Ability is an attribute of an individual that can influence performance on the job.

"knowledges": [
  [ "Mechanical", 92.01 ],
  [ "Production and Processing", 32.67 ],
  [ "Building and Construction", 15.87 ],
  ...
]
"skills": [
  [ "Operation and Control", 63.38 ],
  [ "Equipment Selection", 44.57 ],
  [ "Reading Comprehension", 39.63 ],
  ...
]
"abilities": [
  [ "Manual Dexterity", 93.06 ],
  [ "Deductive Reasoning", 18.82 ],
  [ "Information Ordering", 17.77 ],
  ...
]

Tools and Technologies (experimental)

Tools and Technologies output is currently considered an experimental feature and is only intended for use in early stage development and prototyping.

"tools_techs": [
  {
    "score": 89.08,
    "type": "Tools",
    "title": "Speed sensors",
    "example": "Wire feed rate measurement instruments"
  },
  {
    "score": 59.39,
    "type": "Tools",
    "title": "Desktop computers",
    "example": "Desktop computers"
  },
  {
    "score": 29.69,
    "type": "Technology",
    "title": "Analytical or scientific software",
    "example": "Scientific Software Group Filter Drain FD"
  },
  ...
]

Relevancy Scores

Our scoring mechanisms are based on a number of factors, including result frequencies and proprietary weights. The intent is to provide the consumer of the data with a simple way to sort and compare general relevance of a particular element with other elements of the same type. Within a group of elements of the same type, higher scores indicate greater relevance of that element to the overall analysis than lower scores.

Scores are relative only to elements of the same type (General Work Activity scores have no relevance to Detailed Work Activity scores, for example)

Suggest Edits

Excluding Elements

 

Profiler supports more precise shaping of API requests in order to specifically exclude any of the normally-returned skill elements. This allows consumers of the API to determine what they do and do not need, which consequently makes the response smaller and the processing of the request quicker.

To exclude elements from the response, simply provide an exclude parameter with a comma-separated list of one or more element names that should not be in the response.

metadata
occupations
general_work_activities
intermediate_work_activities
detailed_work_activities
workplace_essentials
knowledges
knowledge_subdomains
skills
abilities
tools

This new functionality is optional. By default, both /competencies/analyze endpoints will return all data elements. To use the exclusion feature, simply provide an additional exclude parameter in the JSON body of your request:

POST /v2/competencies/analyze

{"text":"i am a welder and used welding equipment and acetylene torches","bias":0.4, "exclude":"occupations,detailed_work_activities,knowledges,abilities,tools"}

Caveat

The "flat" profile and "hierarchical" profile respond differently when asked to exclude one or more of the work_activities data elements.

For the flat profile, the response will simply exclude the specific work activities list(s) as specified in the request parameters.

For the hierarchical profile, the response will exclude the specific work activities specified as well as any sets below those in the tree. For example, asking to exclude intermediate_work_activities will exclude those as well as all detailed_work_activities. Asking to exclude general_work_activities will effectively exclude all work activity types from the response.

Suggest Edits

/v2/competencies/analyze/military

This endpoint evaluates a provided MOC (as well as some additional optional parameters) and produces a detailed competencies profile in a flattened structure that represents civilian skills and occupations that most closely relate to the military role identified by the MOC.

 
posthttps://api.skillsengine.com/v2/competencies/analyze/military
POST /v2/competencies/analyze/military

{"moc":"2A554E"}
A binary file was returned

You couldn't be authenticated

{
  "result": {
    "competencies_analysis": {
      "metadata": {},
      "occupations": [],
      "general_work_activities": [],
      "intermediate_work_activities": [],
      "detailed_work_activities": [],
      "workplace_essentials": [],
      "knowledges": [],
      "knowledge_subdomains": [],
      "skills": [],      
      "abilities": [],     
      "tools": [],
      "mocs": []
    }
  }
}
// see Analysis Elements for details

Body Params

moc
string
required

known MOC in all-caps

service_branch
string

helps disambiguate MOCs used by more than one service; must be navy, army, coast guard, marine corps, air force, or special forces

mpc
string

helps disambiguate different military roles held; must be one of officer, warrant, or enlisted

exclude
string

comma-separated list of element types to exclude from the analysis (see Excluding Elements in the Profiler section)

start_date
string

when the individual started their service; helps disambiguate in the case where a MOC was later recycled for a new use

end_date
string

when the individual completed their service; helps disambiguate in the case where a MOC was later recycled for a new use

moc_status
string

leave blank, or one of current_only, obsolete_only, or all

 

Analysis Elements

Occupations

In the case of the Warrior endpoint, you may notice that the Occupations list does not include scores. This is intentional. Because of how Warrior does its inference, scores are not available for the occupations matched. In the case of multiple occupational matches, all occupations should be considered equal-weight suggestions.

Flattened Work Activities

      "general_work_activities": [
        {
          "version": 2,
          "title": "Training and Teaching Others",
          "guid": "073cc097-39c5-4384-b410-2195e609634e",
          "score": 45.52
        },
        {
          "version": 2,
          "title": "Provide Consultation and Advice to Others",
          "guid": "abe6cddd-0679-4491-ad7a-a672d72ceffb",
          "score": 43.5
        },
        ...
      ],
      "intermediate_work_activities": [
        {
          "version": 2,
          "title": "Counsel others about personal matters",
          "guid": "4b5db412-c1b8-47e4-9606-03244fdd7880",
          "score": 33.82
        },
        {
          "version": 2,
          "title": "Evaluate patient or client condition or treatment options",
          "guid": "a7f7d765-c8ca-42bd-b7a6-8ac184cfefc1",
          "score": 28.82
        },
        ...
      ],
      "detailed_work_activities": [
        {
          "version": 2,
          "title": "Assist clients with understanding personal problems",
          "guid": "c1ccb7e1-2ff2-4a3a-b442-ef3b9d264a51",
          "score": 16.47
        },
        {
          "version": 2,
          "title": "Counsel clients or patients regarding personal issues or problems",
          "guid": "663e4b83-9fdb-4170-9888-e00c0731bd59",
          "score": 15.61
        },
        ...
      ]

MOCs

With the Warrior endpoint, we provide an additional array of the actual MOCs matched in our library, along with metadata about each. Because the same MOC might be used for different things by different service branches, or represent multiple MPCs within a single branch, this array may contain multiple elements. The intent is for this to provide downstream consumers with a means by which to prompt their users for more detail in order to focus the profile match (e.g. "Which of the following Service Branches did you mean?")

"mocs": [
	{
		"moc": "2A554E",
		"mpc": "enlisted",
		"service_branch": "air force",
		"moc_title": "Refuel/Bomber Aircraft Maintenance Journeyman, B-1"
  },
  ...
]

Other Elements

See the original, hierarchical Profiler for detailed information on the other available elements...

Suggest Edits

/v2/skills/match

This endpoint analyzes a single sentence and returns multiple related Detailed Work Activities from the SkillsEngine data library.

 
posthttps://api.skillsengine.com/v2/skills/match
POST /v2/skills/match

{"text":"Provide substance abuse education and counseling for at-risk individuals.","depth":20,"cutoff":5.0,"socs":"21-1023.00,21-1029.00,21-1091.00", "similarity_scoring": true}
A binary file was returned

You couldn't be authenticated

{
  "result": {
    "original_sentence": "Provide substance abuse education and counseling for at-risk individuals.",
    "skills": [
      {
        "version": 2,
        "guid": "663e4b83-9fdb-4170-9888-e00c0731bd59",
        "title": "Counsel clients or patients regarding personal issues or problems",
        "match_score": 36.89,
        "iwa_guid": "4b5db412-c1b8-47e4-9606-03244fdd7880",
        "iwa_title": "Counsel others about personal matters",
        "gwa_guid": "abe6cddd-0679-4491-ad7a-a672d72ceffb",
        "gwa_title": "Provide Consultation and Advice to Others",
        "matched_socs": [
          "21-1029.00",
          "21-1023.00"
        ]
      },
      {
        "version": 2,
        "guid": "936c9e29-9e0a-4c6d-b5ed-c2b0d7da49ab",
        "title": "Refer clients or others to community services or resources",
        "match_score": 30.74,
        "iwa_guid": "0cb36e6a-df8d-4ef4-8540-4f62f61b674e",
        "iwa_title": "Advise others on products or services",
        "gwa_guid": "abe6cddd-0679-4491-ad7a-a672d72ceffb",
        "gwa_title": "Provide Consultation and Advice to Others",
        "matched_socs": [
          "21-1029.00",
          "21-1023.00"
        ]
      },
      {
        "version": 2,
        "guid": "4c2f53f5-622a-4cbd-859b-02d5e1f099ad",
        "title": "Plan programs to address community health issues",
        "match_score": 28.6,
        "iwa_guid": "a1b32d32-d65c-433e-be6a-1425d333250f",
        "iwa_title": "Develop organizational or program goals or objectives",
        "gwa_guid": "14a32eba-d07a-4374-a1c4-1f4868d51fbf",
        "gwa_title": "Developing Objectives and Strategies",
        "matched_socs": [
          "21-1091.00",
          "21-1023.00"
        ]
      },
      ...
    ]
  }
}

Body Params

text
string
required

single sentence of text to analyze for related work activities. (cannot be more than 50 words)

depth
int32

adjusts the computational effort the matching algorithm will undertake in attempting to find matches; higher values means more processing, but potentially slower responses

cutoff
double

internal tuning cutoff threshold; adjusts the aggressiveness of relevant skill matching internally prior to final result composition

socs
string

(comma-separated, order-sensitive, optional but recommended); allows the requestor to provide occupational context for a match attempt by supplying one or more comma-separated 8-digit SOC codes. Providing SOC context will dramatically improve matching results in most cases.

similarity_scoring
boolean

(optional) 'true' will turn on optional text-similarity scoring, rather than relevance scoring (false by default)

 

Explanation

The skills/match endpoint allows consumers of the Matcher API to align unstructured skill text to the SkillsEngine library of work activities. The current incarnation of the endpoint allows for a single sentence per request, which is then analyzed and matched against thousands of detailed work activities. The best matches are then scored, sorted, and returned to the requestor in JSON format.

The intent of this endpoint is to help align text with our skill library, in order to find one or more work activities that match, are similar to, or are related to the text provided. By providing occupational context, the requestor can further shape these results to ensure contextually reasonable skill matches.

The socs Parameter

The most important parameter in tuning the results of this endpoint is the socs parameter. Via the socs parameter, a requestor can provide significant context to the matching algorithms, which in turn use that context to ensure resultant matches are more directly relevant to the occupational domain expected by the requestor. For example, without any context, the sentence "Repair buses" could refer to bus drivers (the automobile) or electronics or computer engineers (a data bus). Without occupational context, our algorithm will do the best it can in finding relevant matches, but with context (provided through the socs parameter), consumers of the API can ensure they get more of the matches they expect.

The socs parameter takes a list of multiple 8-digit SOC codes and the algorithm weights its contextualization based on the order of that list. That is, the algorithm considers the first SOC in the list to be of higher importance than the last SOC, so be sure to provide your list of SOCs in the proper order.

The cutoff Parameter

The cutoff parameter is a means by which the requestor can tune internal cutoffs intrinsic to the matching algorithm. It should be noted that this is NOT a "final cutoff" to redact output with a final relevancy score below X; instead, this tuning parameter changes the aggressiveness with which the matching algorithm seeks to populate the final results. A lower number (5.0) will result in a more diverse set of final matches; a higher number (20.0) will significantly limit the final results. In either case, the final resultant matches' scores will be scaled across a spectrum from 1.0 to 99.0 (and we by default don't return any results with a final scaled score lower than 20.0).

Response Data Structure

Root Key

As with the majority of SkillsEngine endpoints, the root key in a successful JSON response is result (the root key in a failure is error).

Original Sentence

The two second-level siblings in the /v2/skills/match response are original_sentence and skills. The original sentence refers to the actual text sentence sent in the original request -- the sentence we analyzed in order to find matches.

Skills

The skills key has as its value a sorted array of hashes. Each hash in that array represents a single Detailed Work Activity that we have matched with the original sentence, as well as a relevancy score. The skills are returned in order of score, highest relevancy first. Each skill hash includes the following elements:

    "version": 2,
    "guid": "936c9e29-9e0a-4c6d-b5ed-c2b0d7da49ab",
    "title": "Refer clients or others to community services or resources",
    "match_score": 30.74,
    "iwa_guid": "0cb36e6a-df8d-4ef4-8540-4f62f61b674e",
    "iwa_title": "Advise others on products or services",
    "gwa_guid": "abe6cddd-0679-4491-ad7a-a672d72ceffb",
    "gwa_title": "Provide Consultation and Advice to Others",
    "matched_socs": [
      "21-1029.00",
      "21-1023.00"
    ]
  • version -- the version identifier for this Detailed Work Activity as retrieved from our core library at that moment.
  • guid -- the globally unique identifier for this Detailed Work Activity
  • title -- the textual title of this Detailed Work Activity
  • match_score -- the relevancy score as computed by our matching algorithm
  • iwa_guid -- the globally unique identifier for the Intermediate Work Activity that exists as the parent of this Detailed Work Activity in our core library
  • iwa_title -- the textual title of the parent Intermediate Work Activity
  • gwa_guid -- the globally unique identifier for the Intermediate's parent General Work Activity (the grandparent of the Detailed Work Activity)
  • gwa_title -- the textual title of the parent General Work Activity
  • matched_socs -- an array of 8-digit SOC codes that indicate when a matched skill is associated in our core library with one or more of the contextual SOCs provided in the original request. This array may be empty in the case where no contextual SOCs were provided, or in the case where a relevant skill was found that is not associated in our library with any of the contextual SOCs specified.

Limitations

The skills/match endpoint is limited to analyzing a single sentence of no more than 50 words. Requests that provide a sentence larger than 50 words will return a 422 and an error message.

Authorization Header Required

This endpoint requires an Authorization header attribute with a valid Bearer <access-token>.

Suggest Edits

/v2/skills/multi_match

This endpoint analyzes a bulk array of multiple sentences and returns an array containing each original sentence paired with multiple related Detailed Work Activities from the SkillsEngine data library.

 
posthttps://api.skillsengine.com/v2/skills/multi_match
POST /v2/skills/multi_match

{"sentences":["Weld things together", "Use an acetylene torch", "Hammer nails into wood"],"depth":20,"cutoff":5.0,"socs":"17-2141.00,49-9041.00,49-1011.00,49-9071.00"}
A binary file was returned

You couldn't be authenticated

{
  "result": [
    {
      "original_sentence": "weld things together",
      "skills": [
        {
          "version": 2,
          "guid": "539f8155-091c-4d0e-92ef-87e270b49cad",
          "title": "Weld metal structures",
          "match_score": 79.72,
          "iwa_guid": "2eabe35f-6a7e-4ad2-8f6c-4840ff4924a5",
          "iwa_title": "Join parts using soldering, welding, or brazing techniques",
          "gwa_guid": "2e603185-6389-4d71-8789-538d3ff65f04",
          "gwa_title": "Handling and Moving Objects",
          "matched_socs": [
            "49-9071.00",
            "49-9041.00",
            "49-1011.00"
          ]
        },
        {
          "version": 2,
          "guid": "93acf6aa-60da-42eb-b9a3-378332bee348",
          "title": "Weld metal parts and components",
          "match_score": 38.49,
          "iwa_guid": "2eabe35f-6a7e-4ad2-8f6c-4840ff4924a5",
          "iwa_title": "Join parts using soldering, welding, or brazing techniques",
          "gwa_guid": "2e603185-6389-4d71-8789-538d3ff65f04",
          "gwa_title": "Handling and Moving Objects",
          "matched_socs": [
            "49-9071.00",
            "49-9041.00"
          ]
        }
      ]
    },
    {
      "original_sentence": "use an acetylene torch",
      "skills": [
        {
          "version": 2,
          "guid": "539f8155-091c-4d0e-92ef-87e270b49cad",
          "title": "Weld metal structures",
          "match_score": 46.49,
          "iwa_guid": "2eabe35f-6a7e-4ad2-8f6c-4840ff4924a5",
          "iwa_title": "Join parts using soldering, welding, or brazing techniques",
          "gwa_guid": "2e603185-6389-4d71-8789-538d3ff65f04",
          "gwa_title": "Handling and Moving Objects",
          "matched_socs": [
            "49-9071.00",
            "49-9041.00",
            "49-1011.00"
          ]
        },
        {
          "version": 2,
          "guid": "39b619cc-52dd-4132-9caa-d3d0c8db0983",
          "title": "Heat material or workpieces to prepare for or complete production",
          "match_score": 37.69,
          "iwa_guid": "b56307f4-6963-4591-87c1-a2f3b11491b6",
          "iwa_title": "Adjust equipment to ensure adequate performance",
          "gwa_guid": "2e603185-6389-4d71-8789-538d3ff65f04",
          "gwa_title": "Handling and Moving Objects",
          "matched_socs": []
        }
      ]
    },
    {
      "original_sentence": "hammer nails into wood",
      "skills": [
        {
          "version": 2,
          "guid": "c95af047-703a-4e60-9796-ffba18ae8573",
          "title": "Install wooden structural components such as sub flooring, rough framing, or partitions",
          "match_score": 52.53,
          "iwa_guid": "3282f5be-69d0-418f-a4fc-9c6831e33301",
          "iwa_title": "Build structures",
          "gwa_guid": "95cb0aab-48a1-4248-8f15-ce3e2895b289",
          "gwa_title": "Performing General Physical Activities",
          "matched_socs": []
        },
        {
          "version": 2,
          "guid": "38398f36-959a-4598-84fa-6f725b03b909",
          "title": "Assemble wood or carpentry products",
          "match_score": 40.22,
          "iwa_guid": "b64a3c52-78d6-417d-a803-3e2db6e73b1d",
          "iwa_title": "Assemble products or work aids",
          "gwa_guid": "2e603185-6389-4d71-8789-538d3ff65f04",
          "gwa_title": "Handling and Moving Objects",
          "matched_socs": []
        }
      ]
    }
  ]
}

Body Params

sentences
array of strings
required

an array of text sentences to analyze for related work activities. (cannot be more than 20 sentences)

depth
int32

adjusts the computational effort the matching algorithm will undertake in attempting to find matches; higher values means more processing, but potentially slower responses

cutoff
double

internal tuning cutoff threshold; adjusts the aggressiveness of relevant skill matching internally prior to final result composition

socs
string

(comma-separated, order-sensitive, optional but recommended); allows the requestor to provide occupational context for a match attempt by supplying one or more comma-separated eight-digit SOC codes. Providing SOC context will dramatically improve matching results in most cases.

similarity_scoring
boolean

(optional) 'true' will turn on optional text-similarity scoring, rather than relevance scoring (false by default)

 

Explanation

The skills/multi_match endpoint allows consumers of the Matcher API to align unstructured skill text to the SkillsEngine library of work activities in bulk. Unlike the standard match endpoint, multi_match allows for an array of multiple sentences (up to 20) sent as part of a single request, all of which are then analyzed and matched against thousands of detailed work activities. The best matches for each provided sentence are then scored, sorted, and returned to the requestor in JSON format.

The socs Parameter

The most important parameter in tuning the results of this endpoint is the socs parameter. Via the socs parameter, a requestor can provide significant context to the matching algorithms, which in turn use that context to ensure resultant matches are more directly relevant to the occupational domain expected by the requestor. For example, without any context, the sentence "Repair buses" could refer to bus drivers (the automobile) or electronics or computer engineers (a data bus). Without occupational context, our algorithm will do the best it can in finding relevant matches, but with context (provided through the socs parameter), consumers of the API can ensure they get more of the matches they expect.

The socs parameter takes a list of multiple 8-digit SOC codes and the algorithm weights its contextualization based on the order of that list. That is, the algorithm considers the first SOC in the list to be of higher importance than the last SOC, so be sure to provide your list of SOCs in the proper order.

The cutoff Parameter

The cutoff parameter is a means by which the requestor can tune internal cutoffs intrinsic to the matching algorithm. It should be noted that this is NOT a "final cutoff" to redact output with a final relevancy score below X; instead, this tuning parameter changes the aggressiveness with which the matching algorithm seeks to populate the final results. A lower number (5.0) will result in a more diverse set of final matches; a higher number (20.0) will significantly limit the final results. In either case, the final resultant matches' scores will be scaled across a spectrum from 1.0 to 99.0 (and we by default don't return any results with a final scaled score lower than 20.0).

Response Data Format

Root Key

As with the majority of SkillsEngine endpoints, the root key in a successful JSON response is result (the root key in a failure is error).

Original Sentences and Skills

Unlike the skills/match endpoint, the multi_match endpoint returns an array of two-key hashes. Each of these hashes represents both the original sentence (from the array of input sentences provided) and then a nested array of skill hashes. These skill hashes follow the same structure as the skills/match endpoint...

Skills

The skills key has as its value a sorted array of hashes. Each hash in that array represents a single Detailed Work Activity that we have matched with the original sentence, as well as a relevancy score. The skills are returned in order of score, highest relevancy first. Each skill hash includes the following elements:

    "version": 2,
    "guid": "936c9e29-9e0a-4c6d-b5ed-c2b0d7da49ab",
    "title": "Refer clients or others to community services or resources",
    "match_score": 30.74,
    "iwa_guid": "0cb36e6a-df8d-4ef4-8540-4f62f61b674e",
    "iwa_title": "Advise others on products or services",
    "gwa_guid": "abe6cddd-0679-4491-ad7a-a672d72ceffb",
    "gwa_title": "Provide Consultation and Advice to Others",
    "matched_socs": [
      "21-1029.00",
      "21-1023.00"
    ]
  • version -- the version identifier for this Detailed Work Activity as retrieved from our core library at that moment.
  • guid -- the globally unique identifier for this Detailed Work Activity
  • title -- the textual title of this Detailed Work Activity
  • match_score -- the relevancy score as computed by our matching algorithm
  • iwa_guid -- the globally unique identifier for the Intermediate Work Activity that exists as the parent of this Detailed Work Activity in our core library
  • iwa_title -- the textual title of the parent Intermediate Work Activity
  • gwa_guid -- the globally unique identifier for the Intermediate's parent General Work Activity (the grandparent of the Detailed Work Activity)
  • gwa_title -- the textual title of the parent General Work Activity
  • matched_socs -- an array of 8-digit SOC codes that indicate when a matched skill is associated in our core library with one or more of the contextual SOCs provided in the original request. This array may be empty in the case where no contextual SOCs were provided, or in the case where a relevant skill was found that is not associated in our library with any of the contextual SOCs specified.

Limitations

The skills/multi_match endpoint is limited to analyzing an array of no more than 20 sentences. Requests that provide more than 20 sentences at once will return a 422 and an error message.

In addition, any individual sentence provided to this endpoint can contain no more than 50 words.

Authorization Header Required

This endpoint requires an Authorization header attribute with a valid Bearer <access-token>.

Suggest Edits

/v2/topics/related

This endpoint analyzes one or more short phrases to find related topics and matching elements from the SkillsEngine core library.

 
posthttps://api.skillsengine.com/v2/topics/related
POST /v2/topics/related

{"texts":["ms word", "access", "dexterity"], "socs":["41-3041.00"]}
A binary file was returned

You couldn't be authenticated

{
  "result": {
    "matches": [
      {
        "dbtype": "tool",
        "type": "technology",
        "category": "Word processing software",
        "guid": "390dcef4-73b1-4a74-a599-5cc6364a6f15",
        "title": "Microsoft Word",
        "score": 100,
        "matched_tokens": [
          "ms word",
          "microsoft word",
          "word powerpoint",
          "word excel",
          "microsoft"
        ]
      },
      {
        "dbtype": "tool",
        "type": "technology",
        "category": "Data base user interface and query software",
        "guid": "e279a735-3791-4db9-8cdf-0927bef4ce95",
        "title": "Microsoft Access",
        "score": 100,
        "matched_tokens": [
          "access"
        ]
      },
      {
        "dbtype": "characteristic",
        "type": "ability",
        "category": "ability",
        "guid": "2fc00d553639f10728c61da01ff25a98",
        "title": "Wrist-Finger Speed",
        "score": 100,
        "matched_tokens": [
          "finger dexterity"
        ]
      },
      {
        "dbtype": "characteristic",
        "type": "skill",
        "category": "skill",
        "guid": "37dcca91f219e9b454183c21e1f57e5c",
        "title": "Coordination",
        "score": 100,
        "matched_tokens": [
          "eye coordination"
        ]
      },
      {
        "dbtype": "tool",
        "type": "technology",
        "category": "Spreadsheet software",
        "guid": "50268cdd-7a8d-43ae-9ade-eadd88e2ff21",
        "title": "Microsoft Excel",
        "score": 85.74,
        "matched_tokens": [
          "word excel",
          "microsoft"
        ]
      },
      {
        "dbtype": "tool",
        "type": "technology",
        "category": "Presentation software",
        "guid": "463e6da6-c2d4-4afc-8876-92a7786322b4",
        "title": "Microsoft PowerPoint",
        "score": 76.22,
        "matched_tokens": [
          "word powerpoint"
        ]
      }
    ],
    "tokens": [
      "ms word",
      "microsoft word",
      "word powerpoint",
      "word excel",
      "microsoft",
      "access",
      "dexterity",
      "manual dexterity",
      "finger dexterity",
      "stamina",
      "eye coordination",
      "hand eye"
    ]
  }
}

Body Params

texts
array of strings
required

an array of one or more short texts (each less than 4 words, preferably) that will be matched to find related topics and matching SkillsEngine library elements

socs
array of strings

(optional but recommended); allows the requestor to provide occupational context for a related topics match by supplying one or more 8-digit SOC codes. Providing SOC context will improve matching and downsample topics likely unrelated to the occupations indicated.

 

Explanation

Our Expander endpoint provides the requestor with a means to find synonyms and highly-related topics to short phrases they provide. These tokens are returned in a standard JSON response, along with an array of rich matches from our curated data library when we surface tokens that we already know about. This allows, for example, the ability to match "ms word" with "Microsoft Word", as well as show that it is closely related to "Microsoft Office" in many occupational contexts.

In general, the topics endpoint works best if provided a small number (3 or less) of very short phrases, themselves consisting of a very small number (3 or less) of words. E.g. ["ms word", "excel", "powerpint"] (spelling mistake there is intentional, to show that the neural net is frequently capable of comprehending even misspelled input texts in the same way that a human might).

We anticipate the use cases around this endpoint to focus on expansion of sparse texts where an author of a resume or job posting may have mentioned certain arbitrary tools, technologies, or characteristics that a human reader would infer to be representative of a much wider list of topics. Expanding the user's text into either a list of raw tokens and/or our canonical library elements can provide downstream matching algorithms with much richer text for keyword matching or other applications.

The socs Parameter

Like many of our endpoints, providing one or more O*NET 8-digit SOCs can help Expander better contextualize the end results, boosting matches that directly relate to the referenced occupations and discarding or downsampling those that do not. While this is an optional parameter, it is highly recommended to get higher-quality results from the endpoint.

Response Data Structure

Root Key

The root key in a successful JSON response is result (the root key in a failure is error).

Matches

Includes a list of highly-relevant matched elements from our curated library. Currently, this list can include Tools/Techs, Knowledges, Skills, Abilities, and Workplace Essentials. It's important to understand that this list of matches is not all-encompassing of anything that might be related to the input text, but rather provides additional detail for surfaced tokens and phrases that we have additional information about. Especially new technologies or concepts (or things that simply don't fit into our current taxonomy) may not be represented in the matches array, even though raw tokens show up for them in the tokens array.

Tokens

This is the raw list of tokens and short phrases surfaced by the neural net that underpins the topic expansion system. This list is not guaranteed to have perfectly clean or grammatically-clear tokens, but rather represents the arrangements of words that the neural net has learned are common insofar as they relate to your input text. For example, "photoshop" may surface tokens that reference the exact product, similar products, the parent company of the product, or general concepts around the product, such as "adobe photoshop", "adobe illustrator", "indesign", and two-token phrases like "photoshop illustrator" and "photoshop indesign", suggesting that the neural net has learned that these words are very often found together in work-related documents. We believe that this 'raw' tokens list can have direct application in matching systems by using these as a hidden list of meta-topics attached on both sides of a matching system (e.g. resumes and job postings).

Performance Caveat

Matching a single word or short phrase generally takes Expander a small fraction of a second. Additional texts provided in the texts array increase this latency, as the system has to iterate over and process all of these texts as well as handle an increasingly large set of results. For this reason, we suggest users of Expander experiment with how many phrases they want to send in a single request of the endpoint. In cases where a multi-second delay is acceptable, using one request with many texts may be fine. In other cases, it may be more advantageous to send only one or two phrases at a time and parallelize multiple endpoint requests to get maximum performance for your downstream application.

Authorization Header Required

This endpoint requires an Authorization header attribute with a valid Bearer <access-token>.

Suggest Edits

/v2/occupations

Returns an array of all known occupations with only first-level data, including SOCs, titles, and descriptions.

 
gethttps://api.skillsengine.com/v2/occupations
GET /v2/occupations
A binary file was returned

You couldn't be authenticated

{
  "result": {
    "occupations": [
			{
        "guid":"4f1e9cd3-c039-40b1-acc2-e61709440f41",
        "soc":"11-1011.00",
        "title":"Chief Executives",
        "short_title":"Chief Executives",
        "description":"Determine and formulate policies and provide overall direction of companies or private and public sector organizations within guidelines set up by a board of directors or similar governing body. Plan, direct, or coordinate operational activities at the highest level of management with the help of subordinate executives and staff managers."
      },
      ...
    ]
  }
}
 

Authorization Header Required

This endpoint requires an Authorization header attribute with a valid Bearer <access-token>.

Suggest Edits

/v2/occupations/soc_codes

Returns an array of occupations with associated information and statistical data based on the O*NET SOCs (Standard Occupational Codes) provided in the request.

 
gethttps://api.skillsengine.com/v2/occupations/soc_codes
GET /occupations/soc_codes?soc_codes=13-2011,15-2031,15-2011

GET /occupations/soc_codes?soc_codes=13-2011,15-2031,15-2011&state_code=TX
A binary file was returned

You couldn't be authenticated

{
  "result": {
    "occupations": [
      {
        "stfips_code": 35,
        "soc_code": "13-2011",
        "title": "Accountants and Auditors",
        "short_title": "Accountants and Auditors",
        "region_code": "NM",
        "base_year": 2012,
        "jobs_base": 5980,
        "projection_year": 2022,
        "jobs_projection_total": 6520,
        "jobs_projection_change": 540,
        "jobs_percent_change": 9.0,
        "average_annual_openings": 230,
        "hourly_mean_wage": 28.97,
        "hourly_median_wage": 26.32,
        "annual_mean_wage": 60250.0,
        "annual_median_wage": 54740.0
      }
    ]
  }
}

Query Params

soc_codes
string
required

a comma-separated list of SOCs

state_code
string

an optional 2-letter state code that will filter results to only include statistical data for the specified state

 

soc_codes must be comma-separated and may be either 6-digit or 8-digit codes. Note that, because they are more granular, 8-digit codes may result in less-detailed results than their 6-digit parents.

Authorization Header Required

This endpoint requires an Authorization header attribute with a valid Bearer <access-token>.