# Query users

The SCIM protocol defines a standard set of query parameters that can be used to filter, sort, and paginate to return zero or more resources in a query response.

> For more on filtering with SCIM routes, please see RFC 7644 Filtering.


Endpoint: GET /scim/v2/Users
Version: latest
Security: BearerAuth

## Query parameters:

  - `filter` (string)
    Clients may request a subset of resources by specifying the "filter" query parameter containing a filter expression.When specified, only those resources matching the filter expression will be returned. The expression language that is used with the filter parameter supports references to attributes and literals.

Attribute names and attribute operators used in filters are case insensitive.

> For more on filtering with SCIM routes, please see RFC 7644 Filtering.
    Example: "userName eq \"john\""

  - `attributes` (string)
    A multi-valued list of strings indicating the names of resource attributes to return in the response, overriding the set of attributes that would be returned by default. Attribute names must be in standard attribute notation (Section 3.10) form.

> See Section 3.9 for additional retrieval query parameters.
    Example: "userName"

  - `excludedAttributes` (string)
    A multi-valued list of strings indicating the names of resource attributes to be removed from the default set of attributes to return. This parameter will have no effect on attributes whose schema "returned" setting is "always" (see Sections 2.2 and 7 of [RFC7643]).  Attribute names must be in standard attribute notation (Section 3.10) form.

> See Section 3.9 for additional retrieval query parameters.
    Example: "givenName"

  - `sortBy` (string)
    The "sortBy" parameter specifies the attribute whose value will be used to order the returned responses. If the "sortBy" ttribute corresponds to a singular attribute, resources are sorted according to that attribute's value; if it's a multi-valued attribute, resources are sorted by the value of the primary attribute (see Section 2.4 of [RFC7643]), if any, or else the first value in the list, if any. If the attribute is complex, the attribute name must be a path to a sub-attribute in standard attribute notation (Section 3.10), e.g., .

For all attribute types, if there is no data for the specified "sortBy" value, they are sorted via the "sortOrder" parameter, i.e., they are ordered last if ascending and first if descending.
    Example: "name.givenName"

  - `sortOrder` (string)
    The order in which the "sortBy" parameter is applied. Allowed values are "ascending" and "descending". If a value for "sortBy" is provided and no "sortOrder" is specified, "sortOrder" will default to ascending. String type attributes are case insensitive by default, unless the attribute type is defined as a case-exact string. "sortOrder" must sort according to the attribute type; i.e., for case-insensitive attributes, sort the result using case-insensitive Unicode alphabetic sort order with no specific locale implied, and for case-exact attribute types, sort the result using case-sensitive Unicode alphabetic sort order.
    Enum: "ascending", "descending"

  - `startIndex` (integer)
    The 1-based index of the first query result. Values of less than  are interpreted as .

> See Section 3.4.2.3 for details about Pagination.
    Example: 1

  - `count` (integer)
    Specifies the desired maximum number of results per page. Negative values are as interpreted as .

> See Section 3.4.2.3 for details about Pagination.
    Example: 10

