com.sovren

Class SovrenClient

java.lang.Object

com.sovren.SovrenClient

public class SovrenClient
extends Object

The SDK client to perform Sovren API calls.

Field Summary

Fields

Modifier and Type	Field and Description
boolean	ShowFullRequestBodyInExceptions Set to true for debugging API errors.

Constructor Summary

Constructors

Constructor and Description
SovrenClient(String accountId, String serviceKey, DataCenter dataCenter, GeocodeCredentials geocodeCredentials) Create an SDK client to perform Sovren API calls with the account information found at https://portal.sovren.com

Method Summary

Modifier and Type	Method and Description
<TTarget extends IParsedDocWithId> BimetricScoreResponse	bimetricScore(ParsedJobWithId sourceJob, List<TTarget> targetDocuments, CategoryWeights preferredWeights, SearchMatchSettings settings) Score one or more target documents against a source job
<TTarget extends IParsedDocWithId> BimetricScoreResponse	bimetricScore(ParsedResumeWithId sourceResume, List<TTarget> targetDocuments, CategoryWeights preferredWeights, SearchMatchSettings settings) Score one or more target documents against a source resume
CreateIndexResponse	createIndex(IndexType type, String indexId) Create a new index
DeleteDocumentResponse	deleteDocument(String indexId, String documentId) Delete an existing document from an index
DeleteIndexResponse	deleteIndex(String indexId) Delete an existing index.
DeleteMultipleDocumentsResponse	deleteMultipleDocuments(String indexId, List<String> documentIds) Delete a group of existing documents from an index
GeocodeJobResponse	geocode(ParsedJob job) Uses the address in the job (if present) to look up geocoordinates and add them into the ParsedJob object.
GeocodeJobResponse	geocode(ParsedJob job, Address address) Use this if you would like to provide an address for geocoding instead of using the one in the parsed job.
GeocodeResumeResponse	geocode(ParsedResume resume) Uses the address in the resume (if present) to look up geocoordinates and add them into the ParsedResume object.
GeocodeResumeResponse	geocode(ParsedResume resume, Address address) Use this if you would like to provide an address for geocoding instead of using the one in the parsed resume.
GeocodeAndIndexJobResponse	geocodeAndIndex(ParsedJob job, IndexSingleDocumentInfo indexingOptions, Address address, boolean indexIfGeocodeFails) Use this if you would like to provide an address for geocoding instead of using the one in the parsed rjobesume.
GeocodeAndIndexJobResponse	geocodeAndIndex(ParsedJob job, IndexSingleDocumentInfo indexingOptions, boolean indexIfGeocodeFails) Uses the address in the job (if present) to look up geocoordinates and add them into the ParsedJob object.
GeocodeAndIndexJobResponse	geocodeAndIndex(ParsedJob job, IndexSingleDocumentInfo indexingOptions, GeoCoordinates coordinates, boolean indexIfGeocodeFails) Use this if you already have latitude/longitude coordinates and simply wish to add them to your parsed job.
GeocodeAndIndexResumeResponse	geocodeAndIndex(ParsedResume resume, IndexSingleDocumentInfo indexingOptions, Address address, boolean indexIfGeocodeFails) Use this if you would like to provide an address for geocoding instead of using the one in the parsed resume.
GeocodeAndIndexResumeResponse	geocodeAndIndex(ParsedResume resume, IndexSingleDocumentInfo indexingOptions, boolean indexIfGeocodeFails) Uses the address in the resume (if present) to look up geocoordinates and add them into the ParsedResume object.
GeocodeAndIndexResumeResponse	geocodeAndIndex(ParsedResume resume, IndexSingleDocumentInfo indexingOptions, GeoCoordinates coordinates, boolean indexIfGeocodeFails) Use this if you already have latitude/longitude coordinates and simply wish to add them to your parsed resume.
GetAccountInfoResponse	getAccountInfo() Get the account info (remaining credits, max concurrency, etc).
GetAllIndexesResponse	getAllIndexes() Get all existing indexes
GetJobResponse	getJob(String indexId, String documentId) Retrieve an existing job from an index
GetResumeResponse	getResume(String indexId, String documentId) Retrieve an existing resume from an index
IndexDocumentResponse	indexDocument(ParsedJob job, String indexId, String documentId, List<String> userDefinedTags) Add a job to an existing index
IndexDocumentResponse	indexDocument(ParsedResume resume, String indexId, String documentId, List<String> userDefinedTags) Add a resume to an existing index
IndexMultipleDocumentsResponse	indexMultipleJobs(List<IndexJobInfo> jobs, String indexId) Add several jobs to an existing index
IndexMultipleDocumentsResponse	indexMultipleResumes(List<IndexResumeInfo> resumes, String indexId) Add several resumes to an existing index
MatchResponse	match(ParsedJob job, List<String> indexesToQuery, CategoryWeights preferredWeights, FilterCriteria filters, SearchMatchSettings settings, int numResults) Find matches for a non-indexed job.
MatchResponse	match(ParsedResume resume, List<String> indexesToQuery, CategoryWeights preferredWeights, FilterCriteria filters, SearchMatchSettings settings, int numResults) Find matches for a non-indexed resume.
MatchResponse	match(String indexId, String documentId, List<String> indexesToQuery, CategoryWeights preferredWeights, FilterCriteria filters, SearchMatchSettings settings, int numResults) Find matches for a resume or job that is already indexed
ParseJobResponse	parseJob(ParseRequest request) Parse a job
ParseResumeResponse	parseResume(ParseRequest request) Parse a resume
SearchResponse	search(List<String> indexesToQuery, FilterCriteria query, SearchMatchSettings settings, PaginationSettings pagination) Search for resumes or jobs that meet specific criteria
SovrenUIClient	ui(MatchUISettings uiOptions) Access methods for generating Sovren Matching UI sessions.
UpdateUserDefinedTagsResponse	updateJobUserDefinedTags(String indexId, String documentId, List<String> userDefinedTags, UserDefinedTagsMethod method) Updates the user-defined tags for a job
UpdateUserDefinedTagsResponse	updateResumeUserDefinedTags(String indexId, String documentId, List<String> userDefinedTags, UserDefinedTagsMethod method) Updates the user-defined tags for a resume

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ShowFullRequestBodyInExceptions

