1. Home >
2. API >
3. 2 >
4. Users >
5. List Users

List Users

Use this API to get a paginated list of users in a OneLogin account.

The list of users can be filtered by a range of user properties including custom attributes. See the Query Parameters section for more detail on the filters that are available.

This call returns up to 50 users per page.

Pagination is implemented using a standard set of querystring variables. Total users, pages and other pagination metadata is available via response headers. For more details see the pagination guide.

Resource URL

https://<subdomain>/api/2/users

Header Parameters

Query Parameters

A combination of the following querystring parameters can be used to filter the list of users returned.

Fields

The fields query parameter is used to return a given list of attributes for each user.

For example if you wanted to return a users id, first name, last name and all of their custom attributes then the following query would be used.

https://<subdomain>.onelogin.com/api/2/users?fields=id,firstname,lastname,custom_attributes

Wildcard

Use the wildcard character * to broaden the scope of your search.

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

• Return the user whose email value equals hazel.zhang@onelogin.com

  https://<subdomain>.onelogin.com/api/2/users?email=hazel.zhang@onelogin.com

• Include wildcards. 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

• 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

• Return users displaying only selected fields per user:

  https://<subdomain>.onelogin.com/api/2/users?fields=email,username,status

• 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*

• 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

• 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

Sample Responses

[{
    "activated_at": null,
    "distinguished_name": null,
    "external_id": null,
    "firstname": "Mike",
    "last_login": null,
    "lastname": "Tester",
    "directory_id": null,
    "invitation_sent_at": null,
    "member_of": null,
    "updated_at": "2019-08-22T18:43:55.188Z",
    "created_at": "2019-08-22T18:43:55.188Z",
    "id": 56781966,
    "invalid_login_attempts": 0,
    "locked_until": null,
    "username": null,
    "email": "mike.tester@onelogin.com",
    "phone": null,
    "state": 1,
    "group_id": null,
    "password_changed_at": "2019-08-22T18:43:55.172Z",
    "status": 1,
    "samaccountname": null
  },
  ...
]

[{
      "lastname": "Slater",
      "last_login": "2020-06-03T19:59:21.382Z",
      "id": 36216766,
      "profile_picture_url": null,
      "firstname": "Kelly"
  },
  ...
]

{
    "message": "query parameter(s) not allowed: custom_attributes.date_of_birth",
    "name": "BadRequestError",
    "statusCode": 400
}

{
    "message": "query parameter(s) not allowed: first_login",
    "name": "BadRequestError",
    "statusCode": 400
}

{
    "message": "Unauthorized",
    "statusCode": 401,
    "name": "UnauthorizedError"
}

{
    "message": "Invalid sort field: created_at",
    "field": "created_at",
    "name": "UnprocessableEntityFieldError",
    "statusCode": 422
}

Postman Collection

Clicking Run in Postman button navigates to the page where you can fork the collection to your workspace. Forking the collection into your workspace will enable you to contribute to the source collection using pull requests. You can also view the collection in a public workspace if you like and even import a copy of the collection using the links present on the screen.

Sample Code

cURL

Replace sample values indicated by < > with your actual values.

List Users

curl 'https://<subdomain>/api/2/users' \
-X GET \
-H "Authorization: bearer <access_token>"

Have a Question?

Found a problem or a bug? Submit a support ticket.

Looking for walkthroughs or how-to guides on OneLogin's user and admin features? Check out the documentation in our Knowledge Base.

Have a product idea or request? Share it with us in our Ideas Portal.