REST API endpoints for contacts — Waply API

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.

string

Unique identifier for the contact, prefixed with con_.

string

The contact’s phone number in E.164 format (for example, +14155552671).

string

The contact’s display name.

string

The contact’s email address.

string[]

Array of tag strings used for segmentation and broadcast targeting.

string

The contact’s current lifecycle stage (for example, lead, customer, churned).

object

Key-value pairs for any custom attributes you have defined on your account.

string

ISO 8601 timestamp of when the contact was created.

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.

number

default:"1"

Page number to retrieve.

number

default:"20"

Number of contacts per page. Maximum is 100.

string

Filter contacts that have this tag applied.

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'

const params = new URLSearchParams({ page: 1, limit: 20, tag: 'vip' });
const response = await fetch(`https://api.waply.io/v1/contacts?${params}`, {
  headers: { 'Authorization': `Bearer ${process.env.WAPLY_API_KEY}` },
});
const { data, total, page } = await response.json();

import requests, os

response = requests.get(
    'https://api.waply.io/v1/contacts',
    headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
    params={'page': 1, 'limit': 20, 'tag': 'vip'},
)
result = response.json()

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.

string

required

Phone number in E.164 format (for example, +14155552671). Must be unique within your account.

string

Display name for the contact.

string

Email address for the contact.

string[]

Tags to assign to the contact. Creates tags that do not already exist.

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

const response = await fetch('https://api.waply.io/v1/contacts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.WAPLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone: '+14155552671',
    name: 'Jane Doe',
    email: 'jane@example.com',
    tags: ['newsletter', 'vip'],
    custom_fields: { account_tier: 'gold' },
  }),
});
const contact = await response.json();

import requests, os

response = requests.post(
    'https://api.waply.io/v1/contacts',
    headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
    json={
        'phone': '+14155552671',
        'name': 'Jane Doe',
        'email': 'jane@example.com',
        'tags': ['newsletter', 'vip'],
        'custom_fields': {'account_tier': 'gold'},
    },
)
contact = response.json()

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.

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'

const response = await fetch('https://api.waply.io/v1/contacts/con_01HXYZ', {
  headers: { 'Authorization': `Bearer ${process.env.WAPLY_API_KEY}` },
});
const contact = await response.json();

import requests, os

response = requests.get(
    'https://api.waply.io/v1/contacts/con_01HXYZ',
    headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
)
contact = response.json()

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.

string

required

The ID of the contact to update.

string

Phone number in E.164 format.

string

Display name for the contact.

string

Email address for the contact.

string[]

Replaces the contact’s existing tags with this array.

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"]
  }'

const response = await fetch('https://api.waply.io/v1/contacts/con_01HXYZ', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.WAPLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Jane Smith',
    tags: ['newsletter', 'vip', 'renewed'],
  }),
});
const updated = await response.json();

import requests, os

response = requests.put(
    'https://api.waply.io/v1/contacts/con_01HXYZ',
    headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
    json={'name': 'Jane Smith', 'tags': ['newsletter', 'vip', 'renewed']},
)
updated = response.json()

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.

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'

await fetch('https://api.waply.io/v1/contacts/con_01HXYZ', {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${process.env.WAPLY_API_KEY}` },
});

import requests, os

requests.delete(
    'https://api.waply.io/v1/contacts/con_01HXYZ',
    headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
)

Response

{
  "success": true
}

​The Contact object

​List contacts

​GET /contacts

​Create a contact

​POST /contacts

​Get a contact

​GET /contacts/

​Update a contact

​PUT /contacts/

​Delete a contact

​DELETE /contacts/

The Contact object

List contacts

GET /contacts

Create a contact

POST /contacts

Get a contact

GET /contacts/

Update a contact

PUT /contacts/

Delete a contact

DELETE /contacts/