Sansan Open API

API Endpoint
https://api.sansan.com/v2.3

Sansan Open API は Sansan の情報を外部アプリケーションから利用できるプログラミングインタフェースです。取得した名刺などの情報を使って自社の顧客情報やビジネス情報と結びつけることで、より有用な情報にし、あなたのビジネスを強力に後押しします。

API の利用にあたって

API の利用には、API利用規約が適用され、API を利用するとAPI利用規約に同意したものとみなされます。

アクセス権の考え方

API を利用する際のアクセス権限はリクエストの際に付与されている API Key によって決まります。 API Key はユーザごとに異なりますので、 API Key を使うことでそのユーザのアクセス権を引き継いでいるということになります。例えば、アプリケーション側で Sansan の全名刺情報にアクセスしたい場合、 API Key を発行したユーザが Sansan において同一の権限を持っている必要があります。

共通仕様

概要

API を利用する際の共通仕様は以下のとおりです。

項目 説明
APIのバージョン 2.3
使用するプロトコル HTTPS
文字コード UTF‒8

リクエストヘッダ

API をリクエストする場合には、以下の共通リクエストヘッダが必要です。

ヘッダ 説明
X-Sansan-App-Id Sansan から発行した Application ID (英数字)
X-Sansan-Api-Key Sansan ユーザ毎に発行される API Key (32 桁の英数字)

※ X-Sansan-App-Id はパートナープログラムを申込み頂いたアプリケーションにのみ必要です。

パートナープログラムとは

レスポンスヘッダ

サーバから共通して返される HTTP レスポンスヘッダはありません。

API 呼び出し方法

Sansan Open API は RESTful API 設計に従って提供されており、標準の HTTP メソッドを使用して名刺データリソースを取得します。

API Key

API を組み込んだアプリケーションが Sansan Open API にアクセスするには API Key が必要です。 API Key の発行は Sansan のユーザが行いますが、事前に自社の Sansan 管理者から API を利用できる権限を与えられている必要があります。 API Key の発行は右上メニューの設定、または管理者設定の外部サービス連携画面より、 API Key を選択して行います。

API Key を発行

API Key の発行

呼び出し回数制限

Sansan Open API には 10 回 /1 秒の呼び出し回数制限が設けられています。呼び出し回数制限は API Key 毎に決まります。一定時間での API 呼び出し回数が制限を超えた場合は特別なレスポンスを返します。詳しくは ステータスコード一覧 を参照してください。なお、呼び出し回数制限値は予告なく変更する場合があります。

クロスドメインリクエスト

Sansan Open API はクロスドメイン HTTP リクエストを許可しません。つまり、XMLHttpRequest を使ってブラウザから直接的に Sansan Open API にリクエストを送信できません。

呼び出しの並列化

Sansan Open API は並列で実行できます。アプリケーションが大量の情報を扱う必要がある場合には、複数の呼び出しを並列処理することで性能を向上させられます。ただし、並列呼び出しに同じ API Key を利用していれば、呼び出し回数の制限は適用されます。また、一定時間に極端に多い処理を受け付けた場合には、呼び出し回数制限と同様に特別なレスポンスを返す可能性がありますのでご注意ください。

ステータスコード一覧

API がエラーになった場合、以下の HTTP ステータスコードが返ってきます。また、一部のエラーにおいては詳細を表す Error object の配列も返却されます。下記以外のステータスコード(200 や 203 等)は HTTP の仕様に準じます。

コード 種別 説明
400 required 必須パラメータなし
invalid_value リクエスト値が不正
expired_token トークンの有効期限切れ
401 invalid_api_key 認証エラー( API Key が不正)
invalid_app_id 認証エラー( Application ID が不正)
403 has_no_permission API 利用権限なし
404 - 指定リソースが存在しない
415 unsupported_media_type Content-Typeが不正
429 too_many_request リクエスト数制限超過
access_count: 現在のアクセス回数
retry_after: 制限が解除されるまでの期間(秒)
500 - サーバエラー
503 - サーバエラー

名刺・人物・タグの共通仕様

レスポンスのデータ形式

Sansan Open API は名刺データリソースを JSON データ形式で返却します。具体的には次のような応答になります。

{
  "hasMore": true,
  "nextPageToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA",
  "data": [
    {
      "id": "37171BA646FD16C8F0960DE7403AAAAA", 
      "companyId": "DLED3O4OE0MA78DQLWO21DBGE5GAAAAA", 
      "personId": "F11E1A1B94EE2B4AB3F01A30C17AAAAA", 
      "exchangeDate": "2015-08-21", 
      "registeredTime": "2015-08-21T11:29:39+09:00", 
      "updatedTime": "2015-08-21T11:29:39+09:00", 
      "owner": {
        "email": "ito@example.com", 
        "id": "ito", 
        "name": "伊藤花子"
      }, 
      "lastName": "伊藤", 
      "firstName": "花子", 
      "lastNameReading": null, 
      "firstNameReading": null, 
      "departmentName": "情報システム部", 
      "title": null, 
      "email": "ito@example.com", 
      "mobile": "080-0000-0000", 
      "companyName": "株式会社 ITO", 
      "countryCode": "JP", 
      "postalCode": "1000001", 
      "address": "東京都台東区池之端 1-1 ビル 101", 
      "prefecture": "東京都", 
      "city": "台東区", 
      "street": "池之端 1-1", 
      "building": "ビル 101", 
      "tel": "0120-000-0000", 
      "secondTel": "0120-200-0000", 
      "fax": "0120-100-0000", 
      "url": "http://ito.example.com",
      "memo": "セミナーで名刺交換", 
      "entryStatus": "completed", 
      "isUserCreated": true
    }
  ]
}

ページネーション

名刺情報のように大きいコレクションが返される可能性のあるリクエストでは、応答ごとに限られた数のアイテムが含まれます。この上限は取得件数 limit (デフォルト 100) で指定されます。また、各応答には hasMore プロパティと nextPageToken プロパティが含まれます。 hasMoretrue である場合、 nextPageToken をリクエストパラメータに指定してさらにデータが取得できます。 なお、 nextPageToken は最初のページをリクエストしてから 6h で有効期限が切れますのでご注意下さい。

補足 (概念図)

名刺の状態について

