PUT/contacts/{contactId}

Updates contact information.

A contact must contain either an email address or a phone number. Note that it is OK for an external message contact to contain neither of them.

If accessibleRange is MEMBER, accessibleMembers is required.

ContactName must contain either firstName or lastName.

You cannot update the nickname of an external contact.

Authorization

oauth2

OAuth 2.0 authentication.
For more information, see Authentication and Authorization.

Scope

contact

HTTP Request

PUThttps://www.worksapis.com/v1.0/contacts/{contactId}

Path Parameters

ParameterTypeDescription
contactId string 

Customer/client contact ID


required
example : contact2-a56d-44a4-5304-033e16fca8d1 

Header Parameters

HeadertypeDescription
Authorization string 

Bearer {token}


required 
Content-Type string 

application/json


required
example : application/json 

Request Body

PropertyTypeDescription
permission object (permission) 

Contact access permission model


required 
contactName object (contactName) 

Contact name


required 
emails array (ContactEmail) 

List of email addresses


minItems : 0
maxItems : 100 
telephones array (ContactTelephone) 

List of phone numbers


minItems : 0
maxItems : 100 
organizations array (ContactOrganization) 

List of organizations


minItems : 0
maxItems : 100 
events array (ContactEvent) 

List of contact events


minItems : 0
maxItems : 100 
locations array (ContactLocation) 

List of addresses


minItems : 0
maxItems : 100 
messengers array (ContactMessenger) 

Messenger information


minItems : 0
maxItems : 100 
websites array (ContactWebsite) 

List of websites


minItems : 0
maxItems : 100 
memo string 

Memo


maxLength : 4000 
contactTagIds array (string) 

List of tags


minItems : 0 
customProperties object (customProperties) 

Contact custom properties.

You need to add a contact custom property first using the Add contact custom properties API operation.

The key of customProperties is the value of propertyName you specified in the Add contact custom field schemas API operation, which is a variable.
The value of customProperties differs in type depending on the propertyType and multiValued values of the field (see the description of each type in CustomProperties for details). In addition, customProperties allows you to specify multiple custom properties together.

 

permission

PropertyTypeDescription
accessibleRange string 

Accessible range

  • ALL: Allows all members in the domain to access the contact.
  • MEMBER: Allows only specific members to access the contact, by specifying accessibleMembers.

required
Allowed values : ALL, MEMBER 
masterUserId string 

User ID of the contact owner

  • accessibleRange: Required if it is MEMBER.
 
isCoEditing boolean 

Indicates whether the contact can be co-edited.

  • If "false", only the contact owner can edit it.

default : true 
accessibleMembers array (ContactAccessibleMember) 

Members who can access the contact (member, team, or group ID)

  • It is required if accessibleRange is MEMBER.

minItems : 0
maxItems : 500
uniqueItems : true 

ContactAccessibleMember

PropertyTypeDescription
id string 

Member ID


required 
type string 

Type of the member who can access the contact

  • USER: Member
  • ORGUNIT: Team
  • GROUP: Group

required
Allowed values : USER, ORGUNIT, GROUP 

contactName

PropertyTypeDescription
firstName string 

First name


maxLength : 100
nullable : true 
lastName string 

Last name


maxLength : 100
nullable : true 
phoneticFirstName string 

First name in Furigana


maxLength : 100
nullable : true 
phoneticLastName string 

Last name in Furigana


maxLength : 100
nullable : true 
nickName string 

Nickname


maxLength : 100
nullable : true 
prefix string 

Courtesy title. It is displayed only in "Get a contact."


maxLength : 100
nullable : true 
suffix string 

Title. It is displayed only in "Get a contact."


maxLength : 100
nullable : true 
middleName string 

Middle name. It is displayed only in "Get a contact."


maxLength : 100
nullable : true 

ContactEmail

PropertyTypeDescription
primary boolean 

Indicates whether it is the primary email.

  • One of the list items must be set as primary.
  • If the primary item is not specified, the first item automatically becomes primary.

required 
email string 

Email address


required
maxLength : 256 

ContactTelephone

PropertyTypeDescription
primary boolean 

Indicates whether it is the primary phone number.

  • One of the list items must be set as primary.
  • If the primary item is not specified, the first item automatically becomes primary.

required 
telephone string 

Phone number


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

