연락처 생성

POST/contacts

연락처를 생성한다.

연락처에 메일 주소 또는 전화번호 둘 중 한 가지 정보는 반드시 있어야 한다. 연락처 접근 가능 범위가 MEMBER라면 접근 가능한 구성원 정보가 반드시 있어야 한다. 연락처 이름 정보에 성과 이름 둘 중 한 가지 정보는 반드시 있어야 한다.

Authorization

oauth2

Authorization Code OAuth Flow

Authorization URL - https://auth.worksmobile.com/oauth2/v2.0/authorize
Token URL - https://auth.worksmobile.com/oauth2/v2.0/token
Refresh URL - https://auth.worksmobile.com/oauth2/v2.0/token

Scope

contact

HTTP Request

POSThttps://www.worksapis.com/v1.0/contacts

Header Parameters

HeadertypeDescription
Authorizationstring

Bearer {token}


required
Content-Typestring

application/json


required
example : application/json

Request Body

PropertyTypeDescription
permissionobject (permission)

연락처 접근 권한 모델


required
contactNameobject (contactName)

연락처 이름 정보


required
emailsarray (ContactEmail)

연락처 메일 목록


minItems : 0
maxItems : 100
telephonesarray (ContactTelephone)

연락처 전화 목록


minItems : 0
maxItems : 100
organizationsarray (ContactOrganization)

연락처 회사/소속 목록


minItems : 0
maxItems : 100
eventsarray (ContactEvent)

연락처 이벤트 목록


minItems : 0
maxItems : 100
locationsarray (ContactLocation)

연락처 주소 목록


minItems : 0
maxItems : 100
messengersarray (ContactMessenger)

연락처 메신저 정보


minItems : 0
maxItems : 100
websitesarray (ContactWebsite)

연락처 웹사이트 목록


minItems : 0
maxItems : 100
memostring

연락처 메모


maxLength : 4000
contactTagIdsarray (string)

연결된 태그 목록


minItems : 0

permission

PropertyTypeDescription
accessibleRangestring

연락처 접근 가능 범위

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

required
Allowed values : ALL, MEMBER
masterUserIdstring

연락처 마스터 구성원 ID

  • accessibleRange : MEMBER 인 경우 필수
isCoEditingboolean

공동 편집 여부.

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

default : true
accessibleMembersarray (ContactAccessibleMember)

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

  • accessibleRange가 MEMBER인 경우 필수

minItems : 0
maxItems : 500
uniqueItems : true

ContactAccessibleMember

PropertyTypeDescription
idstring

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


required
typestring

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

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

required
Allowed values : USER, ORGUNIT, GROUP

contactName

PropertyTypeDescription
firstNamestring

이름


maxLength : 100
nullable : true
lastNamestring

성


maxLength : 100
nullable : true
phoneticFirstNamestring

후리가나 이름


maxLength : 100
nullable : true
phoneticLastNamestring

후리가나 성


maxLength : 100
nullable : true
nickNamestring

닉네임


maxLength : 100
nullable : true
prefixstring

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


maxLength : 100
nullable : true
suffixstring

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


maxLength : 100
nullable : true
middleNamestring

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


maxLength : 100
nullable : true

ContactEmail

PropertyTypeDescription
primaryboolean

대표 메일 여부

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

required
emailstring

메일 주소


required
maxLength : 256

ContactTelephone

PropertyTypeDescription
primaryboolean

대표 전화 여부

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

required
telephonestring

전화번호


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

연락처 전화번호 타입

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

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

직접 입력할 전화번호 타입

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

maxLength : 100
nullable : true

ContactOrganization

PropertyTypeDescription
primaryboolean

대표 회사 여부

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

required
namestring

회사명


maxLength : 100
departmentstring

부서명


maxLength : 100
titlestring

직책명


maxLength : 100

ContactEvent

PropertyTypeDescription
primaryboolean

대표 이벤트 여부

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

required
datestring

날짜(YYYY-MM-DD)


required
typestring

