Conventions for PingOne management APIs


PingOne API requests

Public endpoints

The public endpoint for calling PingOne API services for environments in the North America region is api.pingone.com, and the public endpoint for environments in the European Union region is api.pingone.eu.

Authorization

To make a call to the PingOne API, you’ll need an OAuth 2.0 access token for API authentication. The access token (a JSON Web Token) is accepted per RFC 6750 most commonly through the Authorization HTTP request header. In the code samples in this document, the access token is expressed in the request header as Authorization: Bearer jwtToken. For more information about using access tokens, see Getting started.

HTTP methods

The PingOne API supports the following HTTP methods. Note that a resource may not support all listed methods below. When a method is not supported, the platform returns a 405 METHOD NOT ALLOWED error in the response.

  • POST

    Creates a new resource in the collection. If a specific resource is identified, it performs an operation on that resource.

  • PUT

    Updates a resource in the collection. If a specific resource is identified, it updates all attribute values of the resource.

  • PATCH

    Updates the attributes on an object or a partial update for the specified attributes.

  • GET

    Lists or queries a collection of resources. If a specific resource is identified, it returns the attribute values for the specific resource.

  • DELETE

    Deletes or unlinks a resource from the collection.

A resource supports updating either by replacing the resource (PUT) or partially updating the resource (PATCH). HTTP method overrides are also supported using the X-HTTP-Method-Override header.

Replacing a resource

A PUT request is a replace operation. Requests submitted using PUT will replace attribute values specified in the request and clear any attribute values that aren’t specified.

A null value is represented in a resource by omitting the property, although you can specify null to explicitly clear the value.

Partial updates to a resource

A PATCH operation performs partial updates of a resource. The body of a PATCH operation is similar to that of a PUT operation. However, omitting an attribute in a PATCH operation results in the attribute being ignored.

You can use a value of null to explicitly clear the value.

HTTP method overrides

The PingOne API is designed to be accessible to a large range of clients, including both public clients (such as Javascript) and restricted clients. For HTTP method-restricted clients, an alternate method is supported using the X-HTTP-Method-Override header. When this header is present, the value of the header is used as the method type for the operation.

Here is a sample that overrides the POST HTTP method with a PUT method. The PingOne API will then treat this as a PUT request.

POST /applications/12345 HTTP/1.1
X-HTTP-Method-Override: PUT
Authorization: Bearer jwtToken
{
  "_links" : {
    "self" : { "href" : "https://api.pingone.com/v1/applications/12345" }
  },
  "id" : "12345",
  "name" : "My Application",
  "contact" : "Sarah Coder (sarah@pingdevelopers.com)",
 ...
}

Supported data exchange formats

The PingOne API supports JSON as the data exchange format with UTF-8 character encoding required for request body content. For PUT, POST, and PATCH operations, the Content-type request header identifies the format of the request body. A request header value of application/json specifies the data exchange format as JSON, which, by default, sets the character encoding to UTF-8. Here is a sample:

curl -vX PUT "https://api.pingone.com/v1/environments/{id}/populations/{id}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "name" : "Finance",
  "description" : "Finance and accounting group"
}"

UUIDs for resource identification

Resources in PingOne are identified by their associated UUID (universally unique identifier). API requests use UUIDs in the request URL to specify the resources involved in the operation. For clarity, the code samples in this API Reference use descriptive variables such as {environmentId}, {userId}, {applicationId}, and {deviceId} to represent the UUIDs assigned to PingOne resources.

For example, the following sample request URL specifies a unique device associated with a unique user in a unique environment. The resource ID variables represent specific UUIDs for PingOne resources.

curl -X "GET" "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/devices/{deviceId}"

The actual request URL with UUIDs looks like this:

curl -X "GET" "https://api.pingone.com/v1/environments/88c23def-39c9-4646-8d41-aa91a14a1006/users/8ce55f02-2077-4493-9a6d-0385df1f0772/devices/4ca9eb79-be29-4a1f-9a23-b29d58606e18"

There are a few exceptions to this convention. Notifications template names in PingOne are identified by the template name {templateName} rather than by a UUID. For example, the following request URL returns information about a specific template:

curl -X "GET" "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/{templateName}

The {templateName} variable is replaced by one of the pre-defined notifications template names in PingOne. The actual request URL that uses a defined notifications template called strong_authentication looks like this:

curl -X "GET" "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/templates/strong_authentication

Placeholder syntax

Some requests use placeholder syntax to reference platform resource entities as variables. When placeholder syntax is required, the PingOne resource used as a variable is expressed in placeholder syntax format as ${attribute}. For example, when mapping a SAML name attribute to the PingOne username attribute, the value of the PingOne attribute in the POST request body is expressed as ${user.username}. In most cases where placeholder syntax is required, the placeholder references attributes in the PingOne user schema. The variable is written as a path to the value: ${user.​path.​to.​value}. For example, to reference the name.family user attribute, the variable is written as ${user.​name.​family}.

Placeholder syntax is also used to express sign-on policy condition variables. For example, a condition variable to specify the last completed time the password authenticator was used for sign on is expressed as ${session.​lastSignOn.​withAuthenticator.​pwd.​at}.

Placeholders in sign-on policy conditions often specify a value or range of values to meet the sign-on condition. For example, the sign-on policy associated with the following condition prevents sign-on from devices that contain the remote IP address value specified by the variable ${flow.request.http.remoteIp} in the specified IP address ranges.

"condition": {
   "not": {
        "ipRange": [
            "10.1.1.1/8",
            "10.0.0.0/8"
        ],
        "contains": "${flow.request.http.remoteIp}"
    }
}

Placeholders are also used to specify external identity provider attributes. For example, to specify a Facebook attribute that is mapped to a PingOne attribute, the Facebook attribute is expressed as ${providerAttributes.<Facebook attribute name>}. For example, the following expression maps the PingOne username attribute to the Facebook email attribute.

{
    "name": "username",
    "value": "${providerAttributes.email}"
    "update": "EMPTY_ONLY",
}

The following table shows the PingOne resources that use Placeholder syntax in POST requests.

PingOn resource Placeholder example
Sign-on policy actions ${session.​lastSignOn.​at}
${session.​lastSignOn.​withAuthenticator.​pwd.​at}
${session.​lastSignOn.​withAuthenticator.​mfa.​at}
${flow.​request.​http.​remoteIp}
${user.​*}
Identity providers ${providerAttributes.<IdP attribute name>}
Notifications templates ${user.username}
${otp}
Resource attributes ${user.email}
SAML attribute mapping ${user.id}

Link expansion

You can optimize the information returned by a request through link expansion. Link expansion is helpful when you need the query to return detailed information from an additional resource in the response data. You can identify a resource to expand using the expand query string parameter in the request.

Here is a sample that requests data for a specific user and expands the passwordPolicy attribute to show the password policy’s attribute data.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/password?expand=passwordPolicy" \
-H "Authorization: Bearer jwtToken"

When using the expand parameter in the request, the returned JSON includes an embedded passwordPolicy resource to show the details of the password policy associated with this user:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/users/b94f4977-0d52-4c9d-a5da-e7d42a82f613/password"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
        },
        "user": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/users/b94f4977-0d52-4c9d-a5da-e7d42a82f613"
        },
        "passwordPolicy": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/passwordPolicies/9ad15e9e-3ac6-43f7-86d3-01018f6ef0ad"
        },
        "password.check": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/users/b94f4977-0d52-4c9d-a5da-e7d42a82f613/password"
        },
        "password.reset": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/users/b94f4977-0d52-4c9d-a5da-e7d42a82f613/password"
        },
        "password.set": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/users/b94f4977-0d52-4c9d-a5da-e7d42a82f613/password"
        },
        "password.recover": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/users/b94f4977-0d52-4c9d-a5da-e7d42a82f613/password"
        }
    },
    "environment": {
        "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
    },
    "user": {
        "id": "b94f4977-0d52-4c9d-a5da-e7d42a82f613"
    },
    "passwordPolicy": {
        "id": "9ad15e9e-3ac6-43f7-86d3-01018f6ef0ad"
    },
    "status": "NO_PASSWORD",
    "lastChangedAt": "2019-05-21T18:01:07.413Z",
    "_embedded": {
        "passwordPolicy": {
            "_links": {
                "self": {
                    "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/passwordPolicies/9ad15e9e-3ac6-43f7-86d3-01018f6ef0ad"
                },
                "environment": {
                    "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
                }
            },
            "id": "9ad15e9e-3ac6-43f7-86d3-01018f6ef0ad",
            "environment": {
                "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
            },
            "name": "Standard",
            "description": "A standard policy that incorporates industry best practices",
            "excludesProfileData": true,
            "notSimilarToCurrent": true,
            "excludesCommonlyUsed": true,
            "maxAgeDays": 182,
            "minAgeDays": 1,
            "maxRepeatedCharacters": 2,
            "minUniqueCharacters": 5,
            "history": {
                "count": 6,
                "retentionDays": 365
            },
            "lockout": {
                "failureCount": 5,
                "durationSeconds": 900
            },
            "length": {
                "min": 8,
                "max": 255
            },
            "minCharacters": {
                "1234567890": 1,
                "abcdefghijklmnopqrstuvwxyz": 1,
                "ABCDEFGHIJKLMNOPQRSTUVWXYZ": 1,
                "~!@#$%^&*()-_=+[]{}|;:,.<>/?": 1
            },
            "default": true
        }
    }
}