## Response 200 fields (application/json):

  - `schemas` (array, required)
    Example: ["urn:ietf:params:scim:api:messages:2.0:ListResponse"]

  - `totalResults` (integer)
    The total number of results returned by the list.
    Example: 2

  - `itemsPerPage` (integer)
    The number of resources returned in a list response page.
    Example: 10

  - `startIndex` (integer)
    The 1-based index of the first result in the current set of list results.

  - `resources` (array)
    Example: [{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"id":"2819c223-7f76-453a-919d-413861904646","userName":"bjensen"},{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"id":"c75ad752-64ae-4823-840d-ffa80929976c","userName":"jsmith"}]

  - `resources.id` (string)
    A unique identifier for a SCIM resource as defined by the service provider.

  - `resources.externalId` (string)
    A String that is an identifier for the resource as defined by the provisioning client.

  - `resources.userName` (string, required)
    A service provider's unique identifier for the user, typically used by the user to directly authenticate to the service provider.

  - `resources.name` (object)
    The components of the user's name.

  - `resources.name.formatted` (string)
    The full formatted name of the User.
    Example: "Ms. Barbara Jane Jensen, III"

  - `resources.name.familyName` (string)
    The family name (surname, last name) of the User.
    Example: "Jensen"

  - `resources.name.givenName` (string)
    The first name of the User.
    Example: "Barbara"

  - `resources.name.middleName` (string)
    The middle name(s) of the User.
    Example: "Jane"

  - `resources.name.honorificPrefix` (string)
    The honorific prefix(es) of the User, or title in most Western languages.
    Example: "Ms."

  - `resources.name.honorificSuffix` (string)
    The honorific suffix(es) of the User, or suffix in most Western languages.
    Example: "III"

  - `resources.displayName` (string)
    The name of the user, suitable for display to end-users.

  - `resources.nickName` (string)
    The casual way to address the user in real life, e.g., "Bob" or "Bobby" instead of "Robert".

  - `resources.profileUrl` (string)
    A URI that is a uniform resource locator (as defined in Section 1.1.3 of [RFC3986]) and that points to a location representing the user's online profile (e.g., a web page).  URIs are canonicalized per Section 6.2 of [RFC3986].

  - `resources.title` (string)
    The user's title, such as "Vice President".

  - `resources.userType` (string)
    Used to identify the relationship between the organization and the user. Typical values used might be "Contractor", "Employee", "Intern", "Temp", "External", and "Unknown", but any value may be used.

  - `resources.preferredLanguage` (string)
    Indicates the user's preferred written or spoken languages and is generally used for selecting a localized user interface. The value indicates the set of natural languages that are preferred. The format of the value is the same as the HTTP Accept-Language header field (not including "Accept-Language:") and is specified in Section 5.3.5 of [RFC7231].

  - `resources.locale` (string)
    Used to indicate the User's default location for purposes of localizing such items as currency, date time format, or numerical representations.A valid value is a language tag as defined in [RFC5646].

  - `resources.timezone` (string)
    The User's time zone, in IANA Time Zone database format [RFC6557], also known as the "Olson" time zone database format [Olson-TZ] (e.g., "America/Los_Angeles").

  - `resources.active` (boolean)
    A Boolean value indicating the user's administrative status.

  - `resources.emails` (array)
    Email addresses for the User.

  - `resources.emails.value` (string)
    The value.

  - `resources.emails.type` (string)
    Indicates the email type such as "work" or "personal".

  - `resources.emails.primary` (boolean)
    Indicates the preferred value for this attribute

  - `resources.phoneNumbers` (array)
    Phone numbers for the user.

  - `resources.ims` (array)
    Instant messaging address for the user.

  - `resources.photos` (array)
    A URI that is a uniform resource locator (as defined in Section 1.1.3 of [RFC3986]) that points to a resource location representing the user's image.

  - `resources.addresses` (object)
    A physical mailing address for this user.

  - `resources.addresses.formatted` (string)
    The full mailing address, formatted for display or use with a mailing label.  This attribute may contain newlines.

  - `resources.addresses.streetAddress` (string)
    The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information. This attribute may contain newlines.

  - `resources.addresses.locality` (string)
    The city or locality component.

  - `resources.addresses.region` (string)
    The state or region component.

  - `resources.addresses.postalCode` (string)
    The zip code or postal code component.

  - `resources.addresses.country` (string)
    The country name component.When specified, the value must be in ISO 3166-1 "alpha-2" code format [ISO3166]; e.g., the United States and Sweden are "US" and "SE", respectively.

  - `resources.groups` (array)
    A list of groups to which the user belongs, either through direct membership, through nested groups, or dynamically calculated.

  - `resources.groups.id` (string)

  - `resources.groups.$ref` (string)
    the URI of the corresponding "Group" resources to which the user belongs

  - `resources.entitlements` (string)
    A list of entitlements for the user that represent a thing the user has.

  - `resources.roles` (string)
    A list of roles for the user that collectively represent who the user is, e.g., "Student", "Faculty".  No vocabulary or syntax is specified, although it is expected that a role value is a String or label representing a collection of entitlements. This value has no canonical types.

  - `resources.x509Certificates` (string)
    A list of certificates associated with the resource (e.g., a User).Each value contains exactly one DER-encoded X.509 certificate (see [Section 4 of [RFC5280]](https://datatracker.ietf.org/doc/html/rfc5280#section-4)), which must be base64 encoded per Section 4 of [RFC4648].