> For the complete documentation index, see [llms.txt](https://docs.dfinery.ai/api-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dfinery.ai/api-guide/api/import-api/profile/post.md).

# POST: 유저 속성 생성 및 업데이트

<mark style="color:green;">`POST`</mark> `/api/v1/user-profile`

고객의 유저 속성을 생성 및 업데이트할 수 있는 API입니다.

{% hint style="warning" %}
유저 속성의 생성 및 업데이트 API 호출은 유저의 속성의 변경 시점에만 호출하는 것이 좋습니다. 연동 시에는 항상 [요청 제한](/api-guide/rate-limit.md)을 고려해야 합니다.
{% endhint %}

## **쿼리 파라미터** <a href="#query-parameters" id="query-parameters"></a>

<table><thead><tr><th width="210">이름</th><th>필수값 여부<select><option value="xBw0HvmJduZN" label="선택" color="blue"></option><option value="VBuJ6ubzjfbi" label="필수" color="blue"></option></select></th><th>타입</th><th>설명</th></tr></thead><tbody><tr><td><code>service_id</code></td><td><span data-option="VBuJ6ubzjfbi">필수</span></td><td>String</td><td>서비스 ID</td></tr></tbody></table>

## **헤더** <a href="#headers" id="headers"></a>

<table><thead><tr><th>필드명</th><th>필수값 여부<select><option value="3Gw9yCGdnldk" label="필수" color="blue"></option><option value="mVPQehiUZOei" label="선택" color="blue"></option></select></th><th>타입</th><th>값</th><th>설명</th></tr></thead><tbody><tr><td><code>Content-Type</code></td><td><span data-option="3Gw9yCGdnldk">필수</span></td><td>String</td><td><code>application/json</code></td><td>-</td></tr><tr><td><code>access_token</code></td><td><span data-option="3Gw9yCGdnldk">필수</span></td><td>String</td><td><code>your-api-token-key</code></td><td>API 인증 토큰</td></tr></tbody></table>

## **요청 본문** <a href="#request-body" id="request-body"></a>

<table><thead><tr><th>필드명</th><th>필수값 여부<select><option value="xBw0HvmJduZN" label="선택" color="blue"></option><option value="VBuJ6ubzjfbi" label="필수" color="blue"></option></select></th><th>타입</th><th>설명</th></tr></thead><tbody><tr><td><a href="#identity"><code>identity</code></a></td><td><span data-option="VBuJ6ubzjfbi">필수</span></td><td>Object</td><td>유저 식별자</td></tr><tr><td><a href="#user_properties"><code>user_properties</code></a></td><td><span data-option="VBuJ6ubzjfbi">필수</span></td><td>Object</td><td>유저 속성, Datetime 타입의 경우 UTC 타임존 기준</td></tr><tr><td><code>request_datetime</code></td><td><span data-option="VBuJ6ubzjfbi">필수</span></td><td>Datetime</td><td>요청 시각, ISODate 8601 Format, UTC 타임존 기준<br><code>2024-06-24T06:42:25.394Z</code></td></tr></tbody></table>

### identity <a href="#identity" id="identity"></a>

유저 식별자 정보입니다. **아래 필드 중 적어도 하나의 값을 넣어주어야 합니다.**

<table><thead><tr><th>필드명</th><th>필수값 여부<select><option value="xBw0HvmJduZN" label="선택" color="blue"></option><option value="VBuJ6ubzjfbi" label="필수" color="blue"></option></select></th><th>타입</th><th>설명</th></tr></thead><tbody><tr><td><code>external_id</code></td><td><span data-option="xBw0HvmJduZN">선택</span></td><td>String</td><td>외부 ID</td></tr><tr><td><code>phone_no</code></td><td><span data-option="xBw0HvmJduZN">선택</span></td><td>String</td><td>전화 번호</td></tr><tr><td><code>email</code></td><td><span data-option="xBw0HvmJduZN">선택</span></td><td>String</td><td>이메일</td></tr><tr><td><code>kakao_user_id</code></td><td><span data-option="xBw0HvmJduZN">선택</span></td><td>String</td><td>카카오 ID</td></tr><tr><td><code>line_user_id</code></td><td><span data-option="xBw0HvmJduZN">선택</span></td><td>String</td><td>라인 ID</td></tr></tbody></table>

### user\_properties <a href="#user-properties" id="user-properties"></a>

유저 속성입니다. **필드명은 콘솔에서 사전 등록된 유저 속성의 속성명을, 값은 해당 속성의 값을 넣어주어야 합니다.** 사전 등록된 유저 속성의 종류는 아래와 같습니다.

* [표준 유저 프로필 속성](https://docs.dfinery.ai/user-guide/begin-to-use-dfinery/event-and-property#undefined-8)
* [커스텀 유저 프로필 속성](https://docs.dfinery.ai/user-guide/begin-to-use-dfinery/event-and-property#undefined-16)
* [채널 수신 동의 속성](https://docs.dfinery.ai/user-guide/action/off-site-campaign/opt-state)

<table><thead><tr><th>필드명</th><th>필수값 여부<select><option value="xBw0HvmJduZN" label="선택" color="blue"></option><option value="VBuJ6ubzjfbi" label="필수" color="blue"></option></select></th><th>타입</th><th>설명</th></tr></thead><tbody><tr><td><code>${your-user-property-key}</code></td><td><span data-option="xBw0HvmJduZN">선택</span></td><td>String, Long, Double, Boolean, Datetime, Array</td><td>사전 등록된 유저 속성 정보</td></tr></tbody></table>

## 요청 예시 <a href="#request-example" id="request-example"></a>

```sh
curl -L \
  -X POST \
  -H 'access_token: ${your-import-api-token}' \
  -H 'Content-Type: application/json' \
  'https://openapi.dfinery.ai/api/v1/user-profile?service_id=${your-service-id}' \
  -d '{
  "identity": {
    "external_id": "dfn-user-123"
  },
  "user_properties": {
    "df_gender": "Female"
  },
  "request_datetime": "2024-05-14T06:05:46.363Z"
}
 '
```

## **응답 예시** <a href="#response-example" id="response-example"></a>

### 정상 응답 <a href="#success-response" id="success-response"></a>

```sh
Content-Type: application/json
access_token: text
{
  "status": true,
  "code": 20000,
  "message": "OK",
  "data": true
}
```

### 실패 응답 <a href="#error-response" id="error-response"></a>

자세한 내용은 [상세 응답](/api-guide/api/import-api/response.md) 참고하시면 됩니다.