Cross-origin resource sharing

PingOne supports cross-origin resource sharing (CORS), which gives applications running at different domains permission to access resources on PingOne servers. For example, an application at https://myapp.com that uses PingOne to authenticate users needs to request permission to access resources at https://auth.pingone.com before authentication operations are executed. In this case, a request is made to the resource owner (auth.pingone.com) from the requestor (myapp.com) using CORS headers to ask for access privileges. The response from auth.pingone.com returns the CORS Access-Control-Allow-Origin header with a value that confirms the requestor’s access rights.

PingOne servers are configured to trust all origins. Consequently, when defining an application’s connection to PingOne, you do not need to add your application’s domain to a list of trusted origins. Cross-origin requests that use HTTP methods to modify the resource, such as PUT, PATCH, POST, and DELETE, trigger a preflight request to ensure that the initial request can be sent. The browser initiates a preflight HTTP OPTIONS request to verify that the HTTP method used in the actual request is allowed. In these cases, the response from auth.pingone.com to the preflight request returns a response with the CORS Access-Control-Allow-Methods header to specify the allowed methods.

PingOne API responses

HTTP response headers

The PingOne API includes information about the result of the operation in the HTTP headers. This enables you to determine the appropriate action to take without having to parse the response body.

The following HTTP Headers are returned by every operation:

  • Access-Control-Allow-Headers

    Used in response to a cross-origin resource sharing (CORS) preflight request to indicate the HTTP headers that can be used when making a request.

  • Access-Control-Allow-Max-Age

    Specifies how long the results of a CORS preflight request can be cached.

  • Access-Control-Allow-Methods

    Specifies the method or methods allowed when accessing the resource in response to a CORS preflight request.

  • Cache-Control

    Specifies directives for caching mechanisms in both requests and responses.

  • Content-Type

    Specifies the data exchange format for the response data.

  • Correlation-Id

    A custom header.

  • Date

    Shows the date the response was sent.

  • Expires

    Shows the date and time when the response expires.

  • Pragma

    Used for backwards compatibility with HTTP/1.0 caches in which the Cache-Control HTTP/1.1 header is not yet present.

  • Strict-Transport-Security

    Allows a web site to tell browsers that the site should only be accessed using HTTPS, instead of HTTP.

  • Transfer-Encoding

    Specifies the form of encoding used to safely transfer the entity to the user.

  • Vary

    Determines how to match future request headers to decide whether a cached response can be used rather than requesting a fresh one from the origin server. It is used by the server to indicate which headers it used when selecting a representation of a resource in a content negotiation algorithm.

  • Via

    Used for tracking message forwards, avoiding request loops, and identifying the protocol capabilities of senders along the request/response chain.

  • X-Content-Type-Options

    A marker used by the server to indicate that the MIME types advertised in the Content-Type headers should not be changed and be followed.

  • X-Frame-Options

    This denies rendering in a frame where there is a frame mismatch.

  • X-XSS-Protection

    A feature of Internet Explorer, Chrome, and Safari that stops pages from loading when the browsers detect reflected cross-site scripting (XSS) attacks.

