curl --request POST \
  --url https://api.qonversion.io/v4/users/{user_id}/properties \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "properties": [
    {
      "key": "color",
      "value": "blue"
    },
    {
      "key": "invalid key",
      "value": "oops"
    }
  ]
}
'

{
  "object": "user_properties_set_result",
  "url": "/v4/users/QON_3af4c5b8a4d24f21b72e9d0c8aef9d4e/properties",
  "saved_properties": [
    {
      "object": "user_property",
      "key": "color",
      "value": "blue"
    }
  ],
  "property_errors": [
    {
      "key": "invalid key",
      "error": "property key: invalid key. Error: invalid key format"
    }
  ]
}

User Properties

Set (upsert) properties for a user

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.

POST

users

{user_id}

properties

curl --request POST \
  --url https://api.qonversion.io/v4/users/{user_id}/properties \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "properties": [
    {
      "key": "color",
      "value": "blue"
    },
    {
      "key": "invalid key",
      "value": "oops"
    }
  ]
}
'

{
  "object": "user_properties_set_result",
  "url": "/v4/users/QON_3af4c5b8a4d24f21b72e9d0c8aef9d4e/properties",
  "saved_properties": [
    {
      "object": "user_property",
      "key": "color",
      "value": "blue"
    }
  ],
  "property_errors": [
    {
      "key": "invalid key",
      "error": "property key: invalid key. Error: invalid key format"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication using the project Secret Key (prefixed with sk_, or test_sk_ for sandbox). All v4 public endpoints require the Secret Key — see Authentication. Never expose the Secret Key in client-side code.

Headers

Idempotency-Key

string

Idempotency key for safe retries. Same key returns the original response.

Path Parameters

user_id

string

required

Qonversion User ID. SDK-generated IDs are prefixed with QON_.

Maximum string length: 256

Body

application/json

properties

object[]

required

Required array length: 1 - 100 elements

Show child attributes

Response

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

object

enum<string>

required

Available options:

user_properties_set_result

url

string

required

Example:

"/v4/users/QON_3af4c5b8a4d24f21b72e9d0c8aef9d4e/properties"

saved_properties

object[]

required

Show child attributes

property_errors

object[]

required

Show child attributes

List properties for a user

Get an identity by external ID

REST API v3

REST API v4

Analytics API

Set (upsert) properties for a user

Authorizations

Headers

Path Parameters

Body

Response