---
title: "Set (upsert) properties for a user"
method: POST
path: "/users/{user_id}/properties"
tags: ["User Properties"]
---

# Set (upsert) properties for a user

`POST /users/{user_id}/properties`

Upserts one or more properties for the specified user (1-100 items per call).
Each property is identified by a key; existing values are overwritten.
Supports partial success: as long as **at least one** property passes
validation, the response is 200 with successfully saved properties under
`saved_properties` and per-key failures under `property_errors`.

**Effective validation** (applied per-item):
- `key` — 1-80 characters, matching `^[-a-zA-Z0-9_.:]+$` and containing
  at least one letter. Keys starting with `_` are reserved for Qonversion
  system properties; only pre-registered keys prefixed with `_q_` (e.g.
  `_q_email`, `_q_name`) are accepted.
- `value` — up to 120 bytes, must not contain `\n`, `\r`, `"`, or `'`.

**400 behaviour** — returned without a per-key breakdown when:
- the request itself is malformed (empty array, more than 100 items, or
  key/value exceeding the gateway's 256/1024-character limits), or
- every property in the request fails validation (there is nothing to
  save). In that case retry with the offending keys removed to see
  per-key reasons in the 200 response.

## Path parameters

- `user_id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- V4SetUserPropertiesRequest
  - `properties` V4SetUserPropertyItem[], required
    - `key` string, required — Property key. The request is rejected with 400 only if the key is empty or longer than 256 characters. Effective validation (applied per-item and reported via `property_errors`) additionally requires the key to be at most 80 characters, match `^[-a-zA-Z0-9_.:]+$`, and contain at least one letter. Keys starting with `_` are reserved; only pre-registered keys prefixed with `_q_` are accepted.
    - `value` string, required — Property value. The request is rejected with 400 only if the value is longer than 1024 characters. Effective validation (applied per-item and reported via `property_errors`) additionally requires the value to be at most 120 bytes and to contain no `\n`, `\r`, `"` or `'` characters.

## Response `200`

Properties processed (check property_errors for per-key failures).

- V4UserPropertiesSetResult
  - `object` 'user_properties_set_result', required
  - `url` string, required
  - `saved_properties` V4UserPropertyItem[], required
    - `object` 'user_property', required
    - `key` string, required
    - `value` string, required
  - `property_errors` V4UserPropertyError[], required
    - `key` string, required — Property key that failed to save.
    - `error` string, required — Human-readable error message.

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `404` — User not found
- `415` — Unsupported media type
- `500` — Internal error
- `502` — Storage error
- `504` — Upstream timeout

---

[API](https://skmtc.net/qonversion/apis/qonversion-rest-api-v4.md) · [All operations](https://skmtc.net/qonversion/apis/qonversion-rest-api-v4/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/qonversion/qonversion-rest-api-v4/revisions/e3f72cf8951c/schema)