HTTP response codes

The PingOne API returns the status of an operation as a registered HTTP response code. The HTTP response codes can be summarized as:

  • 200-299

    Confirms a successful call.

  • 300-399

    Indicates that the call or subsequent calls should be made to another resource.

  • 400-499

    Shows that an exception occurred, generally due to client code, insufficient permissions, or incorrect parameters.

  • 500-599

    Shows that an error occurred, generally due to an issue with the service (for example, a service outage).

Operations can also return additional information about a failed operation in the HTTP response body.

Synchronous responses

Responses for synchronous operations have the following behavior:

  • GET operations

    A request that returns a body also returns the code 200 OK with the resource in the body of the response.

  • POST operations

    A request that creates a new resource returns 201 CREATED with a Location header containing the location of the created resource.

  • PUT or PATCH operations

    A request that updates a resource returns 200 OK and the full resource in the body.

  • DELETE operations

    A request that deletes a resource returns 204 NO CONTENT.

Asynchronous responses

The PingOne API can create a long-running or asynchronous operation that can be monitored by a client. An asynchronous operation will have the following behavior:

  • POST operations

    Responses include 202 ACCEPTED with a Location header containing the location of the newly created operation. The client can poll the provided location to check the status of the operation. The operation may also return a suggested number of seconds for the client to recheck the status using the Retry-After HTTP header.

  • Canceling long-running operations

    Some resources may allow the client to cancel an operation by performing a DELETE request on the created resource.

  • Clean up

    The PingOne API will clean up operation history according to the application requirements (such as, keep the last n results, or purge results after the client has verified its success).

Response data structure

All PingOne API resources return data using the HAL+JSON content type. The HAL media type provides a common format for linking API resources. HAL conventions adopted by the PingOne APIs result in an easily readable structure for resource links and for expressing embedded resources contained within parent resources. The following sample shows how embedded resources are structured in the response data.

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/populations"
        }
    },
    "_embedded": {
        "populations": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/populations/5e5cf2d4-2e11-4efc-89f1-73110c277ded"
                    }
                },
                "id": "5e5cf2d4-2e11-4efc-89f1-73110c277ded",
                "environment": {
                    "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                },
                "name": "Accounting",
                "userCount": 6,
                "createdAt": "2018-06-12T19:09:23.756Z"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/populations/14865d2f-5c28-40a2-97e7-10cb921e2ade"
                    }
                },
                "id": "14865d2f-5c28-40a2-97e7-10cb921e2ade",
                "environment": {
                    "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                },
                "name": "Engineering",
                "userCount": 31,
                "createdAt": "2018-06-12T19:09:42.504Z"
            }
        ]
    },
    "count": 2,
    "size": 2
}

For collections, the result data returns a count and size attribute, and all API requests return a self URL under the _links attribute that identifies the URI of the main resource.

The _embedded attribute lists all the results in the collection. In the sample above, the count attributes tells you that there are three roles in the collection. The JSON for each role also shows the embedded permissions associated with the given role.

Relationships between resources or operations can be described as follows:

  • Relationships (one-to-one)

    Where a resource is directly related to another resource (such as employee to manager, user to population, logo to brand), the relationship is generally represented by an attribute as a first-class citizen of the resource. For example:

    • _links object : Contains an href to the actual resource.

    • Payload : Contains the reference as an attribute with the ID. The name of the _links attribute and the attribute in the payload must be the same).

    • Expandable : Yes.

  • Relationships (one-to-many or many-to-one)

    Where a resource or resources may be related to a collection or to many resources. For example, a user to group membership:

    • _links object : Contains an href to the actual resource or collection.

    • Payload : May contain the reference as an attribute with the ID. The name of the _links attribute and the attribute in the payload must be the same).

    • Expandable : No.

  • Informal relationships and links

    Provides navigation and self-discovery of the API and its related resources (such as next page of search results, next authentication service to invoke, or with which environment the resource is associated). For example:

    • _links object : Contains an href to the actual resource, collection, or URL.

    • Payload : Cannot contain the reference as an attribute.

    • Expandable : No.

