> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts

> Create, list, retrieve and update contacts via the Zavu PHP SDK. Manage profile metadata, channels and merge suggestions from your code.

Contacts are automatically created when you send messages. You can retrieve and update contact information.

## Get Contact

```php theme={null}
$result = $client->contacts->retrieve([
    'contactId' => 'con_abc123',
]);

echo $result->id . "\n";
echo $result->phoneNumber . "\n";
echo $result->countryCode . "\n";
echo implode(', ', $result->availableChannels) . "\n";
echo $result->defaultChannel . "\n";
```

## Get Contact by Phone

```php theme={null}
$result = $client->contacts->retrieveByPhone([
    'phoneNumber' => '+14155551234',
]);

echo $result->id . "\n";
echo implode(', ', $result->availableChannels) . "\n"; // ["sms", "whatsapp"]
```

## Create Contact

<Note>
  `create`, `delete`, `merge`, `dismissMergeSuggestion` and the channel operations
  are not generated in the PHP SDK yet. The endpoints work: call them directly, as
  shown below. See the [coverage table](/sdks/overview#coverage).
</Note>

```bash theme={null}
curl -X POST https://api.zavu.dev/v1/contacts \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "John Doe",
    "channels": [
      { "channel": "sms", "identifier": "+14155551234", "isPrimary": true }
    ]
  }'
```

## Update Contact

```php theme={null}
$result = $client->contacts->update([
    'contactId' => 'con_abc123',
    'defaultChannel' => 'whatsapp',
    'metadata' => [
        'name' => 'John Doe',
        'tier' => 'premium',
    ],
]);
```

## List Contacts

```php theme={null}
$result = $client->contacts->list([
    'limit' => 50,
]);

foreach ($result->items as $contact) {
    echo $contact->id . " " . $contact->phoneNumber . "\n";
}

// Filter by phone number
$result = $client->contacts->list([
    'phoneNumber' => '+1415',
]);

// Pagination
$cursor = null;
do {
    $result = $client->contacts->list(['cursor' => $cursor, 'limit' => 50]);
    foreach ($result->items as $contact) {
        echo $contact->id . "\n";
    }
    $cursor = $result->nextCursor;
} while ($cursor !== null);
```

## Channels

Adding, updating, promoting and removing a contact's channels are REST calls
today:

```bash theme={null}
# Add
curl -X POST https://api.zavu.dev/v1/contacts/con_abc123/channels \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "email", "identifier": "john.work@company.com", "label": "work" }'

# Update
curl -X PATCH https://api.zavu.dev/v1/contacts/con_abc123/channels/ch_xyz789 \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "personal", "verified": true }'

# Set as primary for its type
curl -X POST https://api.zavu.dev/v1/contacts/con_abc123/channels/ch_xyz789/primary \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"

# Remove
curl -X DELETE https://api.zavu.dev/v1/contacts/con_abc123/channels/ch_xyz789 \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"
```

<Warning>
  You cannot remove the last channel from a contact.
</Warning>

## Merge Contacts

```bash theme={null}
# Merge the source contact into this one. Channels move to the target and the
# source stops appearing in listings. This cannot be undone.
curl -X POST https://api.zavu.dev/v1/contacts/con_abc123/merge \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sourceContactId": "con_xyz789" }'
```

<Note>
  Zavu does not detect duplicates for you — choose which contacts to merge from
  your own data.
</Note>

## Phone Introspection

Validate a phone number and check available channels:

```php theme={null}
$result = $client->introspect->phone([
    'phoneNumber' => '+14155551234',
]);

echo $result->validNumber . "\n"; // true
echo $result->countryCode . "\n"; // "US"
echo $result->nationalFormat . "\n"; // "(415) 555-1234"
echo $result->lineType . "\n"; // "mobile"
echo implode(', ', $result->availableChannels) . "\n"; // ["sms", "whatsapp"]
echo $result->carrier?->name . "\n"; // "Verizon Wireless"
```