GET/users/{userId}/contacts

구성원이 접근할 수 있는 연락처 목록을 조회한다.

조회 결과는 5만 건까지 조회할 수 있다 조회 결과가 5만 건을 초과하면 생성 일시 또는 수정 일시를 지정해 검색 범위를 조정할 수 있다. 시작 일시와 종료 일시를 지정해 최대 7일 동안의 데이터를 조회할 수 있다.

Authorization

oauth2

OAuth 2.0 인증.
자세한 인증 방식은 인가·인증을 참고한다.

Scope

contact
contact.read

HTTP Request

GEThttps://www.worksapis.com/v1.0/users/{userId}/contacts

Path Parameters

ParameterTypeDescription
userId string 

구성원 ID


required
example : userf7da-f82c-4284-13e7-030f3b4c756x 

Query Parameters

ParameterTypeDescription
count integer 

한 번에 가져오는 데이터 크기


default : 100
minimum : 1
maximum : 500
example : 100
format : int32 
cursor string 

커서


example : JlIBsfJogXpzDGY8OscZziqZpYqCAu3RbZbaFzBb1od6lWQtSdPUd2FIdCuaGgu8DA== 
searchDateType string 

조회 날짜 타입. startDateTime, endDateTime이 조건으로 존재하는 경우 필수.


Allowed values : CREATED_TIME, MODIFIED_TIME
example : CREATED_TIME 
startDateTime string 

시작 일시 - 날짜, 시간, 분, 초 형식(YYYY-MM-DDThh:mm:ssTZD) 「+」는 「%2B」로 인코딩해야 한다.


example : 2021-06-03T10:00:00.000%2B09:00 
endDateTime string 

종료 일시 - 날짜, 시간, 분, 초 형식(YYYY-MM-DDThh:mm:ssTZD) 「+」는 「%2B」로 인코딩해야 한다.


example : 2021-06-03T11:00:00.000%2B09:00 
accessibleRange string 

연락처 접근 가능 범위


Allowed values : ALL, MEMBER
example : ALL 
contactTagId string 

태그 ID


example : ctag2a81-94b6-4642-6903-03aa7977da91 
email string 

이메일 주소. 「@」는 「%40」으로 인코딩해야 하며 부분 일치로 검색된다.

  • 이메일이 여러 개 등록된 연락처의 경우 대표로 설정된 이메일만 검색 대상이 된다.
  • 「@」가 포함되지 않은 키워드는 이메일의 로컬 파트(「@」 앞부분)에서만 부분 일치로 검색된다.
  • 「@」가 포함된 키워드는 전방 일치로 검색된다.

maxLength : 256
example : example%40example.com
nullable : true 
telephone string 

전화번호. 4자리 이상의 숫자만 유효하며 부분 일치로 검색된다.


maxLength : 100
example : 012345678
nullable : true 
searchFilterType string 

검색 필터링 타입. - LINKED_EXTERNAL_USER: 외부 대화 상대 연락처만 노출


Allowed values : LINKED_EXTERNAL_USER
example : LINKED_EXTERNAL_USER 
orderBy string 

정렬 대상: name, createdTime, modifiedTime. 정렬 순서: asc(기본값), desc. 정렬 대상과 순서는 공백으로 구분한다(separator: %20).


example : name%20asc 

Header Parameters

HeadertypeDescription
Authorization string 

Bearer {token}


required 

Response

HTTP 200

연락처 목록 조회 시 응답

PropertyTypeDescription
contacts array (Contact) 

연락처 정보

 
responseMetaData object (responseMetaData) 

페이지 매김 정보

 

Contact

PropertyTypeDescription
contactId string 

고객/거래처 연락처 ID


readOnly : true 
permission object (permission) 

연락처 접근 권한 모델


required 
contactName object (contactName) 

연락처 이름 정보


required 
linkedExternalUser object (linkedExternalUser) 

연락처 외부 대화 상대 정보


readOnly : true 
emails array (ContactEmail) 

연락처 메일 목록


minItems : 0
maxItems : 100 
telephones array (ContactTelephone) 

연락처 전화 목록


minItems : 0
maxItems : 100 
organizations array (ContactOrganization) 

연락처 회사/소속 목록


minItems : 0
maxItems : 100 
events array (ContactEvent) 

연락처 이벤트 목록


minItems : 0
maxItems : 100 
locations array (ContactLocation) 

연락처 주소 목록


minItems : 0
maxItems : 100 
messengers array (ContactMessenger) 

연락처 메신저 정보


minItems : 0
maxItems : 100 
websites array (ContactWebsite) 

연락처 웹사이트 목록


minItems : 0
maxItems : 100 
memo string 

연락처 메모