연락처 이벤트 타입

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

default : CUSTOM
Allowed values : BIRTHDAY, ANNIVERSARY, OTHER, CUSTOM
customTypestring

직접 입력할 이벤트 타입


maxLength : 100
nullable : true
dayTypestring

날짜 타입


default : SOLAR
Allowed values : SOLAR, LUNAR

ContactLocation

PropertyTypeDescription
primaryboolean

대표 주소 여부

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

required
addressstring

주소


required
maxLength : 100
typestring

연락처 주소 타입

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

default : CUSTOM
Allowed values : WORK, HOME, OTHER, CUSTOM
zipCodestring

우편번호


maxLength : 100
customTypestring

직접 입력할 주소 타입


maxLength : 100
nullable : true

ContactMessenger

PropertyTypeDescription
primaryboolean

대표 메신저 여부

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

required
idstring

메신저 ID


required
maxLength : 100
typestring

연락처 메신저 타입

  • FACEBOOK: Facebook
  • LINE: LINE
  • TWITTER:Twitter
  • CUSTOM: 직접 입력

default : CUSTOM
Allowed values : FACEBOOK, LINE, TWITTER, CUSTOM
customTypestring

직접 입력할 메신저 타입


maxLength : 100
nullable : true

ContactWebsite

PropertyTypeDescription
primaryboolean

대표 웹사이트 여부

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

required
urlstring

웹사이트 URL


required
maxLength : 100

Request Example

example

1{
2  "contactTagIds": [
3    "ctag2a81-94b6-4642-6903-03aa7977da91",
4    "3512644d-a731-4602-6912-031febc8bce2"
5  ],
6  "permission": {
7    "masterUserId": "userf7da-f82c-4284-13e7-030f3b4c756x",
8    "isCoEditing": true,
9    "accessibleRange": "ALL"
10  },
11  "createdTime": "2021-08-10T11:05:41+09:00",
12  "modifiedTime": "2021-08-10T11:09:37+09:00",
13  "contactName": {
14    "lastName": "홍",
15    "firstName": "길동",
16    "nickName": "HONG"
17  },
18  "emails": [
19    {
20      "email": "example1@example.com",
21      "primary": true
22    },
23    {
24      "email": "example2@example.com",
25      "primary": false
26    }
27  ],
28  "telephones": [
29    {
30      "type": "CELLPHONE",
31      "telephone": "0000-0001",
32      "primary": true
33    },
34    {
35      "type": "HOME",
36      "telephone": "0000-0002",
37      "primary": false
38    }
39  ],
40  "organizations": [
41    {
42      "name": "exmample company name",
43      "department": "department",
44      "title": "title",
45      "primary": true
46    }
47  ],
48  "locations": [
49    {
50      "address": "example1 address",
51      "zipCode": "00001",
52      "type": "WORK",
53      "primary": true
54    },
55    {
56      "address": "example2 address",
57      "zipCode": "00002",
58      "type": "HOME",
59      "primary": false
60    }
61  ],
62  "events": [
63    {
64      "date": "2021-01-09",
65      "dayType": "SOLAR",
66      "type": "BIRTHDAY",
67      "primary": true
68    },
69    {
70      "date": "2021-08-09",
71      "dayType": "SOLAR",
72      "type": "ANNIVERSARY",
73      "primary": false
74    }
75  ],
76  "messengers": [
77    {
78      "id": "example1",
79      "type": "LINE",
80      "primary": true
81    },
82    {
83      "id": "example2",
84      "type": "CUSTOM",
85      "customType": "Worksmobile",
86      "primary": false
87    }
88  ],
89  "websites": [
90    {
91      "url": "https://example1.com",
92      "primary": true
93    },
94    {
95      "url": "https://example2.com",
96      "primary": false
97    }
98  ],
99  "memo": "memo"
100}

Response

HTTP 201

OK

PropertyTypeDescription
contactIdstring

고객/거래처 연락처 ID


readOnly : true
permissionobject (permission)

연락처 접근 권한 모델