Phone number type

  • CELLPHONE: Mobile
  • WORK: Work
  • HOME: Home
  • WORK_FAX: Work fax
  • HOME_FAX: Home fax
  • OTHER: Others
  • CUSTOM: Custom

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

Custom phone number type.

  • Available only if ContactTelephoneType is CUSTOM.

maxLength : 100
nullable : true 

ContactOrganization

PropertyTypeDescription
primary boolean 

Indicates whether it is the primary organization.

  • One of the list items must be set as primary.
  • If the primary item is not specified, the first item automatically becomes primary.

required 
name string 

Company name


maxLength : 100 
department string 

Department name


maxLength : 100 
title string 

Job title name


maxLength : 100 

ContactEvent

PropertyTypeDescription
primary boolean 

Indicates whether it is the primary event.

  • One of the list items must be set as primary.
  • If the primary item is not specified, the first item automatically becomes primary.

required 
date string 

Date (YYYY-MM-DD)


required 
type string 

Event type

  • BIRTHDAY: Birthday
  • ANNIVERSARY: Anniversary
  • OTHER: Others
  • CUSTOM: Custom

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

Custom event type


maxLength : 100
nullable : true 
dayType string 

Date type


default : SOLAR
Allowed values : SOLAR, LUNAR 

ContactLocation

PropertyTypeDescription
primary boolean 

Indicates whether it is the primary address.

  • One of the list items must be set as primary.
  • If the primary item is not specified, the first item automatically becomes primary.

required 
address string 

Address


required
maxLength : 100 
type string 

Address type

  • WORK: Work
  • HOME: Home
  • OTHER: Others
  • CUSTOM: Custom

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

Zip or postal code


maxLength : 100 
customType string 

Custom address type


maxLength : 100
nullable : true 

ContactMessenger

PropertyTypeDescription
primary boolean 

Indicates whether it is the primary messenger.

  • One of the list items must be set as primary.
  • If the primary item is not specified, the first item automatically becomes primary.

required 
id string 

Messenger ID


required
maxLength : 100 
type string 

Messenger type

  • FACEBOOK: Facebook
  • LINE: LINE
  • TWITTER: X (formerly Twitter)
  • CUSTOM: Custom

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

Custom messenger type


maxLength : 100
nullable : true 

ContactWebsite

PropertyTypeDescription
primary boolean 

Indicates whether it is the primary website.

  • One of the list items must be set as primary.
  • If the primary item is not specified, the first item automatically becomes primary.

required 
url string 

Website URL


required
maxLength : 100 

customProperties

PropertyTypeDescription
propertyName object (propertyName) 

If propertyType is STRING and multiValued is false

  • content is the value of the property.
 
array (CustomPropertyStringMulti) 

If propertyType is STRING and multiValued is true

  • content is the value of the property and represent indicates whether it is primary.
  • If represent is not specified, the first one becomes primary.

maxItems : 10 
object (CustomPropertyLinkSingle) 

If propertyType is LINK and multiValued is false

  • link must be specified.
  • link must be set to a valid URL.
  • If text is “Homepage1” and link is “https://www.unicef.org”:
    <a href = "https://www.unicef.org">Homepage1</a>
  • If link is specified but text is not, the link itself is displayed as the link text.
 
array (CustomPropertyLinkMulti) 

If propertyType is LINK and multiValued is true

  • link must be specified.
  • link must be set to a valid URL.
  • If text is “Homepage1” and link is “https://www.unicef.org”:
    <a href = "https://www.unicef.org">Homepage1</a>
  • If link is specified but text is not, the link itself is displayed as the link text.
  • If represent is not specified, the first one becomes primary.

maxItems : 10 

propertyName

PropertyTypeDescription
content string 

Value if propertyType is STRING


maxLength : 100 

CustomPropertyStringMulti

PropertyTypeDescription
content string 

Value if propertyType is STRING


maxLength : 100 
represent boolean 

Indicates whether it is primary. If multiValued is true, the value whose represent is true is displayed at the beginning of the list.

 

CustomPropertyLinkSingle

PropertyTypeDescription
text string 

Text


maxLength : 100
nullable : true 
link string 

URL


maxLength : 300 

CustomPropertyLinkMulti

PropertyTypeDescription
text string 

Text


maxLength : 100
nullable : true 
link string 

URL


maxLength : 300 
represent boolean 

Indicates whether it is primary. If multiValued is true, the value whose represent is true is displayed at the beginning of the list.

 

