---
agentTools:
  projectIndex: https://docs.zerohash.com/llms.txt
---

# Citizenship Field Deprecation on Participant APIs

## 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.