---
title: "Reference: contacts"
description: "Public CRM contact API for create, read, update, and omnichannel identity resolution."
---

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

# Reference: contacts

## Overview

Use the Contacts API for CRM records stored in Wazapin.

- `contacts` is the canonical customer resource.
- Use `POST /v1/contacts/lookup` to resolve an existing stored contact by one or more identifiers.
- Use `POST /v1/channels/{channelID}/contacts/lookup` only when you need provider-specific profile lookup from a channel.

## Common headers

- **`field`** `string` *(required)* — Primary auth header for public API requests.

- **`field`** `string` *(required)* — Use `application/json`.

## Canonical contact endpoints

| Endpoint | Purpose |
| --- | --- |
| `POST /v1/contacts` | Create or upsert a contact record |
| `GET /v1/contacts` | List stored contacts |
| `GET /v1/contacts/{contactID}` | Get one contact by internal contact ID |
| `PATCH /v1/contacts/{contactID}` | Update a stored contact |
| `DELETE /v1/contacts/{contactID}` | Delete a stored contact |
| `GET /v1/contacts/phone/{phone}` | Get one contact by phone number |
| `POST /v1/contacts/lookup` | Resolve a stored contact by omnichannel identifiers |
| `GET /v1/contacts/{contactID}/identities` | List identities linked to a contact |
| `GET /v1/contacts/{contactID}/notes` | List notes |
| `POST /v1/contacts/{contactID}/notes` | Create note |
| `GET /v1/contacts/{contactID}/tags` | List assigned tags |
| `POST /v1/contacts/{contactID}/tags` | Assign tag |
| `PUT /v1/contacts/{contactID}/consent/{channel}` | Upsert consent state |
| `GET /v1/contacts/{contactID}/consents` | List consent rows |
| `GET /v1/contacts/{contactID}/suppressions` | List suppressions |
| `POST /v1/contacts/{contactID}/suppressions` | Create or update suppression |

## Create a contact

`POST /v1/contacts`

**Request example:**

```bash cURL
curl -X POST "https://api.wazapin.com/v1/contacts" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
"phone_number": "+6281234567890",
"name": "Ujang",
"email": "ujang@example.com",
"external_source": "shopify",
"external_id": "cust_123",
"custom_fields": {
  "tier": "premium"
}
  }'
```

**Response example:**

```json 201 Created
{
  "data": {
"id": "cnt_123",
"phone_number": "+6281234567890",
"name": "Ujang",
"email": "ujang@example.com",
"external_source": "shopify",
"external_id": "cust_123"
  }
}
```

## Resolve a contact

`POST /v1/contacts/lookup`

Use this endpoint when your system knows one or more identifiers, but does not yet know Wazapin's internal `contactID`.

Supported identifier types:

- `contact_id`
- `phone`
- `whatsapp`
- `wa_id`
- `email`
- `external_id`

When `type` is `external_id`, include `source`.

### Resolve by phone

```bash cURL
curl -X POST "https://api.wazapin.com/v1/contacts/lookup" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
"identifiers": [
  {
    "type": "phone",
    "value": "+6281234567890"
  }
]
  }'
```

### Resolve by external identity

```bash cURL
curl -X POST "https://api.wazapin.com/v1/contacts/lookup" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
"identifiers": [
  {
    "type": "external_id",
    "source": "shopify",
    "value": "cust_123"
  }
]
  }'
```

### Resolve response

```json 200 OK
{
  "data": {
"id": "cnt_123",
"phone_number": "+6281234567890",
"name": "Ujang",
"email": "ujang@example.com"
  }
}
```

```json 404 Not Found
{
  "error": "contact not found",
  "code": "not_found"
}
```

```json 409 Conflict
{
  "error": "contact identifiers resolve to different contacts",
  "code": "conflict"
}
```

## Update a contact

`PATCH /v1/contacts/{contactID}`

```bash cURL
curl -X PATCH "https://api.wazapin.com/v1/contacts/cnt_123" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
"name": "Ujang Updated",
"email": "ujang-updated@example.com"
  }'
```

## Provider lookup versus CRM resolve

Use the correct endpoint for the correct job:

- `POST /v1/contacts/lookup`
  - resolves a stored CRM contact inside Wazapin
- `POST /v1/channels/{channelID}/contacts/lookup`
  - looks up provider-specific profile data from a connected channel

If you are building CRM, automation, segmentation, or customer-data workflows, use `lookup`.

## Related pages

- [API overview](/api/overview)
- [Authentication](/api/authentication)
- [API reference](/api-reference)
- [Send a message](/api-reference/messages/send-a-message)

## Example request

Source: https://docs.wazapin.id/api/reference-contacts/index.mdx