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.


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


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