Contacts

Full CRUD over your organization's contacts. All endpoints use API-key authentication and the standard response envelope — see Getting Started for x-api-key, base URL, and rate limits.

---

List Contacts

GET /v1/contacts

cURL

curl -X GET 'https://app.superwaba.com/api/developer/v1/contacts?page=1&limit=20&search=priya' \
  -H 'x-api-key: sgk_YOUR_API_KEY'

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	20	Results per page (max: 100)
search	string	-	Search by name or phone number

Response - 200 OK

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "contact_f1e2d3c4-5678-90ab-cdef-abcdefabcdef",
        "name": "Priya Sharma",
        "phone": "+919876543210",
        "email": "priya@example.com",
        "tags": ["vip", "returning"],
        "created_at": "2026-03-10T08:00:00.000Z"
      }
    ],
    "meta": {
      "page": 1,
      "limit": 20,
      "total": 150
    }
  }
}

Response - 401 Invalid API Key

{
  "success": false,
  "message": "Invalid or missing API key",
  "code": "INVALID_API_KEY",
  "fix": "Include a valid x-api-key header"
}

---

Create / Update Contact

POST /v1/contacts

cURL

curl -X POST 'https://app.superwaba.com/api/developer/v1/contacts' \
  -H 'x-api-key: sgk_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "phone": "919876543210",
  "name": "Priya Sharma",
  "email": "priya@example.com",
  "tags": ["lead", "vip"],
  "attributes": {
    "company": "Acme Inc",
    "source": "website"
  }
}'

Request Body

{
  "phone": "919876543210",
  "name": "Priya Sharma",
  "email": "priya@example.com",
  "tags": ["lead", "vip"],
  "attributes": {
    "company": "Acme Inc",
    "source": "website"
  }
}

Parameters

Parameter	Type	Required	Description
phone	string	Yes	Phone number (E.164 format without +)
name	string	No	Contact display name
email	string	No	Email address
tags	string[]	No	Array of tag strings
attributes	object	No	Custom key-value attributes

Response - 201 Created

{
  "success": true,
  "data": {
    "id": "contact_new12345-6789-01ab-cdef-abcdefabcdef",
    "phone": "919876543210",
    "name": "Priya Sharma",
    "email": "priya@example.com",
    "tags": ["lead", "vip"]
  }
}

Response - 400 Missing Phone

{
  "success": false,
  "message": "Missing required field: phone",
  "code": "MISSING_FIELD",
  "fix": "Include \"phone\" with phone number in E.164 format without \"+\" (e.g. \"919876543210\")"
}

Response - 401 Invalid API Key

{
  "success": false,
  "message": "Invalid or missing API key",
  "code": "INVALID_API_KEY",
  "fix": "Include a valid x-api-key header"
}

---

Get Contact

Fetch a single contact by its id (the id returned by List / Create).

GET /v1/contacts/{id}

cURL

curl -X GET 'https://app.superwaba.com/api/developer/v1/contacts/CONTACT_ID' \
  -H 'x-api-key: sgk_YOUR_API_KEY'

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Contact id (UUID)

Response - 200 OK

{
  "success": true,
  "data": {
    "id": "contact_f1e2d3c4-5678-90ab-cdef-abcdefabcdef",
    "userNumber": "919876543210",
    "userName": "Priya Sharma",
    "countryCode": "91",
    "tags": ["vip", "returning"],
    "params": { "company": "Acme Inc" }
  }
}

Response - 404 Not Found

{
  "success": false,
  "message": "Contact not found",
  "code": "NOT_FOUND"
}

---

Update Contact

Update an existing contact. Only the fields you include are changed. Tag changes are synced to WhatsApp on a best-effort basis.

PATCH /v1/contacts/{id}

cURL

curl -X PATCH 'https://app.superwaba.com/api/developer/v1/contacts/CONTACT_ID' \
  -H 'x-api-key: sgk_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Priya Sharma",
  "tags": ["lead", "vip"]
}'

Request Body

{
  "name": "Priya Sharma",
  "email": "priya@example.com",
  "countryCode": "91",
  "tags": ["lead", "vip"],
  "attributes": { "company": "Acme Inc" }
}

Parameters

Parameter	Type	Required	Description
id	string	Yes	Contact id (path parameter)
name	string	No	Contact display name
email	string	No	Email address
countryCode	string	No	Country calling code
tags	string[]	No	Full array of tags (replaces existing tags)
attributes	object	No	Custom key-value attributes (merged)

Response - 200 OK

{
  "success": true,
  "data": {
    "id": "contact_f1e2d3c4-5678-90ab-cdef-abcdefabcdef",
    "userNumber": "919876543210",
    "userName": "Priya Sharma",
    "tags": ["lead", "vip"]
  }
}

Response - 404 Not Found

{
  "success": false,
  "message": "Contact not found",
  "code": "NOT_FOUND"
}

---

Delete Contact

Delete a contact by id.

DELETE /v1/contacts/{id}

cURL

curl -X DELETE 'https://app.superwaba.com/api/developer/v1/contacts/CONTACT_ID' \
  -H 'x-api-key: sgk_YOUR_API_KEY'

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Contact id (UUID)

Response - 200 OK

{
  "success": true,
  "data": {
    "id": "contact_f1e2d3c4-5678-90ab-cdef-abcdefabcdef",
    "deleted": true
  }
}

Response - 404 Not Found

{
  "success": false,
  "message": "Contact not found",
  "code": "NOT_FOUND"
}