curl -X GET "https://api.guayaba.ai/contacts?status=active&page=1&limit=10" \
-H "X-API-Key: gua_a1b2c3d4_your-api-key-here"
const params = new URLSearchParams({
status: 'active',
page: '1',
limit: '10'
});
const response = await fetch(`https://api.guayaba.ai/contacts?${params}`, {
headers: {
'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
}
});
const data = await response.json();
import requests
response = requests.get(
'https://api.guayaba.ai/contacts',
params={'status': 'active', 'page': 1, 'limit': 10},
headers={'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'}
)
data = response.json()
{
"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
}
}
{
"error": "Unauthorized",
"message": "Invalid or missing API key"
}
Contacts
List Contacts
Retrieve a paginated, filterable list of contacts.
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"
const params = new URLSearchParams({
status: 'active',
page: '1',
limit: '10'
});
const response = await fetch(`https://api.guayaba.ai/contacts?${params}`, {
headers: {
'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
}
});
const data = await response.json();
import requests
response = requests.get(
'https://api.guayaba.ai/contacts',
params={'status': 'active', 'page': 1, 'limit': 10},
headers={'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'}
)
data = response.json()
{
"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
}
}
{
"error": "Unauthorized",
"message": "Invalid or missing API key"
}
Returns a list of contacts for your team, with support for filtering by status, campaign, and search query. Results are paginated.
Query Parameters
number
default:"1"
Page number for pagination.
number
default:"25"
Number of contacts to return per page.
string
Filter contacts by status (e.g.,
active, fulfilled, paused). Use List Statuses to retrieve all valid values for your team.string (UUID)
Filter by campaign ID. Accepts comma-separated values to filter by multiple campaigns at once (e.g.,
uuid1,uuid2).string
Search contacts by name or phone number. Use with
searchBy to narrow the field.string
Restrict the
search parameter to a specific field. Accepted values: name, phone. If omitted, both fields are searched.string
default:"createdAt"
Field to sort results by. Accepted values:
createdAt, fulfilledAt, reAddedAt.string
default:"desc"
Sort direction. Accepted values:
asc, desc.Response
array
Array of contact objects.
Show Contact fields
Show Contact fields
string (UUID)
Contact unique identifier.
string
Contact name.
string
Phone number in E.164 format.
string
IANA timezone string.
string
Current contact status.
object
Custom key-value data stored on the contact.
string (ISO 8601)
Creation timestamp. If the contact was re-added, this reflects the
reAddedAt timestamp.string or null
Timestamp when the contact was fulfilled.
null if not yet fulfilled.string or null
Timestamp when the contact was re-added.
null if never re-added.array
List of campaigns the contact is associated with, each containing
id and name.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"
const params = new URLSearchParams({
status: 'active',
page: '1',
limit: '10'
});
const response = await fetch(`https://api.guayaba.ai/contacts?${params}`, {
headers: {
'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
}
});
const data = await response.json();
import requests
response = requests.get(
'https://api.guayaba.ai/contacts',
params={'status': 'active', 'page': 1, 'limit': 10},
headers={'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'}
)
data = response.json()
{
"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
}
}
{
"error": "Unauthorized",
"message": "Invalid or missing API key"
}