These relationships and references are represented as follows:

  • Links are represented using JSON HAL conventions (such as in a _links object).

  • Links are represented as absolute URLs.

  • Links can be expanded using the expand parameter. The links can also be referenced using the “property-as-resource” pattern.

  • References as attributes have an id value and can also have additional attributes (such as displayName).

Errors

Errors generated by the PingOne API allow you to resolve specific errors programmatically. An error response consists of a high-level error code that must be handled by the client and optional details containing specific information on how to resolve the fault. The PingOne API errors return a response payload formatted as follows:

Attribute Required Description
id Yes A unique identifier that is stored in log files and always included in an error response. This value can be used to track the error received by the client, with server-side activity included for troubleshooting purposes.
code Yes A general fault code which the client must handle to provide all exception handling routines and to localize messages for users. This code is common across all PingOne services and is human readable (such as a defined constant rather than a number).
message Yes A short description of the error. This message is intended to assist with debugging and is returned in English only.
target No The item that caused the error (such as a form field ID or an attribute inside a JSON object).
details No Additional details about the error. Optional information to help resolve the error and to display to users.
innererror No Additional details to help the client developer resolve the fault (primarily for UI validation reasons). The following attributes can be used in the innererror object:
  • rangeMinimumValue. Errors that failed due to range violation. This attribute represents the minimum value of the range.
  • rangeMaximumValue. The maximum range or value of an attribute.
  • allowedPattern. A regex pattern describing an acceptable input pattern.
  • allowedValues. A list describing acceptable values.
  • maximumValue. The maximum value allowed for the request.

A top-level error message looks like this:

HTTP/1.1 400 BAD REQUEST
{
  "id" : "6c796712-0f16-4062-815a-e0a92f4a2143",
  "code" : "INVALID_DATA",
  "message" : "The request could not be completed. One or more validation errors were in the request.”
}

A detail-level error message provides more information about the error. Specific codes at the detail level can be introduced by each service to reflect the actions in that service. A detail-level error message looks like this:

HTTP/1.1 400 BAD REQUEST
{
  "id" : "6c796712-0f16-4062-815a-e0a92f4a2143",
  "code" : "INVALID_DATA",
  "message" : "The request could not be completed. One or more validation errors were in the request.",
  "details" : [
  {
    "code" : "REQUIRED_VALUE",
    "target" : "username",
    "message" : "Username is required and cannot be empty."
  },
  {
    "code" : "INVALID_VALUE",
    "target" : "employeeType",
    "message" : "Invalid value for employee type."
    "innerError" : {
      "allowedValues" : [ "EMPLOYEE", "CONTRACTOR" ]
    }
  }
}

Caching

The PingOne API generally implements HTTP caching of operation responses. When HTTP caching is implemented, the following HTTP response headers are included:

  • ETag

    An arbitrary string for the version of a representation. This includes the media type in the hash value. For example: ETag: "686897696a7c876b7e".

  • Date

    The date and time the response was returned. For example: Date: Sun, 06 Nov 1994 08:49:37 GMT.

  • Cache-Control

    The maximum number of seconds a response can be cached. If caching is not supported for the response, the value is no-cache. For example: Cache-Control: 360 or Cache-Control: no-cache.

  • Expires

    If Cache-Control is supplied, this header contains the timestamp for when the response expires. If caching is not supported for the response, this header is not present. For example: Expires: Sun, 06 Nov 1994 08:49:37 GMT.

  • Pragma

    When the Cache-Control value is no-cache, this header is also set to no-cache. If caching is not supported for the response, this header is not present. For example: Pragma: no-cache.

  • Last-Modified

    The timestamp for when the resource itself was last modified. For example: Last-Modified: Sun, 06 Nov 1994 08:49:37 GMT.

  • Varies

    This header is included for user-specific headers (such as Authorization) in multi-tenant scenarios.

Paging, ordering, and filtering collections

Pagination

PingOne supports cursor-based pagination to return large collections in consumable pages. When an operation supports pagination, the following conventions are used:

  • Page limits

    Page limits are requested using the limit query string. If the limit parameter value is omitted, the operation returns the lesser of the service-defined maximum page size or the number of items in the collection.

  • Self, next, and previous links

    The response body includes a self link in the _links object. If there are more pages available, the response includes a next link in the _links object. If there are previous pages of results available, the response includes a prev link in the _links object.

  • Multiple pages

    If there is more than one page, the response returns a URL-safe cursor in the cursor query string parameter for the next or prev links.

  • Response metadata

    The response can include the following metadata about the results in the body of the payload:

    • count (optional).

      Describes the number of items in the collection or result set (such as the total item count). If a response does not return a count attribute, this usually means there are many in the result set.

    • size (optional).

      Describes the size of the page of results (such as the limit or service-defined maximum page size).

Here is a sample request that limits the collection returned to a maximum of 2.

GET /environments/{id}/populations?limit=2 HTTP/1.1

Here is the response body.

{
 "_links" : {
  "self" : { "href" : "https://api.pingone.com/v1/environments/{id}}/populations?limit=2" },
  "next" : { "href" : "https://api.pingone.com/v1/environments/{id}}/populations?cursor=xygdhs&limit=2" }
 },
 "count" : 50,
 "size" : 2,
 "_embedded" : {
  "populations" [
   {
    "name" : "Accounting",
    "id" : "12345-aaa-12345"
   },
   {
    "name" : "Engineering",
    "id" : "12345-aaa-12346"
   }
  ]
 }
}

Ordering collections

The PingOne API supports ordering collection results. The following conventions are used:

  • order query string

    The order query string parameter specifies the attribute used to order the results. To return a collection in descending order, prefix the attribute with a minus sign ("-"). Here is a sample of ordering on the startDate attribute in descending order:

    https://api.pingone.com/v1/environments/{environmentID}/activeIdentityCounts?filter=startDate ge "2019-05-01T19:00:00Z" and samplingPeriod eq "10"&limit=10&order=-startDate
  • Multiple column ordering

    An operation can support ordering multiple columns in the order parameter by separating the columns with a comma. If an operation supports multiple columns, it treats the comma as a “THEN BY” directive. For example, order=dateTime,name indicates that the collection is sorted by dateTime then by name.

Filtering collections

Requests that return a large number of items can be filtered using the filter query string parameter. The PingOne platform supports the SCIM protocol filtering operators listed in the following table. However, a particular operation may not support all SCIM filtering operators. If a filtering operator is not supported, the operation returns 400 REQUEST_FAILED code in the response. The details section of the message returns an INVALID_FILTER code as the cause of the error.

Operator Description Behavior
eq equal The attribute and operator values are identical.
ne not equal The attribute and operator values must not be identical for a match.
co contains The entire operator value must be a substring of the attribute value for a match.
sw starts with The entire operator value must be a substring of the attribute value, starting at the beginning of the attribute value. This criterion is satisfied if the two strings are identical.
ew ends with The entire operator value must be a substring of the attribute value, matching at the end of the attribute value. This criterion is satisfied if the two strings are identical.
pr present (has value) If the attribute has a non-empty or non-null value, or if it contains a non-empty node for complex attributes, there is a match.
gt greater than If the attribute value is greater than the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value.
ge greater than or equal to If the attribute value is greater than or equal to the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value.
lt less than If the attribute value is less than the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value.
le less than or equal to If the attribute value is less than or equal to the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison, and for DateTime types, it is a chronological comparison. For integer attributes, it is a comparison by numeric value.

For example, here is a sample SCIM filtering expression that returns users with a last name of “Smith” and a phone number that starts with the “512” area code:

https://api.pingone.com/v1/environments/{envID}/users?filter=name.family eq "Smith" and mobilePhone sw "512"

Here is the same filter with URL-encoding to account for spaces (%20) and quotation marks (%22):

https://api.pingone.com/v1/environments/{envID}/users?filter=name.family%20eq%20%22Smith%22%20and%20mobilePhone%20sw%20%22512%22

For more information about the SCIM Protocol Specification, see “Section 3.4.2.2. Filtering,” in the SCIM Protocol Specification.