Skip to main

API Technical Specs

Learn how to configure and leverage our services to achieve your toughest recruiting needs.
SaaS     |

Generate the Matching UI

POST /ui/v10/matcher/resume
POST /ui/v10/matcher/joborder
POST /ui/v10/matcher/indexes/(indexId)/documents/(documentId)
POST /ui/v10/searcher
POST /ui/v10/scorer/bimetric/resume
POST /ui/v10/scorer/bimetric/joborder

Generate an HTML user interface for matching/searching that can be consumed in your client application.

  • Pagination settings in the SaasRequest such as Take or Skip will be accepted in Search queries, but ignored in Match queries.
  • UserDefinedTags can be set in the FilterCriteria and passed through in the background ONLY if there are no UserDefinedTagsPicklists specified in the request.

Request Body

UIOptionsoptionalobject
Object representing various options for generating the UI.
UIOptions.Usernameoptionalstring
The username of the current user. *If you do not provide this, the user will be required to login when they view the page.
UIOptions.Styleoptionalobject
Specifies custom style options for this session.
UIOptions.Style.PrimaryColoroptionalstring
An HTML color used to generate several related colors for various UI elements. For example: #077799.
UIOptions.Style.HeaderColoroptionalstring
An HTML color used for the background of the section/accordian headers. For example: #077799.
UIOptions.Style.SquareCornersoptionalboolean
true to use square corners for UI elements. Default is false for rounded corners.
UIOptions.Style.FontFamilyoptionalstring
A CSS font-family to use for all UI elements. For example: Arial.
UIOptions.Style.FontUrloptionalstring
If you'd like to use a non-standard font, specify the URL where that font can be downloaded here. For example: https://fonts.googleapis.com/css2?family=Montserrat:wght@400;500;600;700&display=swap. Note that you also need to define the FontFamily if you use this option.
UIOptions.ShowFilterCriteriaoptionalboolean
Allow the user to see/modify the filter criteria.
UIOptions.ExecuteImmediatelyoptionalboolean
Execute the query as soon as the page loads.
UIOptions.ShowBanneroptionalboolean
Show the banner containing your account logo inside the matching UI.
UIOptions.ShowWeightsoptionalboolean
Allow the user to see/modify the category weights.
UIOptions.ShowDetailsButtonoptionalboolean
Show a button that opens the 'details' popup containing detailed job/resume info.
UIOptions.ShowFindSimilaroptionalboolean
Adds a button in the Actions menu that matches other jobs/resumes similar to the current one.
UIOptions.ShowWebSourcingoptionalboolean
Include Sovren custom web sourcing in search/match results. Cannot be used for bimetric scoring.
UIOptions.ShowJobBoardsoptionalboolean
Allow job boards in search/match results. Cannot be used for bimetric scoring. Must add credentials atMy Sovren Portal
UIOptions.DefaultJobBoardsoptionalstring[]
The job boards to include in search/match results initially. Users can override after the initial search/match. Cannot be used for bimetric scoring. Must add credentials atMy Sovren Portal. Optional values are:
  • Monster
  • CareerBuilder
  • Nexxt
  • WhoKnows
  • Web
