See api-docs Menu

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.

Syncing Users

When attempting to sync users between OneLogin and another system it is more efficient to use the updated_since query parameter as this will let you return only the users that have changed since the last time you checked.

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

Authorization

required

string

Set to bearer <access_token>.

Set <access_token> to the access token you generated using the Generate Token API.

The access token must have been generated using an API credential pair created using the scope required to call this API. This API can be called using any one of the following scopes: Read Users, Manage users, Read All, or Manage All.

Query Parameters

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

created_since

string

An ISO8601 timestamp value that returns all users created after a given date & time. e.g. 2020-07-01T20:38:24Z

created_until

string

An ISO8601 timestamp value that returns all users created before a given date & time.

updated_since

string

An ISO8601 timestamp value that returns all users updated after a given date & time.

updated_until

string

An ISO8601 timestamp value that returns all users updated before a given date & time.

last_login_since

string

An ISO8601 timestamp value that returns all users that logged in after a given date & time.

last_login_until

string

An ISO8601 timestamp value that returns all users that logged in before a given date & time.

firstname

string

The first name of the user

lastname

string

The last name of the user

email

string

The email address of the user

username

string

The username for the user

samaccountname

string

The AD login name for the user

directory_id

string

The ID in OneLogin of the Directory that the user belongs to

external_id

string

An external identifier that has be set on the user

app_id

string

The ID of a OneLogin Application

user_ids

string

A comma separated list of OneLogin User IDs

custom_attributes.{attribute_name}

string

The short name of a custom attribute. Note that the attribute name is prefixed with custom_attributes.

fields

string

A comma separated list user attributes to return.

e.g. id,firstname,lastname,profile_picture_url

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
  },
  ...
]

With a limited set of fields

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

An invalid search parameter was used.

{
    "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
}

Typically, this error means that your access token value is invalid.

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

You cant sort on this field.

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

Postman Collection

Run In Postman

    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.