This guide covers best practices for integrators using the Watt Data V2 MCP tools as a direct JSON-RPC API rather than through an LLM client like Claude Desktop.

API Endpoints

The V2 API uses a single versioned endpoint: /v2/mcp

Response Formats

The V2 API supports two response modes controlled by the Accept header:

JSON (RESTful)

Accept: application/json

Returns pure JSON responses. Use this when you want a standard REST-style integration where each request returns a single JSON object.

{
  "entities": [...],
  "stats": { "requested": 5, "resolved": 3, "rate": 0.6 },
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "tool_trace_id": "trace_abc123"
}

Server-Sent Events (SSE)

Accept: application/json, text/event-stream

Returns responses as SSE event messages, where each event's data field contains JSON. Use this for streaming integrations or when tool calls may produce incremental results.

event: message
data: {"jsonrpc":"2.0","result":{"entities":[...],"stats":{...}},"id":1}

SSE mode is useful for long-running operations where you want to receive progress updates or partial results as they become available.

Data Volatility Guidelines

Understanding data volatility is critical for building reliable integrations. Different identifiers have different stability characteristics and caching requirements.

Trait IDs and Hashes

Trait data can be referenced in two ways:

Trait Hash (Recommended):

• trait_hash is a stable hash based on domain, name, and value
• Does not change when the identity graph is reprocessed
• Safe to cache and use in saved queries
• Returned by trait_list and trait_search

Trait ID (Legacy):

• trait_id is a numeric identifier that may change during data reprocessing
• Subject to volatility when new signals are integrated or data is updated
• Use only for immediate queries, not for long-term storage

Recommended Approach - Use trait_search:

Use the trait_search tool to discover traits on-demand using natural language descriptions. This provides the most flexibility and automatically adapts to data changes without caching concerns.

If Caching Traits:

When building saved queries or long-term integrations:

• Use trait_hash for stable references
• Cache trait_hash values indefinitely
• If using trait_id, cache for at most 1 hour
• Implement empty-result detection logic that refreshes from trait_list or trait_search

Entity IDs

Entity IDs should be treated as subject to change at any time. They must never be cached or persisted.

Requirements:

• Do not cache entity IDs
• Do not persist entity IDs
• Do not use entity IDs as stable references
• Always use original identifiers (email, phone, address, MAID) as stable keys

To Retrieve Updated Information:

Call entity_resolve with the original identifiers to obtain current entity IDs for each query.

Why This Matters:

Entity IDs may change as the identity graph is updated. Storing entity IDs leads to stale references that point to incorrect or non-existent records.

Integration Best Practices

Stateless Query Patterns

1. Use trait_search for trait discovery - Describe your target audience in natural language instead of maintaining trait mappings
2. Resolve identities at query time - Never cache entity IDs; resolve fresh for each query
3. Use original identifiers as stable keys - Email, phone, address are your persistent references
4. Use trait_hash for saved queries - Store trait references using stable hashes instead of volatile IDs
5. Treat each API session as independent - Minimal state should persist between queries

Recommended Workflow

For audience discovery:

1. Use trait_search with natural language description of target audience
2. Extract trait IDs from results
3. Use trait IDs in entity_find boolean expressions
4. Export results if needed (CSV, JSON, JSONL)

For identity enrichment:

1. Call entity_resolve with email, phone, or address
2. Extract entity IDs from resolution results
3. Call entity_enrich with entity IDs and desired domains
4. Use enriched data immediately (do not persist entity IDs)

Error Recovery

1. On empty results from trait_search, try broader or alternative query terms
2. On "trait not found" errors, refresh trait cache and retry
3. On empty results from entity_enrich, re-resolve identities and retry
4. Implement exponential backoff for transient failures

Workflow Sessions

Use workflow_id to correlate related queries within a single user interaction, but do not persist workflow state beyond the immediate session.

Next Steps

• Review Getting Started for authentication, workflow sessions, and export formats
• Explore individual tool documentation for detailed parameters and examples
• Review workflow guides for complete implementation examples