UIOptions.ShowSavedSearchesoptionalboolean
Allow the user to save custom searches or select from premade criteria templates.
UIOptions.Hooksoptionalobject
Contains all the User Action Hooks for this session.
UIOptions.Hooks.Clientoptionalobject[]
The client-side User Action Hooks for this session.
UIOptions.Hooks.Client[i].LinkTextoptionalstring
Text to display on the button for the user action.
UIOptions.Hooks.Client[i].IsBulkoptionalboolean
Allows users to select multiple documents and perform this action on all of them at once. Note that this can only be set to true when you use a JSAction. UrlActions are not supported. See here for more info.
UIOptions.Hooks.Client[i].UrlActionoptionalobject
A URL action to perform when the user clicks the button.
UIOptions.Hooks.Client[i].UrlAction.Urloptionalstring
The URL to show (either in another tab/window or in an iFrame inside the Matching UI).
UIOptions.Hooks.Client[i].UrlAction.Targetoptionalstring
Use sovren to open a popup inside the Matching UI and display the webpage. Any other value will be used just like the target attribute on a normal anchor tag (_blank for a new tab/window, etc).
UIOptions.Hooks.Client[i].JsActionoptionalobject
A Javascript action to perform when the user clicks the button.
UIOptions.Hooks.Client[i].JsAction.Targetoptionalstring
One of parent or opener, depending if you use an iFrame to show the Matching UI in your system, or if you open it in a separate tab/window.
UIOptions.Hooks.Client[i].JsAction.TargetOriginoptionalstring
The 'targetOrigin' parameter for the window.postMessage() call. For more information see here.
UIOptions.Hooks.Client[i].JsAction.Dataoptionalany
Any data you want to be sent (in addition to document information) in the 'message' parameter for the window.postMessage() call. For more information see here.
UIOptions.Hooks.Serveroptionalobject[]
The server-side (HTTP POST) User Action Hooks for this session.
UIOptions.Hooks.Server[i].LinkTextoptionalstring
The text to display on the button for the user action.
UIOptions.Hooks.Server[i].Urloptionalstring
The URL for an HTTP POST call to perform some action in your system.
UIOptions.Hooks.Server[i].CustomInfooptionalany
Any data from your system that you need to associate with this session/action. This is sent (in addition to document information) in the POST body. For more information see User Action Hooks.
UIOptions.Hooks.Server[i].IsBulkoptionalboolean
Allows users to select multiple documents and perform this action on all of them at once. See User Action Hooks for more info.
UIOptions.Hooks.Sourcingoptionalobject[]
The Sourcing (HTTP POST) User Action Hooks for this session.
UIOptions.Hooks.Sourcing[i].LinkTextoptionalstring
The text to display on the button for the user action.
UIOptions.Hooks.Sourcing[i].Urloptionalstring
The URL for an HTTP POST call to perform some action in your system.
UIOptions.Hooks.Sourcing[i].CustomInfooptionalany
Any data from your system that you need to associate with this session/action. This is sent (in addition to document information) in the POST body. For more information see User Action Hooks.
UIOptions.Hooks.OnUpdateoptionalobject
This is called when the user makes category weight changes or adds/removes filter criteria and then re-runs the query. You can use these to store user preferences for use on future queries.
UIOptions.Hooks.OnUpdate.Serveroptionalobject
Makes a POST call to the specified URL with the filter/weights data.
UIOptions.Hooks.OnUpdate.Server.Urloptionalstring
The URL for an HTTP POST call to perform some action in your system.
UIOptions.Hooks.OnUpdate.Server.CustomInfooptionalany
Any data from your system that you need to associate with this session/action. This is sent (in addition to filter criteria and suggested weights) in the POST body. For more information see here.
UIOptions.Hooks.OnUpdate.Clientoptionalobject
Makes a Javscript call via postMessage containing the filter/weights data.
UIOptions.Hooks.OnUpdate.Client.Targetoptionalstring
One of parent or opener, depending if you use an iFrame to show the Matching UI in your system, or if you open it in a separate tab/window.
UIOptions.Hooks.OnUpdate.Client.TargetOriginoptionalstring
The 'targetOrigin' parameter for the window.postMessage() call. For more information see here.
UIOptions.Hooks.OnUpdate.Client.Dataoptionalany
Any data you want to be sent (in addition to filter criteria and suggested weights) in the 'message' parameter for the window.postMessage() call. For more information see here.
UIOptions.UserDefinedTagsPicklistsoptionalobject[]
An array of picklists populated with user-defined tags for users to select from and filter on.
UIOptions.UserDefinedTagsPicklists[i].Labeloptionalstring
The label that will appear above the picklist in the UI.
UIOptions.UserDefinedTagsPicklists[i].Optionsoptionalobject[]
An array of user-defined tags to be used as the options in the picklist.
UIOptions.UserDefinedTagsPicklists[i].Options[j].Valueoptionalstring
The user-defined tag.
UIOptions.UserDefinedTagsPicklists[i].Options[j].Textoptionalstring
The text that will show in the picklist for the user-defined tag.
UIOptions.SkillsAutoCompleteCustomSkillsListoptionalstring[]
String[] of your custom skills list names. The builtin Sovren skills lists are always included.
SaasRequestrequiredobject
The SaaS request that defines the match/search. See the AI Match and AI Search endpoints for details.
SaasRequest.IndexIdsToSearchIntorequiredstring[]
The ids (case-insensitive) of the indexes in which you want to find results. This is the only required value in the SaasRequest.
SaasRequest.*optionalany
All of the parameters that are supported in the normal AI Match and AI Search requests are supported, apart from pagination settings for Match queries as noted above.
ParseOptionsoptionalobject
Object representing parsing options to use when parsing resumes from external sources, such as job boards and Sovren custom web sourcing.
ParseOptions.Configurationoptionalstring
Optional parser configuration string to be used for parsing. If not specified, the default parser configuration will be used. For more information regarding the parser configuration string and assistance generating one, refer to the Parser Configuration Documentation.
ParseOptions.SkillsDataoptionalstring[]
String[] of your custom skills list names and the Sovren "builtin" skills list. If no list is provided the Sovren builtin skills list will be used. The parser automatically detects language and looks for a corresponding skills list in that language, if no match is found this list is ignored.
ParseOptions.NormalizerDataoptionalstring
Name of your custom normalization data file. If no list is provided the Sovren builtin skills list will be used (english only). When using custom normalization files the language to be used is determined by the Parser (the default fall back language is English if the Parser cannot find a match).
GeocodeOptionsoptionalobject
All of the parameters that are supported in the normal parsing geocode options requests are supported. See Parse a Resume for more details.

