Community articleSocial People Finder API5.0
Added by IBM contributorIBM on June 18, 2014
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

A type-ahead search service to find people in the organization, that produces personalized results tailored for who's searching.


A type-ahead search service to find people in the organization.

This API is accessible with no authentication and could be used by 3rd party / in-house application as a typeahead people search back-end.

Key features:

  1. Personalized results - highly relevant personalized results reflecting the Searcher's social network and organizational structure.
  2. Associative search - Allows searching by more than just names, by mixing keyword from: names, job roles, email, address, tags.
  3. Speed - Supports high query throughput to produce instant results user experience
  4. Spelling Tolerant - Overcomes misspells by phonetic similarity matching.
  5. Clarity - Results data is highlighted (query term match evidence).
  6. Confidence - each result includes a confidence value, reflecting a confidence estimate on whether the person result is who the Searcher is searching for.

See a request/response example below.


Query parameters reference:

The order of the parameters in the requests do not matter. The parameter names are case-sensitive; they must be entered in the format documented. Any unknown or unsupported parameters submitted as part of a request will be ignored.

Response notes:

  1. The "Confidence" response field, is set to low, medium, high per search result, reflecting a confidence estimate on whether the person result is who the Searcher is searching for.
  2. The response does NOT include photo URLs. The client is expected to be able to construct a photo URL using the supplied person Id.
Method URI Description
GET /search/anonymous/people/typeahead No authentication. Searcher is unknown. Results are not personalized unless email parameter is present.
GET /search/basic/people/typeahead Basic Authentication
GET /search/fba/people/typeahead Form based authentication
GET /search/oauth/people/typeahead OAuth
Content Type: application/json
Name Type Optional Description
string No one or more query terms. A term could be a prefix query (name, tags, job desc, etc...). Example values (each wrapped in quotes): "gil", "gili na", "gili Nachum search", "gili Nachum isr", "gili Nachum israel", "Nachum israel gili".
Notes: 1. The query matches across all indexed terms (name, tags, job desc, etc...). 2. A query term would match if it matches an indexed term or a prefix of it.
int Yes results page number. Value range: >=1.
int Yes number of results in page. Value range: 0-500.
string Yes Email address that identifies the Searcher. Example:
This parameter isn't needed if the Searcher user is logged in.
The email parameter overrides the logged-in user value.
You might use this parameter for:
1. Personalized searches generated by clients not logged in to Connections (e.g., IBM Sametime client plugin).
2. Testing purposes.
3. Personalizing search experience for non logged in searchers.
If Searcher is not logged in and this parameter is not specified then then the ranking of search results would not be personalized.
boolean Yes Whether to rank friends of the Searcher higher in the search results.
boolean Yes If false, the search algorithm could decide to include results with phonetic similarity to query terms (for example: returning "Laura" when searching for "Lora"). phonetic search results are included if low relevancy search results are detected.
If true, no phonetics matching will ever be attempted.
boolean Yes Whether to highlight the content of matched fields.
boolean Yes Whether to try and match query terms against all indexed fields, or only against names and emails.
Would usually be false unless:
1. Replacing a legacy search widget that was searching over names and emails only, that isn't capable to handle and present evidence for matches in other metadata fields (like country, tags).
2. The caller of the API knows that it's query consist of names or emails only.
3. Attempting to perform name detection (as in asking: is this string a name?).
Note you may want to use the disablePhonetics parameter in conjunction with this parameter.
boolean Yes Whether to require that at least one of the terms in the query match names or emails.
string Yes Allows the server admin to tell which app/component generated which requests. Doesn't affect search response.
This parameter doesn't affect the response in any way. Not to be confused with the client parameter which affects response output.
The parameter's purpose is to allow the server admin to understand which requests were generated by which apps, or by which components within IBM Connections.
Pick any value as long as its descriptive, yet short, and is very unlikely to already be used. All the requests generated from a specific app/component should use the same parameter value.
object Yes Allows specifying additional fields that results should include per confidence level.
The following fields are always returned for low confidence (and above): id, name, jobResponsibility, email, userType, confidence, score
The additionalFields parameter allows you have the results include additional fields. If a field is include for a certain confidence level (e.g., low), it will also be included in higher confidence levels (medium or high).
Possible additional fields are: givenNames, tag, workPhone, mobilePhone, tieLine, address fields (country, state, city, location, postalCode), timeZone, timeZoneUTCOffset, organizationTitle, preferredFirstName, surname
Syntax: This parameter is a JSON object with the keys being confidence levels (low/medium/high) and the values are an array of field names that results with this confidence level will always include.
For example: {'low':['country','phoneNumber'],'high':['tag']} means that for confidence low and medium we'll return country and phone number (in addition to the fields specified in the server side and for high confidence level we'll return also tags (even if they do not match the query).
Content Type: application/json
Code Description
OK. Indicates that the request was received successfully.
Bad Request. Will also contain a textual error message indicating a client error.
Unauthorized. Returned when no authenticated user is attempting to access a secure context path.
Internal server error. The server encountered an unexpected condition that prevented it from fulfilling the request.
searching for all users with "gi" appearing in their name or other profile fields.

Response returned by the server
  "totalResults": 221,  // An approximation of the total number of results in the index (page agnostic). The accuracy of this figure is not guaranteed in all cases.
  "startIndex": 1,      // Result offset in relation to the first page (equals 1 in first page. Equals 11 in second page when pageSize=10)
  "numResultsInCurrentPage": 2,   // Number of results this page contains (equals to persons array size)
  "persons": [

        "id":"5025b040-8e85-102b-9993-99c200cfc5b7", // userid
        "name": "<B>Gi</B>li Nachum", // Display name
        "givenNames": [


         ] // additional matching given names

         "userType": "employee", // [employee|visitor|contact], values other than employee used in smartcloud

         "jobResponsibility": "ICS search - Developer",

         "email": "<B>gi</B>",

         "tags": ["<B>gi</B>raffe"], // Tags that matched the query. Max of 5 tags.

         "country": "united states",

         "confidence":"high", // [high|medium|low]

         "score": 9.181154,
      { ... }