Upgrading to v1

This guide covers API changes and migration steps for v1 of the Watt API.

Breaking Changes Checklist

Address these changes in priority order:

Breaking Changes

Contact Metadata Structure (v1.8.0)

Contact data now returns objects with compliance metadata instead of simple string arrays. This affects get_person, resolve_identities, and find_persons:

Before:

{
  "email": ["jane@example.com"],
  "phone": ["+12125551234"]
}

After:

{
  "emails": [{
    "email_address": "jane@example.com",
    "opted_in": true
  }],
  "phones": [{
    "phone_number": "+12125551234",
    "phone_type": "mobile",
    "carrier": "Verizon",
    "do_not_call": false
  }]
}

Migration: Update your code to access nested fields and check compliance flags before contacting users.

Cluster Field Naming (v1.0.3)

Cluster-related fields have been renamed for consistency:

• cluster_name → name
• cluster_value → value
• cluster_domain → domain

Migration: Update field references in your code. This affects list_clusters, get_cluster, search_clusters, and analyze_customers responses.

Removed Domains

The following domains have been removed in v1 and are no longer valid:

• engagement - Engagement metrics have been consolidated into other domains
• geographic - Geographic attributes are now handled via the location filter parameter

Migration: If your integration statically defines domain lists, update them to remove these values. Using removed domains will result in validation errors.

analyze_customers Output (v1.6.0)

The analyze_customers tool now returns cluster_hash instead of cluster_id in all output fields. The cluster_hash is a stable identifier that persists across data rebuilds.

Before:

{
  "cluster_id": "3300000001",
  "name": "tech_affinity",
  "domain": "interest"
}

After:

{
  "cluster_hash": "a8f3bc1d2e3f4a5b6c7d8e9f0a1b2c3d",
  "name": "tech_affinity",
  "domain": "interest"
}

Use cluster_hash in targeting expressions for reliable, long-lived audience definitions.

resolve_identities Address Behavior (v1.7.0)

Address matching behavior has changed:

• Returns only the best-scoring person(s) per input address
• Minimum quality threshold of 0.75 (~31m distance) excludes weak matches
• Household members tied at max score are all returned
• Maximum batch size: 1,000 addresses per request (v1.7.1)

Migration: If you relied on receiving all matches within an H3 cell, update your code to handle single best-match results per address. Consider using geographic filtering in find_persons if you need broader area coverage.

API Versioning (v1.6.0)

Versioned endpoints are available for version pinning:

• /v1/mcp - Versioned MCP endpoint
• /v1/mcp/m2m - Versioned M2M endpoint

Unversioned routes (/mcp, /mcp/m2m) remain available but may shift to newer API versions over time. Use versioned endpoints when you need to pin to a specific API version.

New Features

cluster_hash Support (v1.5.0)

All cluster-related tools now support cluster_hash:

• list_clusters returns cluster_hash in response
• get_cluster accepts cluster_hash parameter
• find_persons expressions support both cluster_id and cluster_hash
• search_clusters returns cluster_hash in results

Recommendation: Use cluster_hash for saved queries and targeting expressions. Unlike cluster_id, these identifiers remain stable across data rebuilds.

search_clusters Tool (v1.2.0)

New semantic search tool for finding clusters by natural language description instead of exact names. Uses Gemini embeddings for intelligent matching.

Example:

{
  "query": "people interested in outdoor activities",
  "limit": 10
}

ICP Analysis Workflow (v1.4.0)

Three new tools for customer profiling:

• generate_url_for_upload - Get presigned URL for CSV upload
• analyze_customers - Profile customer data and generate personas
• generate_audience - Create lookalike audiences from personas

These tools enable AI-driven customer segmentation and lookalike audience generation from your existing customer data.

Multi-identifier Support (v1.5.0)

Enhanced identifier handling across tools:

• analyze_customers accepts arrays for email_columns, phone_columns, address_columns
• find_persons can export multiple identifier types per row (email, phone, address, name, maid)

Example find_persons request:

{
  "expression": "cluster_hash:a8f3bc1d2e3f4a5b6c7d8e9f0a1b2c3d",
  "export_identifiers": ["email", "phone", "maid"],
  "format": "csv"
}

Pagination (v1.0.5 - v1.1.0)

Both list_clusters and find_persons support pagination:

Response fields:

• offset - Current offset in results
• has_more - Whether more results are available
• next_offset - Offset value for next page

Example:

{
  "offset": 0,
  "limit": 100
}

Geographic Filtering (v1.0.1)

Both find_persons and get_person support location filtering:

Example:

{
  "location": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "radius_km": 50
  }
}

Uses H3 geospatial indexing for efficient proximity queries.

MAID/IDFA/GAID Resolution (v1.0.3)

resolve_identities now supports mobile advertising identifiers with multiple hash formats:

• IDFA (Apple)
• GAID (Google/Android)
• Automatic format detection and normalization

Deprecations

identifiers Field in resolve_identities (v1.1.0)

The identifiers field was removed from output. Use criterion_type in the matches array instead to identify which input matched each person.

Migration: Replace references to the top-level identifiers field with criterion_type from individual match objects.

Intent Domain Consolidation (v1.4.0)

The separate intent_topic and intent_category domains have been merged into a unified intent domain.

Migration: Update domain requests from intent_topic or intent_category to intent.

Example:

{
  "domains": ["intent"]
}

Limits and Constraints

Data Format Changes

Phone Numbers (v1.0.2)

Phone numbers are now normalized to E.164 format, preserving the + prefix and country code:

• Before: 2125551234
• After: +12125551234

MAID Normalization (v1.5.0)

Mobile advertising IDs are automatically normalized to lowercase UUID format with hyphens. Various input formats are accepted and converted to standard form.

Person IDs (v1.0.0)

person_id is now consistently returned as a string across all tools. Update any code that assumes numeric person IDs.

Performance Improvements

Optimized Address Resolution (v1.6.2)

Address matching now uses H3-indexed tables for significantly faster lookups. No code changes required.

Efficient Identity Resolution (v1.0.4)

Identity resolution queries now use IN clause patterns instead of multiple OR conditions, providing O(1) complexity regardless of identifier count.

Memory-Efficient Pagination (v1.1.0)

find_persons pagination uses subBitmap() to prevent out-of-memory errors on large audiences. Supports audiences up to 15M persons.

Dynamic H3 Resolution (v1.1.0)

Geospatial queries automatically select the optimal H3 resolution based on radius, optimizing large-area queries while maintaining accuracy.

Error Handling

Validation Details (v1.7.1)

INVALID_PARAMS errors now include specific validation details to aid debugging:

{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Validation failed",
    "details": {
      "field": "email_columns",
      "reason": "Must be array of strings"
    }
  }
}

Graceful Degradation (v1.4.0, v1.6.1)

Tools now handle missing data gracefully:

• get_person skips corrupted domain data instead of failing
• analyze_customers returns resolved CSV columns when enrichment data is unavailable
• Specific error codes for CSV access failures

Testing Your Migration

1. Update endpoint URLs to versioned paths (/v1/mcp) if you need version pinning
2. Test contact metadata parsing with new object structure (v1.8.0)
3. Verify cluster_hash handling in targeting expressions (v1.6.0)
4. Check address resolution for best-match behavior (v1.7.0)
5. Update field references from old cluster naming (v1.0.3)
6. Test error handling with new validation details (v1.7.1)

Getting Help

If you encounter issues during migration:

• Review tool reference documentation for updated schemas
• Check error messages for specific validation details
• Use submit_feedback tool to report data quality issues
• Contact support for integration assistance