Skip to main content
GET
/
contacts
curl -X GET "https://api.guayaba.ai/contacts?status=active&page=1&limit=10" \
  -H "X-API-Key: gua_a1b2c3d4_your-api-key-here"

{
  "contacts": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "name": "John Doe",
      "phoneNumber": "+11234567890",
      "timezone": "America/New_York",
      "status": "active",
      "customVariables": {
        "email": "john@example.com"
      },
      "createdAt": "2026-01-15T10:30:00.000Z",
      "fulfilledAt": null,
      "reAddedAt": null,
      "campaigns": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Q1 Outreach"
        }
      ]
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "limit": 10
  }
}
Returns a list of contacts for your team, with support for filtering by status, campaign, and search query. Results are paginated.

​
Query Parameters

​
page
number
default:"1"
Page number for pagination.
​
limit
number
default:"25"
Number of contacts to return per page.
​
status
string
Filter contacts by status (e.g., active, fulfilled, paused). Use List Statuses to retrieve all valid values for your team.
​
campaignId
string (UUID)
Filter by campaign ID. Accepts comma-separated values to filter by multiple campaigns at once (e.g., uuid1,uuid2).
​
search
string
Search contacts by name or phone number. Use with searchBy to narrow the field.
​
searchBy
string
Restrict the search parameter to a specific field. Accepted values: name, phone. If omitted, both fields are searched.
​
sortBy
string
default:"createdAt"
Field to sort results by. Accepted values: createdAt, fulfilledAt, reAddedAt.
​
sortOrder
string
default:"desc"
Sort direction. Accepted values: asc, desc.

​
Response

​
contacts
array
Array of contact objects.
​
pagination
object
curl -X GET "https://api.guayaba.ai/contacts?status=active&page=1&limit=10" \
  -H "X-API-Key: gua_a1b2c3d4_your-api-key-here"

{
  "contacts": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "name": "John Doe",
      "phoneNumber": "+11234567890",
      "timezone": "America/New_York",
      "status": "active",
      "customVariables": {
        "email": "john@example.com"
      },
      "createdAt": "2026-01-15T10:30:00.000Z",
      "fulfilledAt": null,
      "reAddedAt": null,
      "campaigns": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Q1 Outreach"
        }
      ]
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "limit": 10
  }
}