See api-docs Menu

List Users

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

Early Preview

This API is in early preview and may be subject to change.

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.

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://<api-domain>/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

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://api.us.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://api.us.onelogin.com/api/2/users?email=katinka*

    https://api.us.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://api.us.onelogin.com/api/2/users?sort=+firstname

  • Return users displaying only selected fields per user:

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

  • Return users based on custom attribute value:

    https://api.us.onelogin.com/api/2/users?custom_attributes.employeeNumber=123456

    Also supports wildcard search

    https://api.us.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://api.us.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://api.us.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

Replace sample variables indicated by {{ }} with your actual values.

Download for the Users API

Sample Code

cURL

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

List Users

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

Have a Question?

Have a how-to question? Seeing a weird error? Ask us about it on StackOverflow.

Found a bug? Submit a support ticket.

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