Sample Request

{ ... 
{ ... 
Username :  "",{ ... 
PrimaryColor :  "",HeaderColor :  "",SquareCorners :  false,FontFamily :  "",FontUrl :  "",
},
ShowFilterCriteria :  true,ExecuteImmediately :  false,ShowBanner :  true,ShowWeights :  true,ShowDetailsButton :  true,ShowFindSimilar :  true,ShowWebSourcing :  true,ShowJobBoards :  true,[ ... 
"",
],
ShowSavedSearches :  true,{ ... 
[ ... 
{
LinkText :  "",IsBulk :  false,{ ... 
Url :  "",Target :  "",
},
{ ... 
Target :  "",TargetOrigin :  "",{ ... 
},
},
},
],
[ ... 
{
LinkText :  "",Url :  "",{ ... 
},
IsBulk :  false,
},
],
[ ... 
{
LinkText :  "",Url :  "",{ ... 
},
},
],
{ ... 
{ ... 
Url :  "",{ ... 
},
},
{ ... 
Target :  "",TargetOrigin :  "",{ ... 
},
},
},
},
[ ... 
{
Label :  "",[ ... 
{
Value :  "",Text :  "",
},
],
},
],
[ ... 
"",
],
},
{ ... 
[ ... 
"",
],
* :  "...",
},
{ ... 
Configuration :  "",[ ... 
"",
],
NormalizerData :  "",
},
{ ... 
* :  "...",
},
}

Response Body

urlstring
The endpoint to hit to get the generated Matching UI. The first request to this endpoint will automatically authenticate the user. Subsequent requests (who are not already authenticated) will require a login. This url will be valid for at least 24 hours.
expires_ininteger
The number of seconds until the url auto-authentication expires.

Sample Response

{ ... 
url :  "",expires_in :  0,
}