# Search Users

Search for end-users, bots or distribution lists (groups) by first name, last name, display name, and email, and filter results by company, title, location, marketCoverage, responsibility, function, or instrument.

## POST /v1/user/search

> Search for users by name or email address

```json
{"openapi":"3.1.1","info":{"title":"Pod API","version":"20.17.1"},"servers":[{"url":"http://yourpodURL.symphony.com/pod"}],"paths":{"/v1/user/search":{"post":{"summary":"Search for users by name or email address","parameters":[{"schema":{"type":"integer"},"name":"skip","description":"number of records to skip","in":"query"},{"schema":{"type":"integer"},"name":"limit","description":"Max number of records to return. If no value is provided, 50 is the default.","in":"query"},{"schema":{"type":"boolean"},"name":"local","description":"If true then a local DB search will be performed and only local pod users will be\nreturned. If absent or false then a directory search will be performed and users\nfrom other pods who are visible to the calling user will also be returned.\n","in":"query","required":false},{"schema":{"type":"string"},"name":"sessionToken","description":"Session authentication token.","in":"header","required":true}],"tags":["Users"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSearchResults"}}}},"204":{"description":"No user found."},"400":{"description":"Client error, see response body for further details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized: Invalid session token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden: Caller lacks necessary entitlement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error, see response body for further details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSearchQuery"}}},"description":"search criteria","required":true}}}},"components":{"schemas":{"UserSearchResults":{"type":"object","properties":{"count":{"description":"The total number of users which matched the search criteria.","type":"integer","format":"int64"},"skip":{"description":"The number of skipped results.","type":"integer","format":"int64"},"limit":{"description":"The number of returned results.","type":"integer","format":"int64"},"searchQuery":{"$ref":"#/components/schemas/UserSearchQuery"},"users":{"description":"A list of users which matched by the search criteria.","type":"array","items":{"$ref":"#/components/schemas/UserV2"}}}},"UserSearchQuery":{"type":"object","properties":{"query":{"type":"string","description":"search / query term.  This can be firstname, lastname, displayname or email"},"filters":{"$ref":"#/components/schemas/UserSearchFilter"}}},"UserSearchFilter":{"type":"object","properties":{"accountTypes":{"$ref":"#/components/schemas/StringList","description":"type of user used to search"},"title":{"type":"string","description":"user's job title"},"company":{"type":"string","description":"company name"},"location":{"type":"string","description":"city of the user's job location"},"marketCoverage":{"type":"string","description":"geographic area the user works with"},"responsibility":{"type":"string","description":"user's responsibility"},"function":{"type":"string","description":"user's function"},"instrument":{"type":"string","description":"higher level instrument for the Asset Classes"}}},"StringList":{"type":"array","items":{"type":"string"}},"UserV2":{"description":"User record version 2","type":"object","properties":{"id":{"type":"integer","format":"int64"},"emailAddress":{"type":"string","format":"email"},"firstName":{"type":"string"},"lastName":{"type":"string"},"displayName":{"type":"string"},"title":{"type":"string"},"company":{"type":"string"},"username":{"type":"string"},"location":{"type":"string"},"accountType":{"type":"string","enum":["NORMAL","SYSTEM","SDL"]},"avatars":{"$ref":"#/components/schemas/AvatarList"},"workPhoneNumber":{"type":"string","description":"Note: only available if the application has the extended user or contact permission"},"mobilePhoneNumber":{"type":"string","description":"Note: only available if the application has the extended user or contact permission"},"jobFunction":{"type":"string","description":"Note: only available if the application has the extended user or contact permission"},"department":{"type":"string","description":"Note: only available if the application has the extended user or contact permission"},"division":{"type":"string","description":"Note: only available if the application has the extended user or contact permission"},"roles":{"$ref":"#/components/schemas/StringList"},"userMetadata":{"type":"object","description":"Metadata map of key/values","additionalProperties":{"type":"object"}}}},"AvatarList":{"type":"array","items":{"$ref":"#/components/schemas/Avatar"}},"Avatar":{"type":"object","properties":{"size":{"description":"The Avatar Size","type":"string"},"url":{"description":"Url of the image","type":"string"}}},"Error":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}}}}}}
```

### Request Example

```bash
curl -X POST \
https://acme.symphony.com/pod/v1/user/search?local=false \
-H "sessionToken: SESSION_TOKEN" \
-H "Content-Type: application/json"  \
-d '{
  "query": "jane",
  "filters": {
    "title": "Sales Manager",
    "location": "San Francisco",
    "company": "Symphony",
    "marketCoverage":"EMEA",
    "responsibility":"BAU",
    "function":"Trade Management",
    "instrument":"Securities",
    "accountTypes":["NORMAL","SDL"]
  }
}'
```

> #### 📘 Note
>
> * This endpoint can return inexact matches of the specified criteria, while [Find Users](https://rest-api.symphony.com/main/user-management/find-users) returns only exact matches.
> * Account type:
>   * The `accountType` field can contain a list of strings with the following supported values: `NORMAL`, `SYSTEM`, or `SDL`. Please note that if this is not specified, then the default search will return `NORMAL` and `SYSTEM` users in the payload.
>   * The `accountType` field returns `NORMAL` if the user is a user account, `SYSTEM` if the user is a service account, or `SDL` if the user is a Symphony Distribution List (Groups).\
>     **User location, title and email:** the `location`, `title` and `emailAddress` fields are returned only if the user is an internal user of the current pod. When searching between cross-pods, these fields will not be returned.

The caller can specify whether to search locally (within the caller's company) or globally across companies that have enabled external communications.

To search for external users, the parameter **local** needs to be set as **false** and the service account has to be enabled externally. To do so, make sure at least one of the two following external entitlements are enabled, otherwise, the search will return zero results.\
• Can chat in external IM/MIMs\
• Can chat in private external rooms

By default, searches are performed externally. Set `local=true` to search locally.

### Searching external users by email

The service account is allowed to search for users using their registered email even without having a previous connection with them.

### OBO enabled endpoint

When calling this as an [OBO-enabled endpoint](https://rest-api.symphony.com/apps-on-behalf-of-obo/obo-enabled-endpoints#api-endpoints-enabled-for-obo), use the [OBO User Authenticate](https://rest-api.symphony.com/main/apps-on-behalf-of-obo/obo-rsa-user-authentication-by-user-id) token for `sessionToken`.