added

Update participant endpoint

Release Date

Available in Cert as of December 7, 2022

Once Cert testing has been completed, platforms may be approved for Prod use

Release Type

Actionable, non-breaking – Updates required for platforms, but it will not break current functionality

Summary

Zero Hash has added an endpoint (PATCH /participants/customers/{participant_code}) that permits platforms to update certain participant data. This enables address updates to participants, which allows for easier reporting (including tax reporting) and improved end user experience when transacting on the Zero Hash platform.

Important note: This endpoint does not support updating entities, which will come at a later date on a distinct endpoint. Updating authorized minors occurs on a different endpoint that is not public.

Updatable Information

Fixed pieces of participant information are updatable via this new endpoint:

  • Name
  • Address
  • Email
  • ID

Zero Hash requires that platforms perform due diligence when a participant updates fundamental pieces of their identity, so a <platform_updated_at> timestamp has been introduced to capture when the platform validated and approved the participant submitted update.

Requirements:
All update requests must include the following. Requests that don’t include the following will fail.

  • participant_code – The unique identifier of the participant being updated
  • platform_updated_at – A UNIX (ms) timestamp of when the platform verified/accepted the participant requested update

Endpoints Impacted

The addition of this endpoint does not impact the functionality of any other existing endpoints; however, it is inherently tied to POST /participants/customers/new.

New Endpoint:

PATCH /participants/customers/{participant_code}

Seeing as the endpoint request involves a <participant_code>, multiple participants cannot be updated in one call.

Action Required

Platforms are required to backfill data that was previously updated by participants. Platforms should also begin to pass participant updates through as those updates are verified/approved to ensure no disruption in participant access to transactions, and to enable accurate state reporting for Zero Hash. This includes all address updates, not just updates in and out of heavily regulated jurisdictions.

Success and Failure Messages

A platform can send one update at a time (e.g. just address), or multiple (e.g. name and address); however, if segment requirements are not met, the whole update will be declined.

Breakdown:

ScenarioResponse
Successfully updated data200 + payload of the updated participant record
Submits data that is not updatable400: Cannot update the requested fields: {fields listed}
Segment requirements were not met400: Data segment validation failed. One or more segment fields either invalid or not provided. Segment error: “{required field} required field”, “{field_name} should match format {required format}”
Participant is not allowed to be updated via this endpoint400 - Participant {participant_code} is not a customer
Platform is not approved to submit participant updates403 - Participant {platform_code} is not allowed to submit/update customers
Relationship does not exist between the platform and participant403 - Participant {participant_code} is not a customer of {platform_code}
Only platform_updated_at is submitted400 - platform_updated_at submitted with no data segment to update

Restricted Jurisdiction Residents

When updating participant data, platforms may find that a participant is moving from a less restricted jurisdiction to a more heavily restricted jurisdiction, or vice versa. The most prominent example right now is a participant moving to or from New York (NY). Specifically, New York residents can only trade a subset of Zero Hash supported assets.

Participant moves to NY who holds a NY restricted asset:
These participants will be allowed to hold, sell, or withdraw the NY restricted asset at any time. They will not be able to buy, deposit, transfer, or **gain rewards in the NY restricted asset.

Participant moves out of NY:
Once the address update is successful, the participant will be able to make requests for assets that were not available in NY, barring the assets are allowed in the new participant jurisdiction. Platforms are encouraged to get proof of new address across the board, and especially for those leaving NY

Participant moves to Hawaii:
Hawaii is not a permitted jurisdiction for Zero Hash. Participants moving to Hawaii will need to undergo a one-time divestiture, which can be arranged by reaching out to [email protected].

Relevant Documentation

Please reference the Participants section of the API documentation.