Filter By Phone Number

GET

/api/v1/contacts/phone/{phone}

Retrieve a single contact by phone number.

The number is compared digits-only: a leading +, spaces, dashes and brackets in your input are ignored, and every phone stored on a contact is compared the same way. So +959123456789, 959123456789 and 959-123-456-789 all resolve to the same contact. WhatsApp contacts are stored as the international number without + (the WhatsApp ID); contacts created from calls or entered manually are stored as typed.

When several contacts share the number, the one where it is the primary phone is returned, then the most recently created.

Returns the same object as Detail (GET /api/v1/contacts/{id}), including platformContacts and their rooms/channels.

404 — no contact holds that number.

400 — the value is not a phone number (must contain digits; only +, spaces, dashes and brackets are allowed around them).

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Path Params

Responses

🟢200OK

application/json

Bodyapplication/json

🟠400Bad Request

🟠404Not Found

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://apigw.klinkcx.com/api/v1/contacts/phone/959123456789' \
--header 'Authorization: Bearer <token>'

Response Example

200 - Success

Same shape as the Detail endpoint

{
  "status": "success",
  "message": "contact",
  "data": {
    "id": "c786bb40-a58e-4d60-afe6-061e2b819811",
    "name": "FrankMcCallister",
    "address": null,
    "channel": null,
    "notes": null,
    "socialProfileUrl": "https://assets.protocol.chat/avatars/frank.jpg",
    "tags": [
      {
        "id": "4d45ba6c-728e-4ca8-91cb-91bac1572622",
        "name": "platinum"
      }
    ],
    "company": {
      "id": "547f2af6-1e6d-420e-aaed-b6448d37fd08",
      "name": "K-Link",
      "phone": null,
      "address": null,
      "industry": null
    },
    "email": [
      {
        "email": "frankmccallister@gmail.com",
        "isPrimary": true
      }
    ],
    "phone": [
      {
        "phone": "1-800-759-3000",
        "isPrimary": true
      }
    ],
    "customFields": [
      {
        "system_name": "demo_test",
        "display_name": "demo test ddddfee erefesf",
        "type": "text",
        "value": "another field"
      }
    ]
  }
}

Modified at 2026-09-04 03:03:41

Update tags

Listing