See api-docs Menu
  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.

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.

Many of the search tools described in our Getting Started documentation can be applied to your parameters, allowing you to fine-tune your results.

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

Sample Responses

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized
  • 422 Unprocessable Entity
[{
    "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.