名刺は以下の状態を持ちます。関連するタイムスタンプはソートに使うことができます。

所有者と取得できる名刺の範囲について

名刺やタグを持つユーザを所有者と呼びます。 名刺を取得する範囲は、me (自分の所有する名刺) か、all (自分から参照できるの範囲の全ての名刺) を指定できます。所有者からは参照できない範囲については以下ヘルプをご覧ください。

名寄せと人物について

同一人物と判断された名刺は名寄せされます。最新の名刺は名刺交換日が最新のものです。

名刺API

名刺API では Sansan にある自社の保有する名刺情報にのみアクセスできます。他社が保有する名刺情報を参照することはできません。

名刺 Set 取得(期間指定)

GET https://api.sansan.com/v2.3/bizCards?updatedFrom=2015-08-21T11:29:39+09:00&updatedTo=2015-08-22T11:29:39+09:00&nextPageToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA&includePastBizCards=false&range=me&entryStatus=completed&orderBy=updatedAt&orderDirection=asc&limit=100
Responses200400

BizCard object を data に持つ List object 。 BizCard object の並び順は、名刺登録日時の降順となります。

Headers
Content-Type: application/json
Body
{
  "hasMore": true,
  "nextPageToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA",
  "data": [
    {
      "id": "37171BA646FD16C8F0960DE7403AAAAA",
      "companyId": "DLED3O4OE0MA78DQLWO21DBGE5GAAAAA",
      "personId": "F11E1A1B94EE2B4AB3F01A30C17AAAAA",
      "exchangeDate": "2015-08-21",
      "registeredTime": "2015-08-21T11:29:39+09:00",
      "updatedTime": "2015-08-21T11:29:39+09:00",
      "owner": {
        "id": "ito",
        "name": "伊藤花子",
        "email": "ito@example.com"
      },
      "lastName": "伊藤",
      "firstName": "花子",
      "lastNameReading": "null",
      "firstNameReading": "null",
      "departmentName": "情報システム部",
      "title": "null",
      "email": "ito@example.com",
      "mobile": "080-0000-0000",
      "companyName": "株式会社 ITO",
      "countryCode": "JP",
      "postalCode": "1000001",
      "address": "東京都台東区池之端 1-1 ビル 101",
      "prefecture": "東京都",
      "city": "台東区",
      "street": "池之端 1-1",
      "building": "ビル 101",
      "tel": "0120-000-0000",
      "secondTel": "0120-200-0000",
      "fax": "0120-100-0000",
      "url": "http://ito.example.com",
      "memo": "セミナーで名刺交換",
      "entryStatus": "completed",
      "isUserCreated": true
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "hasMore": {
      "type": "boolean"
    },
    "nextPageToken": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "InternalServerError",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "エラー種別"
    },
    "message": {
      "type": "string",
      "description": "エラーメッセージ"
    },
    "error": {
      "type": "array",
      "description": "種別毎の詳細情報"
    }
  }
}

名刺 Set 取得(期間指定)
GET/bizCards{?updatedFrom,updatedTo,nextPageToken,includePastBizCards,range,entryStatus,orderBy,orderDirection,limit}

期間指定で名刺の集合(Set)を取得します。名刺 ( data キー以下のデータ)の並び順は、名刺登録日時の降順となります。

URI Parameters
HideShow
updatedFrom
string (required) Example: 2015-08-21T11:29:39+09:00

名刺更新日時 “YYYY-MM-DDThh:mm:ssTZD” 形式

updatedTo
string (required) Example: 2015-08-22T11:29:39+09:00

名刺更新日時 “YYYY-MM-DDThh:mm:ssTZD” 形式

nextPageToken
string (optional) Default: null Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA

次のページの検索結果を取得するためのトークン。トークンが指定された場合、トークン発行時に指定された他のパラメータの値を引き継ぐ。

includePastBizCards
boolean (optional) Default: false Example: false

過去の名刺情報も含めて取得する。

Choices: true false

range
string (optional) Default: me Example: me

対象とする所有者の範囲

Choices: me all

entryStatus
array[enum] (optional) Default: completed Example: completed

対象とする名刺入力状態。複数指定可能 (例: …/bizCards?entryStatus=completed&entryStatus=processing&…)

Choices: processing completed unreadable

orderBy
string (optional) Default: updatedAt Example: updatedAt

レスポンスに含まれる名刺の並び順に使用するプロパティ

Choices: registeredAt completedAt updatedAt

orderDirection
string (optional) Default: asc Example: asc

レスポンスに含まれる名刺の並び順

Choices: asc desc

limit
number (optional) Default: 100 Example: 100

取得する一覧の上限。 1〜300 まで指定可能。


名刺 Set 取得(条件指定)

GET https://api.sansan.com/v2.3/bizCards/search?nextPageToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA&includePastBizCards=false&range=me&companyName=株式会社 ITO&name=伊藤花子&email=ito@example.com&tel=0120-000-0000&mobile=080-0000-0000&tagId=DLED3O4OE0MA78DQLWO21DBGE5GG8HYV&entryStatus=completed&orderBy=registeredAt&orderDirection=desc&limit=100
Responses200400

BizCard object を data に持つ List object。 BizCard object の並び順は、名刺登録日時の降順となります。

Headers
Content-Type: application/json
Body
{
  "hasMore": true,
  "nextPageToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA",
  "data": [
    {
      "id": "37171BA646FD16C8F0960DE7403AAAAA",
      "companyId": "DLED3O4OE0MA78DQLWO21DBGE5GAAAAA",
      "personId": "F11E1A1B94EE2B4AB3F01A30C17AAAAA",
      "exchangeDate": "2015-08-21",
      "registeredTime": "2015-08-21T11:29:39+09:00",
      "updatedTime": "2015-08-21T11:29:39+09:00",
      "owner": {
        "id": "ito",
        "name": "伊藤花子",
        "email": "ito@example.com"
      },
      "lastName": "伊藤",
      "firstName": "花子",
      "lastNameReading": "null",
      "firstNameReading": "null",
      "departmentName": "情報システム部",
      "title": "null",
      "email": "ito@example.com",
      "mobile": "080-0000-0000",
      "companyName": "株式会社 ITO",
      "countryCode": "JP",
      "postalCode": "1000001",
      "address": "東京都台東区池之端 1-1 ビル 101",
      "prefecture": "東京都",
      "city": "台東区",
      "street": "池之端 1-1",
      "building": "ビル 101",
      "tel": "0120-000-0000",
      "secondTel": "0120-200-0000",
      "fax": "0120-100-0000",
      "url": "http://ito.example.com",
      "memo": "セミナーで名刺交換",
      "entryStatus": "completed",
      "isUserCreated": true
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "hasMore": {
      "type": "boolean"
    },
    "nextPageToken": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "InternalServerError",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "エラー種別"
    },
    "message": {
      "type": "string",
      "description": "エラーメッセージ"
    },
    "error": {
      "type": "array",
      "description": "種別毎の詳細情報"
    }
  }
}

