Social People Finder API5.0
Added by IBM contributorIBM | Edited by Claudia R Elbourn on June 30, 2015
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/basic/people/typeahead Basic Authentication
GET /search/{auth}/people/typeahead OAuth
Content Type: application/json
Name Type Optional Description
enumerated No The authorization protocol being used by your application to access Connections Cloud.
Authorized values:
  • bearer
  • basic
Name Type Optional Description
string No one or more query terms. A term could be a prefix or a full token. For example: "gil", "gili sm", "gili smith sales", "gili Smith can", "gili smith canada", "smith canada gili".
The query will try to match across all indexed terms (name, email, job responsibility, tags, address).
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).
Name Type Optional Description
enumerated No The authentication mechanism selected by your application to access the API.
Basic is the Base64 encoding of the IBM Connections Cloud username and password: Base64(username:password). For example, Base64(
Bearer is the oauth 2.0 access token that is generated when the user grants your application access to IBM Connections Cloud services.
See the reference topic "OAuth 2.0 APIs for web server flow" for more information.
Authorized values:
  • bearer
  • basic
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 Smith", // Display name
        "givenNames": [


         ] // additional matching given names

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

         "jobResponsibility": "sales manager",

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

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

         "country": "canada",

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

         "score": 9.181154,
      { ... }