GET/contacts

顧客/取引先の連絡先リストを取得する。

  • 開始/終了日時フィルターで指定できる期間は最大 7 日間。
  • 開始/終了日時フィルターのどちらかのみ指定した場合、指定日から 7 日以内に登録/更新された連絡先リストを取得できる。
  • 連絡先は、最大 5 万件まで取得できる。
  • 5 万件を超える場合には、フィルター条件を調整する。

注意

  • X(Twitter) に対する Response Body の SNS タイプ messenger[].protocol.type には、TWITTER が返りますが、2026年7月下旬を目処に X に変更を予定しています。

Authorization

oauth2

Access Token を指定します。
指定の方法や Access Token の取得方法は 共通仕様 を参照してください。

Scope

contact
contact.read

HTTP Request

GEThttps://www.worksapis.com/v1.0/contacts

Query Parameters

ParameterTypeDescription
count integer 

取得数


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

リストのカーソル値 (URL エンコードする)


example : JlIBsfJogXpzDGY8OscZziqZpYqCAu3RbZbaFzBb1od6lWQtSdPUd2FIdCuaGgu8DA== 
searchDateType string 

フィルター日時タイプ
startDateTime、endDateTime を使用する場合に指定。

  • CREATED_TIME : 登録日時
  • MODIFIED_TIME : 更新日時

Allowed values : CREATED_TIME, MODIFIED_TIME
example : CREATED_TIME 
startDateTime string 

開始日時フィルター (YYYY-MM-DDThh:mm:ssTZD)


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

終了日時フィルター (YYYY-MM-DDThh:mm:ssTZD)


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

アクセス許可範囲フィルター

  • MEMBER : 指定ユーザーのみ
  • ALL : 全てのユーザー

Allowed values : ALL, MEMBER
example : ALL 
contactTagId string 

連絡先タグ ID フィルター


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

メールアドレス フィルター
「@」 は 「%40」 にエンコードする。

  • 代表メールアドレスのみが検索対象になります。
  • 「@」を含まない場合には、代表メールアドレスの localpart に対して部分一致で検索されます。
  • 「@」を含む場合には、代表メールアドレスに対して前方一致で検索されます。

maxLength : 256
example : example%40example.com
nullable : true 
telephone string 

電話番号フィルター
4字以上の数字のみが有効で、部分一致で検索される。


maxLength : 100
example : 012345678
nullable : true 
searchFilterType string 

検索フィルタリングタイプ

  • LINKED_EXTERNAL_USER : 外部ユーザーのみ

Allowed values : LINKED_EXTERNAL_USER
example : LINKED_EXTERNAL_USER 
orderBy string 

ソート

  • ソートフィールド:
    • name : 名前 (既定)
    • createdTime : 登録日時
    • modifiedTime : 更新日時
  • 並び順:
    • asc : 昇順 (既定)
    • desc : 降順
      ソートフィールドと並び順はスペースで区切る (separator : %20)

example : name%20asc 

Header Parameters

HeadertypeDescription
Authorization string 

Bearer {token}


required 

Response

HTTP 200

連絡先リスト

PropertyTypeDescription
contacts array (Contact) 

取引先情報

 
responseMetaData object (responseMetaData) 

レスポンスのメタデータ

 

Contact

PropertyTypeDescription
contactId string 

連絡先 ID


readOnly : true 
permission object (permission) 

アクセス権限モデル


required 
contactName object (contactName) 

氏名モデル


required 
linkedExternalUser object (linkedExternalUser) 

外部ユーザーモデル


readOnly : true 
emails array (ContactEmail) 

メールアドレスリスト


minItems : 0
maxItems : 100 
telephones array (ContactTelephone) 

電話番号リスト


minItems : 0
maxItems : 100 
organizations array (ContactOrganization) 

会社/所属リスト


minItems : 0
maxItems : 100 
events array (ContactEvent) 

誕生日/記念日リスト


minItems : 0
maxItems : 100 
locations array (ContactLocation) 

住所リスト


minItems : 0
maxItems : 100 
messengers array (ContactMessenger) 

SNS リスト


minItems : 0
maxItems : 100 
websites array (ContactWebsite) 

Web サイトリスト


minItems : 0
maxItems : 100 
memo string 

メモ


maxLength : 4000 
contactTagIds array (string) 

連絡先タグリスト


minItems : 0 
customProperties object (customProperties) 