Request Example

example

1{2  "permission": {3    "masterUserId": "userf7da-f82c-4284-13e7-030f3b4c756x",4    "isCoEditing": true,5    "accessibleRange": "ALL"6  },7  "contactName": {8    "lastName": "Doe",9    "firstName": "John",10    "nickName": "JD"11  },12  "emails": [13    {14      "email": "example1@example.com",15      "primary": true16    },17    {18      "email": "example2@example.com",19      "primary": false20    }21  ],22  "telephones": [23    {24      "type": "CELLPHONE",25      "telephone": "0000-0001",26      "primary": true27    },28    {29      "type": "HOME",30      "telephone": "0000-0002",31      "primary": false32    }33  ],34  "organizations": [35    {36      "name": "example company name",37      "department": "department",38      "title": "title",39      "primary": true40    }41  ],42  "locations": [43    {44      "address": "example1 address",45      "zipCode": "00001",46      "type": "WORK",47      "primary": true48    },49    {50      "address": "example2 address",51      "zipCode": "00002",52      "type": "HOME",53      "primary": false54    }55  ],56  "events": [57    {58      "date": "2021-01-09",59      "dayType": "SOLAR",60      "type": "BIRTHDAY",61      "primary": true62    },63    {64      "date": "2021-08-09",65      "dayType": "SOLAR",66      "type": "ANNIVERSARY",67      "primary": false68    }69  ],70  "messengers": [71    {72      "id": "example1",73      "type": "LINE",74      "primary": true75    },76    {77      "id": "example2",78      "type": "CUSTOM",79      "customType": "Worksmobile",80      "primary": false81    }82  ],83  "websites": [84    {85      "url": "https://example1.com",86      "primary": true87    },88    {89      "url": "https://example2.com",90      "primary": false91    }92  ],93  "memo": "memo",94  "contactTagIds": [95    "ctag2a81-94b6-4642-6903-03aa7977da91",96    "3512644d-a731-4602-6912-031febc8bce2"97  ],98  "customProperties": {99    "string_single": {100      "content": "ext_id"101    },102    "string_multi": [103      {104        "content": "ext_id",105        "represent": true106      },107      {108        "content": "connect",109        "represent": false110      }111    ],112    "link_single": {113      "text": "worksmobile",114      "link": "https://contact.worksmobile.com"115    },116    "link_multi": [117      {118        "text": "worksmobile",119        "link": "https://contact.worksmobile.com",120        "represent": true121      },122      {123        "text": "line",124        "link": "https://www.line.me/",125        "represent": false126      }127    ]128  }129}

Response

HTTP 200

OK

PropertyTypeDescription
contactId string 

Customer/client contact ID


readOnly : true 
permission object (permission) 

Contact access permission model


required 
contactName object (contactName) 

Contact name


required 
linkedExternalUser object (linkedExternalUser) 

External message contact information


readOnly : true 
emails array (ContactEmail) 

List of email addresses


minItems : 0
maxItems : 100 
telephones array (ContactTelephone) 

List of phone numbers


minItems : 0
maxItems : 100 
organizations array (ContactOrganization) 

List of organizations


minItems : 0
maxItems : 100 
events array (ContactEvent) 

List of contact events


minItems : 0
maxItems : 100 
locations array (ContactLocation) 

List of addresses


minItems : 0
maxItems : 100 
messengers array (ContactMessenger) 

Messenger information


minItems : 0
maxItems : 100 
websites array (ContactWebsite) 

List of websites


minItems : 0
maxItems : 100 
memo string 

Memo


maxLength : 4000 
contactTagIds array (string) 

List of tags


minItems : 0 
customProperties object (customProperties) 

Contact custom properties.

You need to add a contact custom property first using the Add contact custom properties API operation.

The key of customProperties is the value of propertyName you specified in the Add contact custom field schemas API operation, which is a variable.
The value of customProperties differs in type depending on the propertyType and multiValued values of the field (see the description of each type in CustomProperties for details). In addition, customProperties allows you to specify multiple custom properties together.

 
createdTime string 

Contact creation time

  • Format: YYYY-MM-DDThh:mm:ssTZD

readOnly : true 
modifiedTime string 

Contact update time

  • Format: YYYY-MM-DDThh:mm:ssTZD

readOnly : true 

permission

PropertyTypeDescription
accessibleRange string 

