Reference Values
Enterprise clients should not hardcode every selectable value. Use reference endpoints, endpoint schemas, and response values to keep customer tools aligned with the organization configuration.
Discovery order
- Use documented reference endpoints such as
GET /api/v1/countriesfor country and territory data. - Use list endpoints that return allowed roles, packages, plans, add-ons, and member permissions.
- Use endpoint schemas for request fields that have a fixed public contract.
- Store the public value returned by the API, not the dashboard display label.
Values clients commonly need
| Area | Where to discover it | Client behavior |
|---|---|---|
| Countries and territories | GET /api/v1/countries | Store the returned public code or value expected by the target endpoint. |
| Member roles | GET /api/v1/member-roles | Store role_id for user, member, and permission workflows. |
| Member permissions | GET /api/v1/member-permissions | Store permission keys only when editing role permissions. |
| Packages and subscriptions | Package, plan, and subscription endpoints | Store package_id, plan_id, and subscription_id. |
| Add-ons | Values supplied during organization onboarding and the add-on endpoint paths | Store the assigned public add-on slug and version. There is currently no public add-on discovery endpoint. |
| Smartlink platforms | Smartlink response and request schemas | Store platform codes such as spotify or apple_music as documented by the endpoint. |
| Review statuses | Release review responses | Display the returned review_status and tolerate new values. |
| Delivery statuses | Release review and delivery responses | Display the returned delivery_status and tolerate new values. |
Documented release examples
These values appear in public examples and are useful for smoke tests:
| Type | Example values |
|---|---|
| Release format | single, ep, album |
| Artist role | Primary Artist, Featured Artist, Composer, Producer, Remixer |
| Destination channel | spotify, apple_music, youtube_music |
| Genre | Electronic, Ambient |
| Language | English, en |
| Territory | GB, US |
Endpoint pages remain authoritative for exact accepted request values. If an endpoint expects a display label in one field and a code in another, follow that endpoint.
Status handling
Clients must not crash on a status value they do not recognize.
Recommended behavior:
- Display the raw returned value.
- Store the timestamp of the first observation.
- Keep the record visible to operators.
- Log the endpoint and public reference for mapping updates.
- Avoid irreversible automation for unknown states.
See Delivery Statuses for release workflow state families.
Public reference rule
Values that identify an object always use that object's own public reference, such as release_id or checkout_id. Store them exactly as returned and do not flatten them into a generic identifier column in your own system. The full list is in Response Conventions.
Common questions
Can I cache reference data? Yes, and you should. Countries, roles, and permissions change rarely. Refresh on a schedule rather than on every request, and refresh immediately if a request fails validation on a value you cached.
Should I store the display label or the code? The value the API returns. Dashboard labels can change without the underlying value changing.
What if an endpoint expects a label in one field and a code in another? Follow that endpoint page. It is authoritative for its own request body.
Was this page helpful?