連絡先カスタムプロパティ
連絡先カスタムプロパティの登録 を利用して、事前にカスタムフィールドを作成します。

  • customProperties の key の値は、連絡先カスタムプロパティの登録 で設定した propertyName の値です。
  • customProperties の value の値は、フィールドの propertyType、multiValued の値によって type が異なります。詳細は customProperties を参照してください。
  • customProperties では、複数の連絡先カスタムプロパティに対する値を同時に設定することができます。
 
createdTime string 

登録日時 (YYYY-MM-DDThh:mm:ssTZD)


readOnly : true 
modifiedTime string 

更新日時 (YYYY-MM-DDThh:mm:ssTZD)


readOnly : true 

permission

PropertyTypeDescription
accessibleRange string 

アクセス許可範囲

  • ALL : 全てのユーザー
  • MEMBER : 指定ユーザーのみ

required
Allowed values : ALL, MEMBER 
masterUserId string 

連絡先の管理者ユーザー ID

  • accessibleRange が MEMBER の場合は必須。
 
isCoEditing boolean 

共同編集フラグ

  • true : アクセス許可ユーザーは編集可能
  • false : 連絡先の管理者ユーザーのみ編集可能

default : true 
accessibleMembers array (ContactAccessibleMember) 

アクセス許可ユーザーリスト

  • accessibleRange が MEMBER の場合は必須

minItems : 0
maxItems : 500
uniqueItems : true 

ContactAccessibleMember

PropertyTypeDescription
id string 

アクセス許可ユーザー ID (ユーザー ID、組織 ID、グループ ID)


required 
type string 

アクセス許可ユーザータイプ

  • USER : ユーザー
  • ORGUNIT : 組織 (組織直属ユーザーだけにアクセス許可)
  • GROUP : グループ (グループで同じドメインのユーザーだけにアクセス許可)

required
Allowed values : USER, ORGUNIT, GROUP 

contactName

PropertyTypeDescription
firstName string 

名


maxLength : 100
nullable : true 
lastName string 

姓


maxLength : 100
nullable : true 
phoneticFirstName string 

フリガナ 名


maxLength : 100
nullable : true 
phoneticLastName string 

フリガナ 姓


maxLength : 100
nullable : true 
nickName string 

ニックネーム


maxLength : 100
nullable : true 
prefix string 

敬称
API では 連絡先の取得 でのみ取得できる。


maxLength : 100
nullable : true 
suffix string 

呼称
API では 連絡先の取得 でのみ取得できる。


maxLength : 100
nullable : true 
middleName string 

ミドルネーム API では 連絡先の取得 でのみ取得できる。


maxLength : 100
nullable : true 

linkedExternalUser

PropertyTypeDescription
id string 

外部ユーザー ID

 
type string 

外部ユーザータイプ

  • LINE : LINE ユーザー
  • WORKS : 他のドメインの外部ユーザー

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

外部ユーザーを連絡先に追加したユーザー ID リスト

 

ContactEmail

PropertyTypeDescription
primary boolean 

代表メールアドレスフラグ

  • リストで 1 つのメールアドレスを代表に指定する必要がある。
  • 指定しない場合、最初のメールアドレスが代表メールアドレスとなる。

required 
email string 

メールアドレス


required
maxLength : 256 

ContactTelephone

PropertyTypeDescription
primary boolean 

代表電話フラグ

  • リストで 1 つの電話番号を代表に指定する必要がある。
  • 指定しない場合、最初の電話番号が代表電話となる。

required 
telephone string 

電話番号


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

電話番号タイプ

  • CELLPHONE: 携帯電話
  • WORK : 会社
  • HOME : 自宅
  • WORK_FAX : 会社 FAX
  • HOME_FAX : 自宅 FAX
  • OTHER : その他
  • CUSTOM : カスタム

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

カスタム電話番号タイプ

  • 電話番号タイプが CUSTOM の場合に指定可能

maxLength : 100
nullable : true 

ContactOrganization

PropertyTypeDescription
primary boolean 

代表会社フラグ

  • リストで 1 つの会社/所属を代表に指定する必要がある。
  • 指定しない場合、最初の会社/所属が代表会社/代表所属となる。

required 
name string 

会社名


maxLength : 100 
department string 

部署名


maxLength : 100 
title string 

役職名


maxLength : 100 

ContactEvent

PropertyTypeDescription
primary boolean 

代表イベントフラグ

  • リストで 1 つのイベントを代表に指定する必要がある。
  • 指定しない場合、最初のイベントが代表イベントとなる。

required 
date string 

日付(YYYY-MM-DD)


required 
type string 

イベントタイプ

  • BIRTHDAY : 誕生日
  • ANNIVERSARY : 記念日
  • OTHER : その他
  • CUSTOM : カスタム

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

