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

string

required

Primary auth header for public API requests.

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

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

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

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

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

200 OK

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

404 Not Found

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

409 Conflict

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

Update a contact

PATCH /v1/contacts/{contactID}

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.

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

​Overview

​Common headers

​Canonical contact endpoints

​Create a contact

​Resolve a contact

​Resolve by phone

​Resolve by external identity

​Resolve response

​Update a contact

​Provider lookup versus CRM resolve

​Related pages

Overview

Common headers

Canonical contact endpoints

Create a contact

Resolve a contact

Resolve by phone

Resolve by external identity

Resolve response

Update a contact

Provider lookup versus CRM resolve

Related pages