Skip to main content
Contacts represent the people you message through Waply. Each contact has a phone number, optional profile fields, tags for segmentation, and a lifecycle stage. Use the contacts API to sync your CRM, import subscribers, or manage contacts programmatically.

​
The Contact object

Every contacts endpoint returns a Contact object or an array of Contact objects.
​
id
string
Unique identifier for the contact, prefixed with con_.
​
phone
string
The contact’s phone number in E.164 format (for example, +14155552671).
​
name
string
The contact’s display name.
​
email
string
The contact’s email address.
​
tags
string[]
Array of tag strings used for segmentation and broadcast targeting.
​
lifecycle_stage
string
The contact’s current lifecycle stage (for example, lead, customer, churned).
​
custom_fields
object
Key-value pairs for any custom attributes you have defined on your account.
​
created_at
string
ISO 8601 timestamp of when the contact was created.
​
updated_at
string
ISO 8601 timestamp of the most recent update to the contact.

​
List contacts

​
GET /contacts

Returns a paginated list of contacts. Use query parameters to filter by tag or search by name or phone number.
​
page
number
default:"1"
Page number to retrieve.
​
limit
number
default:"20"
Number of contacts per page. Maximum is 100.
​
tag
string
Filter contacts that have this tag applied.
​
search
string
Search contacts by name or phone number. Partial matches are supported.
curl --request GET \
  --url 'https://api.waply.io/v1/contacts?page=1&limit=20&tag=vip' \
  --header 'Authorization: Bearer YOUR_API_KEY'
Response 
{
  "data": [
    {
      "id": "con_01HXYZ",
      "phone": "+14155552671",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "tags": ["vip", "newsletter"],
      "lifecycle_stage": "customer",
      "custom_fields": { "account_tier": "gold" },
      "created_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-03-22T14:30:00Z"
    }
  ],
  "total": 142,
  "page": 1
}

​
Create a contact

​
POST /contacts

Creates a new contact. The contact’s phone number must be unique within your account.
​
phone
string
required
Phone number in E.164 format (for example, +14155552671). Must be unique within your account.
​
name
string
Display name for the contact.
​
email
string
Email address for the contact.
​
tags
string[]
Tags to assign to the contact. Creates tags that do not already exist.
​
custom_fields
object
Key-value pairs matching the custom fields defined in your Waply account settings.
curl --request POST \
  --url https://api.waply.io/v1/contacts \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "phone": "+14155552671",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "tags": ["newsletter", "vip"],
    "custom_fields": { "account_tier": "gold" }
  }'
Response 
{
  "id": "con_01HXYZ",
  "phone": "+14155552671",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "tags": ["newsletter", "vip"],
  "lifecycle_stage": "lead",
  "custom_fields": { "account_tier": "gold" },
  "created_at": "2026-04-16T10:00:00Z",
  "updated_at": "2026-04-16T10:00:00Z"
}

​
Get a contact

​
GET /contacts/

Returns a single contact by its ID.
​
id
string
required
The ID of the contact to retrieve.
curl --request GET \
  --url https://api.waply.io/v1/contacts/con_01HXYZ \
  --header 'Authorization: Bearer YOUR_API_KEY'
Response 
{
  "id": "con_01HXYZ",
  "phone": "+14155552671",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "tags": ["newsletter", "vip"],
  "lifecycle_stage": "customer",
  "custom_fields": { "account_tier": "gold" },
  "created_at": "2026-01-10T09:00:00Z",
  "updated_at": "2026-03-22T14:30:00Z"
}

​
Update a contact

​
PUT /contacts/

Updates an existing contact. Include only the fields you want to change — fields you omit retain their existing values.
​
id
string
required
The ID of the contact to update.
​
phone
string
Phone number in E.164 format.
​
name
string
Display name for the contact.
​
email
string
Email address for the contact.
​
tags
string[]
Replaces the contact’s existing tags with this array.
​
custom_fields
object
Merges these key-value pairs into the contact’s existing custom fields.
curl --request PUT \
  --url https://api.waply.io/v1/contacts/con_01HXYZ \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Jane Smith",
    "tags": ["newsletter", "vip", "renewed"]
  }'
Response Returns the full updated Contact object. 
{
  "id": "con_01HXYZ",
  "phone": "+14155552671",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "tags": ["newsletter", "vip", "renewed"],
  "lifecycle_stage": "customer",
  "custom_fields": { "account_tier": "gold" },
  "created_at": "2026-01-10T09:00:00Z",
  "updated_at": "2026-04-16T11:45:00Z"
}

​
Delete a contact

​
DELETE /contacts/

Permanently deletes a contact. This action cannot be undone. The contact’s conversation history is retained for audit purposes.
​
id
string
required
The ID of the contact to delete.
curl --request DELETE \
  --url https://api.waply.io/v1/contacts/con_01HXYZ \
  --header 'Authorization: Bearer YOUR_API_KEY'
Response 
{
  "success": true
}