# List users

Returns a paginated list of users, 100 users per page by default.
When querying larger instances, reduce the count parameter to 1,000 or less, and use the startIndex parameter to paginate through users.
It's possible to return a list of specific types of users with the filter parameter.
Examples:

  /list?filter=userName eq "testuser"
  /list??filter=status eq "PENDING_ACTIVATION"
  /list??filter=id eq "91f659cd-6ded-4d92-aa5c-144c3b5455c3" and status eq "PENDING_ACTIVATION"

Endpoint: GET /scim/v2/Users
Version: 2026-02-20
Security: bearerAuth

## Header parameters:

  - `Idempotency-Key` (string)
    Specify a unique idempotency key if you want to perform an idempotent POST or PATCH request. Do not use this header in other request types. 

With this header specified, the Zuora server can identify subsequent retries of the same request using this value, which prevents the same operation from being performed multiple times by accident.

  - `Accept-Encoding` (string)
    Include the Accept-Encoding: gzip header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response. 

If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a Content-Encoding header with the compression algorithm so that your client can decompress it.

  - `Content-Encoding` (string)
    Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

  - `Zuora-Track-Id` (string)
    A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

  - `Zuora-Entity-Ids` (string)
    An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you should not set this header.

## Response 200 fields (application/json):

  - `schemas` (array)
    A list of schema URNs that describe the structure of the response.
    Example: ["urn:ietf:params:scim:api:messages:2.0:ListResponse"]

  - `totalResults` (integer)
    The total number of results matching the query.
    Example: 327

  - `resources` (array)
    Example: [{"schemas":["urn:zuora:scim:schemas:1.0:UserExtension","urn:ietf:params:scim:schemas:core:2.0:User"],"id":"91f659cd-6ded-4d92-bd5c-144c3b5455c4","meta":{"created":"2023-07-04T10:12:03.721Z","resourceType":"User","location":"http://localhost:9900/scim/v2/Users/91f659cd-6ded-4d92-bd5c-144c3b5455c4"},"userName":"aghosh+123","name":{"formatted":"aghosh g","familyName":"g","givenName":"aghosh"},"displayName":"aghosh g","preferredLanguage":"en","locale":"en-US","active":false,"emails":[{"value":"aghosh+123@zuora.com","display":"aghosh+123@zuora.com","type":"work","primary":true}],"roles":[{"value":"ADMIN","display":"ADMIN"}],"urn:zuora:scim:schemas:1.0:UserExtension":{"schemas":["urn:zuora:scim:schemas:1.0:UserExtension"],"organizationId":"ec141dc2-901e-4813-a25d-ef480cff1e26","status":"PENDING_ACTIVATION","ssoEnabled":false,"region":"US"}},{"schemas":["urn:zuora:scim:schemas:1.0:UserExtension","urn:ietf:params:scim:schemas:core:2.0:User"],"id":"eb48a32d-2fe6-48d1-8a18-797919f3810a","meta":{"created":"2023-07-13T06:15:25.836Z","resourceType":"User","location":"http://localhost:9900/scim/v2/Users/eb48a32d-2fe6-48d1-8a18-797919f3810a"},"userName":"Amy+555","name":{"formatted":"Amy Lawrence","familyName":"Amy","givenName":"Lawrence"},"displayName":"Amy Lawrence","preferredLanguage":"en","locale":"en-US","active":true,"emails":[{"value":"asmurugesan+555@zuora.com","display":"asmurugesan+555@zuora.com","type":"work","primary":true}],"groups":[{"value":"7f5c248e-44e8-48d3-bacc-b5bd1253c2e4","display":""}],"roles":[{"value":"USER","display":"USER"}],"urn:zuora:scim:schemas:1.0:UserExtension":{"schemas":["urn:zuora:scim:schemas:1.0:UserExtension"],"organizationId":"rc141dc2-901e-4813-a25d-ef480cff1e26","status":"ACTIVE","ssoEnabled":false,"region":"EU"}}]

  - `resources.schemas` (array)
    A list of schema URNs that describe the structure of the user resource.

  - `resources.id` (string)
    The unique identifier for the user resource.

  - `resources.meta` (object)

  - `resources.meta.created` (string)
    The timestamp when the user resource was created.

  - `resources.meta.resourceType` (string)
    The type of resource, in this case, 'User'.

  - `resources.meta.location` (string)
    The URI of the user resource.

  - `resources.userName` (string)
    The username associated with the user account.

  - `resources.name` (object)

  - `resources.name.formatted` (string)
    The full name of the user, formatted for display.

  - `resources.name.familyName` (string)
    The user's family (last) name.

  - `resources.name.givenName` (string)
    The user's given (first) name.

  - `resources.displayName` (string)
    The display name of the user.

  - `resources.preferredLanguage` (string)
    The preferred language of the user.

  - `resources.locale` (string)
    The locale of the user.

  - `resources.active` (boolean)
    Indicates whether the user account is active.

  - `resources.emails` (array)

  - `resources.emails.value` (string)
    The email address of the user.

  - `resources.emails.display` (string)
    The display name associated with the email address.

  - `resources.emails.type` (string)
    The type of email address (e.g., work, home).

  - `resources.emails.primary` (boolean)
    Indicates whether this email address is the primary one for the user.

  - `resources.roles` (array)

  - `resources.roles.value` (string)
    The role identifier associated with the user.

  - `resources.roles.display` (string)
    The display name of the role.

  - `resources.groups` (array)

  - `resources.groups.value` (string)
    The group identifier to which the user belongs.

  - `resources.groups.display` (string)
    The display name of the group.

  - `resources.urn:zuora:scim:schemas:1.0:UserExtension` (object)

  - `resources.urn:zuora:scim:schemas:1.0:UserExtension.schemas` (array)
    A list of schema URNs specific to the UserExtension.

  - `resources.urn:zuora:scim:schemas:1.0:UserExtension.organizationId` (string)
    The identifier of the organization to which the user belongs.

  - `resources.urn:zuora:scim:schemas:1.0:UserExtension.status` (string)
    The current status of the user account (e.g., ACTIVE, PENDING_ACTIVATION).

  - `resources.urn:zuora:scim:schemas:1.0:UserExtension.ssoEnabled` (boolean)
    Indicates whether Single Sign-On (SSO) is enabled for the user.

  - `resources.urn:zuora:scim:schemas:1.0:UserExtension.region` (string)
    The region where the user is located.

  - `startIndex` (integer)
    The index of the first result in the current page.
    Example: 1

  - `itemsPerPage` (integer)
    The number of items per page in the response.
    Example: 100