Accessible range

  • ALL: Allows all members in the domain to access the contact.
  • MEMBER: Allows only specific members to access the contact, by specifying accessibleMembers.

required
Allowed values : ALL, MEMBER 
masterUserId string 

User ID of the contact owner

  • accessibleRange: Required if it is MEMBER.
 
isCoEditing boolean 

Indicates whether the contact can be co-edited.

  • If "false", only the contact owner can edit it.

default : true 
accessibleMembers array (ContactAccessibleMember) 

Members who can access the contact (member, team, or group ID)

  • It is required if accessibleRange is MEMBER.

minItems : 0
maxItems : 500
uniqueItems : true 

ContactAccessibleMember

PropertyTypeDescription
id string 

Member ID


required 
type string 

Type of the member who can access the contact

  • USER: Member
  • ORGUNIT: Team
  • GROUP: Group

required
Allowed values : USER, ORGUNIT, GROUP 

contactName

PropertyTypeDescription
firstName string 

First name


maxLength : 100
nullable : true 
lastName string 

Last name


maxLength : 100
nullable : true 
phoneticFirstName string 

First name in Furigana


maxLength : 100
nullable : true 
phoneticLastName string 

Last name in Furigana


maxLength : 100
nullable : true 
nickName string 

Nickname


maxLength : 100
nullable : true 
prefix string 

Courtesy title. It is displayed only in "Get a contact."


maxLength : 100
nullable : true 
suffix string 

Title. It is displayed only in "Get a contact."


maxLength : 100
nullable : true 
middleName string 

Middle name. It is displayed only in "Get a contact."


maxLength : 100
nullable : true 

linkedExternalUser

PropertyTypeDescription
id string 

External message contact ID

 
type string 

External message contact type

  • LINE: LINE message contact
  • WORKS: External message contact in another domain

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

List of user IDs who added the external message contact to their contacts.

 

ContactEmail

PropertyTypeDescription
primary boolean 

Indicates whether it is the primary email.

  • One of the list items must be set as primary.
  • If the primary item is not specified, the first item automatically becomes primary.

required 
email string 

Email address


required
maxLength : 256 

ContactTelephone

PropertyTypeDescription
primary boolean 

Indicates whether it is the primary phone number.

  • One of the list items must be set as primary.
  • If the primary item is not specified, the first item automatically becomes primary.

required 
telephone string 

Phone number


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

Phone number type

  • CELLPHONE: Mobile
  • WORK: Work
  • HOME: Home
  • WORK_FAX: Work fax
  • HOME_FAX: Home fax
  • OTHER: Others
  • CUSTOM: Custom

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

Custom phone number type.

  • Available only if ContactTelephoneType is CUSTOM.

maxLength : 100
nullable : true 

ContactOrganization

PropertyTypeDescription
primary boolean 

Indicates whether it is the primary organization.

  • One of the list items must be set as primary.
  • If the primary item is not specified, the first item automatically becomes primary.

required 
name string 

Company name


maxLength : 100 
department string 

Department name


maxLength : 100 
title string 

Job title name


maxLength : 100 

ContactEvent

PropertyTypeDescription
primary boolean 

Indicates whether it is the primary event.

  • One of the list items must be set as primary.
  • If the primary item is not specified, the first item automatically becomes primary.

required 
date string 

Date (YYYY-MM-DD)


required 
type string 

Event type

  • BIRTHDAY: Birthday
  • ANNIVERSARY: Anniversary
  • OTHER: Others
  • CUSTOM: Custom

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

Custom event type


maxLength : 100
nullable : true 
dayType string 

Date type


default : SOLAR
Allowed values : SOLAR, LUNAR 

ContactLocation

PropertyTypeDescription
primary boolean 

Indicates whether it is the primary address.

  • One of the list items must be set as primary.
  • If the primary item is not specified, the first item automatically becomes primary.

required 
address string 

Address


required
maxLength : 100 
type string 

Address type

  • WORK: Work
  • HOME: Home
  • OTHER: Others
  • CUSTOM: Custom

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

Zip or postal code


maxLength : 100 
customType string 

Custom address type


maxLength : 100
nullable : true 

ContactMessenger

PropertyTypeDescription
primary boolean 

Indicates whether it is the primary messenger.

  • One of the list items must be set as primary.
  • If the primary item is not specified, the first item automatically becomes primary.

required 
id string 

