Using Query Parameters

The following querystring parameters can be used to filter results as well as control pagination, sorting, and specify the fields in the payload that is returned.

Fields

When you call a resource API, include the fields query parameter to return only the attributes you want to return. Generally you can include any field that is normally returned on a Get single resource endpoint. For example, to return only the app name and id, use the field parameter with this criteria:

https://<subdomain>.onelogin.com/api/2/apps?fields=id,name

The response will return user objects that look like this:

{
  "id": 134598765,
  "name": "Salesforce"
}

Search

When you call a resource API, include a search parameter to return only the results that meet your criteria. For example, you can search for a specific attribute value:

https://<subdomain>.onelogin.com/api/2/apps?name=dropbox

The following examples illustrate how to use various query parameters to return subsets of users:

Exact match. Return the user whose email value equals hazel.zhang@onelogin.com https://<subdomain>.onelogin.com/api/2/users?email=hazel.zhang@onelogin.com
Wildcard. In many cases, you can use the wildcard character * to broaden the scope of your search. For example, you can return all users whose email values start with Katinka or all users whose email values end with @onelogin.com: https://<subdomain>.onelogin.com/api/2/users?email=katinka* https://<subdomain>.onelogin.com/api/2/users?email=*@onelogin.com
Sort. Return users sorted by firstname. Use + to sort in ascending order or - to sort in descending order: https://<subdomain>.onelogin.com/api/2/users?sort=+firstname
Displayed fields. Return users displaying only selected fields per user: https://<subdomain>.onelogin.com/api/2/users?fields=email,username,status
Custom attributes. Return users based on custom attribute value: https://<subdomain>.onelogin.com/api/2/users?custom_attributes.employeeNumber=123456 Also supports wildcard search https://<subdomain>.onelogin.com/api/2/users?custom_attributes.fav_color=re*
Time-bound. Return users updated after a given date. 2010-11-01T19:44:55.681Z. https://<subdomain>.onelogin.com/api/2/users?updated_since=2010-11-01T19:44:55Z Return users created within a window of time bound by specific created_at values using the created_since and created_until parameters: https://<subdomain>.onelogin.com/api/2/users?created_since=2010-11-01T19:44:55Z&created_until=2011-11-01T19:44:55Z

Pagination

When working with list endpoints that support pagination a simple set of querystring variables can be supplied to limit the size of the result set and request a specific page of results.

The List Events endpoint uses cursor-based pagination and returns its pagination object (next_cursor, has_more) in the response body rather than in the headers described below. See that page for details.

`limit`	The total number of items returned per page. The maximum limit varies between endpoints, see the relevant endpoint documentation for the specific limit.
`page`	The page number of results to return.
`cursor`	Set to the value extracted from `Before-Cursor` or `After-Cursor` headers to return the previous or next page.

For example:

GET https://<subdomain>.onelogin.com/api/2/apps?page=2&limit=10

or

GET https://<subdomain>.onelogin.com/api/2/apps?cursor=bGltaXQ9MTAwMCZwYWdlPTM%3D

Response Headers

When pagination is available the following set of headers will be returned. Use these headers to learn the total number of items in the list and the current page that is being returned. Link, Before-Cursor, and After-Cursor are also available for conveniently returning surrounding pages of results.

`Current-Page`	The index number of the current page being returned.
`Page-Items`	The number of items returned in the response.
`Total-Count`	The total number of items across all pages.
`Total-Pages`	The total number of pages to return all results.
`Link`	A set of urls which contains premade links for first, next
`Before-Cursor`	A string that can be used to request the page of results that preceed the current page using the same set of search filters and pagination options.
`After-Cursor`	A string that can be used to request the page of results that follows the current page using the same set of search filters and pagination options.

For example:

< HTTP/1.1 200 OK
< After-Cursor: bGltaXQ9MTAwMCZwYWdlPTM%3D
< Before-Cursor: bGltaXQ9MTAwMCZwYWdlPTE%3D
< Cache-Control: private, max-age=0, must-revalidate
< Content-Type: application/json; charset=utf-8
< Current-Page: 1
< Date: Tue, 17 Mar 2020 17:31:48 GMT
< ETag: "e61dd3c3f9a934f750c5014f42de24d6"
< Link: <https://<subdomain>.onelogin.com/api/2/apps?limit=5&page=1&sort=+name>; rel="first",<https://<subdomain>.onelogin.com/api/2/apps?limit=5&page=16&sort=+name>; rel="last",<https://<subdomain>.onelogin.com/api/2/apps?limit=5&page=2&sort=+name>; rel="next",
< Page-Items: 5
< Status: 200 OK
< Strict-Transport-Security: max-age=63072000
< Total-Count: 80
< Total-Pages: 16
< X-Content-Type-Options: nosniff
< X-Request-Id: 5E710983-944069C8-E36A-0A0B05CA-01BB-100FFDC0-506C
< X-Xss-Protection: 1; mode=block
< Content-Length: 18019

Sort

When you call a resource API, include the sort query parameter to sort results by a specific field. For example, when fetching a list of apps use the sort parameter with criteria of name and - to return resources sorted by name field value in descending order. For example:

https://<subdomain>.onelogin.com/api/2/apps?sort=-name

Use a + instead of - to sort in ascending order. For example:

https://<subdomain>.onelogin.com/api/2/apps?sort=+name