名刺 Set 取得(条件指定)
GET/bizCards/search{?nextPageToken,includePastBizCards,range,companyName,name,email,tel,mobile,tagId,entryStatus,orderBy,orderDirection,limit}

条件指定で名刺の集合(Set)を取得します。 名刺 ( data キー以下のデータ) の並び順は、名刺登録日時の降順となります。

URI Parameters
HideShow
nextPageToken
string (optional) Default: null Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA

次のページの検索結果を取得するためのトークン。トークンが指定された場合、トークン発行時に指定された他のパラメータの値を引き継ぐ。

includePastBizCards
boolean (optional) Default: false Example: false

過去の名刺情報も含めて取得する。

Choices: true false

range
string (optional) Default: me Example: me

対象とする所有者の範囲

Choices: me all

companyName
string (optional) Example: 株式会社 ITO

部分一致で会社名を検索

name
string (optional) Example: 伊藤花子

前方一致で氏名を検索

email
string (optional) Example: ito@example.com

完全一致でメールアドレスを検索

tel
string (optional) Example: 0120-000-0000

部分一致で電話番号を検索

mobile
string (optional) Example: 080-0000-0000

部分一致で携帯番号を検索

tagId
array[string] (optional) Example: DLED3O4OE0MA78DQLWO21DBGE5GG8HYV

Sansan 内のタグID (タグSet取得API にて取得可能)。複数指定可能。 (例: …/bizCards/search?tagId[]=tag1&tagId[]=tag2&…)

entryStatus
array[enum] (optional) Default: completed Example: completed

対象とする名刺入力状態。複数指定可能 (例: …/bizCards?entryStatus=completed&entryStatus=processing&…)

Choices: processing completed unreadable

orderBy
string (optional) Default: registeredAt Example: registeredAt

レスポンスに含まれる名刺の並び順に使用するプロパティ

Choices: registeredAt completedAt updatedAt

orderDirection
string (optional) Default: desc Example: desc

レスポンスに含まれる名刺の並び順

Choices: asc desc

limit
number (optional) Default: 100 Example: 100

取得する一覧の上限。 1〜300 まで指定可能。


名刺情報

GET https://api.sansan.com/v2.3/bizCards/DLED3O4OE0MA78DQLWO21DBGE5GG8HYV
Responses200400
Headers
Content-Type: application/json
Body
{
  "id": "37171BA646FD16C8F0960DE7403AAAAA",
  "companyId": "DLED3O4OE0MA78DQLWO21DBGE5GAAAAA",
  "personId": "F11E1A1B94EE2B4AB3F01A30C17AAAAA",
  "exchangeDate": "2015-08-21",
  "registeredTime": "2015-08-21T11:29:39+09:00",
  "updatedTime": "2015-08-21T11:29:39+09:00",
  "owner": {
    "id": "ito",
    "name": "伊藤花子",
    "email": "ito@example.com"
  },
  "lastName": "伊藤",
  "firstName": "花子",
  "lastNameReading": "null",
  "firstNameReading": "null",
  "departmentName": "情報システム部",
  "title": "null",
  "email": "ito@example.com",
  "mobile": "080-0000-0000",
  "companyName": "株式会社 ITO",
  "countryCode": "JP",
  "postalCode": "1000001",
  "address": "東京都台東区池之端 1-1 ビル 101",
  "prefecture": "東京都",
  "city": "台東区",
  "street": "池之端 1-1",
  "building": "ビル 101",
  "tel": "0120-000-0000",
  "secondTel": "0120-200-0000",
  "fax": "0120-100-0000",
  "url": "http://ito.example.com",
  "memo": "セミナーで名刺交換",
  "entryStatus": "completed",
  "isUserCreated": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "名刺ID"
    },
    "companyId": {
      "type": "string",
      "description": "会社ID"
    },
    "personId": {
      "type": "string",
      "description": "人物ID"
    },
    "exchangeDate": {
      "type": "string",
      "description": "名刺交換日 “YYYY-MM-DD” 形式"
    },
    "registeredTime": {
      "type": "string",
      "description": "名刺登録日時 \"YYYY-MM-DDThh:mm:ssTZD\" 形式"
    },
    "updatedTime": {
      "type": "string",
      "description": "名刺更新日時 \"YYYY-MM-DDThh:mm:ssTZD\" 形式"
    },
    "owner": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ユーザID"
        },
        "name": {
          "type": "string",
          "description": "ユーザ名"
        },
        "email": {
          "type": "string",
          "description": "メールアドレス"
        }
      },
      "description": "所有者を表すユーザオブジェクト"
    },
    "lastName": {
      "type": "string",
      "description": "姓"
    },
    "firstName": {
      "type": "string",
      "description": "名"
    },
    "lastNameReading": {
      "type": [
        "string",
        "null"
      ],
      "description": "姓カナ"
    },
    "firstNameReading": {
      "type": [
        "string",
        "null"
      ],
      "description": "名カナ"
    },
    "departmentName": {
      "type": "string",
      "description": "部署名"
    },
    "title": {
      "type": [
        "string",
        "null"
      ],
      "description": "役職"
    },
    "email": {
      "type": "string",
      "description": "メールアドレス"
    },
    "mobile": {
      "type": "string",
      "description": "携帯番号"
    },
    "companyName": {
      "type": "string",
      "description": "会社名"
    },
    "countryCode": {
      "type": "string",
      "description": "国コード(ISO 3166-1 alpha-2形式)"
    },
    "postalCode": {
      "type": "string",
      "description": "郵便番号"
    },
    "address": {
      "type": "string",
      "description": "住所。prefecture、city、street、buildingを連結した文字列"
    },
    "prefecture": {
      "type": "string",
      "description": "都道府県"
    },
    "city": {
      "type": "string",
      "description": "市区町村"
    },
    "street": {
      "type": "string",
      "description": "番地"
    },
    "building": {
      "type": "string",
      "description": "ビル名"
    },
    "tel": {
      "type": "string",
      "description": "電話番号"
    },
    "secondTel": {
      "type": "string",
      "description": "電話番号2"
    },
    "fax": {
      "type": "string",
      "description": "FAX番号"
    },
    "url": {
      "type": "string",
      "description": "URL"
    },
    "memo": {
      "type": "string",
      "description": "名刺に記載されたメモ"
    },
    "entryStatus": {
      "type": "string",
      "enum": [
        "completed",
        "processing",
        "unreadable"
      ],
      "description": "データを入力中の名刺(processing)、データの入力が完了した名刺(completed)、データの入力ができなかった名刺(unreadable)"
    },
    "isUserCreated": {
      "type": "boolean",
      "description": "ユーザーが作成した名刺かどうか。ユーザが名刺新規作成や名刺インポートから作成した名刺(true)、スキャナやアプリから取り込みSansanによるデータ化が行われた名刺(false)"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "InternalServerError",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "エラー種別"
    },
    "message": {
      "type": "string",
      "description": "エラーメッセージ"
    },
    "error": {
      "type": "array",
      "description": "種別毎の詳細情報"
    }
  }
}

