Get Customer/Client Contacts

    Gets customer/client contacts.

    • You can get up to 50,000 search results (page * maxResults).
    • If the number of search results is over 50,000, specify CREATION_TIME and MODIFICATION_TIME to adjust the search range.
    • You can get customer/client contacts for up to 7 days by specifying startDateTime and endDateTime.

    API Type

    Server API

    Request URL

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

    HTTP Method

    GET

    Path Parameters

    Parameter Type Length Required Description
    domainId Integer Y Domain ID

    Request Parameter

    Parameter Type Length Required Description
    page Integer N Page
    ● Default: 1
    maxResults Integer N Size of data to get per page.
    ● It can be between 1 and 500.
    ● Default: 500
    searchDateType String N Search date type
    ● CREATION_TIME: Creation date and time (default)
    ● MODIFICATION_TIME: Update date and time
    Any values not specified here will be set to CREATION_TIME.
    startDateTime String N Start date and time
    ● It is in the date and time format described in ISO 8601 (YYYY-MM-DDThh:mm:ssTZD).
    ● Example) 2020-04-05T00:00:00+09:00
    ● : and + must be URL encoded to %3A and %2B, respectively.
    endDateTime String N End date and time
    ● It is in the date and time format described in ISO 8601 (YYYY-MM-DDThh:mm:ssTZD).
    ● Example) 2020-04-06T00:00:00+09:00
    ● : and + must be URL encoded to %3A and %2B, respectively.
    tagResourceId String N Tag resource ID
    open Boolean N Indicates whether to show a contact.
    ● true： To all
    ● false： To members only
    filterWorksAt Boolean N Indicates whether to get external contacts only.
    ● true： Get external contacts only.
    userId String N Member ID. The API gets contacts that the member has access to.
    keyword String N Keyword to search by, such as name, company name and tag name.
    orderBy String N Sort by
    ● NAME: Name
    ● CREATION_TIME: Creation date and time (default)
    ● MODIFICATION_TIME: Update date and time
    sortOrder String N Sort order
    ● ASC: Ascending (default)
    ● DESC: Descending

    Request Example

    GET https://apis.worksmobile.com/r/apiid/contact/v3/domains/123/shared/contacts?page=1&maxResults=500&searchDateType=CREATION_TIME&startDateTime=2020-04-05T00%3A00%3A00%2B09%3A00&endDateTime=2020-04-06T00%3A00%3A00%2B09%3A00

    Response

    It returns customer/client contacts as a list in “contacts” of the response body with HTTP status 200 if successful.

    Property Type Description
    contacts[] List List of customer/client contacts
    contacts[].resourceId String Customer/client resource ID
    contacts[].open Boolean Indicates whether to show the contact.
    contacts[].isCoEditing Boolean Indicates whether to allow co-editing of the contact.
    ● true: Any shared members can co-edit.
    ● false: Only the master can edit.
    contacts[].masterUserId String Master member ID (email) of the contact
    contacts[].sharedMembers[] List List of shared members if the open property is “false”.
    contacts[].sharedMembers[].id String ID (email) of a shared member or organization.
    contacts[].sharedMembers[].type String Type of sharedMembers[].id
    ● USER: Member
    ● ORGUNIT: Organization
    contacts[].tagResourceIds[] List<String> List of tag resource IDs
    contacts[].name Object Name
    contacts[].name.lastName String Family name
    contacts[].name.firstName String Given name
    contacts[].name.phoneticLastName String Family name in Furigana
    contacts[].name.phoneticFirstName String Given name in Furigana
    contacts[].name.nickName String Nickname
    contacts[].emails[] List List of emails addresses
    contacts[].emails[].address String Email address
    contacts[].emails[].represent Boolean Indicates whether it is the default email address.
    contacts[].phones[] List List of phone numbers
    contacts[].phones[].value String Phone number.
    At least one number and - * # + P T ( ) are allowed only.
    contacts[].phones[].type String Phone number type
    ● MOBILE: Mobile phone
    ● WORK: Office
    ● HOME: Home
    ● WORK_FAX: Office fax
    ● HOME_FAX: Home fax
    ● OTHER: Others
    ● CUSTOM: Custom
    contacts[].phones[].customType String Custom phone number type.
    Available if the phone number type is CUSTOM.
    contacts[].phones[].represent Boolean Indicates whether it is the default phone number.
    contacts[].organizations[] List List of organizations
    contacts[].organizations[].name String Company name
    contacts[].organizations[].department String Department name
    contacts[].organizations[].title String Position name
    contacts[].organizations[].represent Boolean Indicates whether it is the default company.
    contacts[].locations[] List List of addresses
    contacts[].locations[].value String Address
    contacts[].locations[].zipcode String Zip or postal code
    contacts[].locations[].type String Address type
    ● WORK: Office
    ● HOME: Home
    ● OTHER: Others
    ● CUSTOM: Custom
    contacts[].locations[].customType String Custom address type.
    Available if the address type is CUSTOM.
    contacts[].locations[].represent Boolean Indicates whether it is the default address.
    contacts[].events[] List List of events
    contacts[].events[].value String Date (yyyyMMdd)
    contacts[].events[].dayType String Date type
    ● S: Solar calendar
    ● L: Lunar calendar
    contacts[].events[].type String Event type
    ● BIRTHDAY: Date of birth
    ● ANNIVERSARY: Anniversary
    ● OTHER: Others
    ● CUSTOM: Custom
    contacts[].events[].customType String Custom event type.
    Available if the event type is CUSTOM.
    contacts[].events[].represent Boolean Indicates whether it is the default event.
    contacts[].messengers[] List List of messengers
    contacts[].messengers[].id String Messenger ID
    contacts[].messengers[].type String Messenger type
    ● LINE: LINE
    ● FACEBOOK: Facebook
    ● TWITTER: Twitter
    ● CUSTOM: Custom
    contacts[].messengers[].customType String Custom messenger type.
    Available if the messenger type is CUSTOM.
    contacts[].messengers[].customType Boolean Indicates whether it is the default messenger.
    contacts[].websites[] List List of websites
    contacts[].websites[].value String Website URL
    contacts[].websites[].represent Boolean Indicates whether it is the default website.
    contacts[].photos[] List List of photos
    The first one is used as the profile picture.
    contacts[].photos[].path String Path of the uploaded photo
    contacts[].photos[].represent Boolean Indicates whether it is the default photo.
    contacts[].memo String Memo
    contacts[].worksAt Object External contact information (returned only if it is an external contact.)
    contacts[].worksAt.type String External contact type
    ● line: LINE contact
    ● worksat: WORKSAT contact of another domain
    contacts[].worksAt.resourceId String External contact resource ID
    contacts[].worksAt.buddyUserIds String IDs of the members who added the external contact to their contacts.
    contacts[].creationTime String Contact creation time
    ● It is in the date and time format described in ISO 8601 (YYYY-MM-DDThh:mm:ssTZD).
    ● Example) 2020-04-05T19:30:04+09:00
    contacts[].modificationTime String Contact update time
    ● It is in the date and time format described in ISO 8601 (YYYY-MM-DDThh:mm:ssTZD).
    ● Example) 2020-04-05T19:30:04+09:00
    nextPage Integer Next page. It is returned only if there is a next page.

    Response Example

    {
   "contacts":[
      {
         "resourceId":"230e2625-x31b-41d4-a916-689055440000",
         "open":true,
         "isCoEditing": true,
         "masterUserId": "account1@example.com",
         "name":{
            "firstName":"April",
            "lastName":"Jackson",
            "nickName":"Bella"
         },
         "emails":[
            {
               "address":"april.jackson@email.com",
               "represent":true
            }
         ],
         "creationTime":"2020-04-01T08:10:18+09:00",
         "modificationTime":"2020-04-03T07:30:04+09:00"
      },
      {
         "resourceId":"550e8400-e29b-41d4-a716-446655440000",
         "open":false,
         "isCoEditing": true,
         "masterUserId": "account1@example.com",
         "sharedMembers":[
            {
               "id":"account1@example.com",
               "type":"USER"
            },
            {
               "id":"account2@example.com",
               "type":"USER"
            },
            {
               "id":"account3@example.com",
               "type":"USER"
            },
            {
               "id":"orgunit1@example.com",
               "type":"ORGUNIT"
            }
         ],
         "tagResourceIds":[
            "efse4567-e89b-12d3-a456-426614174000",
            "774117c8-7a68-4c67-62a8-0312dd90b9b3"
         ],
         "name":{
            "firstName":"First Name",
            "lastName":"Last Name",
            "nickName":"Nickname"
         },
         "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",
         "worksAt":[
            {
               "type":"LINE",
               "resourceId":"741ec794-9bf8-4759-1eef-03ffa18ca759",
               "buddyUserIds":[
                  "account1@example.com"
               ]
            }
         ],
         "creationTime":"2020-04-05T19:30:04+09:00",
         "modificationTime":"2020-04-06T21:30:04+09:00"
      }
   ],
   "nextPage":2
}

    Error Code

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