> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manalens.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Properties

> Merge-update the properties of one user profile. Set a Discord ID, Steam ID, email, socials or any custom property, or send null to delete a property, in one PUT request.

```http theme={null}
PUT /v0/projects/{projectId}/profiles/{userId}/properties
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Sets and deletes properties on the profile of one identified user. Keys that you do not send keep their values. The response returns the merged properties, so you do not need a second read.

## Authentication

Use an API key (`ua_api_...`, or an older `ua_mcp_...` key) with the **`profiles:write`** scope. See [Authentication](https://docs.manalens.dev/api/authentication.md#api-keys).

* The key works on its own project only. A key of another project gets `404`.
* The key acts for the member who created it. That member must be an owner, admin or editor.
* Call this endpoint from a server. A request with a browser `Origin` header gets `403`.

Editors can also change properties in the dashboard on the profile's **Properties** tab.

## Path parameters

| Parameter | Rule |
| - | - |
| `projectId` | The project ID |
| `userId` | The customer `user_id` that you send with `identify`. 1 to 255 characters. URL-encode it. |

A profile is keyed by `user_id`. An anonymous visitor has no profile to write to: identify the visitor first. If no profile exists for the `user_id`, the write creates it.

## Body

A flat object of properties. Send 1 to 50 keys.

| Rule | Value |
| - | - |
| Key | Starts with a letter, then letters, digits, `_`, `.` or `-`. At most 100 characters. |
| Value | A string (at most 1024 characters), a number, a boolean, or `null` |
| `null` | Deletes the property |
| Reserved keys | `user_id` (it is the profile key, so it cannot be set or unset here) and `company_domain` (derived from `email`) |
| Reserved value | The string `_is_deleted` (Formo's internal marker). Send `null` to delete. |

[Known properties](https://docs.manalens.dev/api/profiles/known-properties.md) such as `discord_id` and `steam_id` must be strings and pass a light format check. Any other key is a custom property.

```json theme={null}
{
  "discord_id": "112233445566778899",
  "display_name": "Luca",
  "twitter": null,
  "level": 12
}
```

## Response

`200`:

```json theme={null}
{
  "user_id": "player_42",
  "properties": {
    "discord_id": "112233445566778899",
    "display_name": "Luca",
    "level": 12,
    "plan": "pro"
  },
  "set": ["discord_id", "display_name", "level"],
  "deleted": ["twitter"],
  "updated_at": "2026-11-15T12:00:00.000Z"
}
```

| Field | Notes |
| - | - |
| `properties` | The profile after this write: the properties read before the write, with this update merged in |
| `set`, `deleted` | The keys that this request set and deleted |
| `updated_at` | The time of the write |

The write goes through the event pipeline. Reports, the Users page and `GET` reads show it after a few seconds.

## Delete a property

Send `null`. Set and delete can go in the same request:

```bash theme={null}
curl -sS -X PUT \
  -H "Authorization: Bearer $UA_PROJECT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "discord_id": "112233445566778899", "twitter": null }' \
  "https://YOUR_API_ENDPOINT/v0/projects/$PROJECT_ID/profiles/player_42/properties"
```

A deleted property is gone from the profile, the Properties tab and MCP `get_profile` until you set a new value. Deleting `email` also deletes the derived `company_domain`.

## Link a Discord account (P-2470)

A Discord bot or your website links a player to a Discord account with one call. The bot knows the Discord user ID (a snowflake), and your game or site knows the `user_id`:

```js theme={null}
await fetch(`${API}/v0/projects/${projectId}/profiles/${encodeURIComponent(userId)}/properties`, {
  method: 'PUT',
  headers: { authorization: `Bearer ${process.env.UA_PROJECT_KEY}`, 'content-type': 'application/json' },
  body: JSON.stringify({ discord_id: interaction.user.id, discord: interaction.user.username }),
});
```

To unlink, send `{ "discord_id": null, "discord": null }`. Keep the key in the bot's server-side secrets, never in a client.

## Errors

| Status | Code | Meaning |
| - | - | - |
| `400` | `INVALID_PROPERTIES` | A key, a value or the `userId` failed validation. The message names the key, never the value. Nothing is written. |
| `401` | `UNAUTHORIZED` | The key is missing, unknown or revoked |
| `402` | `SUBSCRIPTION_REQUIRED` | The workspace has no active subscription or trial |
| `403` | `FORBIDDEN` | The key has no `profiles:write` scope, its creator is below editor, or the request came from a browser |
| `403` | `WORKSPACE_SUSPENDED` | The workspace is suspended. Reads still work. |
| `404` | `NOT_FOUND` | The key belongs to another project |
| `413` | `TOO_LARGE` | The body is larger than 64 KB |
| `429` | `TOO_MANY_REQUESTS` | The key or workspace budget is used up. Wait for `Retry-After`. |
| `429` | `RATE_LIMITED` | The project sent too many server events and profile writes this minute |

`PUT` is idempotent: you can retry the same body after a `429` or a `5xx`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.