## Response 401 fields (application/json):

  - `success` (boolean)
    Indicates whether the request was successful or not. In this case, it will be false due to unauthorized access.

  - `reasons` (array)

  - `reasons.message` (string)
    A brief description of the reason for the unauthorized access. Provides context for the failure.
    Example: "Unauthorized"

  - `reasons.code` (string)
    A code representing the error. Used for programmatic identification of the error.
    Example: "90000011"

## Response 403 fields (application/json):

  - `timestamp` (string)
    The timestamp when the error occurred. Provides context for when the error happened.
    Example: "2023-07-28T10:47:07.931+00:00"

  - `status` (integer)
    The HTTP status code for the error. Indicates that the server understood the request but refuses to authorize it.
    Example: 403

  - `error` (string)
    A brief description of the error. Indicates that access is forbidden.
    Example: "Forbidden"

  - `message` (string)
    A detailed message about the error, usually describing why the request was forbidden.
    Example: "Admin access denied"

  - `path` (string)
    The URI path of the request that caused the error. Helps in identifying the resource involved in the error.
    Example: "/scim/v2/Users"

## Response 404 fields (application/json):

  - `schemas` (array)
    A list of schema URNs related to the error response. Provides information about the error response structure.

  - `status` (string)
    The HTTP status code for the error. Indicates that the requested resource could not be found.
    Example: "404"

  - `detail` (string)
    A description of the error. Provides details about why the resource was not found.
    Example: "Resource not found"