apiringcentralscimscim2

Search/List Users Filter Expression Syntax in RingCentral SCIM 2.0 API

In the RingCentral API reference there is a Search/List Users function that requires a filter expression. What is the syntax of this filter expression? The description of the filter parameter is simply "only support 'userName' or 'email' filter expressions for now".

Solution

  • The Search/List Users API is a SCIM 2.0 API so it follows the SCIM 2.0 conventions as defined by IETF RFC-7644.

    Here's the section on filtering:

    https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.2

    3.4.2.2. Filtering

    Filtering is an OPTIONAL parameter for SCIM service providers. Clients MAY discover service provider filter capabilities by looking at the filter attribute of the ServiceProviderConfig endpoint (see Section 4). 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 SHALL 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 example, the following two expressions will evaluate to the same logical value:

    filter=userName Eq "john"

    filter=Username eq "john"

    For RingCentral, you can use the following examples:

    https://platform.ringcentral.com/scim/v2/Users?filter=userName eq "john@example.com"
https://platform.ringcentral.com/scim/v2/Users?filter=email eq "john@example.com"

    In the SCIM API, a user can only have a single username but multiple email addresses. For RingCentral, they are the same because RingCentral only supports a single email address.