AI용 문서
본 문서는 AI에게 첨부하여 세일즈맵 API 관련 질문을 할 수 있도록 정리한 비공식 레퍼런스입니다. 내용의 정확성을 보장하지 않으며, 정확한 사항은 아래 개발자용 문서를 참고해주시거나, 채널톡으로 문의해 주세요.
세일즈맵은 B2B 영업 CRM이다. AI 에이전트가 유저의 요청을 이해하고 적절한 API를 선택하려면 각 개념의 비즈니스 맥락을 알아야 한다.
핵심 오브젝트
고객 (People)
실제 사람. 영업 대상 담당자.
모든 영업의 시작점. 이메일/전화로 연락하는 대상
회사 (Organization)
고객이 소속된 기업.
B2B에서 실제 계약 주체. 고객 여러 명이 한 회사에 속함
리드 (Lead)
아직 검증되지 않은 잠재 기회.
”이 고객이 관심 있을 수도?” 단계. 확인 후 딜로 전환
딜 (Deal)
검증된 영업 기회. 매출과 직결.
”실제로 계약 가능성 있음” 단계. 파이프라인으로 진행 추적
파이프라인 (Pipeline)
딜/리드의 진행 단계 흐름.
영업 프로세스를 시각화. 예: 초기접촉→니즈파악→제안→협상→성사/실패
견적서 (Quote)
딜/리드에 연결된 가격 제안서.
고객에게 보내는 공식 가격표. 상품×수량×할인
상품 (Product)
판매하는 제품/서비스.
견적서에 포함되는 단위. 일반/구독(월간·연간)
시퀀스 (Sequence)
자동화된 이메일 캠페인.
고객에게 단계별로 이메일을 자동 발송. 오픈/클릭/회신 추적
TODO
영업 담당자의 할 일.
전화, 미팅, 업무 등 follow-up 관리
메모 (Memo)
고객/딜 등에 남기는 내부 기록.
미팅 노트, 상담 내용 등 팀 공유
웹 폼 (WebForm)
외부 리드 수집 폼.
웹사이트에 삽입하여 문의/신청 자동 수집
커스텀 오브젝트
워크스페이스별 맞춤 데이터.
계약, 프로젝트 등 기본 오브젝트로 안 되는 것
영업 흐름 예시
웹폼 제출 → 고객+회사 자동생성 → 리드 생성 → 시퀀스 등록(자동 이메일)
→ 응답 오면 딜로 전환 → 파이프라인 단계별 진행 → 견적서 발송 → 성사/실패히스토리 vs 액티비티
기록 대상
필드 값 변경 내역
이벤트/활동 타임라인
용도
”이 고객 이름이 언제 바뀌었지?” “담당자가 누구에서 누구로?"
"이 고객에게 이메일 보낸 적 있나?” “최근 활동이 뭐야?”
컨설팅 활용
데이터 변경 추적, 감사(audit)
고객 engagement 분석, 영업 활동량 파악
핵심 필드
fieldName, fieldValue (무엇이 어떤 값으로)
type (어떤 활동), 관련 리소스 ID
시퀀스의 비즈니스 의미
시퀀스는 영업 자동화의 핵심이다:
목적: 잠재 고객에게 시간차를 두고 이메일을 자동 발송하여 응답률을 높임
구조: 여러 단계(step)로 구성. 각 단계는 이메일, SMS, 카카오 알림톡 발송 또는 TODO 생성
추적: 이메일 오픈, 링크 클릭, 회신을 자동 추적
비즈니스 판단 기준:
오픈율 높지만 클릭 없음 → 제목은 좋지만 본문/CTA 개선 필요
클릭은 있지만 회신 없음 → 관심은 있으나 행동 유도 부족
회신 있음 → 즉시 개인화된 follow-up 필요
예시: “콜드 메일 시퀀스” = 3일차 첫 메일 → 6일차 후속 메일 → 7일차 전화 TODO 자동 생성
기본 설정
응답 구조 공통 패턴
목록 조회 응답의 각 항목은
id+ 한글 필드명이 직접 속성으로 반환된다.관계형 필드는
{"id": "uuid", "name": "이름"}객체 또는 배열로 반환.RecordId: 세일즈맵 UI에서 RecordId로 표시되는 값은 API 응답의id필드와 동일. API 사용 시id필드를 사용하면 됨.페이지네이션: 응답에
nextCursor키가 없으면 마지막 페이지. 페이지당 50건.단일 조회(
GET /v2/{resource}/{id})의 응답은 모두 배열로 래핑된다:data.people[0],data.deal[0],data.organization[0],data.lead[0]단일 ID 조회이지만 배열
[{...}]형태. 반드시[0]으로 접근.
fieldList 데이터 필드 유형 (검증됨)
모든 생성/수정 API에서 fieldList 배열로 커스텀 필드 값을 지정한다.
필드 이름은 세일즈맵 워크스페이스의 한글 이름과 정확히 일치해야 한다.
선택형 필드의 값도 세일즈맵에 등록된 옵션과 정확히 일치해야 한다. 미등록 값 입력 시 에러:
기본 유형
숫자
numberValue
{ "name": "인센티브", "numberValue": 50000 }
"인센티브": 50000
True/False
booleanValue
{ "name": "구글 폼 제출", "booleanValue": true }
"구글 폼 제출": true
날짜
dateValue
{ "name": "생년월일", "dateValue": "1990-05-15" }
"생년월일": "1990-05-14T15:00:00.000Z"
날짜(시간)
dateValue
{ "name": "날짜시간", "dateValue": "2026-02-27T10:30:00.000Z" }
"날짜시간": "2026-02-27T10:30:00.000Z"
단일 선택
stringValue
{ "name": "유입경로", "stringValue": "블로그" }
"유입경로": "블로그"
복수 선택
stringValueList
{ "name": "복수 선택", "stringValueList": ["1", "2"] }
"복수 선택": ["1", "2"]
날짜 주의: dateValue에 날짜만 ("1990-05-15") 보내면 KST→UTC 변환되어 -9시간 조정된 값으로 저장됨.
관계 유형
사용자(단일)
userValueId
{ "name": "AAA", "userValueId": "<userId>" }
"AAA": {"id": "dac27c65-...", "name": "세일즈맵 관리자"}
회사(복수)
organizationValueIdList
{ "name": "자회사", "organizationValueIdList": ["<orgId>"] }
"자회사": [{"id": "0193f1aa-...", "name": "캐치톡"}]
고객(복수)
peopleValueIdList
{ "name": "고객 - 1", "peopleValueIdList": ["<id>"] }
"고객 - 1": [{"id": "019c9d9c-...", "name": "관계필드테스트"}]
회사(단일)
organizationValueId
{ "name": "거래처", "organizationValueId": "<orgId>" }
"거래처": {"id": "...", "name": "회사명"}
고객(단일)
peopleValueId
{ "name": "담당자", "peopleValueId": "<id>" }
"담당자": {"id": "...", "name": "이름"}
사용자(복수)
userValueIdList
{ "name": "참여자", "userValueIdList": ["<id>"] }
"참여자": [{"id": "...", "name": "이름"}]
파이프라인
pipelineValueId
{ "name": "파이프라인", "pipelineValueId": "<id>" }
"파이프라인": {"id": "...", "name": "이름"}
파이프라인 단계
pipelineStageValueId
{ "name": "단계", "pipelineStageValueId": "<id>" }
"파이프라인 단계": {"id": "...", "name": "단계명"}
웹 폼(단일)
webformValueId
{ "name": "웹폼", "webformValueId": "<id>" }
"웹폼": {"id": "...", "name": "이름"}
딜(복수)
dealValueIdList
{ "name": "딜 목록", "dealValueIdList": ["<id>"] }
"딜 목록": [{"id": "...", "name": "딜명"}]
시퀀스(단일)
sequenceValueId
{ "name": "시퀀스", "sequenceValueId": "<id>" }
"시퀀스": {"id": "...", "name": "이름"}
시퀀스(복수)
sequenceValueIdList
{ "name": "시퀀스 목록", "sequenceValueIdList": ["<id>"] }
"시퀀스 목록": [{"id": "...", "name": "이름"}]
fieldList 주의사항
딜
금액은 fieldList가 아닌 top-levelprice파라미터로 전달. fieldList에 넣으면 에러:"금액 값은 fieldList이 아닌 파라메터 입니다."파이프라인/파이프라인 단계는 딜/리드 생성 시 별도 body 파라미터(
pipelineId,pipelineStageId)로도 지정 가능.
읽기전용 필드 (수정 불가)
2026-02-27 전수 테스트 완료. 커스텀 필드는 기본적으로 모두 수정 가능. 아래는 수정 불가능한 시스템 필드만 정리.
수정 API 파라미터 정리 (2026-02-27 실제 검증)
top-level 파라미터 (실제 작동하는 것만):
People
name, organizationId
이름/담당자/회사
Organization
name
이름 (이것만 작동)
Deal
name, price, status, pipelineId+pipelineStageId, peopleId, organizationId
이름/금액/상태/담당자/파이프라인/고객/회사
Lead
name, pipelineId+pipelineStageId, peopleId, organizationId
이름/담당자/파이프라인/고객/회사
담당자 변경 방법:
fieldList+userValueIdstringValue(사용자 이름)로는 불가. 에러:"담당자에 userValueId가 없습니다"
이메일/전화 변경: fieldList + stringValue로만 가능
Deal status 값 (대소문자 구분): "Won", "Lost", "In progress" (소문자 불가)
People (고객) — 읽기전용 시스템 필드
Organization (회사) — 읽기전용 시스템 필드
Deal (딜) — 읽기전용 시스템 필드
파이프라인 자동 생성 필드도 모두 읽기전용{단계명}({파이프라인명})로 진입한 날짜 / 에서 보낸 누적 시간 / 에서 퇴장한 날짜
Lead (리드) — 읽기전용 시스템 필드
파이프라인 자동 생성 필드도 Deal과 동일 패턴으로 모두 읽기 전용.
항상 읽기전용인 커스텀 필드 타입
formula (수식)
"계산 유형의 필드는 수정 및 생성의 대상이 될 수 없습니다"
multiAttachment (첨부파일)
"설정할 수 없는 {entity} 필드"
multiPeopleGroup (고객 그룹)
"설정할 수 없는 {entity} 필드"
multiTeam (팀)
People/Org 불가. Deal/Lead 커스텀 팀 필드는 teamValueIdList로 가능
추가 주의
생성 날짜는 People/Org/Deal 모두 dateValue로 수정 가능 (예상 외)수신 거부 여부(People)는 booleanValue로 수정 가능Deal
마감일은 상태가 Won, Lost일 때만 입력/수정 가능(아닐 시 201 응답이지만 값 미반영)pipelineStageId변경 시 반드시pipelineId와 함께 전송빈 문자열
""로 기존 값 클리어 가능. 복수선택은 빈 배열[]불가
엔드포인트
회사 (Organization)
비즈니스: B2B 영업의 거래 대상 기업. 고객(담당자)의 상위 개념. 같은 회사에 여러 고객이 속할 수 있다.
목록 조회
실제 응답 예시:
생성
실제 응답:
중복 이름 에러: (기존 회사 재활용 가능)
단일 조회
배열 래핑 — response.data.organization[0]으로 접근.
수정
삭제
POST /v2/organization/delete로 라우트 자체는 존재 (400 응답). body 파라미터 형식 미공개.
히스토리
회사 필드 변경 이력. “이 회사 담당자가 누구에서 누구로 바뀌었지?” 같은 추적에 사용.
실제 응답 예시:
type 값: editField
액티비티
회사와 관련된 모든 활동 타임라인. “이 회사에 최근 연락한 적 있나?” 파악에 사용.
실제 응답 예시:
type 값: create, email, emailOpen, webFormSubmit, memoCreate, meeting
항목 스키마: { id, type, date, organizationId, emailId, messageId, threadId, webFormId, webFormName, smsId, memoId, todoId }
고객 (People)
비즈니스: 실제 영업 대상인 사람. 이메일/전화로 연락하는 담당자. 회사에 소속되며, 딜/리드의 주체가 된다.
목록 조회
실제 응답 예시:
생성
실제 응답:
이메일 중복 감지: 이메일이 동일한 고객이 이미 있으면 isDuplicate: true와 기존 고객 정보가 반환될 수 있음.
단일 조회
배열 래핑 — response.data.people[0]으로 접근. 목록 조회와 동일 스키마 (커스텀 필드 포함 120개+ 필드).
수정
삭제
POST /v2/people/delete로 라우트 존재 (400 응답). body 파라미터 형식 미공개.
히스토리
고객 필드 변경 이력. “이 고객 담당자가 바뀐 적 있나?” “이메일이 수정됐나?” 같은 추적.
실제 응답 예시:
type 값: editField, editOrganizationConnect
항목 스키마: { id, peopleId, type, organization, fieldName, fieldValue, ownerId, createdAt }
organization: 회사 연결 변경 시{_id, name}객체, 아니면nullfieldValue: 유형에 따라 string, number, boolean,{_id, name}객체 등
액티비티
고객과 관련된 모든 활동. “이 고객에게 이메일 보낸 적 있나?” “웹폼 제출한 적 있나?” 파악.
실제 응답 예시:
type 값: create, memoCreate, webFormSubmit, email, emailOpen
항목 스키마: { id, type, date, peopleId, emailId, messageId, threadId, webFormId, webFormName, smsId, memoId, todoId, documentId, documentName }
People만
documentId,documentName필드 추가 존재
딜 (Deal)
비즈니스: 검증된 영업 기회. 매출 예측의 기반. 파이프라인 단계를 따라 진행되며, 최종적으로 성사(Won) 또는 실패(Lost).
목록 조회
실제 응답 예시 (주요 필드):
참고: 딜은 파이프라인 단계별 추적 필드(N단계(파이프라인명)로 진입한 날짜, 에서 보낸 누적 시간, 에서 퇴장한 날짜)가 자동 생성되어 필드가 수백 개일 수 있다.
단일 조회
배열 래핑 — response.data.deal[0]으로 접근. (모든 단일 조회 공통)
생성
실제 검증된 요청:
응답:
수정
pipelineStageId는 pipelineId 지정 시 필수.
삭제
POST /v2/deal/delete로 라우트 존재 (400 응답). body 파라미터 형식 미공개.
주의: POST /v2/deal/<dealId>/delete (path에 ID)는 404 — 작동하지 않음.
히스토리
딜 필드 변경 이력. “이 딜의 금액이 변경됐나?” “담당자가 바뀌었나?” “파이프라인 단계가 언제 이동했나?”
실제 응답 예시:
type 값: editField, editOrganizationConnect, editPeopleConnection
항목 스키마: { id, dealId, type, people, organization, fieldName, fieldValue, ownerId, createdAt }
people: 고객 연결 변경 시{_id, name}, 아니면nullorganization: 회사 연결 변경 시{_id, name}, 아니면null
액티비티
딜 관련 모든 활동. “이 딜에 이메일/메모/TODO가 있었나?” 파악.
dealStatus필드로 딜 상태 변화도 추적.
실제 응답 예시:
type 값: create, memoCreate, todoCreate, email
항목 스키마: { id, type, date, dealId, emailId, messageId, threadId, webFormId, webFormName, smsId, memoId, todoId, dealStatus }
Deal만
dealStatus필드 추가 존재
견적서 조회
비즈니스: 딜에 연결된 가격 제안서 목록. “이 딜에 견적서 보냈나?” “총액이 얼마지?”
실제 응답 예시:
견적서 스키마:
id
UUID
견적서 ID
메인 견적서 여부
boolean
딜의 대표 견적서 여부
공유 링크
string/null
외부 공유 URL
금액
number
할인 적용 후 총액
담당자
{id, name}
견적 작성자
이름
string
견적서명
할인
number
전체 할인값
할인 유형
string
"percentage" 또는 "amount"
견적 구성 상품
array
포함된 상품 목록 (아래)
견적 구성 상품 스키마:
id
UUID
항목 ID
productId
UUID
상품 ID
금액
number
단가
수량
number
수량
할인
number
개별 할인값
할인 유형
string
"percentage" 또는 "amount"
부가세
number
부가세
전체 금액
number
할인·부가세 적용 후 최종 금액
결제 횟수
number
구독 상품의 결제 횟수
시작 결제일
datetime/null
구독 시작 결제일
마지막 결제일
datetime/null
구독 마지막 결제일
리드 (Lead)
비즈니스: 아직 검증되지 않은 잠재 영업 기회. 딜보다 앞 단계. “관심은 있는데 진짜 사려는 건지 모르겠어” 상태. 딜로 전환(convert)할 수 있다. 파이프라인은 선택사항.
딜과 거의 동일한 구조. 차이점: pipelineId/pipelineStageId가 선택사항, status 불필요.
삭제
히스토리
실제 응답 예시:
type 값: editField, editOrganizationConnect, editPeopleConnection
항목 스키마: { id, leadId, type, people, organization, fieldName, fieldValue, ownerId, createdAt }
액티비티
실제 응답 예시:
type 값: create, todoCreate, webFormSubmit, memoCreate, email
항목 스키마: { id, type, date, leadId, emailId, messageId, threadId, webFormId, webFormName, smsId, memoId, todoId }
검색 (Search Record)
비즈니스: 복합 조건으로 오브젝트 검색. “이메일 있는 고객 중 이름에 ‘김’이 포함된 사람”, “금액 1000만원 이상인 딜” 같은 조건 검색.
Rate Limit: 요청당 10 포인트 소모 (일반 API보다 비용 높음)
요청 Body
filterGroupList: 그룹 간 OR, 최대 3개. 필수 (빈 배열 불가).filters: 필터 간 AND, 최대 3개fieldName: 기본/커스텀 필드의 한글 이름value:EXISTS/NOT_EXISTS만 생략 가능. 빈 문자열""불가.
지원 Operator
공통
EQ, NEQ, EXISTS, NOT_EXISTS
문자열
CONTAINS, NOT_CONTAINS
숫자
LT, LTE, GT, GTE
선택
IN, NOT_IN, LIST_CONTAIN, LIST_NOT_CONTAIN
날짜(지정)
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
주의:
Relation 필드 (담당자, 파이프라인, 파이프라인 단계, 고객, 회사 등): UUID 값만 허용,
CONTAINS/NOT_CONTAINS불가.EXISTS/NOT_EXISTS는 값 없이 사용 가능MultiSelect:
EQ/NEQ대신LIST_CONTAIN/LIST_NOT_CONTAINDATE_BETWEENvalue:["2025-01-01", "2025-12-31"]배열빈 값 체크:
EXISTS/NOT_EXISTS사용 (NEQ+""안됨)
응답
id와name만 포함. 상세 정보 필요 시 개별 조회 API 호출.페이지 사이즈: 50건
custom-object타입 미지원 →Invalid targetType
검증된 사용 예시
이메일로 고객 1건 검색:
AND (이메일 있는 + 이름 “테스트” 포함):
OR (이름 “테스트” 또는 “관리자”):
견적서 (Quote)
비즈니스: 고객에게 공식적으로 보내는 가격 제안서. 딜/리드에 연결되며, 여러 상품을 포함. 할인·부가세 자동 계산.
생성
quoteProductList 항목:
name
string
Y
상품 이름
productId
string
상품 있으면
상품 ID
price
number
상품 있으면
단가
amount
number
상품 있으면
수량
paymentCount
number
구독만
결제 횟수
paymentStartAt
date
구독만
시작 결제일
fieldList
array
N
상품 커스텀 필드
조회 (딜/리드 연결)
견적서 응답 스키마는 딜 섹션의 “견적서 조회” 참고.
연관관계 (Association)
비즈니스: 오브젝트 간 연결 관계 조회. “이 고객이 어떤 회사에 속해있지?” “이 딜에 연결된 고객은?”
Primary와 Custom 두 가지.
Primary (FK 직접 연결)
검증된 응답:
targetType / toTargetType:
people,organization,deal,lead,memoID 목록만 반환
Custom (커스텀 필드 연결)
검증된 응답:
targetType / toTargetType:
people,organization,deal,lead,custom-objectID + label 반환.
label은 커스텀 필드 이름.
실전 팁: Primary로 안 나오면 Custom으로도 시도. FK인지 커스텀 필드인지 명확하지 않은 경우가 있으므로 유동적으로.
커스텀 오브젝트 (Custom Object)
비즈니스: 기본 오브젝트로 관리할 수 없는 데이터. 예: 계약, 프로젝트, 자산 등. 워크스페이스마다 다르게 정의.
목록 조회
실제 응답 예시:
customObjectDefinitionId: 이 레코드가 속한 커스텀 오브젝트 정의(스키마/타입). 같은 definition에 여러 레코드가 속함.Definition 전용 조회 API는 없음 — definition ID는 각 레코드의
customObjectDefinitionId에서 확인.필드 정의는
GET /v2/field/custom-object로 조회 가능.
생성
수정
단일 조회
응답에서 필드가 직접 속성으로 반환된다 (다른 오브젝트와 동일 패턴).
삭제
히스토리
실제 응답 예시:
type 값: editField
항목 스키마: { id, customObjectId, type, fieldName, fieldValue, ownerId, createdAt }
액티비티
실제 응답 예시:
type 값: create, memoCreate
항목 스키마: { id, type, date, customObjectId, emailId, messageId, threadId, smsId, memoId, todoId, meetingId, kakaoAlimtalkId, emailLinkId }
커스텀 오브젝트만
meetingId,kakaoAlimtalkId,emailLinkId추가 (webFormId 없음)
필드 정의 (Field)
비즈니스: 워크스페이스에 정의된 필드 목록 조회. MCP 구현 시 필수 — 어떤 필드가 있고, 어떤 값이 유효한지 동적으로 파악.
검증된 응답 예시:
필드 스키마: { id, name, type, required, optionList? }
optionList는singleSelect/multiSelect필드에만 존재옵션 항목:
{ id, value }
지원되는 type 파라미터:
deal, lead, people, organization, product, quote, todo, custom-object (하이픈 필수)
필드 type 값 목록: string, number, boolean, date, dateTime, singleSelect, multiSelect, user, multiUser, people, multiPeople, organization, multiOrganization, deal, multiDeal, multiLead, pipeline, pipelineStage, multiProduct, multiAttachment, webForm, multiWebForm, sequence, multiSequence, multiCustomObject, multiPeopleGroup, multiLeadGroup, team, multiTeam
파이프라인 (Pipeline)
비즈니스: 딜/리드의 진행 단계를 정의하는 프레임워크. 예: “초기 접촉 → 니즈 파악 → 제안 → 협상 → 성사/실패”. 영업 프로세스를 시각화하고, 각 단계에 머문 시간을 추적하여 병목 구간을 파악.
검증된 응답:
키:
pipelineStageList(단계 배열)단계 순서:
index(0부터)
상품 (Product)
비즈니스: 판매하는 제품/서비스. 견적서에 포함되는 단위. 일반 상품과 구독(월간/연간) 상품이 있다.
검증된 응답 예시:
웹 폼 (WebForm)
비즈니스: 웹사이트에 삽입하는 리드 수집 폼. 고객이 문의/신청을 제출하면 자동으로 고객+회사가 생성된다.
목록 조회
검증된 응답:
제출 목록 조회
비즈니스: “이 웹폼으로 어떤 문의가 들어왔지?” — 폼 제출 내역과 자동 생성된 고객/회사/리드 ID 확인.
실제 응답 예시:
웹폼 제출 스키마:
id
UUID
제출 ID
peopleId
UUID/null
자동 생성/매칭된 고객
organizationId
UUID/null
자동 생성/매칭된 회사
dealId
UUID/null
자동 생성된 딜
leadId
UUID/null
자동 생성된 리드
contents
array
폼 입력 값. [{label, value}]
createdAt
datetime
제출 시각
활용: contents[].label로 폼 필드명, contents[].value로 입력값 확인. peopleId/organizationId로 자동 생성된 레코드에 후속 작업 가능.
TODO
비즈니스: 영업 담당자의 할 일 관리. 전화, 미팅, 업무 등 follow-up 스케줄링. 고객/딜/리드/회사에 연결 가능. 시퀀스에서 자동 생성될 수도 있음 (예: “3일 후 전화” step).
생성 API 없음. 읽기 전용. TODO는 UI나 시퀀스(createTodo step)에서만 생성된다.
검증된 응답 예시:
TODO 스키마:
id
UUID
TODO ID
peopleId
UUID/null
연결된 고객
organizationId
UUID/null
연결된 회사
dealId
UUID/null
연결된 딜
leadId
UUID/null
연결된 리드
제목
string
TODO 제목
내용
string/null
상세 내용. 미팅 예약 시 예약자·이메일·장소 등 포함
유형
string
"전화", "미팅", "업무", "이메일" 등
완료
boolean
완료 여부
시작일
datetime
시작 시각
종료일
datetime
종료 시각
완료일
datetime/null
실제 완료 시각
위치
string/null
미팅 장소
담당자
{id, name}
할당된 담당자
참석자
array
미팅 참석자 목록
메모 (Memo)
비즈니스: 고객/딜/회사 등에 남기는 내부 기록. 미팅 노트, 상담 내용, 팀 공유 메모. 히스토리가 아닌 자유 형식 텍스트.
목록 조회
정렬: createdAt 오름차순 (오래된 순 → 최신이 마지막 페이지).
생성 — 오브젝트 수정 API의 memo 파라미터 사용
별도 메모 생성 API는 없다. 오브젝트 수정 시 memo 파라미터에 텍스트를 넣으면 해당 오브젝트에 메모가 새로 생성된다.
검증 결과 (People, Organization, Deal 모두 동일하게 동작 확인):
생성된 메모는 GET /v2/memo 목록에도 등록된다.
검증된 응답 예시:
메모 스키마:
id
UUID
메모 ID
htmlBody
string
HTML 형식 본문
text
string
평문 본문
유형
array
메모 유형 태그 (빈 배열 가능)
dealId
UUID/null
연결된 딜
leadId
UUID/null
연결된 리드
peopleId
UUID/null
연결된 고객
organizationId
UUID/null
연결된 회사
productId
UUID/null
연결된 상품
quoteId
UUID/null
연결된 견적서
todoId
UUID/null
연결된 TODO
parentId
UUID/null
부모 메모 (대댓글)
ownerId
UUID
작성자 ID
참고: 메모는 다른 오브젝트와 달리 camelCase 키를 사용 (htmlBody, createdAt 등). 유형만 한글.
사용자 (User)
비즈니스: CRM 사용자(영업 담당자). 고객/딜의 “담당자”로 할당되는 주체.
목록 조회
검증된 응답:
내 정보 조회
검증된 응답:
주의: user/me와 user 목록의 스키마가 다르다.
/me:email없음,role없음,room{id,name}있음 (room = 워크스페이스)목록:
email있음,role있음,room없음
팀 (Team)
비즈니스: 영업팀 그룹. 고객/딜의 “팀” 필드로 할당. 팀별 성과 분석에 활용.
검증된 응답:
이메일 (Email)
비즈니스: 고객과 주고받은 이메일 내역. 수동 발송 + 시퀀스 자동 발송 모두 포함. 이메일 ID는 액티비티에서
type: "email"항목의emailId로 얻을 수 있다.
단일 조회
실제 응답 예시:
이메일 스키마:
id
UUID
이메일 ID
subject
string
제목
from
string
발신자 이메일 주소
to
string[]
수신자 목록
cc
string[]
참조 목록
bcc
string[]
숨은참조 목록
status
string
발송 상태. "delivery" 등
messageId
string
RFC 2822 Message-ID 헤더
date
datetime
발송/수신 일시
이메일 조회 플로우:
고객 액티비티에서
type: "email"항목의emailId확보GET /v2/email/{emailId}로 상세 조회
이메일 본문(body) 미제공: 문서에는 body 필드가 있다고 되어있으나, 실제 5건 테스트 결과 body/htmlBody/content 필드 전혀 없음. 메타데이터만 조회 가능. (개발팀 문의 필요)
날짜 필드명: 문서에는 sentAt이지만 실제는 date.
목록 조회 (GET /v2/email)는 존재하지 않음 (404). 반드시 개별 ID로 조회해야 한다.
잘못된 ID 시: { "success": false, "reason": "이메일을 찾을 수 없습니다." }
시퀀스 (Sequence)
비즈니스: 자동화된 이메일 캠페인. 잠재 고객에게 시간차를 두고 이메일을 자동 발송하고, 오픈/클릭/회신을 추적.
영업 자동화의 핵심 도구:
콜드 메일 시퀀스: 신규 잠재 고객에게 단계별 접근
팔로우업 시퀀스: 미팅 후 후속 조치 자동화
리텐션 시퀀스: 기존 고객 재접촉
시퀀스 구조: 시퀀스 → 단계(Step) → 고객 등록(Enrollment) → 타임라인(Timeline)
목록 조회
검증된 응답 예시:
주의: _id 사용 (id 아님).
단일 조회
단계 조회 (Step)
시퀀스의 각 단계 정의. “이 시퀀스가 며칠 간격으로 뭘 하는지” 파악.
실제 응답 예시 (콜드 메일 시퀀스 — 3단계):
Step 스키마:
id
UUID
단계 ID
index
number
순서 (0부터)
type
string
"sendEmail" (이메일 발송) 또는 "createTodo" (TODO 자동 생성)
executeImmediately
boolean
즉시 실행 여부
businessDay
number
이전 단계로부터 대기 영업일 수
executionTime
string
실행 시각 ("0900" = 오전 9시)
비즈니스 해석 예시: 위 콜드 메일 시퀀스는:
등록 후 3영업일 → 오전 9시에 첫 이메일 발송
6영업일 후 → 후속 이메일 발송
1영업일 후 → 전화 TODO 자동 생성 (담당자에게 “전화해라” 리마인더)
등록 목록 조회 (Enrollment)
이 시퀀스에 등록된 고객 목록. “이 시퀀스에 몇 명이 등록되어 있지?”
검증된 응답:
Enrollment 스키마: { _id, peopleId, createdAt }
_id사용 (id아님)status,currentStepOrder같은 필드는 없음 (개발팀 문의 필요)
등록 타임라인 조회 (Timeline)
특정 고객의 시퀀스 진행 상황. “이메일 보냈나? 열었나? 링크 클릭했나? 회신했나?”
실제 응답 예시:
Timeline eventType 목록:
sendEmail
이메일 발송됨
시퀀스 단계 실행 확인
emailOpen
이메일 오픈됨 (여러 번 가능)
관심 있음. 오픈 횟수가 높으면 적극 관심
emailLinkClick
이메일 내 링크 클릭
강한 관심 시그널. CTA가 효과적
emailReply
이메일 회신
가장 강한 시그널. 즉시 개인화 follow-up 필요
Timeline 스키마: { eventType, stepIndex, date, emailId, linkUrl?, linkName? }
emailId: 해당 이벤트와 관련된 이메일 ID (GET /v2/email/{emailId}로 상세 조회 가능)linkUrl,linkName은emailLinkClick일 때만 존재stepIndex로 어느 단계의 이메일에 대한 반응인지 파악
문서 vs 실제 차이:
리스트 키
enrollmentList
sequenceEnrollmentList
Enrollment ID
id
_id
Enrollment 상태
status 존재
없음
Enrollment 등록일
enrolledAt
createdAt
Timeline 이벤트 유형
type
eventType
Timeline 단계
stepOrder
stepIndex (0-based)
Timeline 시간
createdAt
date
Timeline ID
id 존재
없음
시퀀스 분석 플로우:
GET /v2/sequence→ 시퀀스 목록GET /v2/sequence/{id}/step→ 각 단계 구성 파악GET /v2/sequence/{id}/enrollment→ 등록된 고객 목록GET /v2/sequence/enrollment/{enrollId}/timeline→ 개별 고객 반응 분석오픈만 하고 클릭 없으면 → 본문/CTA 개선 필요
클릭은 있지만 회신 없으면 → 다음 메일에서 직접 미팅 제안
회신 있으면 → 시퀀스 성공, 1:1 대응으로 전환
히스토리/액티비티 URL 패턴
반드시 slash notation. dot notation은 전부 404.
히스토리 총정리
“무엇이 언제 어떻게 바뀌었나?” — 필드 변경 감사(audit) 로그.
공통 스키마: { id, [objectType]Id, type, fieldName, fieldValue, ownerId, createdAt }
type 값 정리:
editField
필드 값 변경
모든 오브젝트
editOrganizationConnect
회사 연결 변경
People, Deal, Lead
editPeopleConnection
고객 연결 변경
Deal, Lead
오브젝트별 차이:
People:
organization필드 추가 ({_id, name}또는null)Deal/Lead:
people,organization필드 추가Organization/Custom Object: 추가 필드 없음
fieldValue 타입별 형태:
텍스트:
"박일환"숫자:
0,50000불린:
true,false관계:
{"_id": "uuid", "name": "이름"}
액티비티 총정리
“이 오브젝트에 어떤 일이 있었나?” — 이벤트 타임라인.
공통 스키마: { id, type, date, [objectType]Id, emailId, messageId, threadId, smsId, memoId, todoId }
type 값 정리:
create
오브젝트 생성
—
email
이메일 수신/발신
emailId
emailOpen
이메일 오픈 추적
emailId
memoCreate
메모 생성
memoId
todoCreate
TODO 생성
todoId
webFormSubmit
웹폼 제출
webFormId, webFormName
meeting
미팅
—
오브젝트별 추가 필드:
People:
+ documentId, documentName, webFormId, webFormNameDeal:
+ dealStatus, webFormId, webFormNameOrganization/Lead:
+ webFormId, webFormNameCustom Object:
+ meetingId, kakaoAlimtalkId, emailLinkId(webFormId 없음)
삭제 API 패턴
모든 삭제는 동일한 패턴:
고객
POST /v2/people/delete
O (400)
body 파라미터 미공개
회사
POST /v2/organization/delete
O (400)
body 파라미터 미공개
딜
POST /v2/deal/delete
O (400)
body 파라미터 미공개
리드
POST /v2/lead/delete
O (400)
body 파라미터 미공개
커스텀 오브젝트
POST /v2/custom-object/delete
O (400)
body 파라미터 미공개
중요:
POST /v2/{resource}/{id}/delete(path에 ID) → 404. 작동하지 않음.DELETE /v2/{resource}/{id}→ 405"Invalid Request Method". REST 표준 방식 미지원.라우트 자체는 존재하지만 body 파라미터 형식이 공개되지 않아 사용 불가. → 개발팀 문의 필요
웹훅 (Webhook)
비즈니스: 세일즈맵에서 이벤트 발생 시 외부 시스템에 실시간 알림. 자동화 파이프라인의 트리거.
설정
세일즈맵 설정 > 웹훅에서 URL 등록 및 구독 이벤트 선택
타임아웃: 10초 이내 응답 필요
재시도: 실패 시 10분 간격, 최대 10회
서명 검증: 현재 미제공
페이로드
beforeField / afterField 형태
비어있음
null
null
암호화
"암호화된 데이터"
상수
True/False
boolean
true
날짜
string
"2024-04-16"
날짜(시간)
string
"2024-04-16 오전 07시 18분"
숫자
number
12000
텍스트 / 단일선택
string
"서울시 강남구"
복수 선택
string[]
["내과", "외과"]
관계(단일)
{id, name}
{"id": "<id>", "name": "이름"}
관계(복수)
[{id, name}]
[{"id": "<id>", "name": "이름"}]
파이프라인 단계 변경 시 afterField는 객체: {"id": "<stageId>", "name": "단계명"} → afterField.name으로 접근
eventId 동작
고객 생성 →
생성+수정웹훅이 동일 eventId고객 병합 →
삭제+병합웹훅이 동일 eventId
구독 가능한 이벤트
고객/회사/리드/딜: 생성, 수정, 삭제, 병합 커스텀 오브젝트: 생성, 수정, 삭제 (병합 없음)
핸들러 패턴
공통 에러
검증된 특수 에러:
베스트 프랙티스
요청 간격: 0.1~0.15초 (rate limit 방지)
배치 처리: 5개씩
Promise.allSettled웹훅 응답: 10초 내 200 응답, 처리는 비동기
중복 이벤트:
eventId + objectId로 감지회사 중복: 생성 실패 시 에러의
data.id로 기존 회사 활용필드명: 세일즈맵 UI의 한글 이름과 정확히 일치
URL 패턴: 히스토리/액티비티는 slash notation만 작동
시퀀스 ID:
_id사용 (id아님)Field API:
GET /v2/field/{type}으로 필드 정의 동적 조회딜 금액:
pricetop-level 파라미터로 전달 (fieldList 아님)이메일 조회: 액티비티에서
emailId확보 →GET /v2/email/{id}개별 조회시퀀스 분석: 목록 → step → enrollment → timeline 순서로 drill-down
Last updated
Was this helpful?