名刺情報
GET/bizCards/{id}

指定された名刺 ID を持つ名刺情報を取得します。該当する名刺が同一の名刺所有者のもとで名寄せされていれば、名寄せ結果の最新の名刺が返却されます。この場合、パラメータで指定した名刺 ID と、返却される名刺の id が異なることになります。

URI Parameters
HideShow
id
string (required) Example: DLED3O4OE0MA78DQLWO21DBGE5GG8HYV

Sansan 内で名刺を一意に区別する識別子


名刺画像取得

GET https://api.sansan.com/v2.3/bizCards/DLED3O4OE0MA78DQLWO21DBGE5GG8HYV/image?side=front
Responses200404

JPEG 形式の名刺の画像データ

Headers
Content-Type: image/jpeg
Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "InternalServerError",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "エラー種別"
    },
    "message": {
      "type": "string",
      "description": "エラーメッセージ"
    },
    "error": {
      "type": "array",
      "description": "種別毎の詳細情報"
    }
  }
}

名刺画像取得
GET/bizCards/{id}/image{?side}

指定された名刺 ID を持つ名刺の画像データを JPEG 形式で取得します。名刺はおもて裏の両面の画像を持ちます。どちらの面の画像を取得するかは side パラメータで指定できます。

URI Parameters
HideShow
id
string (required) Example: DLED3O4OE0MA78DQLWO21DBGE5GG8HYV

Sansan内で名刺を一意に区別する識別子

side
string (optional) Default: front Example: front

名刺画像のおもて面、裏面を指定

Choices: front back


名刺のタグ Set 取得

GET https://api.sansan.com/v2.3/bizCards/DLED3O4OE0MA78DQLWO21DBGE5GG8HYV/tags?nextPageToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA&limit=100
Responses200400

Tag object を data に持つ List object

