Getting Started
Authentication
API Versioning
V3 API Standard Collection Parameters
Access Requests
Account Activities
Certifications
Certification Summaries
Public Identities
Public Identities Config
Requestable Objects
Saved Search
Scheduled Search
Search
Reference
Models
IAI Recommendations
IAI Peer Group Strategies
Access Request Approvals
Access Requests
Account Activities
Accounts
Certifications
Certification Campaigns
Lifecycle States
Managed Clusters
Non-Employee Lifecycle Management
Notifications
OAuth Clients
Password Dictionary
Personal Access Tokens
Public Identity Config
Requestable Objects
Role Insights
Service Desk Integration
Sources
Tagged Objects
Task Management
Triggers
SOD Policy
Reference
Models

V3 API Standard Collection Parameters

Many “collection” endpoints in the IdentityNow V3 and beta APIs support a generic syntax for paginating, filtering and sorting the results.

A “collection” endpoint has the following characteristics:

  • The HTTP verb is always GET
  • The last component in the URL is a plural noun
  • The return value from a successful request is always an array of JSON objects; this array may be empty if there are no results

Paginating Results

Pagination is achieved with the following parameters. All are optional.

limit
Integer that specifies the maximum number of results to return. If not specified a default limit will be used. For most collection endpoints, this is 250, but some endpoints may have different values. Default: If the default is not documented, 250 should be assumed. In addition, most resources impose a max value for limit of 250.

offset
Integer that specifies the offset of the first result from the beginning of the collection. For example, offset=500, then the system will return at most limit results starting at index 500. Indexing is 0-based, so the first item in the entire result set is at index 0. Default: 0 if not specified.

count
Boolean that indicates whether a total count will be returned in the X-Total-Count response header. The value will be the total size of the collection that would be returned if limit and offset were ignored. For example, if the total number of results is 1000, then count=true would return 1000 in the X-Total-Count header. Since requesting a total count can have performance impact, it is recommended not to send count=true if no use is being made of that value. Default: False.

Filtering Results

Any collection with a filters parameter supports Filtering. This means that an item will only be included in the returned array if the filters expression evaluates to true for that item.

Data Types

Filter expressions are applicable to fields of the following types:

Filter Syntax

The syntax of V3 filters is similar to, but not exactly the same as, that specified by the SCIM standard. Some key differences are

A slightly different set of supported operators Case-sensitivity of operators. All V3 filter operators are in lowercase; it is illegal to specify “EQ” instead of “eq”, for instance.

Primitive Operators

These filter operators apply directly to fields and their values:

Operator Description Example
ca True if the collection-valued field contains all the listed values. groups ca (“Venezia”,“Firenze”)
co True if the value of the fieldcontains the specified value as a substring.(Applicable to string-valued fields only.) name co “Rajesh”
eq True if the value of the field indicated by the first operand isequal to the value specified by the second operand. identitySummary.id eq “2c9180846e85e4b8016eafeba20c1314”
ge True if the value of the field indicated by the first operand isgreater or equal to the value specified by the second operand. daysUntilEscalation ge 7 name ge “Genaro”
gt True if the value of the field indicated by the first operand isgreater than the value specified by the second operand. daysUntilEscalation gt 7 name gt “Genaro” created gt 2018-12-18T23:05:55Z
in True if the field value is in the list of values. accountActivityItemId in (“2c9180846b0a0583016b299f210c1314”,“2c9180846b0a0581016b299e82560c1314”)
le True if the value of the field indicated by the first operand is less or equal to the value specified by the second operand. daysUntilEscalation le 7 name le “Genaro”
lt True if the value of the field indicated by the first operand is less than the value specified by the second operand. daysUntilEscalation lt 7 name lt “Genaro” created lt 2018-12-18T23:05:55Z
ne True if the value of the field indicated by the first operand isnot equal to the value specified by the second operand. type ne “ROLE”
pr True if the field is present, that is, not null. pr accountRequestInfo
sw True if the value of the field starts with the specified value.(Applicable to string-valued fields only.) name sw “Rajesh”
Operator Description Example
and True if both the filter-valued operands are true. startDate gt 2018 and name sw “Genaro”
not True if the filter-valued operand is false. not groups ca (“Venezia”,“Firenze”)
or True if either of the filter-valued operands are true. startDate gt 2018 or name sw “Genaro”

Composite Operators

These operators are applied to other filter expressions:

Operator Description Example
and True if both the filter-valued operands are true. startDate gt 2018 and name sw “Genaro”
not True if the filter-valued operand is false. not groups ca (“Venezia”,“Firenze”)
or True if either of the filter-valued operands are true. startDate gt 2018 or name sw “Genaro”

Known Limitations

Although filter expressions are a very general mechanism, individual API endpoints will only support filtering on a specific set of fields that are relevant to that endpoint, and will frequently only support a subset of operations for each field. For example, an endpoint might allow filtering on the name field but not support use of the co operator on that field. Consult the documentation for each API endpoint to determine what fields and operators can be used.

Attempts to use an unsupported filter expression will result in a 400 Bad Request response.

NOTES:

Unless explicitly noted otherwise, strings are compared lexicographically. Most comparisons are not case sensitive. Any situations where the comparisons are case sensitive will be called out.

Date-times are compared temporally; an earlier date-time is less than a later date-time.

The usual precedence/associativity of the composite operators applies, with not having higher priority than and, which in turn has higher priority than or. Parentheses can be used to override this precedence.

Examples: not prop1 eq val1 or prop2 eq val2 and prop3 eq val3

is equivalent to

(not (prop1 eq val1)) or ((prop2 eq val2) and (prop3 eq val3))

and

not (prop1 eq val1 or prop2 eq val2) and prop3 eq val3

is equivalent to

(not ((prop1 eq val1) or (prop2 eq val2))) and (prop3 eq val3)

Sorting Results

Sorting of results is supported with the standard sorters parameter. Its syntax is a set of comma-separated field names. Each field name may be optionally prefixed with a “-” character, which indicates the sort is descending based on the value of that field. Otherwise, the sort is ascending.

For example, to sort primarily by name in ascending order, and secondarily by modified date in descending order, you would specify:

sorters=name,-modified****