---
title: "Update user properties"
method: PUT
path: "/v0/profiles/{address}/properties"
tags: ["Profiles"]
---

# Update user properties

`PUT /v0/profiles/{address}/properties`

## Request

- Base URL: `https://api.formo.so`
- URL: `https://api.formo.so/v0/profiles/{address}/properties`
- Auth: HTTP bearer

Set or unset first-party properties for a wallet profile. Override display name, email, socials, avatar, location, and other identity fields. Send `null` as a value to delete (unset) that property: the field then reads as null everywhere, including over any globally-enriched fallback value, until a new value is set. `user_id` cannot be unset (it participates in identity stitching). Set-and-unset compose in a single call. Note: profile enrichment snapshots are versioned, but first-party property overrides (and their deletions) are always current; a point-in-time read (`timestamp`) reflects the latest overrides, so a deletion also masks historical reads.

## Path parameters

- `address` string, required

## Request body

- object: Merge-update of profile properties. Only the listed keys are accepted; unknown keys are rejected. At least one key must be provided. A `null` value unsets the property (not allowed for `user_id`). The literal string `_is_deleted` is a reserved internal tombstone and is rejected as a value.
  - `user_id` string
  - `display_name` string, nullable
  - `email` string, nullable
  - `farcaster` string, nullable
  - `discord` string, nullable
  - `twitter` string, nullable
  - `telegram` string, nullable
  - `instagram` string, nullable
  - `website` string, nullable
  - `github` string, nullable
  - `linkedin` string, nullable
  - `facebook` string, nullable
  - `tiktok` string, nullable
  - `youtube` string, nullable
  - `reddit` string, nullable
  - `avatar` string, nullable
  - `description` string, nullable
  - `location` string, nullable
  - `ens` string, nullable
  - `lens` string, nullable
  - `basenames` string, nullable
  - `linea` string, nullable

## Response `200`

Properties updated. Returns the merged identity (the keys actually set, plus address + updated_at) so callers can cache without a follow-up read.

- UpdateUserPropertiesResponse: Echo of the wallet identity after the merge-update applied. Synthesised from the request payload; analytics ingestion is eventually consistent, so the response reflects the applied write rather than a follow-up read.
  - `address` string, required
  - `updated_at` string, date-time, required
  - `user_id` string, nullable
  - `display_name` string, nullable
  - `email` string, nullable
  - `farcaster` string, nullable
  - `discord` string, nullable
  - `twitter` string, nullable
  - `telegram` string, nullable
  - `instagram` string, nullable
  - `website` string, nullable
  - `github` string, nullable
  - `linkedin` string, nullable
  - `facebook` string, nullable
  - `tiktok` string, nullable
  - `youtube` string, nullable
  - `reddit` string, nullable
  - `avatar` string, nullable
  - `description` string, nullable
  - `location` string, nullable
  - `ens` string, nullable
  - `lens` string, nullable
  - `basenames` string, nullable
  - `linea` string, nullable

## Other responses

- `400`: The request was rejected. `code` is either `INVALID_VALIDATION_REQUEST` (Zod schema mismatch; `details` carries a `{ fieldPath: message }` map) or `BAD_REQUEST` (semantic validation failure outside Zod, e.g. mismatched IDs, business-rule violations). Branch on `code`, not status, to tell the two apart.
- `401`: Missing or invalid API key.
- `403`: The API key is valid but lacks the required scope for this endpoint.
- `404`: The requested resource does not exist or is not visible to this API key's workspace.
- `429`: Per-workspace rate limit exceeded. Inspect the `RateLimit-*` response headers and back off.
- `500`: An unexpected error occurred on the server. The error has been logged; retry with exponential backoff.

---

[API](https://skmtc.dev/formo/apis/formo-public-api.md) · [All operations](https://skmtc.dev/formo/apis/formo-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/formo/apis/formo-public-api/revisions/67ada57df63c?raw)