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
- 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 updatedplatform_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:
| Scenario | Response |
|---|---|
| Successfully updated data | 200 + payload of the updated participant record |
| Submits data that is not updatable | 400: Cannot update the requested fields: {fields listed} |
| Segment requirements were not met | 400: 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 endpoint | 400 - Participant {participant_code} is not a customer |
| Platform is not approved to submit participant updates | 403 - Participant {platform_code} is not allowed to submit/update customers |
| Relationship does not exist between the platform and participant | 403 - Participant {participant_code} is not a customer of {platform_code} |
Only platform_updated_at is submitted | 400 - 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
Relevant Documentation
Please reference the Participants section of the API documentation.