연락처 API 레퍼런스

고객사 서버에서 API 키로 주소록 연락처를 등록·수정·조회·대량 등록 (8개 엔드포인트)

참고인증
모든 Service API 요청에는 X-API-KEY 헤더를 포함해야 합니다. API Key는 콘솔 > 개발자 > API 키 관리에서 발급받으며, 조직별 허용 IP(화이트리스트)에서만 호출할 수 있습니다. Service API 이용에는 API_ACCESS 기능(PRO 이상 플랜)이 필요합니다. 공통 규칙은 API 개요를 참고하세요.
TIPSDK 방식과의 차이
브라우저·앱에 내장하는 Web/App SDK는 X-App-ID + X-Mobile-App-API-Key로 인증하며 identify()를 씁니다 (연락처 SDK 연동 가이드). 이 문서는 고객사 서버가 API 키로 직접 호출하는 방식으로, URL을 API로 생성하는 것과 동일한 인증 체계입니다. 두 경로 모두 같은 마스터 주소록에 저장됩니다.

POST /api/v1/service/messaging/contacts

연락처를 등록합니다. externalUserId가 있으면 같은 주소록 내에서 기존 연락처를 찾아 있으면 갱신(200), 없으면 생성(201)합니다. 전달한 필드만 반영되고 보내지 않은 필드는 기존 값이 유지됩니다. 새로 생성된 연락처의 출처는 origin = "API"로 기록됩니다.

Request Body

필드타입최대 길이설명
nameString100이름
phoneNumberString20전화번호 — 서버에서 정규화 후 AES-256 암호화 저장
emailString200이메일 — AES-256 암호화 저장
externalUserIdString200고객사 서비스의 회원 ID — upsert 기준 키
pushIdentifyString500앱푸시 식별자(핑거푸시 토큰)
pushTokenIdxLong-앱푸시 토큰 인덱스
localeString10언어/지역 코드 (예: ko, en)
pushOptInBoolean-앱푸시 수신동의
smsOptInBoolean-SMS 수신동의
emailOptInBoolean-이메일 수신동의
alimtalkOptInBoolean-알림톡 수신동의
pushAdOptInBoolean-앱푸시 광고 수신동의
smsAdOptInBoolean-SMS 광고 수신동의
emailAdOptInBoolean-이메일 광고 수신동의
alimtalkAdOptInBoolean-알림톡 광고 수신동의
nightAdOptInBoolean-야간 광고 수신동의
tagsString[]-태그 목록
customFieldsObject값 2000자등급·생일 등 임의 속성 — 세그먼트 custom.* 소스 (가이드). 값은 텍스트로 저장·반환(숫자·불리언도 문자열), 키는 연락처당 기본 50개까지·이름 최대 50자. 상한/길이 초과분은 오류 없이 무시·절삭. 기본값은 조직별 조정 가능
groupIdLong-주소록 그룹 ID — 지정 시 해당 주소록에 자동 배정. 미지정 시 기본 주소록

요청 예시

cURL
curl -X POST https://fplink.net/api/v1/service/messaging/contacts \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -d '{
    "externalUserId": "u1001",
    "name": "홍길동",
    "phoneNumber": "01012345678",
    "email": "gildong@example.com",
    "smsOptIn": true,
    "emailAdOptIn": true,
    "tags": ["vip", "seoul"],
    "customFields": { "grade": "gold", "birthday": "1990-07-26", "point": 15000 }
  }'

Response

생성 시 201 Created, 갱신 시 200 OK로 연락처 객체를 반환합니다(전화·이메일은 복호화되어 반환).

JSON
{
  "id": 90231,
  "name": "홍길동",
  "phoneNumber": "01012345678",
  "email": "gildong@example.com",
  "externalUserId": "u1001",
  "origin": "API",
  "smsOptIn": true,
  "emailAdOptIn": true,
  "tags": ["vip", "seoul"],
  "customFields": { "grade": "gold", "birthday": "1990-07-26", "point": "15000" }
}
참고웹훅 이벤트
등록·수정 시 contact.created / contact.updated 웹훅이, 모든 수신동의가 해제되면 contact.opt_out 웹훅이 발사됩니다. 자세한 내용은 웹훅 연동 가이드를 참고하세요.

POST /api/v1/service/messaging/contacts/bulk

여러 연락처를 한 번에 등록합니다. 요청 본문은 연락처 객체의 배열이며 최대 1000건까지 허용됩니다. 각 항목은 단건 API와 동일한 필드를 사용하고 externalUserId 기준으로 upsert됩니다.

Query Parameters

파라미터타입기본값설명
asyncBooleanfalsetrue면 즉시 jobId를 반환하고 백그라운드에서 처리
groupIdLong-전체 항목을 지정 주소록에 배정 (개별 항목의 groupId가 우선)

요청 예시

cURL
curl -X POST https://fplink.net/api/v1/service/messaging/contacts/bulk \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -d '[
    { "externalUserId": "u1001", "name": "홍길동", "smsOptIn": true },
    { "externalUserId": "u1002", "name": "김철수", "smsOptIn": false }
  ]'

Response

JSON
{ "created": 1, "updated": 1, "failed": 0 }
TIP대량 건은 비동기 권장
건수가 많으면 ?async=true로 호출하세요. 202 Accepted와 함께 jobId가 반환되며, GET /api/v1/service/messaging/contacts/bulk-jobs/{jobId}로 진행 상황을 조회할 수 있습니다.

PUT /api/v1/service/messaging/contacts/{id}

지정 연락처를 수정합니다. 단건 등록과 동일한 필드를 사용하며 전달한 필드만 반영됩니다. 대상이 없으면 404를 반환합니다.

cURL
curl -X PUT https://fplink.net/api/v1/service/messaging/contacts/90231 \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -d '{ "smsAdOptIn": false, "customFields": { "grade": "vip" } }'

DELETE /api/v1/service/messaging/contacts/{id}

연락처를 비활성화(soft delete)합니다. 성공 시 204 No Content를 반환합니다.

cURL
curl -X DELETE https://fplink.net/api/v1/service/messaging/contacts/90231 \
  -H "X-API-KEY: your-api-key"

GET /api/v1/service/messaging/contacts

연락처 목록을 조회합니다. 필터·페이징을 지원합니다.

파라미터타입설명
keywordString이름·전화·이메일 검색어
originString출처 필터 (예: API, SDK)
pushOptIn / smsOptIn / emailOptInBoolean수신동의 필터
page / sizeInteger페이지 번호(0부터) / 페이지 크기
cURL
curl "https://fplink.net/api/v1/service/messaging/contacts?keyword=홍길동&smsOptIn=true&page=0&size=20" \
  -H "X-API-KEY: your-api-key"

GET /api/v1/service/messaging/contacts/{id}

ID로 연락처 단건을 조회합니다. 대상이 없으면 404를 반환합니다.

GET /api/v1/service/messaging/contacts/by-phone

전화번호로 연락처를 조회합니다.

cURL
curl "https://fplink.net/api/v1/service/messaging/contacts/by-phone?phone=01012345678" \
  -H "X-API-KEY: your-api-key"

GET /api/v1/service/messaging/contacts/by-email

이메일로 연락처를 조회합니다.

cURL
curl "https://fplink.net/api/v1/service/messaging/contacts/by-email?email=gildong@example.com" \
  -H "X-API-KEY: your-api-key"
참고주소록(그룹)과 세그먼트
주소록 그룹 관리(/api/v1/service/messaging/groups)와 멤버 배정 API도 함께 제공됩니다. 이 API로 등록한 customFields는 콘솔 세그먼트 조건의 custom.* 소스로 즉시 사용됩니다.