curl -X POST https://api.guayaba.ai/contacts \
-H "Content-Type: application/json" \
-H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
-d '{
"phoneNumber": "+11234567890",
"campaignId": "550e8400-e29b-41d4-a716-446655440000",
"name": "John Doe",
"customVariables": {
"email": "john@example.com",
"company": "Acme Inc"
}
}'
const response = await fetch('https://api.guayaba.ai/contacts', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
},
body: JSON.stringify({
phoneNumber: '+11234567890',
campaignId: '550e8400-e29b-41d4-a716-446655440000',
name: 'John Doe',
customVariables: {
email: 'john@example.com',
company: 'Acme Inc'
}
})
});
const data = await response.json();
import requests
response = requests.post(
'https://api.guayaba.ai/contacts',
headers={
'Content-Type': 'application/json',
'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
},
json={
'phoneNumber': '+11234567890',
'campaignId': '550e8400-e29b-41d4-a716-446655440000',
'name': 'John Doe',
'customVariables': {
'email': 'john@example.com',
'company': 'Acme Inc'
}
}
)
data = response.json()
{
"success": true,
"data": {
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"phoneNumber": "+11234567890",
"name": "John Doe",
"campaignId": "550e8400-e29b-41d4-a716-446655440000",
"customVariables": {
"email": "john@example.com",
"company": "Acme Inc"
},
"timezone": "America/New_York",
"status": "active",
"createdAt": "2026-01-15T10:30:00.000Z"
}
}
{
"error": "Validation error",
"message": "phoneNumber is required and must be in E.164 format"
}
{
"error": "Not found",
"message": "Campaign not found"
}
Contacts
Create Contact
Create a new contact and associate them with a campaign.
POST
/
contacts
curl -X POST https://api.guayaba.ai/contacts \
-H "Content-Type: application/json" \
-H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
-d '{
"phoneNumber": "+11234567890",
"campaignId": "550e8400-e29b-41d4-a716-446655440000",
"name": "John Doe",
"customVariables": {
"email": "john@example.com",
"company": "Acme Inc"
}
}'
const response = await fetch('https://api.guayaba.ai/contacts', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
},
body: JSON.stringify({
phoneNumber: '+11234567890',
campaignId: '550e8400-e29b-41d4-a716-446655440000',
name: 'John Doe',
customVariables: {
email: 'john@example.com',
company: 'Acme Inc'
}
})
});
const data = await response.json();
import requests
response = requests.post(
'https://api.guayaba.ai/contacts',
headers={
'Content-Type': 'application/json',
'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
},
json={
'phoneNumber': '+11234567890',
'campaignId': '550e8400-e29b-41d4-a716-446655440000',
'name': 'John Doe',
'customVariables': {
'email': 'john@example.com',
'company': 'Acme Inc'
}
}
)
data = response.json()
{
"success": true,
"data": {
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"phoneNumber": "+11234567890",
"name": "John Doe",
"campaignId": "550e8400-e29b-41d4-a716-446655440000",
"customVariables": {
"email": "john@example.com",
"company": "Acme Inc"
},
"timezone": "America/New_York",
"status": "active",
"createdAt": "2026-01-15T10:30:00.000Z"
}
}
{
"error": "Validation error",
"message": "phoneNumber is required and must be in E.164 format"
}
{
"error": "Not found",
"message": "Campaign not found"
}
Creates a new contact and enrolls them in the specified campaign. If a contact with the same phone number was previously deleted, they will be reactivated. If a contact already exists and is active, this request will update their information.
Request Body
string
required
Phone number in E.164 format (e.g.,
+11234567890).string (UUID)
required
The ID of the campaign to associate this contact with. Use List Campaigns to retrieve valid IDs.
string
Full name of the contact. Maximum 255 characters.
string
IANA timezone string (e.g.,
America/New_York). If omitted, the timezone is auto-detected from the phone number’s area code.object
Key-value pairs of custom data to store on the contact.
For campaigns with appointment scheduling enabled,
customVariables.email is required.Response
boolean
Always
true on a successful request.object
The created or updated contact object.
Show Contact fields
Show Contact fields
string (UUID)
Unique identifier for the contact.
string
Phone number in E.164 format.
string
Contact name.
string (UUID)
Associated campaign ID.
object
Custom key-value data stored on the contact.
string
IANA timezone string.
string
Contact status. Newly created contacts start as
active.string (ISO 8601)
Timestamp of when the contact was created.
curl -X POST https://api.guayaba.ai/contacts \
-H "Content-Type: application/json" \
-H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
-d '{
"phoneNumber": "+11234567890",
"campaignId": "550e8400-e29b-41d4-a716-446655440000",
"name": "John Doe",
"customVariables": {
"email": "john@example.com",
"company": "Acme Inc"
}
}'
const response = await fetch('https://api.guayaba.ai/contacts', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
},
body: JSON.stringify({
phoneNumber: '+11234567890',
campaignId: '550e8400-e29b-41d4-a716-446655440000',
name: 'John Doe',
customVariables: {
email: 'john@example.com',
company: 'Acme Inc'
}
})
});
const data = await response.json();
import requests
response = requests.post(
'https://api.guayaba.ai/contacts',
headers={
'Content-Type': 'application/json',
'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
},
json={
'phoneNumber': '+11234567890',
'campaignId': '550e8400-e29b-41d4-a716-446655440000',
'name': 'John Doe',
'customVariables': {
'email': 'john@example.com',
'company': 'Acme Inc'
}
}
)
data = response.json()
{
"success": true,
"data": {
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"phoneNumber": "+11234567890",
"name": "John Doe",
"campaignId": "550e8400-e29b-41d4-a716-446655440000",
"customVariables": {
"email": "john@example.com",
"company": "Acme Inc"
},
"timezone": "America/New_York",
"status": "active",
"createdAt": "2026-01-15T10:30:00.000Z"
}
}
{
"error": "Validation error",
"message": "phoneNumber is required and must be in E.164 format"
}
{
"error": "Not found",
"message": "Campaign not found"
}