Add Customer/Client Contacts

Creates customer/client contacts in a specified domain of a tenant by using server authentication. You can create up to 50,000 contacts.
A contact must contain either an email address or a phone number.

API Type

Server API

Request URL

https://apis.worksmobile.com/r/{API ID}/contact/v3/domains/{domainId}/shared/contacts

HTTP Method

POST

Path Parameters

Parameter	Type	Length	Required	Description
domainId	Integer		Y	Domain ID

Request Body

Parameter	Type	Length	Required	Description
open	Boolean		Y	Indicates whether to show a contact. ● true: To anyone ● false: To shared members only
isCoEditing	Boolean		N	Indicates whether to allow co-editing of a contact. ● true: Any shared members can co-edit (default). ● false: Only the master can edit.
masterUserId	String		N	Master member ID (email) of a contact
sharedMembers[]	List	500	N	List of shared members. The maximum number of shared members is 500. Required if the open parameter is “false”.
sharedMembers[].id	String		Y	ID (email) of a shared member, organization or group. Member’s email address for the Basic and Premium products. ● The format is localpart@domain (localpart@group for the Lite product). ● If an organization ID is specified, a contact is shared with only the members who directly belong to the organization and not with those who belong to the sub organizations. ● If a group ID is specified, a contact is shared with only the group members in the same domain, and the individual group member IDs are stored.
sharedMembers[].type	String		Y	Type of sharedMembers[].id ● USER: Member ● ORGUNIT: Organization ● GROUP: Group
tagResourceIds[]	List<String>		N	List of tag resource IDs
name	Object		Y	Name
name.lastName	String	100 characters	N	Family name (Either lastName or firstName must be specified.)
name.firstName	String	100 characters	N	Given name (Either lastName or firstName must be specified.)
name.phoneticLastName	String	100 characters	N	Family name in Furigana
name.phoneticFirstName	String	100 characters	N	Given name in Furigana
name.prefix	String	100 characters	N	Courtesy title (Honor)
name.suffix	String	100 characters	N	Title (Suffix)
name.middleName	String	100 characters	N	Middle name (Middle)
name.nickName	String	100 characters	N	Nickname
emails[]	List	100 entries	N	List of email addresses
emails[].address	String	256 characters	Y	Email address. Standard email address format only.
emails[].represent	Boolean		Y	Indicates whether it is the default email address.
phones[]	List	100 entries	N	List of phone numbers
phones[].value	String	100 characters	Y	Phone number. At least one number and - * # + P T ( ) are allowed only.
phones[].type	String		Y	Phone number type ● MOBILE: Mobile phone ● WORK: Office ● HOME: Home ● WORK_FAX: Office fax ● HOME_FAX: Home fax ● OTHER: Others ● CUSTOM: Custom Any values not specified here will be set to CUSTOM.
phones[].customType	String	100 characters	N	Custom phone number type. Available if the phone number type is CUSTOM.
phones[].represent	Boolean		Y	Indicates whether it is the default phone number.
organizations[]	List	100 entries	N	List of organizations
organizations[].name	String	100 characters	Y	Company name
organizations[].department	String	100 characters	Y	Department name
organizations[].title	String	100 characters	Y	Position name
organizations[].represent	Boolean		Y	Indicates whether it is the default company.
locations[]	List	100 entries	N	List of addresses
locations[].value	String	100 characters	Y	Address
locations[].zipcode	String	100 characters	Y	Zip or postal code
locations[].type	String		Y	Address type ● WORK: Office ● HOME: Home ● OTHER: Others ● CUSTOM: Custom Any values not specified here will be set to CUSTOM.
locations[].customType	String	100 characters	N	Custom address type. Available if the address type is CUSTOM.
locations[].represent	Boolean		Y	Indicates whether it is the default address.
events[]	List	100 entries	N	List of events
events[].value	String	100 characters	Y	Date (yyyyMMdd)
events[].dayType	String		Y	Date type ● S: Solar calendar ● L: Lunar calendar Any values not specified here will be set to S.
events[].type	String		Y	Event type ● BIRTHDAY: Date of birth ● ANNIVERSARY: Anniversary ● OTHER: Others ● CUSTOM: Custom Any values not specified here will be set to CUSTOM.
events[].customType	String	100 characters	N	Custom event type. Available if the event type is CUSTOM.
events[].represent	Boolean		Y	Indicates whether it is the default event.
messengers[]	List	100 entries	N	List of messengers
messengers[].id	String	100 entries	Y	Messenger ID
messengers[].type	String		Y	Messenger type ● LINE: LINE ● FACEBOOK: Facebook ● TWITTER: Twitter ● CUSTOM: Custom Any values not specified here will be set to CUSTOM.
messengers[].customType	String	100 characters	N	Custom messenger type. Available if the messenger type is CUSTOM.
messengers[].represent	Boolean		Y	Indicates whether it is the default messenger.
websites[]	List	100 entries	N	List of websites
websites[].value	String	100 characters	Y	Website URL
websites[].represent	Boolean		Y	Indicates whether it is the default website.
photos[]	List	6 entries	N	List of photos The first one is used as the profile picture.
photos[].path	String		Y	Path of the uploaded photo. Refer to Upload Photos for Customer/Client Contacts.
photos[].represent	Boolean		Y	Indicates whether it is the default photo.
memo	String	4000 characters	N	Memo