Headers
Content-Type: application/json
Body
{
  "hasMore": true,
  "nextPageToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA",
  "data": [
    {
      "Id": "DLED3O4OE0MA78DQLWO21DBGE5GG8HYV",
      "name": "コンサルタント",
      "type": "private",
      "owner": {
        "id": "ito",
        "name": "伊藤花子",
        "email": "ito@example.com"
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "hasMore": {
      "type": "boolean"
    },
    "nextPageToken": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "InternalServerError",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "エラー種別"
    },
    "message": {
      "type": "string",
      "description": "エラーメッセージ"
    },
    "error": {
      "type": "array",
      "description": "種別毎の詳細情報"
    }
  }
}

名刺のタグ Set 取得
GET/bizCards/{id}/tags{?nextPageToken,limit}

名刺に付与されたタグの一覧を取得します。

URI Parameters
HideShow
id
string (required) Example: DLED3O4OE0MA78DQLWO21DBGE5GG8HYV

Sansan内で名刺を一意に区別する識別子

nextPageToken
string (optional) Default: null Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA

次のページの検索結果を取得するためのトークン。トークンが指定された場合、トークン発行時に指定された他のパラメータの値を引き継ぐ。

limit
number (optional) Default: 100 Example: 100

取得する一覧の上限。 1〜300 まで指定可能。


人物API

人物API では Sansan にある自社の保有する名刺情報にのみアクセスできます。他社が保有する名刺情報を参照することはできません。

人物取得

GET https://api.sansan.com/v2.3/persons/F11E1A1B94EE2B4AB3F01A30C17527C7
Responses200400
Headers
Content-Type: application/json
Body
{
  "id": "Hello, world!",
  "headBizCard": {
    "id": "37171BA646FD16C8F0960DE7403AAAAA",
    "companyId": "DLED3O4OE0MA78DQLWO21DBGE5GAAAAA",
    "personId": "F11E1A1B94EE2B4AB3F01A30C17AAAAA",
    "exchangeDate": "2015-08-21",
    "registeredTime": "2015-08-21T11:29:39+09:00",
    "updatedTime": "2015-08-21T11:29:39+09:00",
    "owner": {
      "id": "ito",
      "name": "伊藤花子",
      "email": "ito@example.com"
    },
    "lastName": "伊藤",
    "firstName": "花子",
    "lastNameReading": "null",
    "firstNameReading": "null",
    "departmentName": "情報システム部",
    "title": "null",
    "email": "ito@example.com",
    "mobile": "080-0000-0000",
    "companyName": "株式会社 ITO",
    "countryCode": "JP",
    "postalCode": "1000001",
    "address": "東京都台東区池之端 1-1 ビル 101",
    "prefecture": "東京都",
    "city": "台東区",
    "street": "池之端 1-1",
    "building": "ビル 101",
    "tel": "0120-000-0000",
    "secondTel": "0120-200-0000",
    "fax": "0120-100-0000",
    "url": "http://ito.example.com",
    "memo": "セミナーで名刺交換",
    "entryStatus": "completed",
    "isUserCreated": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "人物ID"
    },
    "headBizCard": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "名刺ID"
        },
        "companyId": {
          "type": "string",
          "description": "会社ID"
        },
        "personId": {
          "type": "string",
          "description": "人物ID"
        },
        "exchangeDate": {
          "type": "string",
          "description": "名刺交換日 “YYYY-MM-DD” 形式"
        },
        "registeredTime": {
          "type": "string",
          "description": "名刺登録日時 \"YYYY-MM-DDThh:mm:ssTZD\" 形式"
        },
        "updatedTime": {
          "type": "string",
          "description": "名刺更新日時 \"YYYY-MM-DDThh:mm:ssTZD\" 形式"
        },
        "owner": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "ユーザID"
            },
            "name": {
              "type": "string",
              "description": "ユーザ名"
            },
            "email": {
              "type": "string",
              "description": "メールアドレス"
            }
          },
          "description": "所有者を表すユーザオブジェクト"
        },
        "lastName": {
          "type": "string",
          "description": "姓"
        },
        "firstName": {
          "type": "string",
          "description": "名"
        },
        "lastNameReading": {
          "type": [
            "string",
            "null"
          ],
          "description": "姓カナ"
        },
        "firstNameReading": {
          "type": [
            "string",
            "null"
          ],
          "description": "名カナ"
        },
        "departmentName": {
          "type": "string",
          "description": "部署名"
        },
        "title": {
          "type": [
            "string",
            "null"
          ],
          "description": "役職"
        },
        "email": {
          "type": "string",
          "description": "メールアドレス"
        },
        "mobile": {
          "type": "string",
          "description": "携帯番号"
        },
        "companyName": {
          "type": "string",
          "description": "会社名"
        },
        "countryCode": {
          "type": "string",
          "description": "国コード(ISO 3166-1 alpha-2形式)"
        },
        "postalCode": {
          "type": "string",
          "description": "郵便番号"
        },
        "address": {
          "type": "string",
          "description": "住所。prefecture、city、street、buildingを連結した文字列"
        },
        "prefecture": {
          "type": "string",
          "description": "都道府県"
        },
        "city": {
          "type": "string",
          "description": "市区町村"
        },
        "street": {
          "type": "string",
          "description": "番地"
        },
        "building": {
          "type": "string",
          "description": "ビル名"
        },
        "tel": {
          "type": "string",
          "description": "電話番号"
        },
        "secondTel": {
          "type": "string",
          "description": "電話番号2"
        },
        "fax": {
          "type": "string",
          "description": "FAX番号"
        },
        "url": {
          "type": "string",
          "description": "URL"
        },
        "memo": {
          "type": "string",
          "description": "名刺に記載されたメモ"
        },
        "entryStatus": {
          "type": "string",
          "enum": [
            "completed",
            "processing",
            "unreadable"
          ],
          "description": "データを入力中の名刺(processing)、データの入力が完了した名刺(completed)、データの入力ができなかった名刺(unreadable)"
        },
        "isUserCreated": {
          "type": "boolean",
          "description": "ユーザーが作成した名刺かどうか。ユーザが名刺新規作成や名刺インポートから作成した名刺(true)、スキャナやアプリから取り込みSansanによるデータ化が行われた名刺(false)"
        }
      },
      "description": "人物の主な情報を表す名刺オブジェクト"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "InternalServerError",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "エラー種別"
    },
    "message": {
      "type": "string",
      "description": "エラーメッセージ"
    },
    "error": {
      "type": "array",
      "description": "種別毎の詳細情報"
    }
  }
}

人物取得
GET/persons/{id}

指定された人物 ID を持つ人物情報を取得します。該当する名刺が名寄せされていれば、名寄せ結果の最新の名刺を表す BizCard オブジェクトが返却されます。

URI Parameters
HideShow
id
string (required) Example: F11E1A1B94EE2B4AB3F01A30C17527C7

Sansan 内で人物を一意に区別する識別子


タグAPI

タグAPI では Sansan にある自社の保有する名刺情報にのみアクセスできます。他社が保有する名刺情報を参照することはできません。

タグ Set 取得

GET https://api.sansan.com/v2.3/tags?nextPageToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA&range=me&type=private&limit=100
Responses200400

Tag object を data に持つ List object

