# Contacts

> Create, read, update, and delete contacts and contact lists via the WAFlow Public API.

Source: https://edesy.in/docs/waflow/api/contacts

Manage the people you message and the lists you group them into.

**Required scopes:** `contacts.read` for reads, `contacts.write` for writes.

## List contacts

```http
GET /api/v1/contacts
```

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `search` | string | Match name, phone, or email |
| `page` | integer | Page number (default 1) |
| `pageSize` | integer | Items per page (default 50, max 100) |

**Response:**
```json
{
  "success": true,
  "contacts": [
    { "id": 42, "phoneNumber": "+919812345678", "firstName": "Raj", "email": "raj@example.com" }
  ],
  "pagination": { "page": 1, "pageSize": 50, "total": 1 }
}
```

**cURL Example:**
```bash
curl "https://waflow.edesy.in/api/v1/contacts?search=raj&pageSize=20" \
  -H "X-API-Key: wc_your_api_key"
```

---

## Create a contact

```http
POST /api/v1/contacts
```

**Request Body:**
```json
{
  "phoneNumber": "+919812345678",
  "firstName": "Raj",
  "lastName": "Sharma",
  "email": "raj@example.com",
  "customFields": { "plan": "gold" },
  "notes": "VIP customer"
}
```

Only `phoneNumber` is required. Created contacts are tagged `source: api`.

**cURL Example:**
```bash
curl -X POST "https://waflow.edesy.in/api/v1/contacts" \
  -H "X-API-Key: wc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+919812345678", "firstName": "Raj" }'
```

---

## Get a contact

```http
GET /api/v1/contacts/{id}
```

Returns `404` with `code: NOT_FOUND` if the contact doesn't exist.

---

## Update a contact

```http
PATCH /api/v1/contacts/{id}
```

**Request Body** (any subset):
```json
{
  "firstName": "Rajesh",
  "email": "rajesh@example.com",
  "customFields": { "plan": "platinum" },
  "optedOut": false
}
```

---

## Delete a contact

```http
DELETE /api/v1/contacts/{id}
```

**Response:**
```json
{ "success": true }
```

---

## Contact lists

Group contacts into static lists (useful as campaign audiences).

### List all lists

```http
GET /api/v1/contact-lists
```

### Create a list

```http
POST /api/v1/contact-lists
```

**Request Body:**
```json
{ "name": "VIP Customers", "description": "High‑value accounts" }
```

### Get a list

```http
GET /api/v1/contact-lists/{id}
```

### Add contacts to a list

```http
POST /api/v1/contact-lists/{id}/contacts
```

**Request Body:**
```json
{ "contactIds": [42, 43, 44] }
```

**Response:**
```json
{ "success": true, "added": 3 }
```

### Delete a list

```http
DELETE /api/v1/contact-lists/{id}
```

**cURL Example:**
```bash
curl -X POST "https://waflow.edesy.in/api/v1/contact-lists" \
  -H "X-API-Key: wc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "VIP Customers" }'
```