Skip to main content
GET
/
api
/
contacts
List contacts
curl --request GET \
  --url https://core-api.getaptly.com/api/contacts \
  --header 'x-token: <api-key>'
{
  "data": [
    {
      "_id": "abc123",
      "firstname": "Jane",
      "lastname": "Smith",
      "fullname": "Jane Smith",
      "contactType": "Tenant",
      "email": [
        "jane@example.com"
      ],
      "phone": [
        {
          "number": "+14155551234",
          "type": "mobile"
        }
      ],
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-06-01T09:30:00Z",
      "customFields": {
        "DbJT6rMdnuds7vSbP": {
          "name": "Named On Lease",
          "dataType": "boolean-checkbox",
          "optional": true,
          "value": null
        },
        "5D8LYiyMt54aKD7x9": {
          "name": "Occupant Role",
          "dataType": "text",
          "optional": true,
          "value": null
        }
      }
    }
  ],
  "count": 1,
  "page": 0,
  "pageSize": 200
}

Authorizations

​
x-token
string
header
required

Query Parameters

​
page
integer
required

Zero-based page number. Up to 200 contacts per page.

Required range: x >= 0
​
contact_type
string

Filter by contact type ID.

​
email
string

Filter by email address (case-insensitive exact match).

​
phone
string

Filter by phone number. Formatting is ignored — digits are matched as a substring of stored numbers.

​
name
string

Fuzzy name search. Each word in the query must appear in the contact's full name (case-insensitive). For example, "john sm" matches "John Smith" or "Johnny Smalls".

​
updated_after
string<date-time>

Return only contacts updated after this timestamp (inclusive). Accepts any ISO 8601 date-time string, e.g. 2024-01-01T00:00:00Z. Useful for syncing — fetch only records that changed since your last pull.

​
updated_before
string<date-time>

Return only contacts updated before this timestamp (inclusive). Accepts any ISO 8601 date-time string. Can be combined with updated_after to filter a specific time window.

Response

Paginated list of contacts.

​
data
object[]
​
count
integer

Total number of matching contacts.

​
page
integer
​
pageSize
integer