Assign Unowned Contacts

# Assign Unowned Marketing Contacts

Assign an owner to all marketing contacts that currently have no owner. Unowned contacts create gaps in reporting, prevent proper lead routing, and mean no one is accountable for follow-up on marketing-generated responses.

## Why This Matters

Marketing contacts without an owner are a blind spot. They receive campaigns but no one sees their responses. They appear in aggregate metrics but not in individual pipeline views. In owner-based dashboards and reports, they simply do not exist. For teams using round-robin or territory-based routing, unowned contacts bypass the entire system.

## Prerequisites

- Phase 1 hygiene and earlier Phase 3 enrichment processes completed
- Access to Contacts with permission to bulk edit owner assignments
- **Approval from team leads before bulk assignment.** This is a business decision, not just a technical one. Get sign-off on the assignment strategy before proceeding.

## Interview: Gather Requirements

Before executing, collect the following information from the user:

**Q1: Who should unowned contacts be assigned to?**
- Examples: "Assign all to our Integration User", "Distribute across the sales team", "Assign to the Marketing Team user", "Assign to specific reps by territory"
- Default: No default -- this is a business decision that requires team lead approval

**Q2: Should we use territory-based routing, round-robin, or a single catch-all owner?**
- Examples: Territory-based (assign by geography or industry), round-robin (distribute evenly across active reps), catch-all (assign all to one user)
- Default: Catch-all to a single integration/service user as a temporary measure, with plans to implement proper routing later

## Plan

1. Identify all marketing contacts with no owner (before state)
2. Decide on the assignment strategy (catch-all user vs. territory rules)
3. Execute the bulk assignment
4. Verify all marketing contacts have owners (after state)

## Before State

### Create the Unowned Marketing Contacts List

1. Go to **Contacts > Lists > Create list**
2. Select **Active list**
3. Name: `CLEANUP: Unowned Marketing Contacts`
4. Add filters:
   - Marketing contact status > is any of > Marketing contact
   - AND Contact owner > is unknown
5. Save the list and note the count

### Script Approach

```python
import os
from hubspot import HubSpot
from dotenv import load_dotenv

load_dotenv()
api_client = HubSpot(access_token=os.getenv("HUBSPOT_API_TOKEN"))

# Count unowned marketing contacts
result = api_client.crm.contacts.search_api.do_search(
    public_object_search_request={
        "filterGroups": [{
            "filters": [
                {
                    "propertyName": "hs_marketable_status",
                    "operator": "EQ",
                    "value": "true"
                },
                {
                    "propertyName": "hubspot_owner_id",
                    "operator": "NOT_HAS_PROPERTY"
                }
            ]
        }],
        "limit": 0
    }
)
print(f"Unowned marketing contacts: {result.total}")
```

## Execute

### Assignment Strategy Decision

Choose one of these approaches (requires team lead approval):

**Option A: Catch-All User (Simplest)**
- Assign all unowned contacts to a single integration/service user
- Pro: Fast, ensures 100% coverage immediately
- Con: One "owner" accumulates a large number of contacts; not meaningful for routing
- Best when: You plan to implement proper routing later and just need coverage now

**Option B: Territory/Region Rules**
- Assign based on contact geography, industry, or company size
- Pro: More meaningful ownership, better for sales follow-up
- Con: Requires a defined routing matrix and more complex execution
- Best when: You have established sales territories

**Option C: Round-Robin**
- Distribute evenly across active sales reps
- Pro: Fair distribution, immediate accountability
- Con: May assign contacts to reps who do not cover that segment
- Best when: Small team, all reps handle all segments

### Bulk Assignment via UI

1. Open the unowned marketing contacts list
2. Click the checkbox in the table header to select all contacts on the page
3. Click **Select all X contacts** to select across all pages
4. Click **Edit** in the toolbar
5. In the property dropdown, select **Contact owner**
6. Search for and select the chosen owner
7. Click **Update**
8. Confirm the bulk edit
9. For large numbers (5,000+), HubSpot processes in batches. This may take several minutes.

### Bulk Assignment via API

```python
# Pattern for API-based assignment
# Useful for territory-based rules or when UI bulk edit times out

OWNER_ID = "your-owner-id"  # Get from Owners API

# 1. Search for unowned marketing contacts (paginate through all)
# 2. Build batch update payload with hubspot_owner_id = OWNER_ID
# 3. Submit in batches of 100 via crm.contacts.batch_api.update

# For territory-based routing:
# 1. Search for unowned marketing contacts
# 2. For each contact, determine territory based on country/state/industry
# 3. Map territory to owner ID
# 4. Batch update with the appropriate owner per contact
```

**API notes:**
- Get owner IDs from the Owners API: `api_client.crm.owners.owners_api.get_page()`
- To find a specific owner by email: iterate through owners and match on `email`
- Batch update accepts up to 100 records per call
- Rate limit: 100 requests per 10 seconds

## After State

Wait 5-10 minutes for HubSpot to finish processing, then verify.

```python
# Re-run the same search
result = api_client.crm.contacts.search_api.do_search(
    public_object_search_request={
        "filterGroups": [{
            "filters": [
                {
                    "propertyName": "hs_marketable_status",
                    "operator": "EQ",
                    "value": "true"
                },
                {
                    "propertyName": "hubspot_owner_id",
                    "operator": "NOT_HAS_PROPERTY"
                }
            ]
        }],
        "limit": 0
    }
)
print(f"Unowned marketing contacts: {result.total} (should be 0)")
```

**Verification checklist:**

1. The unowned marketing contacts list shows 0 contacts
2. Re-run the before-state script — count should be 0
3. Spot-check 5-10 contacts that were previously unowned — confirm they show the assigned owner
4. Check owner-based dashboards/reports to confirm the previously invisible contacts now appear

## Key Technical Learnings

- **This is a business decision, not just a technical one.** Always get approval from sales/marketing leadership on the assignment strategy before executing. Bulk-assigning contacts to the wrong people creates confusion and erodes trust.
- **A catch-all user is a temporary solution.** If you assign to a single integration user, plan a follow-up process to redistribute contacts to actual sales reps when proper routing is established.
- **Pair with lead owner cleanup.** Once proper routing is in place, revisit contacts under the catch-all user and reassign them to real owners.
- **HubSpot bulk edit limits.** For very large batches (10,000+), the UI bulk edit may time out. Use the API approach instead, which handles pagination and batching gracefully.
- **New contacts need routing too.** After this one-time cleanup, implement a workflow or lead rotation rule to automatically assign owners to new marketing contacts going forward.