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


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.


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": [
  • 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.



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>.