# List users

Returns your agency’s active users (agents) that are shown on the website, with contact details, team, division and number of listings.

Source: https://dev.alterestate.com/users
Last updated: 2026-10-13

> This section was called Agents in earlier versions of the documentation. The endpoint path is still /api/v1/agents/.

```http
GET https://secure.alterestate.com/api/v1/agents/
```

Authentication: `aetoken: your_public_token`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `full_name` | query | string | no | Matches first or last name. |
| `position` | query | string | no | Exact position, for example Real estate agent. |
| `division` | query | number | no | Division ID. |

Example request:

```bash
curl --request GET \
  --url 'https://secure.alterestate.com/api/v1/agents/' \
  --header 'aetoken: your_public_token' \
  --header 'Accept: application/json'
```

Response 200 OK:

```json
[
  {
    "id": 67,
    "uid": "ABCDEFGHJKLM",
    "slug": "john-doe",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "email": "johndoe@agency.com",
    "phone": "+14070000000",
    "priority": 0,
    "position": "Real estate agent",
    "avatar": "https://d2p0bx8wfdkjkb.cloudfront.net/static/user-67/avatar.png",
    "division": "Santo Domingo",
    "facebook_username": "agencydr",
    "instagram_username": "agency",
    "rate": null,
    "team": "Downtown team",
    "user_type": "1",
    "company": "Demo Realty",
    "bio": "<p>Specialist in Naco and Piantini.</p>",
    "properties": 67,
    "company_domain": "demo.alterestate.com"
  }
]
```

Response 500 Server Error:

```json
{
  "detail": "A server error occurred."
}
```

## Response fields

| Field | Description |
| --- | --- |
| uid | User identifier. Use it in related (Create a lead) and agents (List properties). |
| slug | Public profile slug. |
| full_name, email, phone | Contact details. phone uses E.164. |
| position, team, division | Role and organization inside the agency. |
| priority | Display order set by the agency. Results are sorted by it. |
| avatar, bio | Profile photo URL and biography. bio may contain HTML; sanitize it before rendering. |
| facebook_username, instagram_username | Social profiles, when set. |
| rate | Average rating from testimonials, or null. |
| properties | Number of listings assigned to the user. |
| company, company_domain | Agency name and website domain. |

## Notes

- Only active users with Show on website enabled are returned.
- Results are a plain array, not paginated.
- Franchises configured to share agents return users from every agency in the organization.

## Status codes

| Status | Meaning |
| --- | --- |
| 200 | The request succeeded. |
| 400 | A parameter or the body is invalid. The response names the field. |
| 401 | The token is missing or invalid. |
| 404 | The resource or route does not exist. |
| 429 | Too many requests. Wait and retry. |
| 500 | Server error while processing the request. |

## FAQ

### Does the AlterEstate users endpoint return inactive users?

No. GET /api/v1/agents/ only returns active users who are shown on the agency website.

### Where do I get the public token for the users endpoint?

An administrator copies it from Settings → Public API Token in the AlterEstate dashboard, and you send it in the aetoken header.