> 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 %}

## **쿼리 파라미터**

<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>

## **헤더**

<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>

## **요청 본문**

<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

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

<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

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

* [표준 유저 프로필 속성](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>

## 요청 예시

```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"
}
 '
```

## **응답 예시**

### 정상 응답

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

### 실패 응답

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.dfinery.ai/api-guide/api/import-api/profile/post.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.