required
contactNameobject (contactName)

연락처 이름 정보


required
linkedExternalUserobject (linkedExternalUser)

연락처 외부 대화 상대 정보


readOnly : true
emailsarray (ContactEmail)

연락처 메일 목록


minItems : 0
maxItems : 100
telephonesarray (ContactTelephone)

연락처 전화 목록


minItems : 0
maxItems : 100
organizationsarray (ContactOrganization)

연락처 회사/소속 목록


minItems : 0
maxItems : 100
eventsarray (ContactEvent)

연락처 이벤트 목록


minItems : 0
maxItems : 100
locationsarray (ContactLocation)

연락처 주소 목록


minItems : 0
maxItems : 100
messengersarray (ContactMessenger)

연락처 메신저 정보


minItems : 0
maxItems : 100
websitesarray (ContactWebsite)

연락처 웹사이트 목록


minItems : 0
maxItems : 100
memostring

연락처 메모


maxLength : 4000
contactTagIdsarray (string)

연결된 태그 목록


minItems : 0
createdTimestring

연락처 생성 시간

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

readOnly : true
modifiedTimestring

연락처 수정 시간

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

readOnly : true

permission

PropertyTypeDescription
accessibleRangestring

연락처 접근 가능 범위

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

required
Allowed values : ALL, MEMBER
masterUserIdstring

연락처 마스터 구성원 ID

  • accessibleRange : MEMBER 인 경우 필수
isCoEditingboolean

공동 편집 여부.

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

default : true
accessibleMembersarray (ContactAccessibleMember)

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

  • accessibleRange가 MEMBER인 경우 필수

minItems : 0
maxItems : 500
uniqueItems : true

ContactAccessibleMember

PropertyTypeDescription
idstring

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


required
typestring

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

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

required
Allowed values : USER, ORGUNIT, GROUP

contactName

PropertyTypeDescription
firstNamestring

이름


maxLength : 100
nullable : true
lastNamestring

성


maxLength : 100
nullable : true
phoneticFirstNamestring

후리가나 이름


maxLength : 100
nullable : true
phoneticLastNamestring

후리가나 성


maxLength : 100
nullable : true
nickNamestring

닉네임


maxLength : 100
nullable : true
prefixstring

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


maxLength : 100
nullable : true
suffixstring

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


maxLength : 100
nullable : true
middleNamestring

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


maxLength : 100
nullable : true

linkedExternalUser

PropertyTypeDescription
idstring

외부 대화 상대 ID

typestring

외부 대화 상대 타입

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

Allowed values : LINE, WORKS
readOnly : true
buddyUserIdsarray (string)

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

ContactEmail

PropertyTypeDescription
primaryboolean

대표 메일 여부

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

required
emailstring

메일 주소


required
maxLength : 256

ContactTelephone

PropertyTypeDescription
primaryboolean

대표 전화 여부

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

required
telephonestring

전화번호


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

연락처 전화번호 타입

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

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

직접 입력할 전화번호 타입

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

maxLength : 100
nullable : true

ContactOrganization

PropertyTypeDescription
primaryboolean

대표 회사 여부

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

required
namestring

회사명


maxLength : 100
departmentstring

부서명


maxLength : 100
titlestring

직책명


maxLength : 100

ContactEvent

PropertyTypeDescription
primaryboolean

대표 이벤트 여부

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

required
datestring

날짜(YYYY-MM-DD)


required
typestring

연락처 이벤트 타입

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

default : CUSTOM
Allowed values : BIRTHDAY, ANNIVERSARY, OTHER, CUSTOM
customTypestring

직접 입력할 이벤트 타입


maxLength : 100
nullable : true
dayTypestring

날짜 타입


default : SOLAR
Allowed values : SOLAR, LUNAR

ContactLocation

PropertyTypeDescription
primaryboolean

대표 주소 여부

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

required
addressstring

주소


required
maxLength : 100
typestring

연락처 주소 타입

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

default : CUSTOM
Allowed values : WORK, HOME, OTHER, CUSTOM
zipCodestring

