curl -X POST https://api.guayaba.ai/contacts/update \
-H "Content-Type: application/json" \
-H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
-d '{
"phone": "+11234567890",
"status": "fulfilled"
}'
curl -X POST https://api.guayaba.ai/contacts/update \
-H "Content-Type: application/json" \
-H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
-d '{
"phone": "+11234567890",
"campaignId": "550e8400-e29b-41d4-a716-446655440000"
}'
curl -X POST https://api.guayaba.ai/contacts/update \
-H "Content-Type: application/json" \
-H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
-d '{
"phone": "+11234567890",
"status": "active",
"campaignId": "550e8400-e29b-41d4-a716-446655440000"
}'
const response = await fetch('https://api.guayaba.ai/contacts/update', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
},
body: JSON.stringify({
phone: '+11234567890',
status: 'fulfilled'
})
});
const data = await response.json();
import requests
response = requests.post(
'https://api.guayaba.ai/contacts/update',
headers={
'Content-Type': 'application/json',
'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
},
json={
'phone': '+11234567890',
'status': 'fulfilled'
}
)
data = response.json()
{
"success": true,
"message": "Contact updated successfully",
"contact": {
"id": "contact-uuid-here",
"phoneNumber": "+11234567890",
"name": "John Doe",
"campaignId": "550e8400-e29b-41d4-a716-446655440000",
"status": "fulfilled",
"fulfilledAt": "2026-04-22T15:30:00.000Z",
"updatedAt": "2026-04-22T15:30:00.000Z"
}
}
{
"error": "Validation error",
"message": "At least one of status or campaignId must be provided"
}
{
"error": "Unauthorized",
"message": "Invalid or missing API key"
}
{
"error": "Not found",
"message": "Contact not found"
}
{
"error": "Rate limit exceeded",
"message": "Too many requests"
}
Contacts
Update Contact By Phone Number
Update a contact’s status or campaign by phone number.
POST
/
contacts
/
update
curl -X POST https://api.guayaba.ai/contacts/update \
-H "Content-Type: application/json" \
-H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
-d '{
"phone": "+11234567890",
"status": "fulfilled"
}'
curl -X POST https://api.guayaba.ai/contacts/update \
-H "Content-Type: application/json" \
-H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
-d '{
"phone": "+11234567890",
"campaignId": "550e8400-e29b-41d4-a716-446655440000"
}'
curl -X POST https://api.guayaba.ai/contacts/update \
-H "Content-Type: application/json" \
-H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
-d '{
"phone": "+11234567890",
"status": "active",
"campaignId": "550e8400-e29b-41d4-a716-446655440000"
}'
const response = await fetch('https://api.guayaba.ai/contacts/update', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
},
body: JSON.stringify({
phone: '+11234567890',
status: 'fulfilled'
})
});
const data = await response.json();
import requests
response = requests.post(
'https://api.guayaba.ai/contacts/update',
headers={
'Content-Type': 'application/json',
'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
},
json={
'phone': '+11234567890',
'status': 'fulfilled'
}
)
data = response.json()
{
"success": true,
"message": "Contact updated successfully",
"contact": {
"id": "contact-uuid-here",
"phoneNumber": "+11234567890",
"name": "John Doe",
"campaignId": "550e8400-e29b-41d4-a716-446655440000",
"status": "fulfilled",
"fulfilledAt": "2026-04-22T15:30:00.000Z",
"updatedAt": "2026-04-22T15:30:00.000Z"
}
}
{
"error": "Validation error",
"message": "At least one of status or campaignId must be provided"
}
{
"error": "Unauthorized",
"message": "Invalid or missing API key"
}
{
"error": "Not found",
"message": "Contact not found"
}
{
"error": "Rate limit exceeded",
"message": "Too many requests"
}
Updates a contact identified by their phone number — no contact ID required. Use this to change a contact’s status or move them to a different campaign from your own systems. Actions are logged as
contacts-actions-by-api so they’re tracked separately from in-app actions.
This endpoint requires an
X-API-Key header. See Authentication for details.Request Body
string
required
Phone number of the contact to update, in E.164 format (e.g.,
+11234567890).string
New status for the contact. Use List Statuses to retrieve valid values. Default system statuses include
active, paused, fulfilled, DNC, not-qualifies, not-interested, not-answering, wrong-number, and talk-to-human.string (UUID)
New campaign to move the contact to.
At least one of
status or campaignId must be provided. You can send both in the same request.Behavior Notes
Terminal statuses cancel outreach
Terminal statuses cancel outreach
Setting a contact to any terminal status (
fulfilled, paused, DNC, not-qualifies, not-interested, not-answering, wrong-number) automatically cancels all scheduled calls, SMS, WhatsApp messages, and triggers for that contact.Re-activating a contact
Re-activating a contact
Setting the status back to
active reschedules outreach based on the contact’s campaign configuration.Changing campaigns
Changing campaigns
Changing
campaignId cancels scheduled actions from the old campaign and schedules new actions based on the new campaign’s configuration.Action logging
Action logging
Updates made through this endpoint are logged as
contacts-actions-by-api and do not inflate in-app action stats.Response
boolean
Always
true on a successful request.string
Human-readable confirmation message.
object
The updated contact object.
Show Contact fields
Show Contact fields
string (UUID)
Contact unique identifier.
string
Phone number in E.164 format.
string
Contact name.
string
Updated contact status.
string (UUID)
Current campaign ID.
string (ISO 8601)
Timestamp when the contact was marked as fulfilled. Only present when status is
fulfilled.string (ISO 8601)
Timestamp of this update.
curl -X POST https://api.guayaba.ai/contacts/update \
-H "Content-Type: application/json" \
-H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
-d '{
"phone": "+11234567890",
"status": "fulfilled"
}'
curl -X POST https://api.guayaba.ai/contacts/update \
-H "Content-Type: application/json" \
-H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
-d '{
"phone": "+11234567890",
"campaignId": "550e8400-e29b-41d4-a716-446655440000"
}'
curl -X POST https://api.guayaba.ai/contacts/update \
-H "Content-Type: application/json" \
-H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
-d '{
"phone": "+11234567890",
"status": "active",
"campaignId": "550e8400-e29b-41d4-a716-446655440000"
}'
const response = await fetch('https://api.guayaba.ai/contacts/update', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
},
body: JSON.stringify({
phone: '+11234567890',
status: 'fulfilled'
})
});
const data = await response.json();
import requests
response = requests.post(
'https://api.guayaba.ai/contacts/update',
headers={
'Content-Type': 'application/json',
'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
},
json={
'phone': '+11234567890',
'status': 'fulfilled'
}
)
data = response.json()
{
"success": true,
"message": "Contact updated successfully",
"contact": {
"id": "contact-uuid-here",
"phoneNumber": "+11234567890",
"name": "John Doe",
"campaignId": "550e8400-e29b-41d4-a716-446655440000",
"status": "fulfilled",
"fulfilledAt": "2026-04-22T15:30:00.000Z",
"updatedAt": "2026-04-22T15:30:00.000Z"
}
}
{
"error": "Validation error",
"message": "At least one of status or campaignId must be provided"
}
{
"error": "Unauthorized",
"message": "Invalid or missing API key"
}
{
"error": "Not found",
"message": "Contact not found"
}
{
"error": "Rate limit exceeded",
"message": "Too many requests"
}