# List contacts

Returns the contacts your account can open, 100 per page by default. Search by name, email or phone, and filter by agent, tag or creation date.

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

A contact belongs to the user who registered it. Results follow the token: a user who can view every contact sees the company, a team leader sees the teams they lead plus contacts they created, and an agent sees contacts they are assigned to or created.

| Capability | Endpoint |
| --- | --- |
| List contacts | GET /api/v1/contacts/ |
| Get one contact | GET /api/v1/contacts/view/{uid}/ |
| Create a contact | POST /api/v1/contacts/new/ |
| Update a contact | PATCH /api/v1/contacts/edit/{uid}/ |

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

Authentication: `Authorization: Token your_api_key_here`

| Parameter | In | Type | Required | Group | Description |
| --- | --- | --- | --- | --- | --- |
| `page` | query | integer | no | Pagination | Page number. Defaults to 1. |
| `page_size` | query | integer | no | Pagination | Results per page. Defaults to 100. |
| `search` | query | string | no | Search | Matches name, email, the main phone or an extra phone. Accent insensitive on the name. |
| `full_name` | query | string | no | Search | Partial name match. |
| `email` | query | string | no | Search | Partial email match. Stored emails are lowercase. |
| `agents` | query | string | no | People | Uid of an assigned agent. |
| `created_by` | query | string | no | People | Uid of the user who registered the contact. |
| `tag` | query | string | no | People | Tag uid. |
| `ctype` | query | number | no | People | Contact type id configured by the agency. |
| `startDate` | query | date | no | Dates | Contacts created on or after this date (YYYY-MM-DD). |
| `endDate` | query | date | no | Dates | Contacts created on or before this date (YYYY-MM-DD). |
| `sort` | query | string | no | Sorting | full_name, email, job_place, via or timestamp. Prefix with - for descending. Defaults to name A–Z. |

Example request:

```bash
curl --request GET \
  --url 'https://secure.alterestate.com/api/v1/contacts/?search=Ana' \
  --header 'Authorization: Token your_api_key_here' \
  --header 'Accept: application/json'
```

Response 200 OK:

```json
{
  "count": 128,
  "next": null,
  "previous": null,
  "results": [
    {
      "uid": "D9dEML2g39",
      "full_name": "Ana Martinez",
      "email": "ana@example.com",
      "phone": "+18095550123",
      "phones": [
        {
          "id": 88,
          "phone": "+18095550999",
          "description": "3"
        }
      ],
      "job_place": "Martinez Group",
      "tag": {
        "uid": "TAG01HOT",
        "name": "Hot",
        "color": "#42916F"
      },
      "created_by": 42,
      "agents": [
        {
          "uid": "IZHIZ6C3Z6",
          "first_name": "John",
          "last_name": "Smith",
          "email": "john@agency.com",
          "phone": "+18095550000"
        }
      ],
      "integration_id": null,
      "timestamp": "2026-03-01T23:26:53.402000-04:00"
    }
  ],
  "filters": {
    "search": "Ana"
  }
}
```

## Fields on each contact

| Field | Description |
| --- | --- |
| uid | Public identifier. Use it to retrieve or edit the contact. |
| full_name, email, phone | Name, email and main phone. phone is E.164, for example +18095550123. |
| phones | Extra phones. description is 1 work, 2 home, 3 mobile, 4 other. |
| job_place | Company or workplace. |
| tag | Tag with uid, name and color, or null. |
| agents | Assigned agents, plus the creator when they are not already assigned. Each item has uid, name, email and phone. |
| created_by | Numeric id of the user who registered the contact. |
| integration_id | Id from an external system, when one was stored. |
| timestamp | When the contact was created. |

The list does not accept include_fields. Retrieve a contact for notes, custom fields, contact type and the rest of the profile.

## 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. |
| 403 | The contact already exists, or this user cannot edit it. |
| 404 | The contact does not exist, or this account cannot open it. |
| 429 | Too many requests. Wait and retry. |
| 500 | Server error while processing the request. |

- [Retrieve a contact](https://dev.alterestate.com/contacts/retrieve)
- [Create a contact](https://dev.alterestate.com/contacts/create)
- [Edit a contact](https://dev.alterestate.com/contacts/edit)

## FAQ

### How do I find a contact by phone or email?

Send search with the name, email or phone. email= also matches part of the address. Matches are not case sensitive, and emails are stored lowercase.

### How many contacts does each page return?

100 by default. Pass page_size to change it and page to move forward. next is null on the last page.