# User Properties

{% hint style="info" %}
The HTTP API can only be used in a server environment.
{% endhint %}

Using the User Property API, you can update a user's properties without sending an event.

Updated properties are not applied retroactively and are only applied to events that occur after the update.

Authentication is performed using the SDK Key.

* Add the SDK Key to the HTTP header as shown below.
* You can find the SDK Key in the Hackle Dashboard under [SDK Integration Info](https://dashboard.hackle.io/config/sdk-setting).

```http
X-HACKLE-API-KEY: {YOUR_SERVER_SDK_KEY}
```

***

## User General Properties

### Request

```http
POST https://api.hackle.io/v1/properties
```

### Request Body

| Field      | Type              | Required | Description                                                    |
| ---------- | ----------------- | -------- | -------------------------------------------------------------- |
| userId     | string            | X        | User ID *(required if deviceId is not provided)*               |
| deviceId   | string            | X        | Device ID *(required if userId is not provided)*               |
| operations | Operations Object | O        | An object containing information for updating user properties. |

**Operations Object**

| Field    | Type   | Required | Description                                                                          |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------ |
| $set     | object | X        | Sets the property value. An object of key-value pairs for the properties to set.     |
| $setOnce | object | X        | Sets the value only if it has not been set yet. An object of key-value pairs to set. |
| $unset   | object | X        | Removes the property. An object of key-value pairs for the properties to remove.     |

#### Request Body Example

```shell
curl -i -X POST \
  'https://api.hackle.io/v1/properties' \
  -H 'X-HACKLE-API-KEY: YOUR_SDK_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "19285035",
    "deviceId": "ae2182e0",
    "operations": {
      "$set": {
        "age": 42,
        "grade": "GOLD"
      },
      "$setOnce": {
        "sign_up_date": "2020-01-01"
      },
      "$unset": {
        "membership_type": "-"
      }
    }
  }'
```

### Response

#### 200 OK

Returns a 200 response status for a successful request.

#### 400 Bad Request

Returns a 400 status for invalid request information.

**401 Unauthorized**

Returns a 401 status when the `X-HACKLE-API-KEY` header value is missing or the SDK Key is invalid.

***

## Update User Phone Number Property

### Request

```http
POST https://api.hackle.io/v1/properties/phone-numbers
```

### Request Body

| Field       | Type   | Required | Description                                                                                               |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------------------------- |
| userId      | string | O        | User ID                                                                                                   |
| phoneNumber | string | O        | User phone number ([E.164](https://en.wikipedia.org/wiki/E.164) format) e.g., +821012345678 (recommended) |

#### Request Body Example

```shell
curl -i -X POST \
  'https://api.hackle.io/v1/properties/phone-numbers' \
  -H 'X-HACKLE-API-KEY: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "19285035",
    "phoneNumber": "+821012345678"
  }'
```

### Response

#### 200 OK

Returns a 200 response status for a successful request.

#### 400 Bad Request

Returns a 400 status for invalid request information.

#### 401 Unauthorized

Returns a 401 status when the `X-HACKLE-API-KEY` header value is missing or the SDK Key is invalid.

***

## Delete User Phone Number Property

### Request

```http
DELETE https://api.hackle.io/v1/properties/phone-numbers
```

### Request Parameter

| Field  | Type   | Required | Description |
| ------ | ------ | -------- | ----------- |
| userId | string | O        | User ID     |

#### Request Body Example

```shell
curl -i -X DELETE \
  'https://api.hackle.io/v1/properties/phone-numbers?userId=targetUserId' \
  -H 'X-HACKLE-API-KEY: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json'
```

### Response

#### 200 OK

Returns a 200 response status for a successful request.

#### 400 Bad Request

Returns a 400 status for invalid request information.

#### 401 Unauthorized

Returns a 401 status when the `X-HACKLE-API-KEY` header value is missing or the SDK Key is invalid.

***

## Push Message Subscription Consent User Property

### Request

```http
POST https://api.hackle.io/v1/push-subscriptions
```

### Request Body

| Field                         | Type   | Required | Description                                                                                         |
| ----------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| userId                        | string | X        | User ID (required if deviceId is not provided)                                                      |
| deviceId                      | string | X        | Device ID (required if userId is not provided)                                                      |
| marketingSubscriptionStatus   | String | X        | Marketing message subscription status \* SUBSCRIBED: Subscribed \* UNSUBSCRIBED: Not subscribed     |
| informationSubscriptionStatus | String | X        | Informational message subscription status \* SUBSCRIBED: Subscribed \* UNSUBSCRIBED: Not subscribed |

#### Request Body Example

```shell
curl -i -X POST \
  'https://api.hackle.io/v1/push-subscriptions' \
  -H 'X-HACKLE-API-KEY: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "19285035",
    "deviceId": null,
    "marketingSubscriptionStatus": "UNSUBSCRIBED",
    "informationSubscriptionStatus" : "SUBSCRIBED"
 }'
```

### Response

#### 200 OK

Returns a 200 response status for a successful request.

#### 400 Bad Request

Returns a 400 status for invalid request information.

#### 401 Unauthorized

Returns a 401 status when the `X-HACKLE-API-KEY` header value is missing or the SDK Key is invalid.

***

## Kakao Message Subscription Consent User Property

### Request

```http
POST https://api.hackle.io/v1/kakao-subscriptions
```

### Request Body

| Field                         | Type   | Required | Description                                                                                         |
| ----------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| userId                        | string | O        | User ID                                                                                             |
| marketingSubscriptionStatus   | String | X        | Marketing message subscription status \* SUBSCRIBED: Subscribed \* UNSUBSCRIBED: Not subscribed     |
| informationSubscriptionStatus | String | X        | Informational message subscription status \* SUBSCRIBED: Subscribed \* UNSUBSCRIBED: Not subscribed |

#### Request Body Example

```shell
curl -i -X POST \
  'https://api.hackle.io/v1/kakao-subscriptions' \
  -H 'X-HACKLE-API-KEY: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "19285035",
    "marketingSubscriptionStatus": "UNSUBSCRIBED",
    "informationSubscriptionStatus" : "SUBSCRIBED"
 }'
```

### Response

#### 200 OK

Returns a 200 response status for a successful request.

#### 400 Bad Request

Returns a 400 status for invalid request information.

#### 401 Unauthorized

Returns a 401 status when the `X-HACKLE-API-KEY` header value is missing or the SDK Key is invalid.

***

## Text Message Subscription Consent User Property

### Request

```http
POST https://api.hackle.io/v1/sms-subscriptions
```

### Request Body

| Field                         | Type   | Required | Description                                                                                         |
| ----------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| userId                        | string | O        | User ID                                                                                             |
| marketingSubscriptionStatus   | String | X        | Marketing message subscription status \* SUBSCRIBED: Subscribed \* UNSUBSCRIBED: Not subscribed     |
| informationSubscriptionStatus | String | X        | Informational message subscription status \* SUBSCRIBED: Subscribed \* UNSUBSCRIBED: Not subscribed |

#### Request Body Example

```shell
curl -i -X POST \
  'https://api.hackle.io/v1/sms-subscriptions' \
  -H 'X-HACKLE-API-KEY: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "19285035",
    "marketingSubscriptionStatus": "UNSUBSCRIBED",
    "informationSubscriptionStatus" : "SUBSCRIBED"
 }'
```

### Response

#### 200 OK

Returns a 200 response status for a successful request.

#### 400 Bad Request

Returns a 400 status for invalid request information.

#### 401 Unauthorized

Returns a 401 status when the `X-HACKLE-API-KEY` header value is missing or the SDK Key is invalid.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hackle.io/en/development-guide/http-api/api-properties.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.