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
    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 1000 characters N Memo

    Request Example

    POST https://apis.worksmobile.com/r/apiid/contact/v3/domains/123/shared/contacts
    
    {
       "open":false,
       "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.