Request Example

POST https://apis.worksmobile.com/r/apiid/contact/v3/domains/123/shared/contacts

{
   "open":false,
   "isCoEditing": true,
   "masterUserId": "account1@example.com",
   "sharedMembers":[
      {
         "id":"account1@example.com",
         "type":"USER"
      },
      {
         "id":"account2@example.com",
         "type":"USER"
      },
      {
         "id":"orgunit1@example.com",
         "type":"ORGUNIT"
      },
      {
         "id":"dl_email@example.com",
         "type":"GROUP"
      }
   ],
   "tagResourceIds":[
      "efse4567-e89b-12d3-a456-426614174000",
      "774117c8-7a68-4c67-62a8-0312dd90b9b3"
   ],
   "name":{
      "firstName":"First Name",
      "lastName":"Last Name",
      "nickName":"Nick Name"
   },
   "emails":[
      {
         "address":"example@email.com",
         "represent":true
      }
   ],
   "phones":[
      {
         "value":"0000-0001",
         "type":"WORK",
         "represent":true
      },
      {
         "value":"0000-0002",
         "type":"CUSTOM",
         "customType":"Custom Type",
         "represent":false
      }
   ],
   "organizations":[
      {
         "name":"Organization",
         "department":"Department",
         "title":"Job Title",
         "represent":true
      }
   ],
   "locations":[
      {
         "value":"Home Address",
         "zipcode":"000-111",
         "type":"HOME",
         "represent":true
      },
      {
         "value":"Custom Address",
         "zipcode":"000-111",
         "type":"CUSTOM",
         "customType":"Custom type",
         "represent":false
      }
   ],
   "events":[
      {
         "value":"20170313",
         "dayType":"S",
         "type":"BIRTHDAY",
         "represent":true
      }
   ],
   "messengers":[
      {
         "id":"lineid",
         "type":"LINE",
         "represent":true
      },
      {
         "id":"customid",
         "type":"CUSTOM",
         "customType":"customlabel",
         "represent":false
      }
   ],
   "websites":[
      {
         "value":"homepage.com",
         "represent":true
      }
   ],
   "photos":[
      {
         "path":"/upload/photo/1234.jpg",
         "represent":true
      }
   ],
   "memo":"Memo content"
}

Response

It returns the following property as a response with HTTP status 200 if successful.

Property	Type	Description
resourceId	String	Customer/client resource ID added on success.

Response Example

{
    "resourceId": "550e8400-e29b-41d4-a716-446655440000"
}

Error Code

It returns an error code and message on failure.
Refer to Contacts API Error Codes for details.

LINE WORKS Developers