> For the complete documentation index, see [llms.txt](https://docs.salesmap.kr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.salesmap.kr/developers/api-reference/crm/object-search.md).

# 오브젝트 검색

<mark style="color:yellow;">`POST`</mark> `/v2/object/{targetType}/search`

고객, 회사, 딜, 리드 레코드를 필터 그룹으로 검색합니다. 필터 그룹 사이에는 OR, 같은 그룹 안의 필터 사이에는 AND 조건이 적용됩니다.

### 언제 사용하나요?

외부 시스템에서 CRM 레코드를 동기화하기 전에 이름, 이메일, 금액, 날짜, 선택 필드 같은 조건으로 기존 레코드를 찾을 때 사용합니다. 예를 들어 이메일이 있는 고객 중 이름에 특정 문자열이 포함된 레코드나, 금액이 일정 기준 이상인 딜을 검색할 수 있습니다.

### Headers

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

### Path parameters

| Name         | Type   | Description                                                                                                                                                                |
| ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `targetType` | string | <p>검색할 오브젝트 타입. <code>people</code>, <code>organization</code>, <code>deal</code>, <code>lead</code> 중 하나<br><mark style="color:red;"><strong>Required</strong></mark></p> |

### Query parameters

| Name     | Type   | Description                                       |
| -------- | ------ | ------------------------------------------------- |
| `cursor` | string | 페이지네이션 커서. 이전 응답의 `data.nextCursor` 값을 그대로 전달합니다. |

### Body parameters

| Name                                    | Type                                     | Description                                                                                                                                    |
| --------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `filterGroupList`                       | array                                    | <p>필터 그룹 목록. 1개 이상 3개 이하이며 그룹 사이에는 OR 조건이 적용됩니다.<br><mark style="color:red;"><strong>Required</strong></mark></p>                              |
| `filterGroupList[].filters`             | array                                    | <p>한 그룹 안의 필터 목록. 1개 이상 3개 이하이며 필터 사이에는 AND 조건이 적용됩니다.<br><mark style="color:red;"><strong>Required</strong></mark></p>                        |
| `filterGroupList[].filters[].fieldName` | string                                   | <p>기본 필드 또는 데이터 필드의 이름. 정확한 필드 이름은 <code>GET /v2/field/{type}</code>으로 확인합니다.<br><mark style="color:red;"><strong>Required</strong></mark></p> |
| `filterGroupList[].filters[].operator`  | string                                   | <p>검색 연산자. 아래 연산자 표를 참고하세요.<br><mark style="color:red;"><strong>Required</strong></mark></p>                                                   |
| `filterGroupList[].filters[].value`     | string \| number \| boolean \| string\[] | 비교할 값. `EXISTS`, `NOT_EXISTS`에서는 생략할 수 있고 그 외 연산자에서는 필수입니다. 값의 형식은 연산자와 실제 필드 타입에 맞아야 합니다.                                                     |

{% hint style="info" %}
고객·회사·딜·리드의 이름 필드는 모두 `이름`입니다. `고객 이름`, `회사 이름`, `딜 이름`, `리드 이름`처럼 타입명을 붙이면 유효하지 않은 필드 이름으로 처리됩니다.
{% endhint %}

### Operators

| Category | Operator                                                                                                                                 | 적용 필드 타입                          | Value 규칙                                                                                       |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------- |
| 일치       | `EQ`                                                                                                                                     | 문자열, 숫자, boolean, 단일 선택, 단일 관계 필드 | 실제 필드 타입과 맞는 값을 입력합니다. 숫자 필드는 `EQ`만 지원합니다. 관계 필드는 UUID 또는 레거시 ObjectId 형식의 단일 RecordId를 입력합니다. |
| 불일치      | `NEQ`                                                                                                                                    | 문자열, boolean, 단일 선택, 단일 관계 필드     | 숫자 필드에는 사용할 수 없습니다. 관계 필드는 UUID 또는 레거시 ObjectId 형식의 단일 RecordId를 입력합니다.                        |
| 존재 여부    | `EXISTS`, `NOT_EXISTS`                                                                                                                   | 지원 대상 필드                          | `value`를 생략합니다.                                                                                |
| 문자열      | `CONTAINS`, `NOT_CONTAINS`                                                                                                               | 텍스트 필드                            | 비어 있지 않은 문자열을 입력합니다.                                                                           |
| 숫자 비교    | `LT`, `LTE`, `GT`, `GTE`                                                                                                                 | 숫자 필드                             | JSON number 또는 숫자로 해석 가능한 문자열을 입력합니다. 십진수·지수·16진수(`0x`)·2진수(`0b`)·8진수(`0o`) 문자열을 지원합니다.        |
| 선택·관계    | `IN`, `NOT_IN`                                                                                                                           | 단일·다중 선택 및 단일·다중 관계 필드            | 비어 있지 않은 문자열 하나 또는 문자열 배열을 입력합니다. 관계 필드는 UUID 또는 레거시 ObjectId 형식의 RecordId를 사용합니다.             |
| 목록 포함    | `LIST_CONTAIN`, `LIST_NOT_CONTAIN`                                                                                                       | 다중 선택 및 다중 관계 필드                  | 비어 있지 않은 단일 문자열을 입력합니다. 관계 필드는 UUID 또는 레거시 ObjectId 형식의 단일 RecordId를 사용하며 배열은 허용되지 않습니다.       |
| 날짜       | `DATE_ON_OR_AFTER`, `DATE_ON_OR_BEFORE`, `DATE_IS_SPECIFIC_DAY`                                                                          | 날짜·날짜시간 필드                        | 유효한 날짜 또는 날짜시간 문자열 하나를 입력합니다.                                                                  |
| 날짜 범위    | `DATE_BETWEEN`                                                                                                                           | 날짜·날짜시간 필드                        | 유효한 날짜 또는 날짜시간 문자열 두 개를 담은 배열을 입력합니다.                                                          |
| 상대 날짜    | `DATE_MORE_THAN_DAYS_AGO`, `DATE_LESS_THAN_DAYS_AGO`, `DATE_LESS_THAN_DAYS_LATER`, `DATE_MORE_THAN_DAYS_LATER`, `DATE_AGO`, `DATE_LATER` | 날짜·날짜시간 필드                        | JSON number 또는 숫자로 해석 가능한 문자열을 입력합니다.                                                          |

날짜시간은 `T` 또는 공백으로 날짜와 시간을 구분할 수 있고 타임존은 선택 사항입니다. 예를 들어 `2026-01-01T09:30:00`, `2026-01-01 09:30`을 사용할 수 있습니다.

### Request

#### 이메일이 일치하는 고객 검색

```json
{
  "filterGroupList": [
    {
      "filters": [
        {"fieldName": "이메일", "operator": "EQ", "value": "test@test.com"}
      ]
    }
  ]
}
```

#### 이메일이 있고 이름에 특정 문자열이 포함된 고객 검색

```json
{
  "filterGroupList": [
    {
      "filters": [
        {"fieldName": "이메일", "operator": "EXISTS"},
        {"fieldName": "이름", "operator": "CONTAINS", "value": "테스트"}
      ]
    }
  ]
}
```

#### 명시적으로 체크 해제된 레코드 검색

```json
{
  "filterGroupList": [
    {
      "filters": [
        {"fieldName": "동의 여부", "operator": "EQ", "value": false}
      ]
    }
  ]
}
```

### Response

#### 200

```json
{
  "success": true,
  "data": {
    "objectList": [
      {"id": "<objectId>", "name": "테스트 고객"}
    ],
    "nextCursor": null
  }
}
```

| Name                     | Type           | Description                              |
| ------------------------ | -------------- | ---------------------------------------- |
| `data.objectList`        | array          | 검색 조건에 맞는 레코드 목록입니다.                     |
| `data.objectList[].id`   | string         | 레코드 ID입니다. UUID 또는 레거시 ObjectId일 수 있습니다. |
| `data.objectList[].name` | string         | 레코드 표시 이름입니다.                            |
| `data.nextCursor`        | string \| null | 다음 페이지 커서입니다. 다음 페이지가 없으면 `null`입니다.     |

#### 40x

```json
{
  "success": false,
  "message": "Bad Request",
  "reason": "Invalid Parameters"
}
```

### 주요 에러

| Status | Description                                                        |
| ------ | ------------------------------------------------------------------ |
| 400    | `targetType`이 `people`, `organization`, `deal`, `lead` 중 하나가 아닙니다. |
| 400    | `filterGroupList` 또는 `filters`가 비어 있거나 최대 개수를 초과했습니다.              |
| 400    | 존재하지 않는 `fieldName`을 입력했습니다.                                       |
| 400    | 필드 타입에 맞지 않는 `operator` 또는 `value`를 입력했습니다.                        |
| 400    | 숫자 필드에 `NEQ` 연산자를 사용했습니다.                                          |
| 401    | Authorization 헤더가 없거나 토큰이 유효하지 않습니다.                               |
| 429    | 요청 한도를 초과했습니다.                                                     |


---

# 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.salesmap.kr/developers/api-reference/crm/object-search.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.