Contact API Documentation

1. Overview

The Contact API lets you:

Retrieve (or create) a contact by phone number, including all related data (conversations, groups, tags, attributes, etc.).
Update multiple contact attributes in a single request.

The API automatically normalises phone numbers by stripping non-numeric characters, so all of the following resolve to the same contact:

If the contact does not exist for the authenticated company, it will be created on-the-fly using the supplied phone number.

2. Authentication

The endpoints are protected by Laravel Sanctum.
Pass a bearer token in the Authorization header of every request:

All responses will return 401 Unauthenticated if the token is missing or invalid.

3. Endpoints

3.1 GET `/api/v1/contact/{phone_number}`

Retrieve a contact and all related data.

Parameter	In	Type	Description
phone_number	path	string	Phone number to lookup (any format)

Response 200

{
  "status": "SUCCESS",
  "message": "Operation completed successfully",
  "contact": {
    "id": 1,
    "name": "John Doe",
    "phone_number": "1234567890",
    "dnd_enabled": false,
    "created_at": "2025-07-08T10:00:00.000000Z",
    "updated_at": "2025-07-08T10:00:00.000000Z",
    "conversations": [
      {
        "id": 42,
        "state": "open",
        "created_at": "2025-07-08T09:58:00.000000Z",
        "assigned_staff": {
          "id": 7,
          "name": "Alice Smith",
          "email": "alice@example.com"
        }
      }
    ],
    "contact_attributes": [
      {
        "attribute_name": "age",
        "attribute_value": 30,
        "display_value": "30",
        "attribute_field": {
          "attribute_label": "Age",
          "field_type": "number",
          "is_read_only": false,
          "visibility": "visible_to_all"
        }
      },
      {
        "attribute_name": "is_vip",
        "attribute_value": true,
        "display_value": "Yes",
        "attribute_field": {
          "attribute_label": "VIP Status",
          "field_type": "checkbox",
          "is_read_only": false,
          "visibility": "visible_to_all"
        }
      },
      {
        "attribute_name": "preferred_languages",
        "attribute_value": ["english", "spanish"],
        "display_value": "english, spanish",
        "attribute_field": {
          "attribute_label": "Preferred Languages",
          "field_type": "multiselect",
          "is_read_only": false,
          "visibility": "visible_to_all"
        }
      }
    ],
    "contact_attributes_map": {
      "age": 30,
      "city": "New York",
      "nickname": "Johnny",
      "is_vip": true,
      "preferred_languages": ["english", "spanish"]
    },
    "contact_groups": [{ "id": 3, "name": "VIP" }],
    "tags": [{ "id": 5, "name": "Important" }]
  }
}