List contacts

GEThttps://secure.alterestate.com/api/v1/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.

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}/

Authentication

Send Authorization: Token your_api_key_here. Account token. Keep it on your server.

Pagination

pageinteger: Page number. Defaults to 1.Example: 1
page_sizeinteger: Results per page. Defaults to 100.Example: 100

Search

searchstring: Matches name, email, the main phone or an extra phone. Accent insensitive on the name.Example: Ana
full_namestring: Partial name match.Example: Martinez
emailstring: Partial email match. Stored emails are lowercase.Example: ana@

People

agentsstring: Uid of an assigned agent.Example: IZHIZ6C3Z6
created_bystring: Uid of the user who registered the contact.Example: IZHIZ6C3Z6
tagstring: Tag uid.Example: TAG01HOT
ctypenumber: Contact type id configured by the agency.Example: 37

Dates

startDatedate: Contacts created on or after this date (YYYY-MM-DD).Example: 2026-03-01
endDatedate: Contacts created on or before this date (YYYY-MM-DD).Example: 2026-03-31

Sorting

sortstring: full_name, email, job_place, via or timestamp. Prefix with - for descending. Defaults to name A–Z.Example: -timestamp

Example request

GET

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

Example response

200 OK

{
  "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.

Frequently asked questions

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.

Last updated 2026-10-13. Questions? Emailengineering@alterestate.com.