> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waply.io/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API endpoints for contacts — Waply API

> Create, retrieve, update, delete, and search contacts in your Waply account. Includes the Contact object schema and code examples in curl, JS, and Python.

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.

<ResponseField name="id" type="string">
  Unique identifier for the contact, prefixed with `con_`.
</ResponseField>

<ResponseField name="phone" type="string">
  The contact's phone number in E.164 format (for example, `+14155552671`).
</ResponseField>

<ResponseField name="name" type="string">
  The contact's display name.
</ResponseField>

<ResponseField name="email" type="string">
  The contact's email address.
</ResponseField>

<ResponseField name="tags" type="string[]">
  Array of tag strings used for segmentation and broadcast targeting.
</ResponseField>

<ResponseField name="lifecycle_stage" type="string">
  The contact's current lifecycle stage (for example, `lead`, `customer`, `churned`).
</ResponseField>

<ResponseField name="custom_fields" type="object">
  Key-value pairs for any custom attributes you have defined on your account.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the contact was created.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of the most recent update to the contact.
</ResponseField>

***

## List contacts

### GET /contacts

Returns a paginated list of contacts. Use query parameters to filter by tag or search by name or phone number.

<ParamField query="page" type="number" default="1">
  Page number to retrieve.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Number of contacts per page. Maximum is `100`.
</ParamField>

<ParamField query="tag" type="string">
  Filter contacts that have this tag applied.
</ParamField>

<ParamField query="search" type="string">
  Search contacts by name or phone number. Partial matches are supported.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.waply.io/v1/contacts?page=1&limit=20&tag=vip' \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "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.

<ParamField body="phone" type="string" required>
  Phone number in E.164 format (for example, `+14155552671`). Must be unique within your account.
</ParamField>

<ParamField body="name" type="string">
  Display name for the contact.
</ParamField>

<ParamField body="email" type="string">
  Email address for the contact.
</ParamField>

<ParamField body="tags" type="string[]">
  Tags to assign to the contact. Creates tags that do not already exist.
</ParamField>

<ParamField body="custom_fields" type="object">
  Key-value pairs matching the custom fields defined in your Waply account settings.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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" }
    }'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "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/{id}

Returns a single contact by its ID.

<ParamField path="id" type="string" required>
  The ID of the contact to retrieve.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.waply.io/v1/contacts/con_01HXYZ \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "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/{id}

Updates an existing contact. Include only the fields you want to change — fields you omit retain their existing values.

<ParamField path="id" type="string" required>
  The ID of the contact to update.
</ParamField>

<ParamField body="phone" type="string">
  Phone number in E.164 format.
</ParamField>

<ParamField body="name" type="string">
  Display name for the contact.
</ParamField>

<ParamField body="email" type="string">
  Email address for the contact.
</ParamField>

<ParamField body="tags" type="string[]">
  Replaces the contact's existing tags with this array.
</ParamField>

<ParamField body="custom_fields" type="object">
  Merges these key-value pairs into the contact's existing custom fields.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

**Response**

Returns the full updated Contact object.

```json theme={null}
{
  "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/{id}

Permanently deletes a contact. This action cannot be undone. The contact's conversation history is retained for audit purposes.

<ParamField path="id" type="string" required>
  The ID of the contact to delete.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url https://api.waply.io/v1/contacts/con_01HXYZ \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```

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

  ```python Python theme={null}
  import requests, os

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

**Response**

```json theme={null}
{
  "success": true
}
```