1. Home >
2. API >
3. 2 >
4. Get Started >
5. Using Query Parameters

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.

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