カスタムイベントタイプ

  • イベントタイプが CUSTOM の場合に指定可能

maxLength : 100
nullable : true 
dayType string 

日付形式

  • SOLAR : 西暦
  • LUNAR : 旧暦

default : SOLAR
Allowed values : SOLAR, LUNAR 

ContactLocation

PropertyTypeDescription
primary boolean 

代表住所フラグ

  • リストで 1 つの住所を代表に指定する必要がある。
  • 指定しない場合、最初の住所が代表住所となる。

required 
address string 

住所


required
maxLength : 100 
type string 

住所タイプ

  • WORK : 会社
  • HOME : 自宅
  • OTHER : その他
  • CUSTOM : カスタム

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

郵便番号


maxLength : 100 
customType string 

カスタム住所タイプ

  • 住所タイプが CUSTOM の場合に指定可能

maxLength : 100
nullable : true 

ContactMessenger

PropertyTypeDescription
primary boolean 

代表 SNS フラグ

  • リストで 1 つの SNS を代表に指定する必要がある。
  • 指定しない場合、最初の SNS が代表 SNS となる。

required 
id string 

SNS ID


required
maxLength : 100 
type string 

SNSタイプ

注意

  • Request Body における SNS タイプ messenger[].protocol.type での TWITTER と X は、どちらも X(Twitter) を示します。TWITTER は、2026年11月中旬を目処に廃止を予定しています。
  • X(Twitter) に対する Response Body の SNS タイプ messenger[].protocol.type には、TWITTER が返りますが、2026年7月下旬を目処に X に変更を予定しています。
  • LINE : LINE
  • FACEBOOK : Facebook
  • TWITTER : X (Twitter)
  • X : X (Twitter)
  • CUSTOM : カスタム

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

カスタム SNS タイプ

  • SNS タイプが CUSTOM の場合に指定可能

maxLength : 100
nullable : true 

ContactWebsite

PropertyTypeDescription
primary boolean 

代表 Web サイトフラグ

  • リストで 1 つの Web サイトを代表に指定する必要がある。
  • 指定しない場合、最初の Web サイトが代表 Web サイトとなる。

required 
url string 

WebサイトURL


required
maxLength : 100 

customProperties

PropertyTypeDescription
propertyName object (propertyName) 

propertyType = STRING、multiValued = false の場合

  • content はプロパティの値
 
array (CustomPropertyStringMulti) 

propertyType = STRING、multiValued = true の場合

  • content はプロパティの値を、represent は代表であることを示す。
  • represent を指定しない場合には、最初の項目が代表値となる。

maxItems : 10 
object (CustomPropertyLinkSingle) 

propertyType = LINK で、multiValued = false の場合

  • link は必須。
  • link には有効な URL 形式を指定します。
  • text と link を両方指定し、 text が 'Homepage1'、link が 'https://www.example.com' の場合には以下となる。
    • <a href = "https://www.example.com">Homepage1</a>
  • link のみが指定されている場合には、link が表示テキストになる。
 
array (CustomPropertyLinkMulti) 

propertyType = LINK で、multiValued = true の場合

  • link は必須。
  • link には有効な URL 形式を指定します。
  • text と link を両方指定し、 text が 'Homepage1'、link が 'https://www.example.com' の場合には以下となる。
    • <a href = "https://www.example.com">Homepage1</a>
  • link のみが指定されている場合には、link が表示テキストになる。
  • represent を指定しない場合には、最初の項目が代表値となる。

maxItems : 10 

propertyName

PropertyTypeDescription
content string 

propertyType が STRING の場合の値


maxLength : 100 

CustomPropertyStringMulti

PropertyTypeDescription
content string 

propertyType = STRING の場合の値


maxLength : 100 
represent boolean 

代表値フラグ
multiValued = true の場合、represent = true の値が、リストの最初に表示される。

 

CustomPropertyLinkSingle

PropertyTypeDescription
text string 

テキスト


maxLength : 100
nullable : true 
link string 

URL


maxLength : 300 

CustomPropertyLinkMulti

PropertyTypeDescription
text string 

テキスト


maxLength : 100
nullable : true 
link string 

URL


maxLength : 300 
represent boolean 

代表値フラグ
multiValued = true の場合、represent = true の値が、リストの最初に表示される。

 

responseMetaData

PropertyTypeDescription
nextCursor string 

次のリスト取得時に使用するカーソル値

 

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": "ワークス",13        "firstName": "太郎",14        "nickName": "Works",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