Messenger ID


required
maxLength : 100 
type string 

Messenger type

  • FACEBOOK: Facebook
  • LINE: LINE
  • TWITTER: X (formerly Twitter)
  • CUSTOM: Custom

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

Custom messenger type


maxLength : 100
nullable : true 

ContactWebsite

PropertyTypeDescription
primary boolean 

Indicates whether it is the primary website.

  • One of the list items must be set as primary.
  • If the primary item is not specified, the first item automatically becomes primary.

required 
url string 

Website URL


required
maxLength : 100 

customProperties

PropertyTypeDescription
propertyName object (propertyName) 

If propertyType is STRING and multiValued is false

  • content is the value of the property.
 
array (CustomPropertyStringMulti) 

If propertyType is STRING and multiValued is true

  • content is the value of the property and represent indicates whether it is primary.
  • If represent is not specified, the first one becomes primary.

maxItems : 10 
object (CustomPropertyLinkSingle) 

If propertyType is LINK and multiValued is false

  • link must be specified.
  • link must be set to a valid URL.
  • If text is “Homepage1” and link is “https://www.unicef.org”:
    <a href = "https://www.unicef.org">Homepage1</a>
  • If link is specified but text is not, the link itself is displayed as the link text.
 
array (CustomPropertyLinkMulti) 

If propertyType is LINK and multiValued is true

  • link must be specified.
  • link must be set to a valid URL.
  • If text is “Homepage1” and link is “https://www.unicef.org”:
    <a href = "https://www.unicef.org">Homepage1</a>
  • If link is specified but text is not, the link itself is displayed as the link text.
  • If represent is not specified, the first one becomes primary.

maxItems : 10 

propertyName

PropertyTypeDescription
content string 

Value if propertyType is STRING


maxLength : 100 

CustomPropertyStringMulti

PropertyTypeDescription
content string 

Value if propertyType is STRING


maxLength : 100 
represent boolean 

Indicates whether it is primary. If multiValued is true, the value whose represent is true is displayed at the beginning of the list.

 

CustomPropertyLinkSingle

PropertyTypeDescription
text string 

Text


maxLength : 100
nullable : true 
link string 

URL


maxLength : 300 

CustomPropertyLinkMulti

PropertyTypeDescription
text string 

Text


maxLength : 100
nullable : true 
link string 

URL


maxLength : 300 
represent boolean 

Indicates whether it is primary. If multiValued is true, the value whose represent is true is displayed at the beginning of the list.

 

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": "Doe",17    "firstName": "John",18    "nickName": "JD",19    "phoneticFirstName": null,20    "phoneticLastName": null,21    "prefix": null,22    "suffix": null,23    "middleName": null24  },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": true36    },37    {38      "email": "example2@example.com",39      "primary": false40    }41  ],42  "telephones": [43    {44      "type": "CELLPHONE",45      "telephone": "0000-0001",46      "primary": true,47      "customType": null48    },49    {50      "type": "HOME",51      "telephone": "0000-0002",52      "primary": false,53      "customType": null54    }55  ],56  "organizations": [57    {58      "name": "example company name",59      "department": "department",60      "title": "title",61      "primary": true62    }63  ],64  "locations": [65    {66      "address": "example1 address",67      "zipCode": "00001",68      "type": "WORK",69      "primary": true,70      "customType": null71    },72    {73      "address": "example2 address",74      "zipCode": "00002",75      "type": "HOME",76      "primary": false,77      "customType": null78    }79  ],80  "events": [81    {82      "date": "2021-01-09",83      "dayType": "SOLAR",84      "type": "BIRTHDAY",85      "primary": true,86      "customType": null87    },88    {89      "date": "2021-08-09",90      "dayType": "SOLAR",91      "type": "ANNIVERSARY",92      "primary": false,93      "customType": null94    }95  ],96  "messengers": [97    {98      "id": "example1",99      "type": "LINE",100      "primary": true,101      "customType": null102    },103    {104      "id": "example2",105      "type": "CUSTOM",106      "customType": "Worksmobile",107      "primary": false108    }109  ],110  "websites": [111    {112      "url": "https://example1.com",113      "primary": true114    },115    {116      "url": "https://example2.com",117      "primary": false118    }119  ],120  "memo": "memo",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}

HTTP 400

Bad Request

HTTP 403

Forbidden

HTTP 404

Not Found