> This page is for Developers.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://zuora.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://zuora.ferndocs.com/_mcp/server.

# List users

GET https://one.zuora.com/scim/v2/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"
```


Reference: https://zuora.ferndocs.com/developers/api-reference/zuora-api/oneid/scim/get-list-of-users

## Authentication

- `Authorization` header (bearer token, required) — Use `Bearer {{token}}` in the `Authorization` header for authentication.

## Request

### Headers

- `Idempotency-Key` (string, optional) — 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, optional) — 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, optional) — 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, optional) — 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, optional) — An entity ID. If you have [Zuora Multi-entity](https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/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

OK

- `schemas` (list of string, optional) — A list of schema URNs that describe the structure of the response.
- `totalResults` (integer, optional) — The total number of results matching the query.
- `resources` (list of ScimV2UsersGetResponsesContentApplicationJsonSchemaResourcesItems, optional)
- `startIndex` (integer, optional) — The index of the first result in the current page.
- `itemsPerPage` (integer, optional) — The number of items per page in the response.

## Errors

### 401 Unauthorized Error

Unauthorized

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

### 403 Forbidden Error

Forbidden

- `timestamp` (datetime, optional) — The timestamp when the error occurred. Provides context for when the error happened.
- `status` (integer, optional) — The HTTP status code for the error. Indicates that the server understood the request but refuses to authorize it.
- `error` (string, optional) — A brief description of the error. Indicates that access is forbidden.
- `message` (string, optional) — A detailed message about the error, usually describing why the request was forbidden.
- `path` (string, optional) — The URI path of the request that caused the error. Helps in identifying the resource involved in the error.

### 404 Not Found Error

Not Found

- `schemas` (list of string, optional) — A list of schema URNs related to the error response. Provides information about the error response structure.
- `status` (string, optional) — The HTTP status code for the error. Indicates that the requested resource could not be found.
- `detail` (string, optional) — A description of the error. Provides details about why the resource was not found.

## Types

### ScimV2UsersGetResponsesContentApplicationJsonSchemaResourcesItems

- `schemas` (list of string, optional) — A list of schema URNs that describe the structure of the user resource.
- `id` (string, optional) — The unique identifier for the user resource.
- `meta` (ScimV2UsersGetResponsesContentApplicationJsonSchemaResourcesItemsMeta, optional)
- `userName` (string, optional) — The username associated with the user account.
- `name` (ScimV2UsersGetResponsesContentApplicationJsonSchemaResourcesItemsName, optional)
- `displayName` (string, optional) — The display name of the user.
- `preferredLanguage` (string, optional) — The preferred language of the user.
- `locale` (string, optional) — The locale of the user.
- `active` (boolean, optional) — Indicates whether the user account is active.
- `emails` (list of ScimV2UsersGetResponsesContentApplicationJsonSchemaResourcesItemsEmailsItems, optional)
- `roles` (list of ScimV2UsersGetResponsesContentApplicationJsonSchemaResourcesItemsRolesItems, optional)
- `groups` (list of ScimV2UsersGetResponsesContentApplicationJsonSchemaResourcesItemsGroupsItems, optional)
- `urn:zuora:scim:schemas:1.0:UserExtension` (ScimV2UsersGetResponsesContentApplicationJsonSchemaResourcesItemsUrnZuoraScimSchemas10UserExtension, optional)

### ScimV2UsersGetResponsesContentApplicationJsonSchemaReasonsItems

- `message` (string, optional) — A brief description of the reason for the unauthorized access. Provides context for the failure.
- `code` (string, optional) — A code representing the error. Used for programmatic identification of the error.

### ScimV2UsersGetResponsesContentApplicationJsonSchemaResourcesItemsMeta

- `created` (datetime, optional) — The timestamp when the user resource was created.
- `resourceType` (string, optional) — The type of resource, in this case, 'User'.
- `location` (string, optional) — The URI of the user resource.

### ScimV2UsersGetResponsesContentApplicationJsonSchemaResourcesItemsName

- `formatted` (string, optional) — The full name of the user, formatted for display.
- `familyName` (string, optional) — The user's family (last) name.
- `givenName` (string, optional) — The user's given (first) name.

### ScimV2UsersGetResponsesContentApplicationJsonSchemaResourcesItemsEmailsItems

- `value` (string, optional) — The email address of the user.
- `display` (string, optional) — The display name associated with the email address.
- `type` (string, optional) — The type of email address (e.g., work, home).
- `primary` (boolean, optional) — Indicates whether this email address is the primary one for the user.

### ScimV2UsersGetResponsesContentApplicationJsonSchemaResourcesItemsRolesItems

- `value` (string, optional) — The role identifier associated with the user.
- `display` (string, optional) — The display name of the role.

### ScimV2UsersGetResponsesContentApplicationJsonSchemaResourcesItemsGroupsItems

- `value` (string, optional) — The group identifier to which the user belongs.
- `display` (string, optional) — The display name of the group.

### ScimV2UsersGetResponsesContentApplicationJsonSchemaResourcesItemsUrnZuoraScimSchemas10UserExtension

- `schemas` (list of string, optional) — A list of schema URNs specific to the UserExtension.
- `organizationId` (string, optional) — The identifier of the organization to which the user belongs.
- `status` (string, optional) — The current status of the user account (e.g., ACTIVE, PENDING_ACTIVATION).
- `ssoEnabled` (boolean, optional) — Indicates whether Single Sign-On (SSO) is enabled for the user.
- `region` (string, optional) — The region where the user is located.

## Examples

**Response**

```json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 327,
  "resources": [
    {
      "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
        }
      ],
      "roles": [
        {
          "value": "USER",
          "display": "USER"
        }
      ],
      "groups": [
        {
          "value": "7f5c248e-44e8-48d3-bacc-b5bd1253c2e4",
          "display": ""
        }
      ],
      "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"
      }
    }
  ],
  "startIndex": 1,
  "itemsPerPage": 100
}
```

**SDK Code**

```python
import requests

url = "https://one.zuora.com/scim/v2/Users"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://one.zuora.com/scim/v2/Users';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://one.zuora.com/scim/v2/Users"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://one.zuora.com/scim/v2/Users")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://one.zuora.com/scim/v2/Users")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://one.zuora.com/scim/v2/Users', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://one.zuora.com/scim/v2/Users");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://one.zuora.com/scim/v2/Users")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```