Skip to main content

Location customerMetadata on the public API

Summary​

Practice locations support custom metadata (key/value pairs) for storing external system references:

  • updateLocationMetadata — add or update an entry (max key length 40, value 500, up to 50 keys per location).
  • deleteLocationMetadata — remove an entry by key. If the key does not exist, the mutation returns the location unchanged and does not return an error.
  • PracticeLocation.metadata — read entries as [MetadataEntry] (key, value).

The locationId argument is the location group ID exposed as PracticeLocation.groupId. Existing practice queries continue to work unchanged unless callers request the new metadata field.

Integration guidance​

  • Writing metadata: Call updateLocationMetadata with locationId, key, and value.
  • Removing metadata: Call deleteLocationMetadata with locationId and key. Missing keys are a successful no-op.
  • Reading metadata: Query practice, request locations, and include groupId plus metadata { key value }.
  • External references: Store partner location identifiers in metadata instead of overloading display fields such as the location name.

Example​

mutation UpdateLocationMetadata {
  updateLocationMetadata(
    locationId: "LOCATION_GROUP_ID"
    key: "external_ref"
    value: "LOC-42"
  ) {
    data {
      groupId
      metadata {
        key
        value
      }
    }
    error
  }
}
query PracticeLocations {
  practice {
    locations {
      id
      groupId
      name
      metadata {
        key
        value
      }
    }
  }
}

Migration​

This release is additive. Existing practice clients do not need to change unless they want to write or read custom location metadata.