Release Notes
Portal
Back to All
Deprecated

Citizenship Field Deprecation on Participant APIs

May 11th, 2026

Effective date

July 11, 2026

Release type

Field Deprecation

Summary

The citizenship free-text field is being deprecated across all participant API endpoints. Going forward, citizenship_code (ISO 3166-1 alpha-2 country code, e.g., "US", "GB", "DE") will be the only accepted field for specifying citizenship.

Reason

The current citizenship field accepts any string, which adds complexity to compliance rule evaluation. Standardizing on ISO country codes ensures consistent data and enables citizenship-based policy enforcement.

Affected Endpoints

  • POST /participants/customers/new
  • PATCH /participants/customers/{participant_code}
  • POST /participants/beneficiaries/new
  • PATCH /participants/beneficiaries/{participant_code}
  • POST /participants/entity/new
  • POST /participants/entity/{participant_code}
  • PATCH /participants/entity/{participant_code}/users/{user_code}

Required Action

Platforms must replace any usage of the citizenship field with citizenship_code in API calls. Use ISO 3166-1 alpha-2 codes (e.g., "US" not "United States"). Complete migration before July 11, 2026.

During the 60-day transition period, both fields are accepted. If both are sent, citizenship_code takes precedence.

Once the 60-day transition period is completed, zerohash will remove citizenship from request schemas on all affected endpoints and from response payloads entirely.