maxLength : 4000 
contactTagIds array (string) 

연결된 태그 목록


minItems : 0 
customProperties object (customProperties) 

연락처 커스텀 속성.

연락처 커스텀 속성 추가 API를 이용해 먼저 추가해야 한다.

customProperties의 key는 연락처 커스텀 필드 추가 API에서 설정한 propertyName의 값으로, 변수이다.
customProperties의 value는 해당 필드의 propertyType과 multiValued 설정에 따라 타입이 달라진다(자세한 내용은 CustomProperties 타입별 설명 참고). 또한, customProperties는 여러 커스텀 속성의 값을 함께 설정할 수 있다.

 
createdTime string 

연락처 생성 시간

  • 날짜 및 시간, 분, 초 형식(YYYY-MM-DDThh:mm:ssTZD)

readOnly : true 
modifiedTime string 

연락처 수정 시간

  • 날짜 및 시간, 분, 초 형식(YYYY-MM-DDThh:mm:ssTZD)

readOnly : true 

permission

PropertyTypeDescription
accessibleRange string 

연락처 접근 가능 범위

  • ALL: 도메인 전체 구성원이 접근 가능하다.
  • MEMBER: 특정 멤버만 접근 가능하게 할 수 있다. accessibleMembers에서 설정 할 수 있다.

required
Allowed values : ALL, MEMBER 
masterUserId string 

연락처 마스터 구성원 ID

  • accessibleRange : MEMBER 인 경우 필수
 
isCoEditing boolean 

공동 편집 여부.

  • false인 경우 마스터만 편집 가능.

default : true 
accessibleMembers array (ContactAccessibleMember) 

연락처에 접근 가능한 구성원(구성원, 조직, 그룹의 ID)

  • accessibleRange가 MEMBER인 경우 필수

minItems : 0
maxItems : 500
uniqueItems : true 

ContactAccessibleMember

PropertyTypeDescription
id string 

연락처에 접근 가능한 구성원의 ID


required 
type string 

연락처에 접근 가능한 구성원 타입

  • USER: 구성원
  • ORGUNIT: 조직
  • GROUP: 그룹

required
Allowed values : USER, ORGUNIT, GROUP 

contactName

PropertyTypeDescription
firstName string 

이름


maxLength : 100
nullable : true 
lastName string 

성


maxLength : 100
nullable : true 
phoneticFirstName string 

후리가나 이름


maxLength : 100
nullable : true 
phoneticLastName string 

후리가나 성


maxLength : 100
nullable : true 
nickName string 

닉네임


maxLength : 100
nullable : true 
prefix string 

경칭. "연락처 정보 조회"에서만 표시됨.


maxLength : 100
nullable : true 
suffix string 

호칭. "연락처 정보 조회"에서만 표시됨.


maxLength : 100
nullable : true 
middleName string 

중간 이름. "연락처 정보 조회"에서만 표시됨.


maxLength : 100
nullable : true 

linkedExternalUser

PropertyTypeDescription
id string 

외부 대화 상대 ID

 
type string 

외부 대화 상대 타입

  • LINE: LINE 대화 상대
  • WORKS: 다른 도메인의 외부 대화 상대

Allowed values : LINE, WORKS
readOnly : true 
buddyUserIds array (string) 

외부 대화 상대를 연락처에 추가한 구성원 ID 목록

 

ContactEmail

PropertyTypeDescription
primary boolean 

대표 메일 여부

  • 목록 내 반드시 하나의 대표가 지정되어 있어야 함.
  • 대표를 설정하지 않으면 자동으로 첫 번째 값이 대표로 지정된다.

required 
email string 

메일 주소


required
maxLength : 256 

ContactTelephone

PropertyTypeDescription
primary boolean 

대표 전화 여부

  • 목록 내 반드시 하나의 대표가 지정되어 있어야 함.
  • 대표를 설정하지 않으면 자동으로 첫 번째 값이 대표로 지정된다.

required 
telephone string 

전화번호


