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

# Contacts & Segments

> Manage contacts and create dynamic segments for targeted campaigns

## Contact Management

### Create Contact

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/contacts \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "phone": "+1234567890",
      "name": "John Doe",
      "email": "john@example.com",
      "tags": ["premium", "active"]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api-message.nativehub.live/api/v1/contacts', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      phone: '+1234567890',
      name: 'John Doe',
      email: 'john@example.com',
      tags: ['premium', 'active']
    })
  });
  const contact = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api-message.nativehub.live/api/v1/contacts',
      headers={
          'Authorization': 'Bearer YOUR_TOKEN',
          'Content-Type': 'application/json'
      },
      json={
          'phone': '+1234567890',
          'name': 'John Doe',
          'email': 'john@example.com',
          'tags': ['premium', 'active']
      }
  )
  contact = response.json()
  ```
</CodeGroup>

### Update Contact

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT https://api-message.nativehub.live/api/v1/contacts/cnt_abc123 \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "tags": ["premium", "vip"]
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch('https://api-message.nativehub.live/api/v1/contacts/cnt_abc123', {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tags: ['premium', 'vip']
    })
  });
  ```

  ```python Python theme={null}
  requests.put(
      'https://api-message.nativehub.live/api/v1/contacts/cnt_abc123',
      headers={
          'Authorization': 'Bearer YOUR_TOKEN',
          'Content-Type': 'application/json'
      },
      json={'tags': ['premium', 'vip']}
  )
  ```
</CodeGroup>

### Delete Contact

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api-message.nativehub.live/api/v1/contacts/cnt_abc123 \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript Node.js theme={null}
  await fetch('https://api-message.nativehub.live/api/v1/contacts/cnt_abc123', {
    method: 'DELETE',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
  });
  ```

  ```python Python theme={null}
  requests.delete(
      'https://api-message.nativehub.live/api/v1/contacts/cnt_abc123',
      headers={'Authorization': 'Bearer YOUR_TOKEN'}
  )
  ```
</CodeGroup>

## Importing Contacts

### CSV Format

```csv theme={null}
phone,name,email,tags
+1234567890,John Doe,john@example.com,"premium,active"
+9876543210,Jane Smith,jane@example.com,basic
```

### Upload CSV

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/contacts/import \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -F "file=@contacts.csv"
  ```

  ```javascript Node.js theme={null}
  const formData = new FormData();
  formData.append('file', fs.createReadStream('contacts.csv'));

  const response = await fetch(
    'https://api-message.nativehub.live/api/v1/contacts/import',
    {
      method: 'POST',
      headers: { 'Authorization': 'Bearer YOUR_TOKEN' },
      body: formData
    }
  );
  const result = await response.json();
  ```

  ```python Python theme={null}
  files = {'file': open('contacts.csv', 'rb')}
  response = requests.post(
      'https://api-message.nativehub.live/api/v1/contacts/import',
      headers={'Authorization': 'Bearer YOUR_TOKEN'},
      files=files
  )
  result = response.json()
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "imported": 1250,
  "failed": 3,
  "duplicates": 47,
  "errors": [
    {"row": 15, "reason": "Invalid phone format"}
  ]
}
```

## Bulk Delete

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/contacts/bulk-delete \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "contact_ids": ["cnt_abc123", "cnt_xyz789"]
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch('https://api-message.nativehub.live/api/v1/contacts/bulk-delete', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      contact_ids: ['cnt_abc123', 'cnt_xyz789']
    })
  });
  ```

  ```python Python theme={null}
  requests.post(
      'https://api-message.nativehub.live/api/v1/contacts/bulk-delete',
      headers={
          'Authorization': 'Bearer YOUR_TOKEN',
          'Content-Type': 'application/json'
      },
      json={'contact_ids': ['cnt_abc123', 'cnt_xyz789']}
  )
  ```
</CodeGroup>

## Segments

Segments dynamically group contacts based on conditions.

### Create Segment

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/segments \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Premium Customers",
      "conditions": [
        {"field": "tags", "operator": "contains", "value": "premium"}
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api-message.nativehub.live/api/v1/segments', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Premium Customers',
      conditions: [
        {field: 'tags', operator: 'contains', value: 'premium'}
      ]
    })
  });
  const segment = await response.json();
  ```

  ```python Python theme={null}
  response = requests.post(
      'https://api-message.nativehub.live/api/v1/segments',
      headers={
          'Authorization': 'Bearer YOUR_TOKEN',
          'Content-Type': 'application/json'
      },
      json={
          'name': 'Premium Customers',
          'conditions': [
              {'field': 'tags', 'operator': 'contains', 'value': 'premium'}
          ]
      }
  )
  segment = response.json()
  ```
</CodeGroup>

### Segment Conditions Format

Conditions are JSON objects with:

| Field      | Type         | Description                                      |
| ---------- | ------------ | ------------------------------------------------ |
| `field`    | string       | Contact field: `name`, `phone`, `email`, `tags`  |
| `operator` | string       | `equals`, `contains`, `starts_with`, `ends_with` |
| `value`    | string/array | Value to match                                   |

### Multiple Conditions

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/segments \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Active Premium Users",
      "conditions": [
        {"field": "tags", "operator": "contains", "value": "premium"},
        {"field": "tags", "operator": "contains", "value": "active"}
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch('https://api-message.nativehub.live/api/v1/segments', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Active Premium Users',
      conditions: [
        {field: 'tags', operator: 'contains', value: 'premium'},
        {field: 'tags', operator: 'contains', value: 'active'}
      ]
    })
  });
  ```

  ```python Python theme={null}
  requests.post(
      'https://api-message.nativehub.live/api/v1/segments',
      headers={
          'Authorization': 'Bearer YOUR_TOKEN',
          'Content-Type': 'application/json'
      },
      json={
          'name': 'Active Premium Users',
          'conditions': [
              {'field': 'tags', 'operator': 'contains', 'value': 'premium'},
              {'field': 'tags', 'operator': 'contains', 'value': 'active'}
          ]
      }
  )
  ```
</CodeGroup>

<Info>
  Multiple conditions use AND logic. All conditions must match.
</Info>

## Using Segments for Campaigns

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/campaigns \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Premium Offer",
      "template_id": "tmpl_abc123",
      "segment_id": "seg_xyz789"
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch('https://api-message.nativehub.live/api/v1/campaigns', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Premium Offer',
      template_id: 'tmpl_abc123',
      segment_id: 'seg_xyz789'
    })
  });
  ```

  ```python Python theme={null}
  requests.post(
      'https://api-message.nativehub.live/api/v1/campaigns',
      headers={
          'Authorization': 'Bearer YOUR_TOKEN',
          'Content-Type': 'application/json'
      },
      json={
          'name': 'Premium Offer',
          'template_id': 'tmpl_abc123',
          'segment_id': 'seg_xyz789'
      }
  )
  ```
</CodeGroup>

Segments auto-update. New contacts matching conditions are included in future sends.