# List available owners

**Endpoint:** `POST {veza_url}/api/v1/list_available_owners`\
**Authentication:** Bearer token (`admin`, `operator`, or `nhi_security_admin` role)

Returns a paginated list of active IdP users that are eligible to be assigned as entity owners. Use this endpoint to populate an owner picker before calling [Batch Set Owners](/4yItIzMvkpAvMVFAamTf/developers/api/management/owners/batchsetowners.md).

***

## Minimal Working Example

```bash
curl -X POST "https://your-tenant.veza.com/api/v1/list_available_owners" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "search_value": "alice",
    "page_size": 25
  }'
```

**Response:**

```json
{
  "owners": [
    {
      "entity_id": "abc123",
      "entity_type": "OktaUser",
      "entity_name": "Alice Smith",
      "external_id": "alice@example.com"
    }
  ],
  "next_page_token": "eyJwYWdlIjoxfQ==",
  "has_more": true
}
```

***

## Request Fields

| Field               | Type            | Required | Description                                                                                                                    |
| ------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `search_value`      | string          | No       | Search string for filtering owners. Case-insensitive partial match. If omitted, all available owners are returned (paginated). |
| `search_properties` | array of string | No       | Properties to search on. Defaults to `name` and `email` when `search_value` is provided but this field is empty.               |
| `page_size`         | integer         | No       | Results per page. Defaults to `1000` if unset or `0`.                                                                          |
| `page_token`        | string          | No       | Token from a previous response's `next_page_token`. Omit to get the first page.                                                |

***

## Response Fields

| Field             | Type    | Description                                                                                                                          |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `owners`          | array   | Valid, active owner entities matching the request. Each entry includes `entity_id`, `entity_type`, `entity_name`, and `external_id`. |
| `next_page_token` | string  | Pass this value as `page_token` in the next request to retrieve the following page. Empty when no further pages exist.               |
| `has_more`        | boolean | `true` if additional results are available beyond this page.                                                                         |

***

## What Counts as "Active"

Only active IdP users are returned. Active status is evaluated per IdP type:

| IdP type              | Active condition                                                      |
| --------------------- | --------------------------------------------------------------------- |
| `AzureADUser`         | `account_enabled = true`                                              |
| `OktaUser`            | `status` not in `PROVISIONED`, `DEPROVISIONED`, `STAGED`, `SUSPENDED` |
| `GoogleWorkspaceUser` | `archived = false` and `suspended = false`                            |
| All others            | `is_active` property absent, or `is_active = true`                    |

If a global IdP is configured for your tenant, only that IdP's user type is returned. Otherwise, all IdP user entities are returned.

***

## Pagination Example

Iterate through all available owners by following `next_page_token`:

```bash
# First page
curl -X POST ".../api/v1/list_available_owners" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"page_size": 100}'

# Subsequent pages — use next_page_token from prior response
curl -X POST ".../api/v1/list_available_owners" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"page_size": 100, "page_token": "eyJwYWdlIjoxfQ=="}'
```

Stop when `has_more` is `false` or `next_page_token` is empty.

***

## Common Use Case

Use `list_available_owners` to discover valid candidates before assigning owners with [Batch Set Owners](/4yItIzMvkpAvMVFAamTf/developers/api/management/owners/batchsetowners.md):

1. Call `list_available_owners` with `search_value` to find a user by name or email
2. Copy the `entity_id` and `entity_type` from the response
3. Pass them as `Owner` objects in a `batch_set_owners` request


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/management/owners/listavailableowners.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.