---
title: "Set a profile field for a user."
method: PUT
path: "/_matrix/client/v3/profile/{userId}/{keyName}"
tags: ["User data"]
---

# Set a profile field for a user.

`PUT /_matrix/client/v3/profile/{userId}/{keyName}`

## Request

- Base URL: `https://matrix.org`
- URL: `https://matrix.org/_matrix/client/v3/profile/{userId}/{keyName}`
- Auth: one of:
  - API key in query parameter `access_token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/matrix/apis/matrix-client-server-api/docs/_matrix/client/v3/profile/:userId/:keyName/put.ts> (a function with typed inputs; its response is checked against the schema)

Set or update a profile field for a user. Must be authenticated with an
access token authorised to make changes. Servers MAY impose size limits
on individual fields, and the total profile MUST be under 64 KiB.

Servers MAY reject `null` values. Servers that accept `null` values SHOULD store
them rather than treating `null` as a deletion request. Clients that want to delete a
field, including its key and value, SHOULD use the `DELETE` endpoint instead.

This endpoint uses [capabilities negotiation](https://spec.matrix.org/v1.19/client-server-api/#capabilities-negotiation)
depending on the `keyName`. Clients SHOULD check the value of the
[`m.profile_fields` capability](https://spec.matrix.org/v1.19/client-server-api/#mprofile_fields-capability) to detect
which `keyName`s they are allowed to modify.

## Path parameters

- `userId` string, mx-user-id, required
- `keyName` string, required

## Request body

- object: An object which contains exactly one property. The key of that property MUST match the `keyName` specified in the URL. For `avatar_url`, the value MUST be an MXC URI string. For `displayname`, the value MUST be a string. For `m.tz`, the value MUST be a valid identifier from the [IANA Time Zone Database](https://www.iana.org/time-zones). Servers MAY choose to validate the value. Clients MUST expect unknown or invalid values. For custom keys, any JSON type is allowed. Servers MAY not validate these values, but clients SHOULD follow the format defined for that key.

## Response `200`

The profile field was set.

- object

## Other responses

- `400`: The input was invalid in some way. This can include one of the following error codes: - `M_BAD_JSON`: The provided value is not valid JSON. - `M_MISSING_PARAM`: The required `keyName` property is missing from the request body. - `M_PROFILE_TOO_LARGE`: Storing the supplied value would make the profile exceed its maximum allowed size of 64 KiB. - `M_KEY_TOO_LARGE`: The supplied profile key exceeds the maximum allowed key length of 255 bytes.
- `403`: The server is unwilling to perform the operation, either due to insufficient permissions or because profile modifications are disabled.
- `429`: This request was rate-limited.

---

[API](https://skmtc.dev/matrix/apis/matrix-client-server-api.md) - [All operations](https://skmtc.dev/matrix/apis/matrix-client-server-api/llms.txt) - [OpenAPI document](https://skmtc.dev/matrix/apis/matrix-client-server-api/revisions/c7fe4072c681?raw)