public boolean ShowFullRequestBodyInExceptions

Set to true for debugging API errors. It will show the full JSON request body in SovrenException.RequestBody
NOTE: do not set this to true in your production system, as it increases the memory footprint

Constructor Detail

SovrenClient

public SovrenClient(String accountId,
                    String serviceKey,
                    DataCenter dataCenter,
                    GeocodeCredentials geocodeCredentials)

Create an SDK client to perform Sovren API calls with the account information found at https://portal.sovren.com

Parameters:

accountId - - The account id for your account

serviceKey - - The service key for your account

dataCenter - - The Data Center for your account. Either DataCenter.US or DataCenter.EU

geocodeCredentials - - The credentials you want to use for geocoding, or null

Throws:

IllegalArgumentException - if the accountId, serviceKey, or dataCenter are null/empty

Method Detail

getAccountInfo

public GetAccountInfoResponse getAccountInfo()
                                      throws SovrenException

Get the account info (remaining credits, max concurrency, etc).

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

parseResume

public ParseResumeResponse parseResume(ParseRequest request)
                                throws SovrenException

Parse a resume

Parameters:

request - The request body

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

parseJob

public ParseJobResponse parseJob(ParseRequest request)
                          throws SovrenException

Parse a job

Parameters:

request - The request body

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

createIndex

public CreateIndexResponse createIndex(IndexType type,
                                       String indexId)
                                throws SovrenException

Create a new index

Parameters:

type - The type of documents stored in this index. Either 'Resume' or 'Job'

indexId - The ID to assign to the new index. This is restricted to alphanumeric with dashes and underscores. All values will be converted to lower-case.

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

getAllIndexes

public GetAllIndexesResponse getAllIndexes()
                                    throws SovrenException

Get all existing indexes

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

deleteIndex

public DeleteIndexResponse deleteIndex(String indexId)
                                throws SovrenException

Delete an existing index. Note that this is a destructive action and cannot be undone. All the documents in this index will be deleted.

Parameters:

indexId - The index to delete (case-insensitive).

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

indexDocument

public IndexDocumentResponse indexDocument(ParsedResume resume,
                                           String indexId,
                                           String documentId,
                                           List<String> userDefinedTags)
                                    throws SovrenException

Add a resume to an existing index

Parameters:

resume - A resume generated by the Sovren Resume Parser

indexId - The index the document should be added into (case-insensitive).

documentId - The ID to assign to the new document. This is restricted to alphanumeric with dashes and underscores. All values will be converted to lower-case.

userDefinedTags - The user-defined tags that the resume should have, or null

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

indexDocument

