List Contacts

Retrieve a paginated list of contacts with optional filtering.

Request

GET /contacts

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (min: 1)
per_page	integer	100	Items per page (min: 1, max: 100)
search	string	-	If valid email: exact match on email. Otherwise: search by first_name, last_name, phone, or full name (max 255 characters)
list_uuid	string	-	Filter by contact list membership

Ordering: Results are ordered by created_at descending (newest first).

Example Request

curl -X GET "https://email.easy.tools/api/v1/contacts?page=1&per_page=50&search=john" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response

Success Response (200 OK)

{
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+48123456789",
      "external_id": "customer_123",
      "language": "en",
      "country_code": "US",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    },
    {
      "uuid": "660e8400-e29b-41d4-a716-446655440001",
      "email": "john.smith@example.com",
      "first_name": "John",
      "last_name": "Smith",
      "phone": null,
      "external_id": null,
      "language": "pl",
      "country_code": null,
      "created_at": "2025-01-14T09:00:00Z",
      "updated_at": "2025-01-14T09:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 2
  }
}

Response Fields

Field	Type	Description
uuid	string	Contact's unique identifier
email	string	Contact's email address
first_name	string|null	Contact's first name
last_name	string|null	Contact's last name
phone	string|null	Contact's phone number
external_id	string|null	External identifier for integration purposes
language	string|null	ISO 639-1 language code (2 characters)
country_code	string|null	ISO 3166-1 alpha-2 country code (2 characters)
created_at	string	ISO 8601 timestamp (UTC)
updated_at	string	ISO 8601 timestamp (UTC)

Pagination Object

Field	Type	Description
current_page	integer	Current page number
per_page	integer	Number of items per page
total	integer	Total number of contacts

Error Responses

Validation Error (422 Unprocessable Entity)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid",
    "details": {
      "per_page": ["The per page must not be greater than 100."],
      "list_uuid": ["The list uuid must be a valid UUID."]
    }
  }
}