Skip to main content
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"
    }
  }'

{
  "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"
  }
}
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

​
phoneNumber
string
required
Phone number in E.164 format (e.g., +11234567890).
​
campaignId
string (UUID)
required
The ID of the campaign to associate this contact with. Use List Campaigns to retrieve valid IDs.
​
name
string
Full name of the contact. Maximum 255 characters.
​
timezone
string
IANA timezone string (e.g., America/New_York). If omitted, the timezone is auto-detected from the phone number’s area code.
​
customVariables
object
Key-value pairs of custom data to store on the contact.
For campaigns with appointment scheduling enabled, customVariables.email is required.

​
Response

​
success
boolean
Always true on a successful request.
​
data
object
The created or updated contact object.
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"
    }
  }'

{
  "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"
  }
}