public IndexDocumentResponse indexDocument(ParsedJob job,
                                           String indexId,
                                           String documentId,
                                           List<String> userDefinedTags)
                                    throws SovrenException

Add a job to an existing index

Parameters:

job - A job generated by the Sovren Job Parser

indexId - The index the document should be added into (case-insensitive).

documentId - The ID to assign to the new document. This is restricted to alphanumeric with dashes and underscores. All values will be converted to lower-case.

userDefinedTags - The user-defined tags that the resume should have, or null

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

indexMultipleResumes

public IndexMultipleDocumentsResponse indexMultipleResumes(List<IndexResumeInfo> resumes,
                                                           String indexId)
                                                    throws SovrenException

Add several resumes to an existing index

Parameters:

resumes - The resumes generated by the Sovren Resume Parser paired with their DocumentIds

indexId - The index the documents should be added into (case-insensitive).

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

indexMultipleJobs

public IndexMultipleDocumentsResponse indexMultipleJobs(List<IndexJobInfo> jobs,
                                                        String indexId)
                                                 throws SovrenException

Add several jobs to an existing index

Parameters:

jobs - The jobs generated by the Sovren Job Parser paired with their DocumentIds

indexId - The index the documents should be added into (case-insensitive).

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

deleteDocument

public DeleteDocumentResponse deleteDocument(String indexId,
                                             String documentId)
                                      throws SovrenException

Delete an existing document from an index

Parameters:

indexId - The index containing the document

documentId - The ID of the document to delete

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

deleteMultipleDocuments

public DeleteMultipleDocumentsResponse deleteMultipleDocuments(String indexId,
                                                               List<String> documentIds)
                                                        throws SovrenException

Delete a group of existing documents from an index

Parameters:

indexId - The index containing the documents

documentIds - The IDs of the documents to delete

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

getResume

public GetResumeResponse getResume(String indexId,
                                   String documentId)
                            throws SovrenException

Retrieve an existing resume from an index

Parameters:

indexId - The index containing the resume

documentId - The ID of the resume to retrieve

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

getJob

public GetJobResponse getJob(String indexId,
                             String documentId)
                      throws SovrenException

Retrieve an existing job from an index

Parameters:

indexId - The index containing the job

documentId - The ID of the job to retrieve

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

updateResumeUserDefinedTags

public UpdateUserDefinedTagsResponse updateResumeUserDefinedTags(String indexId,
                                                                 String documentId,
                                                                 List<String> userDefinedTags,
                                                                 UserDefinedTagsMethod method)
                                                          throws SovrenException

Updates the user-defined tags for a resume

Parameters:

indexId - The index containing the resume

documentId - The ID of the resume to update

userDefinedTags - The user-defined tags to add/delete/etc

method - Which method to use for the specified user-defined tags

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

updateJobUserDefinedTags

public UpdateUserDefinedTagsResponse updateJobUserDefinedTags(String indexId,
                                                              String documentId,
                                                              List<String> userDefinedTags,
                                                              UserDefinedTagsMethod method)
                                                       throws SovrenException

Updates the user-defined tags for a job

Parameters:

indexId - The index containing the job

documentId - The ID of the job to update

userDefinedTags - The user-defined tags to add/delete/etc

method - Which method to use for the specified user-defined tags

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

match

public MatchResponse match(ParsedResume resume,
                           List<String> indexesToQuery,
                           CategoryWeights preferredWeights,
                           FilterCriteria filters,
                           SearchMatchSettings settings,
                           int numResults)
                    throws SovrenException

Find matches for a non-indexed resume.

Parameters:

resume - The resume (generated by the Sovren Resume Parser) to use as the source for a match query

indexesToQuery - The indexes to find results in. These must all be of the same type (resumes or jobs)

preferredWeights - The preferred category weights for scoring the results. If null, Sovren will determine the best values based on the source resume

filters - Any filters to apply prior to the match (a result must satisfy all the filters), or null

settings - The settings for this match request. Use null for defaults.

numResults - The number of results to show. Use 0 for the default.

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

match

public MatchResponse match(ParsedJob job,
                           List<String> indexesToQuery,
                           CategoryWeights preferredWeights,
                           FilterCriteria filters,
                           SearchMatchSettings settings,
                           int numResults)
                    throws SovrenException

Find matches for a non-indexed job.

Parameters:

job - The job (generated by the Sovren Job Parser) to use as the source for a match query

indexesToQuery - The indexes to find results in. These must all be of the same type (resumes or jobs)