Headers
Content-Type: application/json
Body
{
  "hasMore": true,
  "nextPageToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA",
  "data": [
    {
      "Id": "DLED3O4OE0MA78DQLWO21DBGE5GG8HYV",
      "name": "コンサルタント",
      "type": "private",
      "owner": {
        "id": "ito",
        "name": "伊藤花子",
        "email": "ito@example.com"
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "hasMore": {
      "type": "boolean"
    },
    "nextPageToken": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "InternalServerError",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "エラー種別"
    },
    "message": {
      "type": "string",
      "description": "エラーメッセージ"
    },
    "error": {
      "type": "array",
      "description": "種別毎の詳細情報"
    }
  }
}

タグ Set 取得
GET/tags{?nextPageToken,range,type,limit}

Sansan にあるタグ一覧を取得します。

URI Parameters
HideShow
nextPageToken
string (optional) Default: null Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA

次のページの検索結果を取得するためのトークン。トークンが指定された場合、トークン発行時に指定された他のパラメータの値を引き継ぐ。

range
string (optional) Default: me Example: me

対象とする所有者の範囲

Choices: me all

type
array[eunm] (optional) Default: private Example: private

対象とするタグの種別。複数指定可能

Choices: private public shared

limit
number (optional) Default: 100 Example: 100

取得する一覧の上限。 1〜300 まで指定可能。


組織の共通仕様

ユーザオブジェクト

組織APIで使用するユーザを表すオブジェクト。

項目名 データ型 説明・入力ルール
TempId string
(ユーザ追加時 : required)
ユーザ追加時の一時的な識別子

入力ルール
・256文字以内
・半角英数のみ
・csv内で同一の TempId を指定することはできません
・ユーザ取得時は常に空白で出力されます
・ユーザ編集時は空白を指定します
UserUuid uuid
(ユーザ編集時 : required)
Sansan内でユーザを一意に区別する識別子

入力ルール
・ユーザ追加時は空白を指定します
・ユーザ編集時はユーザ追加時に生成された ID を指定します
DepartmentId string
(required)
ユーザが所属する部署の識別子

入力ルール
・セミコロン (;) 区切りで複数部署の指定が可能です
・既存の部署に所属させる場合は DepartmentId を指定してください
・新規の部署に所属させる場合は部署の TempId を指定してください

例:
新規部署の場合はtempId:xxxxxxxxxx
既存部署の場合は0000000001
UserId string
(required)
Sansan内でユーザを一意に区別する表示用の識別子

入力ルール
・半角英数、記号 (.-_&) のみ
・20文字以内
・追加後に変更することはできません
UserName string
(required)
ユーザ名

入力ルール
・60文字以内
AlternativeName string
(optional)
ユーザ名の読み

入力ルール
・256文字以内
Email string
(required)
ユーザのメールアドレス

入力ルール
・半角英数、記号のみ
・60文字以内
・企業内で同一メールアドレスを指定できません
SubEmail string
(optional)
ユーザのサブメールアドレス

入力ルール
・半角英数、記号のみ
・60文字以内
EffectiveDateFrom string
(ユーザ追加時 : required)
Sansan の利用を開始する日

入力ルール
・本日以降の日付であること
RFC3339 に準拠していること
・利用開始後に変更することはできません
・ユーザ取得APIから取得された場合はハイフン (-) 区切りです
・ユーザ編集時に空白の場合は、変更無しとなります
Culture int
(optional)
Sansan を利用する際の表示言語

入力ルール
・日本語の場合は0を入力
・英語の場合は1を入力
・中国語 (簡体) の場合は2を入力
・ユーザ追加時に空白の場合は API を実行したユーザの表示言語となります
・ユーザ編集時に空白の場合は、変更無しとなります
MailFormat int
(optional)
メール受信形式

入力ルール
・HTML形式の場合は0を入力
・TEXT形式の場合は1を入力
・ユーザ追加時に空白の場合は、HTML形式となります
・ユーザ編集時に空白の場合は、変更無しとなります
SamlNameId string
(optional)
SAML認証用の識別子

入力ルール
・企業内で同一のSAML Name IDを指定できません
UserType int
(optional)
ユーザ区分

入力ルール
・一般ユーザの権限を付与する場合は 0 を入力
・システム管理者の権限を付与する場合は 1 を入力
・部門管理者の権限を付与する場合は 2 を入力
・ユーザ追加時に空白の場合は、一般ユーザの権限が付与されます
・ユーザ編集時に空白の場合は、変更無しとなります
CanUpdateData int
(optional)
全データを更新できる権限

入力ルール
・権限を付与する場合は 1 を入力
・権限を付与しない場合は 0 を入力
・ユーザ追加時に空白の場合は、権限が付与されません
・ユーザ編集時に空白の場合は、変更無しとなります
DataDownloadPrivilege int
(optional)
名刺・コンタクトをダウンロードできる権限

入力ルール
・マイデータのみのダウンロード権限を付与する場合は 1 を入力
・全データのダウンロード権限を付与する場合は 2 を入力
・指定部署のダウンロード権限を付与する場合は 3 を入力
・権限を付与しない場合は 0 を入力
・ユーザ追加時に空白の場合は、権限が付与されません
・ユーザ編集時に空白の場合は、変更無しとなります
・指定部署のダウンロード権限を付与した場合は、所属部署に対してダウンロード権限が付与されます
EmailDeliveryPrivilege int
(optional)
メール配信を利用できる権限

入力ルール
・権限を付与する場合は 1 を入力
・権限を付与しない場合は 0 を入力
・ユーザ追加時に空白の場合は、権限が付与されません
・ユーザ編集時に空白の場合は、変更無しとなります
SalesforceIntegrationPrivilege - 名刺データを Salesforce へ連携できる権限
(本権限は廃止されました。処理対象外のため、入力内容は無視されますが、csv内の列は削除しないでください。)
DealPrivilege int
(optional)
案件管理を利用できる権限

入力ルール
・一般ユーザとしての利用権限を付与する場合は 1 を入力
・管理者の権限を付与する場合は 2 を入力
・権限を付与しない場合は 0 を入力
・ユーザ追加時に空白の場合は、権限が付与されません
・ユーザ編集時に空白の場合は、変更無しとなります
ApiIntegrationPrivilege int
(optional)
API連携を利用できる権限

入力ルール
・権限を付与する場合は 1 を入力
・権限を付与しない場合は 0 を入力
・ユーザ追加時に空白の場合は、権限が付与されません
・ユーザ編集時に空白の場合は、変更無しとなります
UsageStatisticsPrivilege int
(optional)
Sansan の利用実績を確認できる権限

入力ルール
・権限を付与する場合は 1 を入力
・権限を付与しない場合は 0 を入力
・ユーザ追加時に空白の場合は、権限が付与されません
・ユーザ編集時に空白の場合は、変更無しとなります
OrganizationTreeDownloadPrivilege int
(optional)
組織ツリーをダウンロードできる権限

入力ルール
・権限を付与する場合は 1 を入力
・権限を付与しない場合は 0 を入力
・ユーザ追加時に空白の場合は、権限が付与されません
・ユーザ編集時に空白の場合は、変更無しとなります
DeleteFlag int
(optional)
ユーザを削除する際に使うフラグ

入力ルール
・ユーザを削除する場合は 1 を入力
・ユーザ追加時に空白の場合は、ユーザが削除されません
・ユーザ編集時に空白の場合は、変更無しとなります

部署オブジェクト

組織APIで使用する部署を表すオブジェクト。

項目名 データ型 説明・入力ルール
TempId string
(部署追加時 : required)
部署追加時の一時的な識別子

入力ルール
・256文字以内
・半角英数のみ
・csv内で同一の TempId を指定できません
・部署取得時は常に空白で出力されます
・部署編集時は空白を指定します
DepartmentId string
(部署編集時 : required)
部署の識別子

入力ルール
・部署編集時には部署追加時に生成された ID を指定します
・部署追加時は空白を指定します
DepartmentName string
(required)
部署名

入力ルール
・30文字以内
DepartmentNamePhonetic string
(optional)
部署名の読み

入力ルール
・256文字以内
・小文字のローマ字
・数字
・半角スペース
ParentDepartmentId string
(optional)
親部署 (階層構造上、上階に存在する部署) の識別子

入力ルール
・既存の部署を親部署にする場合は部署追加時に生成された DepartmentId を指定してください
・新規の部署を親部署にする場合は新規部署の TempId を指定してください
・親部署が存在しない場合は空白を指定します

例:
新規部署の場合は tempId:xxxxxxxxxx
既存部署の場合は 0000000001
Order int
(optional)
部署の並び順
DeleteFlag int
(optional)
部署を削除する際に使うフラグ

入力ルール
・部署を削除する場合は 1 を入力
・配下に部署が存在する場合は削除できません
・ユーザが所属している場合は削除できません

組織インポート結果オブジェクト

組織インポートの結果を表すオブジェクト

項目名 データ型 説明・入力ルール
Type int
(required)
結果の種別

入力ルール
・部署の場合は 0 を入力
・ユーザの場合は 1 を入力
Id string
(optional)
元のデータを特定するための識別子

入力ルール
・部署の場合は DepartmentId
・ユーザの場合は UserUuid
・既存の部署、ユーザの場合はリクエストされた値が設定されます
・新規の部署、ユーザの場合は Completed が true の場合に生成された ID が設定されます
TempId string
(optional)
ユーザ、部署追加時の一時的な識別子

入力ルール
・リクエストされた値が設定されます
Completed bool
(required)
組織インポートの実行結果

入力ルール
・組織インポートに成功した場合は true
・組織インポートに失敗した場合は false
ErrorMessage string
(optional)
エラーメッセージ

入力ルール
Completed が false の場合にエラーの詳細が設定されます
・同一の部署、ユーザで複数のエラーが発生した場合はエラーの詳細はセミコロン (;) 区切りで設定されます

組織API

組織API では Sansan にある自社の部署情報およびユーザ情報にアクセスできます。
システム管理者のみ利用可能です。

ユーザ取得

GET https://api.sansan.com/v2.3/organization/users?delimiter=comma
Responses200400

ユーザオブジェクトがcsv形式で返ります

Headers
Content-Type: text/csv
Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "InternalServerError",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "エラー種別"
    },
    "message": {
      "type": "string",
      "description": "エラーメッセージ"
    },
    "error": {
      "type": "array",
      "description": "種別毎の詳細情報"
    }
  }
}

