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.
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
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 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.
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.
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
As with the majority of SkillsEngine endpoints, the root key in a successful JSON response is
result (the root key in a failure is
Original Sentences and Skills
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 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.
skills/multi_matchendpoint 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
Authorizationheader attribute with a valid