ContactsContacts

Contacts

Store and manage contact information for your recipients. Contacts track phone numbers, names, tags, and messaging availability. The lastContactedAt timestamp is automatically updated when sending or receiving messages.

Create a Contact

curl -X POST https://api.textbubbles.com/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14155551234",
    "firstName": "Jane",
    "lastName": "Doe",
    "company": "Acme",
    "tags": ["vip", "enterprise"]
  }'

Auto-Create on Send

Pass createContact: true when sending a message to automatically create a contact:

curl -X POST https://api.textbubbles.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "content": { "text": "Hello!" },
    "createContact": true
  }'

List and Search

# List all contacts
curl https://api.textbubbles.com/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY"
 
# Filter by tag
curl "https://api.textbubbles.com/v1/contacts?tag=vip" \
  -H "Authorization: Bearer YOUR_API_KEY"
 
# Search by name, phone, email, or company
curl "https://api.textbubbles.com/v1/contacts?search=jane" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get a Contact

curl https://api.textbubbles.com/v1/contacts/CONTACT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Update a Contact

curl -X PUT https://api.textbubbles.com/v1/contacts/CONTACT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "tags": ["vip", "enterprise", "priority"]
  }'

Delete a Contact

curl -X DELETE https://api.textbubbles.com/v1/contacts/CONTACT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Bulk Operations

Bulk create (max 100):

curl -X POST https://api.textbubbles.com/v1/contacts/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phoneNumber": "+14155551234", "firstName": "Jane" },
      { "phoneNumber": "+14155559999", "firstName": "John" }
    ]
  }'

Bulk delete:

curl -X DELETE https://api.textbubbles.com/v1/contacts/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["contact-id-1", "contact-id-2"] }'

Focus Status

Check if a contact has a Focus mode active:

curl https://api.textbubbles.com/v1/contacts/+14155551234/focus \
  -H "Authorization: Bearer YOUR_API_KEY"

Endpoints

MethodPathDescription
POST/v1/contactsCreate a contact
GET/v1/contactsList contacts (filter by tag, search)
GET/v1/contacts/:idGet a contact
PUT/v1/contacts/:idUpdate a contact
DELETE/v1/contacts/:idDelete a contact
POST/v1/contacts/bulkBulk create (max 100)
DELETE/v1/contacts/bulkBulk delete by IDs
GET/v1/contacts/:phone/focusGet Focus status
GET/v1/contacts/:phone/facetimeGet FaceTime availability
Typing IndicatorsApple Cash