ユーザ取得
GET/organization/users{?delimiter}

Sansan に登録されたユーザを取得します。レスポンスはcsv形式 (ヘッダ行無し) です。

URI Parameters
HideShow
delimiter
string (optional) Default: comma Example: comma

csv形式のレスポンスの区切り文字

Choices: comma semicolon tab space


部署取得

GET https://api.sansan.com/v2.3/organization/departments?delimiter=comma
Responses200400

部署オブジェクトがcsv形式で返ります

Headers
Content-Type: text/csv
Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "InternalServerError",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "エラー種別"
    },
    "message": {
      "type": "string",
      "description": "エラーメッセージ"
    },
    "error": {
      "type": "array",
      "description": "種別毎の詳細情報"
    }
  }
}

部署取得
GET/organization/departments{?delimiter}

Sansan に登録された部署を取得します。レスポンスはcsv形式 (ヘッダ行無し) です。

URI Parameters
HideShow
delimiter
string (optional) Default: comma Example: comma

csv形式のレスポンスの区切り文字

Choices: comma semicolon tab space


組織インポート予約

POST https://api.sansan.com/v2.3/organization/jobs?encoding=utf8&delimiter=comma
Responses200400
Headers
Content-Type: application/json
Body
{
  "importId": "00000000-0000-0000-0000-000000000000"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "importId": {
      "type": "string",
      "description": "予約を特定するための一意のUUID"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "InternalServerError",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "エラー種別"
    },
    "message": {
      "type": "string",
      "description": "エラーメッセージ"
    },
    "error": {
      "type": "array",
      "description": "種別毎の詳細情報"
    }
  }
}

組織インポート予約
POST/organization/jobs{?encoding,delimiter}

部署とユーザのインポートを予約します。
部署とユーザは個別にインポートすることが可能です。

インポート開始時に部署データ、ユーザデータのチェックが行われ、1行でもエラーとなった場合はインポート処理は実行されません。

部署追加は DepartmentId が生成されます。
ユーザ追加は UserUuid が生成されます。
部署、ユーザの編集時に上記の生成された ID が必要なため、インポート完了したときは組織インポート結果取得を使用して ID を必ず取得してください。

この API によって生成された組織インポート予約を特定するための importId は必ず保管してください。

  • リクエストHeader

    X-Sansan-Api-Key: (APIキー)
    Content-Length: (リクエストBodyのサイズ)
    Content-Type: multipart/form-data; boundary="(任意のバウンダリ文字列)"
  • リクエストBody

    マルチパートでcsvファイルを送信します。

    --(任意のバウンダリ文字列)
    Content-Disposition: form-data; name="(データ種別)"; filename="(任意のファイル名)"
    
    (csvの内容)
    --(任意のバウンダリ文字列)--
    • リクエストHeaderとリクエストBodyの任意のバウンダリ文字列には同じものを設定します。 RFC7578 に従います。
      ただし、リクエストBody末尾には必ず改行コード(CR+LF)が必要です。

    • データ種別は、部署データの場合は department、ユーザデータの場合は user を設定します。

    • csvの内容は、部署データの場合は部署オブジェクトを、ユーザデータの場合はユーザオブジェクトを設定します。

URI Parameters
HideShow
encoding
string (optional) Default: utf8 Example: utf8

リクエストBodyの部署データ、ユーザデータのcsvファイルの文字コード

Choices: utf8 sjis

delimiter
string (optional) Default: comma Example: comma

リクエストBodyの部署データ、ユーザデータのcsvファイルの区切り文字

Choices: comma semicolon tab space


組織インポートデータチェック

POST https://api.sansan.com/v2.3/organization/check?encoding=utf8&delimiter=comma
Responses200400
  • すべてのデータが正常だった場合、レスポンスBodyは空が返ります

  • エラーがあった場合には、組織インポート結果オブジェクトがcsv形式で返ります

