User customerMetadata on the public API

Summary

Users support custom metadata (key/value pairs) similar to contacts, products, and invoices:

• updateUserMetadata — add or update an entry (max key length 40, value 500, up to 50 keys per user).
• deleteUserMetadata — remove an entry by key. If the key does not exist, the mutation returns the user unchanged and does not return an error.
• User.metadata — read entries as [MetadataEntry] (key, value).
• users(filters: …) — optional filters.metadata with a required key and an optional value.

Filter behaviour matches the other metadata-enabled list queries:

• key only — returns users that have any value stored for that key.
• key + value — returns users where that key/value pair matches the same entry.

The users query also supports filters.isClinician for clinician/non-clinician filtering. options.cliniciansOnly is deprecated; use filters.isClinician: true instead.

This release is additive for existing user and users clients. Existing queries continue to work, and callers can opt into metadata reads, metadata filters, and the new clinician filter when needed.

Integration guidance

• Writing metadata: Call updateUserMetadata with userId, key, and value.
• Removing metadata: Call deleteUserMetadata with userId and key. Missing keys are a successful no-op.
• Reading metadata: Query user(id:) or users and request metadata { key value }.
• Listing by metadata: Use users(filters: { metadata: { key: … } }) to match any value for a key, or add value: … for an exact key/value pair.
• Free-text search: users(options: { search: … }) matches first name, last name, email, and stored metadata values (substring match). Use filters.metadata when you need an exact key or key/value pair.
• Filtering clinicians: Use users(filters: { isClinician: true }) instead of options: { cliniciansOnly: true }.

Example

query UsersByExternalRef {
  users(
    pagination: { page: 1, pageSize: 50 }
    filters: {
      metadata: { key: "external_ref", value: "USR-42" }
      isClinician: true
    }
  ) {
    data {
      id
      firstName
      lastName
      metadata {
        key
        value
      }
    }
    pageInfo {
      page
      pageSize
      hasMore
    }
  }
}

Migration

No breaking schema changes for existing user / users clients. If you store partner references only in Semble user metadata today, you can now read them via metadata and find users with filters.metadata instead of maintaining a separate id map outside Semble.

If you currently use options.cliniciansOnly, move to filters.isClinician when regenerating clients. The old option remains available for compatibility but is deprecated.