GET/users/{userId}/contacts

Gets a list of contacts that a member can access.

This API operation can get up to 50,000 contacts. If the number of search results is over 50,000, specify createdTime and modifiedTime to adjust the search range. You can get contacts for up to 7 days by specifying startDateTime and endDateTime.

Authorization

oauth2

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

Scope

contact
contact.read

HTTP Request

GEThttps://www.worksapis.com/v1.0/users/{userId}/contacts

Path Parameters

ParameterTypeDescription
userId string 

Member ID


required
example : userf7da-f82c-4284-13e7-030f3b4c756x 

Query Parameters

ParameterTypeDescription
count integer 

Number of items returned at a time


default : 100
minimum : 1
maximum : 500
example : 100
format : int32 
cursor string 

Cursor


example : JlIBsfJogXpzDGY8OscZziqZpYqCAu3RbZbaFzBb1od6lWQtSdPUd2FIdCuaGgu8DA== 
searchDateType string 

Search date type. It is required if startDateTime and endDateTime are specified.


Allowed values : CREATED_TIME, MODIFIED_TIME
example : CREATED_TIME 
startDateTime string 

Start date (YYYY-MM-DDThh:mm:ssTZD). 「+」 must be URL-encoded to 「%2B」.


example : 2021-06-03T10:00:00.000%2B09:00 
endDateTime string 

End date (YYYY-MM-DDThh:mm:ssTZD). 「+」 must be URL-encoded to 「%2B」.


example : 2021-06-03T11:00:00.000%2B09:00 
accessibleRange string 

Accessible range


Allowed values : ALL, MEMBER
example : ALL 
contactTagId string 

Tag ID


example : ctag2a81-94b6-4642-6903-03aa7977da91 
searchFilterType string 

Search filter type. - LINKED_EXTERNAL_USER: Display only external message contacts.


Allowed values : LINKED_EXTERNAL_USER
example : LINKED_EXTERNAL_USER 
orderBy string 

Sort by: name, createdTime, modifiedTime. Sorting order: asc (default), desc. Use a blank space (%20) to separate "sort by" and "sort order."


example : name%20asc 

Header Parameters

HeadertypeDescription
Authorization string 

Bearer {token}


required 

Response

HTTP 200

Response when getting contacts

PropertyTypeDescription
contacts array (Contact) 

Contact information

 
responseMetaData object (responseMetaData) 

Pagination information

 

Contact

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.

 

responseMetaData

PropertyTypeDescription
nextCursor string 

Cursor value for pagination

 

Response Example

example

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

HTTP 400

Bad Request