GET/contacts/{contactId}

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

注意

  • 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/{contactId}

Path Parameters

ParameterTypeDescription
contactId string 

連絡先 ID


required
example : contact2-a56d-44a4-5304-033e16fca8d1 

Header Parameters

HeadertypeDescription
Authorization string 

Bearer {token}


required 

Response

HTTP 200

OK

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 の値が、リストの最初に表示される。

 

Response Example

example

1{2  "contactId": "contact2-a56d-44a4-5304-033e16fca8d1",3  "contactTagIds": [4    "ctag2a81-94b6-4642-6903-03aa7977da91",5    "3512644d-a731-4602-6912-031febc8bce2"6  ],7  "permission": {8    "masterUserId": "userf7da-f82c-4284-13e7-030f3b4c756x",9    "isCoEditing": true,10    "accessibleRange": "ALL",11    "accessibleMembers": []12  },13  "createdTime": "2021-08-10T11:05:41+09:00",14  "modifiedTime": "2021-08-10T11:09:37+09:00",15  "contactName": {16    "lastName": "ワークス",17    "firstName": "太郎",18    "nickName": "Works",19    "phoneticFirstName": null,20    "phoneticLastName": null,21    "prefix": null,22    "suffix": null,23    "middleName": null24  },25  "linkedExternalUser": {26    "id": "works75b-5b29-4048-4bf5-0336e504a395",27    "type": "WORKS",28    "buddyUserIds": [29      "userf7da-f82c-4284-13e7-030f3b4c756x"30    ]31  },32  "emails": [33    {34      "email": "example1@example.com",35      "primary": true36    },37    {38      "email": "example2@example.com",39      "primary": false40    }41  ],42  "telephones": [43    {44      "type": "CELLPHONE",45      "telephone": "0000-0001",46      "primary": true,47      "customType": null48    },49    {50      "type": "HOME",51      "telephone": "0000-0002",52      "primary": false,53      "customType": null54    }55  ],56  "organizations": [57    {58      "name": "example company name",59      "department": "department",60      "title": "title",61      "primary": true62    }63  ],64  "locations": [65    {66      "address": "example1 address",67      "zipCode": "00001",68      "type": "WORK",69      "primary": true,70      "customType": null71    },72    {73      "address": "example2 address",74      "zipCode": "00002",75      "type": "HOME",76      "primary": false,77      "customType": null78    }79  ],80  "events": [81    {82      "date": "2021-01-09",83      "dayType": "SOLAR",84      "type": "BIRTHDAY",85      "primary": true,86      "customType": null87    },88    {89      "date": "2021-08-09",90      "dayType": "SOLAR",91      "type": "ANNIVERSARY",92      "primary": false,93      "customType": null94    }95  ],96  "messengers": [97    {98      "id": "example1",99      "type": "LINE",100      "primary": true,101      "customType": null102    },103    {104      "id": "example2",105      "type": "CUSTOM",106      "customType": "Worksmobile",107      "primary": false108    }109  ],110  "websites": [111    {112      "url": "https://example1.com",113      "primary": true114    },115    {116      "url": "https://example2.com",117      "primary": false118    }119  ],120  "memo": "memo",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}

HTTP 404

Not Found