preferredWeights - The preferred category weights for scoring the results. If null, Sovren will determine the best values based on the source job

filters - Any filters to apply prior to the match (a result must satisfy all the filters), or null

settings - The settings for this match request. Use null for defaults.

numResults - The number of results to show. Use 0 for the default.

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

match

public MatchResponse match(String indexId,
                           String documentId,
                           List<String> indexesToQuery,
                           CategoryWeights preferredWeights,
                           FilterCriteria filters,
                           SearchMatchSettings settings,
                           int numResults)
                    throws SovrenException

Find matches for a resume or job that is already indexed

Parameters:

indexId - The index containing the document you want to match

documentId - The ID of the document to match

indexesToQuery - The indexes to find results in. These must all be of the same type (resumes or jobs)

preferredWeights - The preferred category weights for scoring the results. If null, Sovren will determine the best values based on the source resume/job

filters - Any filters to apply prior to the match (a result must satisfy all the filters), or null

settings - The settings for this match request. Use null for defaults.

numResults - The number of results to show. Use 0 for the default.

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

search

public SearchResponse search(List<String> indexesToQuery,
                             FilterCriteria query,
                             SearchMatchSettings settings,
                             PaginationSettings pagination)
                      throws SovrenException

Search for resumes or jobs that meet specific criteria

Parameters:

indexesToQuery - The indexes to find results in. These must all be of the same type (resumes or jobs)

query - The search query. A result must satisfy all of these criteria

settings - The settings for this search request. Use null for defaults.

pagination - Pagination settings. Use null for defaults.

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

bimetricScore

public <TTarget extends IParsedDocWithId> BimetricScoreResponse bimetricScore(ParsedResumeWithId sourceResume,
                                                                              List<TTarget> targetDocuments,
                                                                              CategoryWeights preferredWeights,
                                                                              SearchMatchSettings settings)
                                                                       throws SovrenException

Score one or more target documents against a source resume

Type Parameters:

TTarget - Either ParsedResumeWithId or ParsedJobWithId

Parameters:

sourceResume - The source resume

targetDocuments - The target resumes/jobs

preferredWeights - The preferred category weights for scoring the results. If null, Sovren will determine the best values based on the source resume.

settings - The settings for this search request. Use null for defaults.

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

bimetricScore

public <TTarget extends IParsedDocWithId> BimetricScoreResponse bimetricScore(ParsedJobWithId sourceJob,
                                                                              List<TTarget> targetDocuments,
                                                                              CategoryWeights preferredWeights,
                                                                              SearchMatchSettings settings)
                                                                       throws SovrenException

Score one or more target documents against a source job

Type Parameters:

TTarget - Either ParsedResumeWithId or ParsedJobWithId

Parameters:

sourceJob - The source job

targetDocuments - The target resumes/jobs

preferredWeights - The preferred category weights for scoring the results. If null, Sovren will determine the best values based on the source job.

settings - The settings for this search request. Use null for defaults.

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurs

geocode

public GeocodeResumeResponse geocode(ParsedResume resume)
                              throws SovrenException

Uses the address in the resume (if present) to look up geocoordinates and add them into the ParsedResume object. These coordinates are used by the AI Searching/Matching engine.

Parameters:

resume - The resume to insert the geocoordinates (from the address) into

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurred

geocode

public GeocodeResumeResponse geocode(ParsedResume resume,
                                     Address address)
                              throws SovrenException

Use this if you would like to provide an address for geocoding instead of using the one in the parsed resume. The address included in the parsed resume (if present) will not be modified.

Parameters:

resume - The resume to insert the geocoordinates (from the address) into

address - The address to use to retrieve geocoordinates

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurred

geocode

public GeocodeJobResponse geocode(ParsedJob job)
                           throws SovrenException

Uses the address in the job (if present) to look up geocoordinates and add them into the ParsedJob object. These coordinates are used by the AI Searching/Matching engine.

Parameters:

job - The job to insert the geocoordinates (from the address) into

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurred

geocode

public GeocodeJobResponse geocode(ParsedJob job,
                                  Address address)
                           throws SovrenException

Use this if you would like to provide an address for geocoding instead of using the one in the parsed job. The address included in the parsed job (if present) will not be modified.

Parameters:

job - The job to insert the geocoordinates (from the address) into

address - The address to use to retrieve geocoordinates

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurred

geocodeAndIndex

public GeocodeAndIndexResumeResponse geocodeAndIndex(ParsedResume resume,
                                                     IndexSingleDocumentInfo indexingOptions,
                                                     boolean indexIfGeocodeFails)
                                              throws SovrenException

