Reference: contacts

Public CRM contact API for create, read, update, and omnichannel identity resolution.

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:

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:

{
  "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

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

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

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

{
  "error": "contact not found",
  "code": "not_found"
}

{
  "error": "contact identifiers resolve to different contacts",
  "code": "conflict"
}

Update a contact

PATCH /v1/contacts/{contactID}

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.