Why identity resolution needs a visible contract

Most enrichment APIs are optimized around a single moment: returning a value. You submit an identifier and receive an email, a phone number, or a company. The response looks complete because the field is populated. Operationally, it is only the beginning.

The workflow still has to decide whether the record is safe to use. Is the email recent? Was it verified or merely inferred? Did the result come from a trusted cache or a live external lookup? What did that decision cost?

The value is not enough

A contact field without context creates invisible work downstream. Someone, whether a person or an agent, must guess whether the value is current, whether it can be used, and whether another lookup is justified.

For a human operator, this uncertainty slows a workflow. For an automated agent, it becomes a policy problem. The agent cannot make a reliable next decision if the API hides the evidence behind a generic success response.

A resolved value answers “what.” A resolution contract also answers “how sure, how fresh, from where, and at what cost.”

We call that additional context the resolution contract. It is the minimum information required to turn a found value into an accountable input for another system.

Four fields belong in the contract

The exact schema will differ by identifier, but four questions should be answerable from every successful response.

1. How fresh is it?

Freshness should be represented by a date, not a claim. A label such as “high quality” cannot tell a workflow when the value was last checked or when it should be checked again. Return validated_at and let the caller apply the policy appropriate to its use case.

2. How confident are we?

Confidence is not the same as deliverability. A record can be confidently matched to a person while the email itself still carries risk. Keep identity confidence and channel validation separate so callers do not collapse two different decisions into one number.

3. What kind of source produced it?

Callers do not always need the provider name, but they do need the source class: fresh cache, verified external lookup, customer-provided data, or deterministic transformation. That distinction makes auditing and future policy changes possible.

4. What did this resolution cost?

The exact charge belongs in the response. When a cache hit costs zero and an external lookup consumes tokens, the caller should not need to reconstruct that decision from a separate billing page.

{
  "best_email": "avery@northstar.dev",
  "email_type": "business",
  "risk": "valid",
  "validated_at": "2026-07-09",
  "source_class": "fresh_cache",
  "confidence": 0.984,
  "tokens_charged": 0
}

Why agents need this more than dashboards do

A dashboard can hide uncertainty behind visual hierarchy and rely on a person to investigate. An agent receives a tool response and must decide what to do next. Its decision quality is bounded by the context available in that response.

A visible contract lets an agent apply simple, inspectable rules:

• Use a business email only when it was validated within the last 30 days.
• Ask for another identifier when match confidence falls below a defined threshold.
• Avoid a second external lookup when a recent cache hit already satisfies the task.
• Route uncertain or high-cost results to human review instead of improvising.

These are small policies. Together they turn an enrichment call into an infrastructure primitive an agent can use safely.

Make the contract operational

Adding fields to a response is the easy part. The difficult work is ensuring that each field means the same thing across tools, providers, and time.

Start with a written contract. Define what “validated” means, which events update the date, how confidence is calibrated, what source classes exist, and when a token is charged. Then make those definitions observable in tests and billing logs.

The goal is not a larger payload. It is a smaller space for guessing.