v6.1

We are pleased to announce a significant improvement to how you read and write user
profile data. The Users request now returns everything you are able to update, and a
new Tag Groups request tells you exactly which values each field will accept.

New endpoint

Tag Groups

• /tag-groups – returns your organisation's active tag groups and their tags: the
  field names and answer values that the Update Users request accepts.

Read what you can write

The /users request now returns the full set of fields that Update Users can change,
so you can check a user's current state before updating them:

• User title and study start date
• Study stage, courses, education attainment, areas of expertise, and demographic
  identification
• A tags object holding answers to any other tag group you have configured with a
  mapping field name, keyed by that mapping field name
• A custom_answers object holding free-text answers, provided as read-only context

Used together with /tag-groups, this means you can read a user's current answers,
look up the valid values for a field, and send an update with confidence.

Clearer update behaviour

We have documented how Update Users applies the data you send:

• Each field you send replaces that user's existing answers for that field in
  full. Send a field only when you intend to set its complete new value, and omit any
  field you do not want to change.
• Sending an empty array for a field clears all of that user's answers for it.
• An answer that does not match one of your organisation's active tags is silently
  ignored. The request still reports success, and the unmatched value is not
  applied. Use /tag-groups to confirm your values.
• Free-text answers to tag groups that allow custom answers cannot be set through the
  API. To preserve an existing one, keep the group's own tag label (for example
  Other) among the answers you send.

We have also removed fName and lName from the user object in the Invite Users
and Update Users requests. These fields never had any effect, because a user's first
and last name are set by the user themselves at sign-up. The specification now matches
the behaviour, and no change is required on your side.