Skip to content

Name Eligibility Integration Guide

POST /v1/name/eligibility, POST /v2/name/eligibility, and POST /v3/name/eligibility are deprecated.

Use these endpoints only for legacy clients during migration to POST /v1/name/assessment.

POST /v1/name/assessment is the replacement endpoint for partner integrations and should be used for all new builds.

What changes in the migration

Eligibility and assessment are related, but they are not the same contract:

  • Eligibility is a compliance-style output with overallStatus and issues.
  • Assessment is a decision-oriented output with top-level overallStatus, issues, semantic signals, and profile-aware severity mapping.
  • Assessment is the primary partner contract going forward.

Migration plan

  1. Keep legacy eligibility calls running in parallel with assessment.
  2. Compare overallStatus and issues from eligibility with top-level overallStatus and issues.
  3. Move product decisioning to assessment outcomes.
  4. Remove usage of /v1/name/eligibility, /v2/name/eligibility, and /v3/name/eligibility after parity and rollout validation.

Field mapping guide

Legacy eligibility field Assessment replacement Migration note
overallStatus overallStatus Similar job, but the status vocabulary changed
issues[] issues[] Use issues[].code as the stable machine trigger
issues[].severity issues[].severity Severity is now profile-aware
input.* request payload + companyName Assessment response is less input-echo oriented
registrableNames no direct replacement Do not expect auto-generated suggested names from assessment
no legacy equivalent traceId Persist for support and diagnostics
no legacy equivalent semanticFailOpen Important when using checkLevel=full

Rollout advice

  • Start by comparing both endpoints on realistic sandbox payloads.
  • Update workflow logic to branch on top-level overallStatus, not legacy eligibility labels.
  • Review any code that depends on registrableNames, because assessment does not replace that feature directly.
  • Keep the legacy endpoint only until downstream systems no longer depend on the old shape.

Compatibility note

Do not assume 1:1 field mapping between eligibility and assessment. Migrate decision logic intentionally rather than performing a shallow field rename.