required
pattern : [0-9\+\-*#PTpt()\u3000 ]+ 
type string 

연락처 전화번호 타입

  • CELLPHONE: 휴대폰
  • WORK: 회사
  • HOME: 집
  • WORK_FAX: 회사 팩스
  • HOME_FAX: 집 팩스
  • OTHER: 기타
  • CUSTOM: 직접 입력

default : CUSTOM
Allowed values : CELLPHONE, WORK, HOME, WORK_FAX, HOME_FAX, OTHER, CUSTOM 
customType string 

직접 입력할 전화번호 타입

  • 전화번호 타입이 CUSTOM인 경우 입력 가능

maxLength : 100
nullable : true 

ContactOrganization

PropertyTypeDescription
primary boolean 

대표 회사 여부

  • 목록 내 반드시 하나의 대표가 지정되어 있어야 함.
  • 대표를 설정하지 않으면 자동으로 첫 번째 값이 대표로 지정됨.

required 
name string 

회사명


maxLength : 100 
department string 

부서명


maxLength : 100 
title string 

직책명


maxLength : 100 

ContactEvent

PropertyTypeDescription
primary boolean 

대표 이벤트 여부

  • 목록 내 반드시 하나의 대표가 지정되어 있어야 함.
  • 대표를 설정하지 않으면 자동으로 첫 번째 값이 대표로 지정됨.

required 
date string 

날짜(YYYY-MM-DD)


required 
type string 

연락처 이벤트 타입

  • BIRTHDAY: 생일
  • ANNIVERSARY: 기념일
  • OTHER: 기타
  • CUSTOM: 직접 입력

default : CUSTOM
Allowed values : BIRTHDAY, ANNIVERSARY, OTHER, CUSTOM 
customType string 

직접 입력할 이벤트 타입


maxLength : 100
nullable : true 
dayType string 

날짜 타입


default : SOLAR
Allowed values : SOLAR, LUNAR 

ContactLocation

PropertyTypeDescription
primary boolean 

대표 주소 여부

  • 목록 내 반드시 하나의 대표가 지정되어 있어야 함.
  • 대표를 설정하지 않으면 자동으로 첫 번째 값이 대표로 지정됨.

required 
address string 

주소


required
maxLength : 100 
type string 

연락처 주소 타입

  • WORK: 회사
  • HOME: 집
  • OTHER: 기타
  • CUSTOM: 직접 입력

default : CUSTOM
Allowed values : WORK, HOME, OTHER, CUSTOM 
zipCode string 

우편번호


maxLength : 100 
customType string 

직접 입력할 주소 타입


maxLength : 100
nullable : true 

ContactMessenger

PropertyTypeDescription
primary boolean 

대표 메신저 여부

  • 목록 내 반드시 하나의 대표가 지정되어 있어야 함.
  • 대표를 설정하지 않으면 자동으로 첫 번째 값이 대표로 지정됨.

required 
id string 

메신저 ID


required
maxLength : 100 
type string 

연락처 메신저 타입

  • X는 Response Body에서 TWITTER로 반환합니다.
  • 2026년 7월말부터 TWITTER, X 모두 Response Body에서 X로 반환할 예정입니다.
  • 2026년 11월 중순부터 TWITTER는 제거될 예정입니다.
  • FACEBOOK: Facebook
  • LINE: LINE
  • TWITTER: X(트위터)
  • X: X(트위터)
  • CUSTOM: 직접 입력

default : CUSTOM
Allowed values : FACEBOOK, LINE, TWITTER, X, CUSTOM 
customType string 

직접 입력할 메신저 타입


maxLength : 100
nullable : true 

ContactWebsite

PropertyTypeDescription
primary boolean 

대표 웹사이트 여부

  • 목록 내 반드시 하나의 대표가 지정되어 있어야 함.
  • 대표를 설정하지 않으면 자동으로 첫 번째 값이 대표로 지정됨.

required 
url string 

웹사이트 URL


required
maxLength : 100 

customProperties

PropertyTypeDescription
propertyName object (propertyName) 

propertyType이 STRING이고 multiValued가 false일 때

  • content는 해당 속성의 값을 의미한다.
 
array (CustomPropertyStringMulti) 

propertyType이 STRING이고 multiValued가 true일 때

  • content는 해당 속성의 값, represent는 대표 여부를 의미한다.
  • represent 값을 지정하지 않는 경우 첫 번째 항목이 대표가 된다.

maxItems : 10 
object (CustomPropertyLinkSingle) 

propertyType이 LINK이고 multiValued가 false일 때

  • link는 반드시 입력해야 한다.
  • link는 유효한 URL 형식이어야 한다.
  • text와 link가 모두 존재하여 text가 'Homepage1'이고 link가 'https://www.unicef.org'일 때 다음과 같다.
    <a href = "https://www.unicef.org">Homepage1</a>
  • text는 없고 link만 있으면 link가 노출 텍스트가 된다.
 
array (CustomPropertyLinkMulti) 

propertyType이 LINK이고 multiValued가 true일 때

  • link는 반드시 입력해야 한다.
  • link는 유효한 URL 형식이어야 한다.
  • text와 link가 모두 존재하여 text가 'Homepage1'이고 link가 'https://www.unicef.org'일 때 다음과 같다.
    <a href = "https://www.unicef.org">Homepage1</a>
  • text는 없고 link만 있으면 link가 노출 텍스트가 된다.
  • represent 값을 지정하지 않는 경우 첫 번째 항목이 대표가 된다.

maxItems : 10 

propertyName

PropertyTypeDescription
content string 

propertyType이 STRING일 때 값


maxLength : 100 

CustomPropertyStringMulti

PropertyTypeDescription
content string 

propertyType이 STRING일 때 값


maxLength : 100 
represent boolean 

대표 여부. multiValued가 true일 때 represent가 true인 값이 목록의 제일 앞에 노출된다.

 

CustomPropertyLinkSingle

PropertyTypeDescription
text string 

텍스트


maxLength : 100
nullable : true 
link string 

URL


maxLength : 300 

CustomPropertyLinkMulti

PropertyTypeDescription
text string 

텍스트


maxLength : 100
nullable : true 
link string 

URL


maxLength : 300 
represent boolean 

대표 여부. multiValued가 true일 때 represent가 true인 값이 목록의 제일 앞에 노출된다.

 

responseMetaData

PropertyTypeDescription
nextCursor string 

다음 페이지 조회를 위한 커서

 

Response Example

example

1{2  "contacts": [3    {4      "contactId": "contact2-a56d-44a4-5304-033e16fca8d1",5      "permission": {6        "masterUserId": "userf7da-f82c-4284-13e7-030f3b4c756x",7        "isCoEditing": true,8        "accessibleRange": "ALL",9        "accessibleMembers": []10      },11      "contactName": {12        "lastName": "홍",13        "firstName": "길동",14        "nickName": "HONG",15        "phoneticFirstName": null,16        "phoneticLastName": null,17        "prefix": null,18        "suffix": null,19        "middleName": null20      },21      "linkedExternalUser": {22        "id": "works75b-5b29-4048-4bf5-0336e504a395",23        "type": "WORKS",24        "buddyUserIds": [25          "userf7da-f82c-4284-13e7-030f3b4c756x"26        ]27      },28      "emails": [29        {30          "primary": true,31          "email": "example3@example.com"32        },33        {34          "primary": false,35          "email": "example4@example.com"36        }37      ],38      "telephones": [39        {40          "primary": true,41          "telephone": "0000-0001",42          "type": "CELLPHONE",43          "customType": null44        },45        {46          "primary": false,47          "telephone": "0000-0002",48          "type": "HOME",49          "customType": null50        }51      ],52      "organizations": [53        {54          "primary": true,55          "name": "example company name",56          "department": "department",57          "title": "title"58        }59      ],60      "locations": [61        {62          "primary": true,63          "address": "example1 address",64          "type": "WORK",65          "zipCode": "00001",66          "customType": null67        },68        {69          "primary": false,70          "address": "example2 address",71          "type": "HOME",72          "zipCode": "00002",73          "customType": null74        }75      ],76      "events": [77        {78          "primary": true,79          "date": "2021-01-09",80          "type": "BIRTHDAY",81          "dayType": "SOLAR",82          "customType": null83        },84        {85          "primary": false,86          "date": "2021-08-09",87          "type": "ANNIVERSARY",88          "dayType": "SOLAR",89          "customType": null90        }91      ],92      "messengers": [93        {94          "primary": true,95          "id": "example1",96          "type": "LINE",97          "customType": null98        },99        {100          "primary": false,101          "id": "example2",102          "type": "CUSTOM",103          "customType": "Worksmobile"104        }105      ],106      "websites": [107        {108          "primary": true,109          "url": "https://example1.com"110        },111        {112          "primary": false,113          "url": "https://example2.com"114        }115      ],116      "memo": "memo",117      "contactTagIds": [118        "ctag2a81-94b6-4642-6903-03aa7977da91",119        "3512644d-a731-4602-6912-031febc8bce2"120      ],121      "customProperties": {122        "string_single": {123          "content": "ext_id"124        },125        "string_multi": [126          {127            "content": "ext_id",128            "represent": true129          },130          {131            "content": "connect",132            "represent": false133          }134        ],135        "link_single": {136          "text": "worksmobile",137          "link": "https://contact.worksmobile.com"138        },139        "link_multi": [140          {141            "text": "worksmobile",142            "link": "https://contact.worksmobile.com",143            "represent": true144          },145          {146            "text": "line",147            "link": "https://www.line.me/",148            "represent": false149          }150        ]151      },152      "createdTime": "2021-08-10T11:05:41+09:00",153      "modifiedTime": "2021-08-10T11:09:37+09:00"154    }155  ],156  "responseMetaData": {157    "nextCursor": "JlIBsfJogXpzDGY8OscZziqZpYqCAu3RbZbaFzBb1od6lWQtSdPUd2FIdCuaGgu8DA=="158  }159}

HTTP 400

Bad Request