Uses the address in the resume (if present) to look up geocoordinates and add them into the ParsedResume object. These coordinates are used by the AI Searching/Matching engine.

Parameters:

resume - The resume to geocode

indexingOptions - What index/document id to use to index the document after geocoding

indexIfGeocodeFails - Indicates whether or not the document should still be added to the index if the geocode request fails.

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurred

geocodeAndIndex

public GeocodeAndIndexResumeResponse geocodeAndIndex(ParsedResume resume,
                                                     IndexSingleDocumentInfo indexingOptions,
                                                     Address address,
                                                     boolean indexIfGeocodeFails)
                                              throws SovrenException

Use this if you would like to provide an address for geocoding instead of using the one in the parsed resume. The address included in the parsed resume (if present) will not be modified.

Parameters:

resume - The resume to insert the geocoordinates (from the address) into

indexingOptions - What index/document id to use to index the document after geocoding

address - The address to use to retrieve geocoordinates

indexIfGeocodeFails - Indicates whether or not the document should still be added to the index if the geocode request fails.

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurred

geocodeAndIndex

public GeocodeAndIndexResumeResponse geocodeAndIndex(ParsedResume resume,
                                                     IndexSingleDocumentInfo indexingOptions,
                                                     GeoCoordinates coordinates,
                                                     boolean indexIfGeocodeFails)
                                              throws SovrenException

Use this if you already have latitude/longitude coordinates and simply wish to add them to your parsed resume. The coordinates will be inserted into your parsed resume, and the address included in the parsed resume (if present) will not be modified.

Parameters:

resume - The resume to insert the geocoordinates into

indexingOptions - What index/document id to use to index the document after geocoding

coordinates - The geocoordinates to use

indexIfGeocodeFails - Indicates whether or not the document should still be added to the index if the geocode request fails.

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurred

geocodeAndIndex

public GeocodeAndIndexJobResponse geocodeAndIndex(ParsedJob job,
                                                  IndexSingleDocumentInfo indexingOptions,
                                                  boolean indexIfGeocodeFails)
                                           throws SovrenException

Uses the address in the job (if present) to look up geocoordinates and add them into the ParsedJob object. These coordinates are used by the AI Searching/Matching engine.

Parameters:

job - The job to geocode

indexingOptions - What index/document id to use to index the document after geocoding

indexIfGeocodeFails - Indicates whether or not the document should still be added to the index if the geocode request fails.

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurred

geocodeAndIndex

public GeocodeAndIndexJobResponse geocodeAndIndex(ParsedJob job,
                                                  IndexSingleDocumentInfo indexingOptions,
                                                  Address address,
                                                  boolean indexIfGeocodeFails)
                                           throws SovrenException

Use this if you would like to provide an address for geocoding instead of using the one in the parsed rjobesume. The address included in the parsed job (if present) will not be modified.

Parameters:

job - The job to insert the geocoordinates (from the address) into

indexingOptions - What index/document id to use to index the document after geocoding

address - The address to use to retrieve geocoordinates

indexIfGeocodeFails - Indicates whether or not the document should still be added to the index if the geocode request fails.

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurred

geocodeAndIndex

public GeocodeAndIndexJobResponse geocodeAndIndex(ParsedJob job,
                                                  IndexSingleDocumentInfo indexingOptions,
                                                  GeoCoordinates coordinates,
                                                  boolean indexIfGeocodeFails)
                                           throws SovrenException

Use this if you already have latitude/longitude coordinates and simply wish to add them to your parsed job. The coordinates will be inserted into your parsed job, and the address included in the parsed job (if present) will not be modified.

Parameters:

job - The job to insert the geocoordinates into

indexingOptions - What index/document id to use to index the document after geocoding

coordinates - The geocoordinates to use

indexIfGeocodeFails - Indicates whether or not the document should still be added to the index if the geocode request fails.

Returns:

The API response body

Throws:

SovrenException - Thrown when an API error occurred

ui

public SovrenUIClient ui(MatchUISettings uiOptions)

Access methods for generating Sovren Matching UI sessions. For example: sovClient.UI(options).search(...)

Parameters:

uiOptions - Options/settings for the Matching UI.
NOTE: if you do not provide a UIOptions.Username (in MatchUISettings.UIOptions), the user will be prompted to login as soon as the Matching UI session is loaded

Returns:

The client for making Matching UI API calls