우편번호


maxLength : 100
customTypestring

직접 입력할 주소 타입


maxLength : 100
nullable : true

ContactMessenger

PropertyTypeDescription
primaryboolean

대표 메신저 여부

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

required
idstring

메신저 ID


required
maxLength : 100
typestring

연락처 메신저 타입

  • FACEBOOK: Facebook
  • LINE: LINE
  • TWITTER:Twitter
  • CUSTOM: 직접 입력

default : CUSTOM
Allowed values : FACEBOOK, LINE, TWITTER, CUSTOM
customTypestring

직접 입력할 메신저 타입


maxLength : 100
nullable : true

ContactWebsite

PropertyTypeDescription
primaryboolean

대표 웹사이트 여부

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

required
urlstring

웹사이트 URL


required
maxLength : 100

Response Example

example

1{
2  "contactId": "contact2-a56d-44a4-5304-033e16fca8d1",
3  "contactTagIds": [
4    "ctag2a81-94b6-4642-6903-03aa7977da91",
5    "3512644d-a731-4602-6912-031febc8bce2"
6  ],
7  "permission": {
8    "masterUserId": "userf7da-f82c-4284-13e7-030f3b4c756x",
9    "isCoEditing": true,
10    "accessibleRange": "ALL",
11    "accessibleMembers": []
12  },
13  "createdTime": "2021-08-10T11:05:41+09:00",
14  "modifiedTime": "2021-08-10T11:09:37+09:00",
15  "contactName": {
16    "lastName": "홍",
17    "firstName": "길동",
18    "nickName": "HONG",
19    "phoneticFirstName": null,
20    "phoneticLastName": null,
21    "prefix": null,
22    "suffix": null,
23    "middleName": null
24  },
25  "linkedExternalUser": {
26    "id": "works75b-5b29-4048-4bf5-0336e504a395",
27    "type": "WORKS",
28    "buddyUserIds": [
29      "userf7da-f82c-4284-13e7-030f3b4c756x"
30    ]
31  },
32  "emails": [
33    {
34      "email": "example1@example.com",
35      "primary": true
36    },
37    {
38      "email": "example2@example.com",
39      "primary": false
40    }
41  ],
42  "telephones": [
43    {
44      "type": "CELLPHONE",
45      "telephone": "0000-0001",
46      "primary": true,
47      "customType": null
48    },
49    {
50      "type": "HOME",
51      "telephone": "0000-0002",
52      "primary": false,
53      "customType": null
54    }
55  ],
56  "organizations": [
57    {
58      "name": "exmample company name",
59      "department": "department",
60      "title": "title",
61      "primary": true
62    }
63  ],
64  "locations": [
65    {
66      "address": "example1 address",
67      "zipCode": "00001",
68      "type": "WORK",
69      "primary": true,
70      "customType": null
71    },
72    {
73      "address": "example2 address",
74      "zipCode": "00002",
75      "type": "HOME",
76      "primary": false,
77      "customType": null
78    }
79  ],
80  "events": [
81    {
82      "date": "2021-01-09",
83      "dayType": "SOLAR",
84      "type": "BIRTHDAY",
85      "primary": true,
86      "customType": null
87    },
88    {
89      "date": "2021-08-09",
90      "dayType": "SOLAR",
91      "type": "ANNIVERSARY",
92      "primary": false,
93      "customType": null
94    }
95  ],
96  "messengers": [
97    {
98      "id": "example1",
99      "type": "LINE",
100      "primary": true,
101      "customType": null
102    },
103    {
104      "id": "example2",
105      "type": "CUSTOM",
106      "customType": "Worksmobile",
107      "primary": false
108    }
109  ],
110  "websites": [
111    {
112      "url": "https://example1.com",
113      "primary": true
114    },
115    {
116      "url": "https://example2.com",
117      "primary": false
118    }
119  ],
120  "memo": "memo"
121}

HTTP 400

Bad Request

HTTP 403

Forbidden