Headers
Content-Type: text/csv
Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "InternalServerError",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "エラー種別"
    },
    "message": {
      "type": "string",
      "description": "エラーメッセージ"
    },
    "error": {
      "type": "array",
      "description": "種別毎の詳細情報"
    }
  }
}

組織インポートデータチェック
POST/organization/check{?encoding,delimiter}

インポートする部署データ、ユーザデータを事前にチェックします。
部署データとユーザデータは個別にチェックすることが可能です。

部署データがエラーとなった場合はユーザデータのチェックは行われません。

  • リクエストHeader

    X-Sansan-Api-Key: (APIキー)
    Content-Length: (リクエストBodyのサイズ)
    Content-Type: multipart/form-data; boundary="(任意のバウンダリ文字列)"
  • リクエストBody

    マルチパートでcsvファイルを送信します。

    --(任意のバウンダリ文字列)
    Content-Disposition: form-data; name="(データ種別)"; filename="(任意のファイル名)"
    
    (csvの内容)
    --(任意のバウンダリ文字列)--
    • リクエストHeaderとリクエストBodyの任意のバウンダリ文字列には同じものを設定します。 RFC7578 に従います。
      ただし、リクエストBody末尾には必ず改行コード(CR+LF)が必要です。

    • データ種別は、部署データの場合は department、ユーザデータの場合は user を設定します。

    • csvの内容は、部署データの場合は部署オブジェクトを、ユーザデータの場合はユーザオブジェクトを設定します。

URI Parameters
HideShow
encoding
string (optional) Default: utf8 Example: utf8

リクエストBodyの部署データ、ユーザデータのcsvファイルの文字コード

Choices: utf8 sjis

delimiter
string (optional) Default: comma Example: comma

リクエストBodyの部署データ、ユーザデータのcsvファイルの区切り文字

Choices: comma semicolon tab space


組織インポートステータス確認

GET https://api.sansan.com/v2.3/organization/jobs/00000000-0000-0000-0000-000000000000
Responses200400
Headers
Content-Type: application/json
Body
{
  "importStatus": 0
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "importStatus": {
      "type": "number",
      "description": "ステータスを表す数値。0(予約中) 1(実行中) 2(完了) 9(エラー)"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "InternalServerError",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "エラー種別"
    },
    "message": {
      "type": "string",
      "description": "エラーメッセージ"
    },
    "error": {
      "type": "array",
      "description": "種別毎の詳細情報"
    }
  }
}

組織インポートステータス確認
GET/organization/jobs/{importId}

組織インポートのステータスを確認します。
ステータスが 2 (完了) または 9 (エラー) になった場合は、組織インポート結果取得を実行して結果を取得してください。

URI Parameters
HideShow
importId
string (required) Example: 00000000-0000-0000-0000-000000000000

組織インポート予約で生成された UUID


組織インポート結果取得

GET https://api.sansan.com/v2.3/organization/jobs/00000000-0000-0000-0000-000000000000/result
Responses200400

組織インポート結果オブジェクトがカンマ区切りのcsv形式で返ります

Headers
Content-Type: text/csv
Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "InternalServerError",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "エラー種別"
    },
    "message": {
      "type": "string",
      "description": "エラーメッセージ"
    },
    "error": {
      "type": "array",
      "description": "種別毎の詳細情報"
    }
  }
}

組織インポート結果取得
GET/organization/jobs/{importId}/result

組織インポートの実行結果を取得します。
組織インポートのステータスが 2 (完了) または 9 (エラー) の場合のみ結果が取得できます。
レスポンスはcsv形式 (ヘッダ行無し) です。

URI Parameters
HideShow
importId
string (required) Example: 00000000-0000-0000-0000-000000000000

組織インポート予約で生成された UUID


管理API

管理APIでは各ユーザの [設定] や [管理者設定] 等の情報にアクセスできます。
システム管理者のみ利用可能です。

利用するメールソフト

PUT https://api.sansan.com/v2.3/organizationSettings/emailClient
Requestsexample

emailClientには clientSoftware gmail office365 のいずれかを指定します。
clientSoftwareを指定した場合のみ、encodingをリクエストに含め sjis utf8 iso2022jp none のいずれかを指定します。

Headers
Content-Type: application/json
Body
{
  "emailClient": "clientSoftware",
  "encoding": "utf8"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "emailClient": {
      "type": "string",
      "description": "メールソフト"
    },
    "encoding": {
      "type": "string",
      "description": "文字コード"
    }
  }
}
Responses200400

設定された内容が返却されます。

Headers
Content-Type: application/json
Body
{
  "emailClient": "clientSoftware",
  "encoding": "utf8"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "emailClient": {
      "type": "string",
      "description": "メールソフト"
    },
    "encoding": {
      "type": "string",
      "description": "文字コード"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "If clientSoftware is specified for emailClient, encoding must be selected.",
  "error": [
    {
      "Code": "required",
      "field": "encoding"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "エラー種別"
    },
    "message": {
      "type": "string",
      "description": "エラーメッセージ"
    },
    "error": {
      "type": "array",
      "description": "種別毎の詳細情報"
    }
  }
}

利用メールソフト設定
PUT/organizationSettings/emailClient

利用するメールソフトの初期値を設定します。設定後に新規追加されるユーザに対して適用されます。
なお、このAPIで設定する内容は「初期値」であり、各ユーザが後から変更できます。


GET https://api.sansan.com/v2.3/organizationSettings/emailClient
Responses200204
Headers
Content-Type: application/json
Body
{
  "emailClient": "clientSoftware",
  "encoding": "utf8"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "emailClient": {
      "type": "string",
      "description": "メールソフト"
    },
    "encoding": {
      "type": "string",
      "description": "文字コード"
    }
  }
}

利用するメールソフトの初期値が未設定の場合に返却されます。

利用メールソフト取得
GET/organizationSettings/emailClient

現在設定されている利用メールソフトの初期値を取得します。


パートナープログラムのご案内

パートナープログラムとは Sansan API で連携された「商用アプリケーション」を提供する企業のためのプログラムです。パートナーをご希望の場合は partner-inquiry@sansan.com からお問合わせください。

Generated by aglio on 20 Nov 2023