# Users Lookup

## GET /v3/users

> Search users by emails or ids.\
> Only one of the search lists should be informed at a time.\
> Search lists may containt up to 100 elements.<br>

```json
{"openapi":"3.1.1","info":{"title":"Pod API","version":"20.17.1"},"servers":[{"url":"http://yourpodURL.symphony.com/pod"}],"paths":{"/v3/users":{"get":{"summary":"Search users by emails or ids.\nOnly one of the search lists should be informed at a time.\nSearch lists may containt up to 100 elements.\n","parameters":[{"schema":{"type":"string"},"name":"uid","description":"User IDs as a list of decimal integers separated by comma","in":"query","required":false},{"schema":{"type":"string"},"name":"email","description":"List of email addresses separated by comma","in":"query","required":false},{"schema":{"type":"string"},"name":"username","description":"List of username separated by comma","in":"query","required":false},{"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":"boolean"},"name":"active","description":"If not set all user status will be returned,\nif true all active users will be returned,\nif false all inactive users will 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/V2UserList"}}}},"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"}}}}}}}},"components":{"schemas":{"V2UserList":{"description":"List of User record version 2","type":"object","properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/UserV2"},"description":"List of all users found with the search"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/UserError"},"description":"List of all errors found with the informed search criteria"}}},"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"}}},"StringList":{"type":"array","items":{"type":"string"}},"UserError":{"description":"User error information","type":"object","properties":{"error":{"type":"string","description":"Error code informing what is wrong"},"email":{"type":"string","description":"Email with error. Only one of the following fields should be present: email or id"},"id":{"type":"string","description":"Id with error. Only one of the following fields should be present: email or id"}}},"Error":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}}}}}}
```

### Request Examples

```bash
curl -X GET \
  'https://acme.symphony.com/pod/v3/users?uid=7696581394433,7696581394434&local=true' \
   -H 'SessionToken: SESSION_TOKEN' \
```

```bash
curl -X GET \
'https://cip3-qa.symphony.com/pod/v3/users?email=test_1@symphony.com,test_2@symphony.com&local=true' \
 -H 'SessionToken: SESSION_TOKEN' \
```

```bash
curl -X GET \
  'https://cip3-qa.symphony.com/pod/v3/users?username=test_1,test_2&local=true' \
   -H 'SessionToken: SESSION_TOKEN' \
```

### Search for external users

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 IMs\
• Can chat in private external rooms

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

The following fields are stripped for **external** users that **don't have an established connection** with you:

* Email address
* Location
* Title

### 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](/main/apps-on-behalf-of-obo/obo-enabled-endpoints.md#api-endpoints-enabled-for-obo), use the [OBO User Authenticate](/main/apps-on-behalf-of-obo/obo-rsa-user-authentication-by-user-id.md) token for `sessionToken`.

> #### 🚧 Rules & Limitations
>
> * Please note that the endpoint returns only the first 1000 entries.

> #### 📘 Note
>
> **Search list sizes:** search lists may contain up to 100 elements.\
> **Inactive users:** the results will include inactive users.\
> **Account type:** the `accountType` field returns `NORMAL` if the user is a user account and `SYSTEM` if the user is a service account.\
> **User department, location, title and email:** the `department`, `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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://rest-api.symphony.com/main/users/users-lookup-v3.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.