Sansan Open API

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

The Sansan Open API is a programming interface for working with Sansan. By using the information from the business cards you have gotten, and linking it with other customer information and business information your company has, you can make your information more valuable, and push forward your business.

For Using APIs

For using APIs, API Terms of Use will apply; usage of the API will be considered consent to the API terms of usage.

Considerations for access restrictions

The access permissions when using APIs will depend on the API key given at the time of the request. API keys vary for each user, so by using the API key the user’s access permissions are carried forward. For example, if a user wishes to have access to all the business card data in Sansan from the application, the user who issues the API key must have the same permissions in Sansan.

Common Specifications

Summary

Below are the common specifications for using the API.

Item Explanation
API version 2.5
Protocol used HTTPS
Character set UTF-8

Request Header

When making a request to the API, the following common request header is needed.

Header Explanation
X-Sansan-App-Id Application ID issued from Sansan (alpha-numeric)
X-Sansan-Api-Key API Key issued to each Sansan user (32 byte, alpha-numeric)
  • X-Sansan-App-ID is necessary only for applications that have applied for the partner program.

What the partner program is

Response Header

There is no common HTTP response header returned by the server.

How to Call up the API

The Sansan Open API follows the rules of RESTful API design. Basically, standard HTTP methods are used to get a business card data resource.

API Key

For an API using application to access the Sansan Open API, an API key is needed. API keys can be issued by Sansan users, but this user needs to have advance permission to use APIs from the Sansan administrator inside their company. The issuing of API keys can be done from Settings of the upper right menu, or from Administrator Settings, then the screen for Integration with Other Services, and then by selecting API key.

Get an API Key

Issue API Key

Call up Limit to the API

The Sansan Open API is set to be called up at most 10 times in a second. Limits for calling up are distributed into each API Key, and if the set limit is exceeded, a special response will be returned. For more details, please see Error Code Chart . Please be aware that the calling up limit is subject to change without prior notice.

Cross-Domain Requests

The Sansan Open API doesn’t allow cross domain HTTP requests. Web browser cannot send requests with XMLHttpRequest to the Sansan Open API directly.

Call up Concurrency

Sansan Open API can be used in parallel instances. If an application needs to handle a large amount of information, you can improve performance by doing multiple,concurrent call-ups. However, please be aware that if you use the same API key for the concurrent call-ups, the upper limit for call-ups will apply. Also, if in a certain amount of time an exceedingly high number of process requests are received, please be aware that you may receive a special response that is the same as exceeding the limit for calling up.

Error Code Chart

If an error occurs while using the API, the following HTTP status codes will be returned. For some status codes, the error object arrangement, which shows the details of the error, will be returned. Status codes not written below (for example 200 or 203) conform to HTTP specifications.

Code Error Type Explanation
400 required Lacking mandatory parameters
invalid_value Request value is not valid
expired_token Token has expired
401 invalid_api_key Authentication error (API Key is not valid)
invalid_app_id Authentication error (Application ID is not valid)
403 has_no_permission Not allowed to use API
404 - The specified resource does not exist
409 conflict Conflict with other operation.
415 unsupported_media_type Content-Type is not valid
429 too_many_request Request amount exceeds limit.
access_count: Current access count.
retry_after: Amount of time
500 - Server error
503 - Server error

Common specifications for business cards, persons, and tags

Data Format of Response

The Sansan Open API will return the business card resource in the JSON format. To be more specific, it will be returned like this.

{
  "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": "brown@example.com", 
        "id": "brown", 
        "name": "William Brown"
      }, 
      "lastName": "Brown",
      "firstName": "William",
      "lastNameReading": null, 
      "firstNameReading": null, 
      "departmentName": "Information System Division",
      "title": null, 
      "email": "brown@example.com", 
      "mobile": "080-0000-0000", 
      "companyName": "ABC Electric, Inc",
      "countryCode": "JP",
      "postalCode": "1000001", 
      "address": "Tokyo Shibuya-ku Jingumae 1-1 Building 101",
      "prefecture": "Tokyo",
      "city": "Shibuya-ku", 
      "street": "Jingumae 1-1",
      "building": "Building 101",
      "tel": "0120-000-0000", 
      "secondTel": "0120-200-0000", 
      "fax": "0120-100-0000", 
      "url": "http://abcelectric.example.com", 
      "memo": "meet at a seminar",
      "entryStatus": "completed", 
      "isUserCreated": true,
      "tags": [
        {
          "id": "DLED3O4OE0MA78DQLWO21DBGE5GG8HYV",
          "name": "consultant",
          "type": "shared",
          "owner": {
            "email": "brown@example.com", 
            "id": "brown", 
            "name": "William Brown"
          }
        }
      ]
    }
  ]
}

Pagination

Requests that may return many collections/arrays, such as business card information, have a limited number of items per response. This is set with a limit (default of 100) on the number of acquisitions. Each response also contains a hasMore property and nextPageToken property. If hasMore is true, specify nextPageToken as a request parameter and continue. Please also note that nextPageToken expires 6 hours after requesting the first page.

Supplement (Conceptual diagram)

Business card status

Business cards have the following statuses. The related time-stamp can be used to sort.

The relationship between “holders” and “business cards that can be acquired”

Users who have business cards or tags are called holders. The range of business cards that can be acquired can be specified as “me” (only the cards held by oneself) or as “all” (all the cards within the range that can be viewed by oneself). Regarding the range that cannot be viewed by the holder, please see the help pages below.

Recognition as the same person

When two cards are determined to be from the same person, they are collated together. The card with the more recent date received will be the most recent card.

Business Card API

With the Business Card API you will only have access to the business card information held by your company in Sansan. Please be aware that you cannot access the business card information of other Sansan clients.

Business Card Set(Term Specified)

GET https://api.sansan.com/v2.5/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

List object which contains BizCard object as data. The order of the business cards is descending order of the data registered.

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": "brown",
        "name": "William Brown",
        "email": "brown@example.com"
      },
      "lastName": "Brown",
      "firstName": "William",
      "lastNameReading": "null",
      "firstNameReading": "null",
      "departmentName": "Information System Division",
      "title": "null",
      "email": "brown@example.com",
      "mobile": "080-0000-0000",
      "companyName": "ABC Electric, Inc",
      "countryCode": "JP",
      "postalCode": "1000001",
      "address": "Tokyo Shibuya-ku Jingumae 1-1 Building 101",
      "prefecture": "Tokyo",
      "city": "Shibuya-ku",
      "street": "Jingumae 1-1",
      "building": "Building 101",
      "tel": "0120-000-0000",
      "secondTel": "0120-200-0000",
      "fax": "0120-100-0000",
      "url": "http://abcelectric.example.com",
      "memo": "met at a seminar",
      "entryStatus": "completed",
      "isUserCreated": true,
      "tags": [
        {
          "Id": "DLED3O4OE0MA78DQLWO21DBGE5GG8HYV",
          "name": "Consultant",
          "type": "private",
          "owner": {
            "id": "brown",
            "name": "William Brown",
            "email": "brown@example.com"
          }
        }
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "hasMore": {
      "type": "boolean"
    },
    "nextPageToken": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  }
}

For more detail please see Error Code Chart

Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "required field not found.",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Business Card Set(Term Specified)
GET/bizCards{?updatedFrom,updatedTo,nextPageToken,includePastBizCards,range,entryStatus,orderBy,orderDirection,limit}

This will acquire a set of business card based on a specified term. The order of the business cards (Data below data key) is descending order of the data registered.

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

Data Card Registered, format: “YYYY-MM-DDThh:mm:ssTZD”

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

Data Card Registered, format: “YYYY-MM-DDThh:mm:ssTZD”

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

This is a token for acquring the search results from the next page. If a token is specified, it will inherit the values ​​of other parameters specified when issuing it.

includeTags
boolean (optional) Default: false Example: false

When attaching or removing tags, or changing tag names or types, treat this as changing a BizCard object and include tag information in the response.

Choices: true false

includePastBizCards
boolean (optional) Default: false Example: false

This includes previous business card information.

Choices: true false

range
string (optional) Default: me Example: me

Range of holders for acquisition

Choices: me all

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

Specify data condition for business cards to be acquired. Multiple specifications are possible. (example: …/bizCards?entryStatus=completed&entryStatus=processing&…)

Choices: processing completed unreadable

orderBy
string (optional) Default: updatedAt Example: updatedAt

Properties to be used for the order of business cards included in the response.

Choices: registeredAt completedAt updatedAt

orderDirection
string (optional) Default: asc Example: asc

Order of business cards included in the response

Choices: asc desc

limit
number (optional) Default: 100 Example: 100

Upper limit for list to be acquired from 1 to 300 can be specified.


Business Card Set(Conditions Specified)

GET https://api.sansan.com/v2.5/bizCards/search?nextPageToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA&includePastBizCards=false&range=me&companyName=ABC Electric, inc.&name=William Brown&email=brown@example.com&tel=0120-000-0000&mobile=080-0000-0000&tagId=DLED3O4OE0MA78DQLWO21DBGE5GG8HYV&entryStatus=completed&orderBy=registeredAt&orderDirection=desc&limit=100
Responses200400

List object which contains BizCard object as data. The order of BizCard object is descending order of the data registered.

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": "brown",
        "name": "William Brown",
        "email": "brown@example.com"
      },
      "lastName": "Brown",
      "firstName": "William",
      "lastNameReading": "null",
      "firstNameReading": "null",
      "departmentName": "Information System Division",
      "title": "null",
      "email": "brown@example.com",
      "mobile": "080-0000-0000",
      "companyName": "ABC Electric, Inc",
      "countryCode": "JP",
      "postalCode": "1000001",
      "address": "Tokyo Shibuya-ku Jingumae 1-1 Building 101",
      "prefecture": "Tokyo",
      "city": "Shibuya-ku",
      "street": "Jingumae 1-1",
      "building": "Building 101",
      "tel": "0120-000-0000",
      "secondTel": "0120-200-0000",
      "fax": "0120-100-0000",
      "url": "http://abcelectric.example.com",
      "memo": "met at a seminar",
      "entryStatus": "completed",
      "isUserCreated": true,
      "tags": [
        {
          "Id": "DLED3O4OE0MA78DQLWO21DBGE5GG8HYV",
          "name": "Consultant",
          "type": "private",
          "owner": {
            "id": "brown",
            "name": "William Brown",
            "email": "brown@example.com"
          }
        }
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "hasMore": {
      "type": "boolean"
    },
    "nextPageToken": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  }
}

For more detail please see Error Code Chart

Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "required field not found.",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Business Card Set(Conditions Specified)
GET/bizCards/search{?nextPageToken,includePastBizCards,range,companyName,name,email,tel,mobile,tagId,entryStatus,orderBy,orderDirection,limit}

This will acquire a set of business cards based on specified conditions. The order of business cards ( data under the data key) is descending order of the data registered.

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

This is a token for acquring the search results from the next page. If a token is specified, it will inherit the values ​​of other parameters specified when issuing it.

includeTags
boolean (optional) Default: false Example: false

When attaching or removing tags, or changing tag names or types, treat this as changing a BizCard object and include tag information in the response.

Choices: true false

includePastBizCards
boolean (optional) Default: false Example: false

This includes previous business card information.

Choices: true false

range
string (optional) Default: me Example: me

Range of holders for acquisition

Choices: me all

companyName
string (optional) Example: ABC Electric, inc.

Partial match search for Company Name is Sansan.

name
string (optional) Example: William Brown

Prefix match search for person in Sansan.

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

Complete match search for Email in Sansan.

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

Partial match search for Telephone Number in Sansan.

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

Partial match search for Mobile Phone Number in Sansan.

tagId
string (optional) Example: DLED3O4OE0MA78DQLWO21DBGE5GG8HYV

Multiple specifications for Tag IDs in Sansan. (This can be acquired at the Tag Set acquisition API ). Multiple specifications are possible. (e.g.: …/bizCards/search?tagId=tag1&tagId=tag2&…)

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

Specify data condition for business cards to be acquired.Multiple specifications are possible. (example: …/bizCards?entryStatus=completed&entryStatus=processing&…)

Choices: processing completed unreadable

orderBy
string (optional) Default: registeredAt Example: registeredAt

Properties to be used for the order of business cards included in the response.

Choices: registeredAt completedAt updatedAt

orderDirection
string (optional) Default: desc Example: desc

Order of business cards included in the response.

Choices: asc desc

limit
number (optional) Default: 100 Example: 100

Upper limit for list to be acquired from 1 to 300 can be specified.


Business Card

GET https://api.sansan.com/v2.5/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": "brown",
    "name": "William Brown",
    "email": "brown@example.com"
  },
  "lastName": "Brown",
  "firstName": "William",
  "lastNameReading": "null",
  "firstNameReading": "null",
  "departmentName": "Information System Division",
  "title": "null",
  "email": "brown@example.com",
  "mobile": "080-0000-0000",
  "companyName": "ABC Electric, Inc",
  "countryCode": "JP",
  "postalCode": "1000001",
  "address": "Tokyo Shibuya-ku Jingumae 1-1 Building 101",
  "prefecture": "Tokyo",
  "city": "Shibuya-ku",
  "street": "Jingumae 1-1",
  "building": "Building 101",
  "tel": "0120-000-0000",
  "secondTel": "0120-200-0000",
  "fax": "0120-100-0000",
  "url": "http://abcelectric.example.com",
  "memo": "met at a seminar",
  "entryStatus": "completed",
  "isUserCreated": true,
  "tags": [
    {
      "Id": "DLED3O4OE0MA78DQLWO21DBGE5GG8HYV",
      "name": "Consultant",
      "type": "private",
      "owner": {
        "id": "brown",
        "name": "William Brown",
        "email": "brown@example.com"
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Business Card ID"
    },
    "companyId": {
      "type": "string",
      "description": "Company ID"
    },
    "personId": {
      "type": "string",
      "description": "Person ID"
    },
    "exchangeDate": {
      "type": "string",
      "description": "Data Card Received, format: YYYY-MM-DD"
    },
    "registeredTime": {
      "type": "string",
      "description": "Data Card Registered, format: YYYY-MM-DDThh:mm:ssTZD"
    },
    "updatedTime": {
      "type": "string",
      "description": "Data Card Updated, format: YYYY-MM-DDThh:mm:ssTZD"
    },
    "owner": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "User ID"
        },
        "name": {
          "type": "string",
          "description": "Name"
        },
        "email": {
          "type": "string",
          "description": "Email"
        }
      },
      "description": "User object which shows the holder"
    },
    "lastName": {
      "type": "string",
      "description": "Last Name"
    },
    "firstName": {
      "type": "string",
      "description": "First Name"
    },
    "lastNameReading": {
      "type": [
        "string",
        "null"
      ],
      "description": "Last Name spelled in Japanese Kana"
    },
    "firstNameReading": {
      "type": [
        "string",
        "null"
      ],
      "description": "First Name spelled in Japanese Kana"
    },
    "departmentName": {
      "type": "string",
      "description": "Department Name"
    },
    "title": {
      "type": [
        "string",
        "null"
      ],
      "description": "Title"
    },
    "email": {
      "type": "string",
      "description": "Email"
    },
    "mobile": {
      "type": "string",
      "description": "Mobile Phone Number"
    },
    "companyName": {
      "type": "string",
      "description": "Company Name"
    },
    "countryCode": {
      "type": "string",
      "description": "Country code (ISO 3166-1 alpha-2 format)"
    },
    "postalCode": {
      "type": "string",
      "description": "Zip Code"
    },
    "address": {
      "type": "string",
      "description": "Address. String concatenate prefecture, city, street address and building."
    },
    "prefecture": {
      "type": "string",
      "description": "Prefecture"
    },
    "city": {
      "type": "string",
      "description": "City"
    },
    "street": {
      "type": "string",
      "description": "Street address"
    },
    "building": {
      "type": "string",
      "description": "Building Name"
    },
    "tel": {
      "type": "string",
      "description": "Phone Number"
    },
    "secondTel": {
      "type": "string",
      "description": "Phone number2"
    },
    "fax": {
      "type": "string",
      "description": "FAX Number"
    },
    "url": {
      "type": "string",
      "description": "URL"
    },
    "memo": {
      "type": "string",
      "description": "Memo attached to business card"
    },
    "entryStatus": {
      "type": "string",
      "enum": [
        "completed",
        "processing",
        "unreadable"
      ],
      "description": "Processing: This business card is currently being processed. completed: The data entry for this business card is completed. unreadable: This business card could not be processed."
    },
    "isUserCreated": {
      "type": "boolean",
      "description": "Is this a user created business card? true: business card created by a user or business card import. false: business card created via scanner or software that has been digitized by Sansan."
    },
    "tags": {
      "type": "array",
      "description": "Tag object linked to business card"
    }
  }
}

For more detail please see Error Code Chart

Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "required field not found.",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Business Card
GET/bizCards/{id}

Return a business card which holds the specified Business Card ID. If the business card in question is recognized as being from the same person within the cards of one business card holder, business card displaying the most recent business card resulting from the same person identification will be returned. In this case, the Business card ID specified in the parameters will be different from the ID of business card returned.

URI Parameters
HideShow
id
string (required) Example: DLED3O4OE0MA78DQLWO21DBGE5GG8HYV

Identify a business card in Sansan

includeTags
boolean (optional) Default: false Example: false

When attaching or removing tags, or changing tag names or types, treat this as changing a BizCard object and include tag information in the response.

Choices: true false


Business Card Image

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

Image data of the business card in JPEG format.

Headers
Content-Type: image/jpeg

For more detail please see Error Code Chart

Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "required field not found.",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Business Card Image
GET/bizCards/{id}/image{?side}

The image data of the business card with the specified BizCard ID will be returned in JPEG format. Business cards have images of both the front and the reverse of the card. You can specify which side’s image to retrieve with side parameters.

URI Parameters
HideShow
id
string (required) Example: DLED3O4OE0MA78DQLWO21DBGE5GG8HYV

Identify a business card in Sansan

side
string (optional) Default: front Example: front

Specify the front or reverse of the business card image

Choices: front back


Tag Set Assigned to a Business Card

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

List object which contains Tag object as data.

Headers
Content-Type: application/json
Body
{
  "hasMore": true,
  "nextPageToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA",
  "data": [
    {
      "Id": "DLED3O4OE0MA78DQLWO21DBGE5GG8HYV",
      "name": "Consultant",
      "type": "private",
      "owner": {
        "id": "brown",
        "name": "William Brown",
        "email": "brown@example.com"
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "hasMore": {
      "type": "boolean"
    },
    "nextPageToken": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  }
}

For more detail please see Error Code Chart

Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "required field not found.",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Tag Set Assigned to a Business Card
GET/bizCards/{id}/tags{?nextPageToken,limit}

This will acquire a set of tag assigned to a specified business card.

URI Parameters
HideShow
id
string (required) Example: DLED3O4OE0MA78DQLWO21DBGE5GG8HYV

Identify a business card in Sansan

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

This is a token for acquring the search results from the next page. If a token is specified, it will inherit the values ​​of other parameters specified when issuing it.

limit
number (optional) Default: 100 Example: 100

Upper limit for list to be acquired from 1 to 300 can be specified.


Person API

With the Person API you will only have access to the business card information held by your company in Sansan. Please be aware that you cannot access the business card information of other Sansan clients.

Person

GET https://api.sansan.com/v2.5/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": "brown",
      "name": "William Brown",
      "email": "brown@example.com"
    },
    "lastName": "Brown",
    "firstName": "William",
    "lastNameReading": "null",
    "firstNameReading": "null",
    "departmentName": "Information System Division",
    "title": "null",
    "email": "brown@example.com",
    "mobile": "080-0000-0000",
    "companyName": "ABC Electric, Inc",
    "countryCode": "JP",
    "postalCode": "1000001",
    "address": "Tokyo Shibuya-ku Jingumae 1-1 Building 101",
    "prefecture": "Tokyo",
    "city": "Shibuya-ku",
    "street": "Jingumae 1-1",
    "building": "Building 101",
    "tel": "0120-000-0000",
    "secondTel": "0120-200-0000",
    "fax": "0120-100-0000",
    "url": "http://abcelectric.example.com",
    "memo": "met at a seminar",
    "entryStatus": "completed",
    "isUserCreated": true,
    "tags": [
      {
        "Id": "DLED3O4OE0MA78DQLWO21DBGE5GG8HYV",
        "name": "Consultant",
        "type": "private",
        "owner": {
          "id": "brown",
          "name": "William Brown",
          "email": "brown@example.com"
        }
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Person ID"
    },
    "headBizCard": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Business Card ID"
        },
        "companyId": {
          "type": "string",
          "description": "Company ID"
        },
        "personId": {
          "type": "string",
          "description": "Person ID"
        },
        "exchangeDate": {
          "type": "string",
          "description": "Data Card Received, format: YYYY-MM-DD"
        },
        "registeredTime": {
          "type": "string",
          "description": "Data Card Registered, format: YYYY-MM-DDThh:mm:ssTZD"
        },
        "updatedTime": {
          "type": "string",
          "description": "Data Card Updated, format: YYYY-MM-DDThh:mm:ssTZD"
        },
        "owner": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "User ID"
            },
            "name": {
              "type": "string",
              "description": "Name"
            },
            "email": {
              "type": "string",
              "description": "Email"
            }
          },
          "description": "User object which shows the holder"
        },
        "lastName": {
          "type": "string",
          "description": "Last Name"
        },
        "firstName": {
          "type": "string",
          "description": "First Name"
        },
        "lastNameReading": {
          "type": [
            "string",
            "null"
          ],
          "description": "Last Name spelled in Japanese Kana"
        },
        "firstNameReading": {
          "type": [
            "string",
            "null"
          ],
          "description": "First Name spelled in Japanese Kana"
        },
        "departmentName": {
          "type": "string",
          "description": "Department Name"
        },
        "title": {
          "type": [
            "string",
            "null"
          ],
          "description": "Title"
        },
        "email": {
          "type": "string",
          "description": "Email"
        },
        "mobile": {
          "type": "string",
          "description": "Mobile Phone Number"
        },
        "companyName": {
          "type": "string",
          "description": "Company Name"
        },
        "countryCode": {
          "type": "string",
          "description": "Country code (ISO 3166-1 alpha-2 format)"
        },
        "postalCode": {
          "type": "string",
          "description": "Zip Code"
        },
        "address": {
          "type": "string",
          "description": "Address. String concatenate prefecture, city, street address and building."
        },
        "prefecture": {
          "type": "string",
          "description": "Prefecture"
        },
        "city": {
          "type": "string",
          "description": "City"
        },
        "street": {
          "type": "string",
          "description": "Street address"
        },
        "building": {
          "type": "string",
          "description": "Building Name"
        },
        "tel": {
          "type": "string",
          "description": "Phone Number"
        },
        "secondTel": {
          "type": "string",
          "description": "Phone number2"
        },
        "fax": {
          "type": "string",
          "description": "FAX Number"
        },
        "url": {
          "type": "string",
          "description": "URL"
        },
        "memo": {
          "type": "string",
          "description": "Memo attached to business card"
        },
        "entryStatus": {
          "type": "string",
          "enum": [
            "completed",
            "processing",
            "unreadable"
          ],
          "description": "Processing: This business card is currently being processed. completed: The data entry for this business card is completed. unreadable: This business card could not be processed."
        },
        "isUserCreated": {
          "type": "boolean",
          "description": "Is this a user created business card? true: business card created by a user or business card import. false: business card created via scanner or software that has been digitized by Sansan."
        },
        "tags": {
          "type": "array",
          "description": "Tag object linked to business card"
        }
      },
      "description": "Business card object which shows main information about this person."
    }
  }
}

For more detail please see Error Code Chart

Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "required field not found.",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Person
GET/persons/{id}

Information about the person specified by the Person ID will be acquired. If this business card has been identified as the same person as another, the BizCard object displaying the most recent business card resulting from the same person identification will be returned.

URI Parameters
HideShow
id
string (required) Example: F11E1A1B94EE2B4AB3F01A30C17527C7

Identify a business card in Sansan

includeTags
boolean (optional) Default: false Example: false

When attaching or removing tags, or changing tag names or types, treat this as changing a BizCard object and include tag information in the response.

Choices: true false


Reports API

The Report API allows you to access only your company’s data.

Get Report Set

GET https://api.sansan.com/v2.5/reports?updatedFrom=2015-08-21T11:29:39+09:00&updatedTo=2015-08-22T11:29:39+09:00&nextPageToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJzYW5zYW4iLCJleHAiOiIxNTU0MjE1MjY0IiwiU25hcHNob3RJZCI6ImVhMDdhZTY4LTZlY2UtNDRkYS1iNmFhLTU5Zjk5ZDRlMWRlOSIsIkNodW5rSWQiOiIwIiwiTGltaXQiOiIzMDAiLCJPZmZzZXQiOiIzMDAiLCJPcmRlckJ5IjoicmVnaXN0ZXJlZEF0IiwiT3JkZXJEaXJlY3Rpb24iOiJhc2MifQ.Y9ZK5vvxyazGIHo_dj2USrXdR9DDHlW0r6lWJADXYZ8&category=Category&type=Email&range=me&orderBy=updatedAt&orderDirection=desc&limit=100
Responses200400

List object with a data property containing Report objects. The report objects order is by default the date when it was created. If the report object is of type BizCardExchange the startTime and endTime will be null. For all other types startDate and endDate will be null.

Headers
Content-Type: application/json
Body
{
  "hasMore": true,
  "nextPageToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA",
  "data": [
    {
      "id": "37171BA646FABCEDWASDDSDE7403AAAA",
      "registeredTime": "2015-08-21T12:40:39+09:00",
      "updatedTime": "2015-08-22T10:05:01+09:00",
      "startDate": "2015-08-20",
      "endDate": "2015-08-20",
      "startTime": "2015-08-20T11:00:00+09:00",
      "endTime": "2015-08-20T12:00:00+09:00",
      "owner": {
        "id": "brown",
        "name": "William Brown",
        "email": "brown@example.com"
      },
      "externalAttendees": [
        {
          "id": "ABCDAB169LFDSWC8F0960DEPLODAAAAV",
          "personId": "09MJ8G1BER242B4AB3F0UDX8WW17AAAA",
          "companyName": "44 Corporation",
          "lastName": "Yamada",
          "firstName": "Kenji"
        }
      ],
      "internalAttendees": [
        {
          "id": "brown",
          "name": "William Brown",
          "departmentName": "Information System Division"
        }
      ],
      "type": "Meeting",
      "categories": [
        {
          "name": "category",
          "value": "proposal"
        }
      ],
      "title": "online meeting",
      "location": "meeting room A",
      "memo": "Conducted an online meeting with Mr. Yamada."
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "hasMore": {
      "type": "boolean"
    },
    "nextPageToken": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  }
}

For more detail please see Error Code Chart

Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "required field not found.",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Get Report Set
GET/reports{?updatedFrom,updatedTo,nextPageToken,category,type,range,orderBy,orderDirection,limit}

Get a Set of reports. The reports are ordered by update time.

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

Report update time (YYYY-MM-DDThh:mm:ssTZD)

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

Report update time (YYYY-MM-DDThh:mm:ssTZD)

nextPageToken
string (optional) Default: null Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJzYW5zYW4iLCJleHAiOiIxNTU0MjE1MjY0IiwiU25hcHNob3RJZCI6ImVhMDdhZTY4LTZlY2UtNDRkYS1iNmFhLTU5Zjk5ZDRlMWRlOSIsIkNodW5rSWQiOiIwIiwiTGltaXQiOiIzMDAiLCJPZmZzZXQiOiIzMDAiLCJPcmRlckJ5IjoicmVnaXN0ZXJlZEF0IiwiT3JkZXJEaXJlY3Rpb24iOiJhc2MifQ.Y9ZK5vvxyazGIHo_dj2USrXdR9DDHlW0r6lWJADXYZ8

Token for getting the next page (will keep the arguments supplied on creation i.e. previous requests arguments).

category
array[string] (optional) Default: null Example: Category

Search categories by exact match. Multiple inputs possible. (e.g. …/reports?category[]=Category1&category[]=Category2&…)

type
array[string] (optional) Default: null Example: Email

Search types by exact match. Multiple inputs possible. (e.g. …/reports?type[]=Meeting&type[]=Call&…)

Choices: Meeting Call Email BizCardExchange

range
string (optional) Default: me Example: me

Search by ownership.

Choices: me all

orderBy
string (optional) Default: updatedAt Example: updatedAt

Property which the reports will be ordered by.

Choices: registeredAt updatedAt

orderDirection
string (optional) Default: desc Example: desc

Order direction.

Choices: asc desc

limit
number (optional) Default: 100 Example: 100

Limitation of how many reports are returned.


Tag API

With the Tag API you will only have access to the business card information held by your company in Sansan. Please be aware that you cannot access the business card information of other Sansan clients.

Tag Set

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

List object which contains Tag object as data.

Headers
Content-Type: application/json
Body
{
  "hasMore": true,
  "nextPageToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA",
  "data": [
    {
      "Id": "DLED3O4OE0MA78DQLWO21DBGE5GG8HYV",
      "name": "Consultant",
      "type": "private",
      "owner": {
        "id": "brown",
        "name": "William Brown",
        "email": "brown@example.com"
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "hasMore": {
      "type": "boolean"
    },
    "nextPageToken": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  }
}

For more detail please see Error Code Chart

Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "required field not found.",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Tag Set
GET/tags{?nextPageToken,range,type,limit}

Acquires a tag list in Sansan.

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

This is a token for acquring the search results from the next page. If a token is specified, it will inherit the values ​​of other parameters specified when issuing it.

range
string (optional) Default: me Example: me

Range of holders for acquisition

Choices: me all

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

Multiple specifications for tag types. Multiple specifications are possible.

Choices: private public shared

limit
number (optional) Default: 100 Example: 100

Upper limit for list to be acquired from 1 to 300 can be specified.


Common specifications for organizations

User object

This is an object used in the organization API that represents a user.

Item name Data type Explanation, input rules
TempId string
(Required when adding users)
This is the temporary identifier used when adding users.

Input rules
・Must be 256 characters or less
・One-byte alphanumerics only
・The same TempId cannot be used more than once in one CSV.
・When acquiring users, this will be output as blank.
・When editing users, this is left blank.
UserUuid uuid
(Required when editing users)
This is the identifier to uniquely identify a user in Sansan.

Input rules
・When adding users, this is left blank.
・When editing users, this will specify the ID generated when the user was added.
DepartmentId string
(required)
This is the identifier for the department that the user belongs to.

Input rules
・By using semicolons (;) as separators, multiple departments can be specified.
・If this person will be put into an existing department, please specify the DepartmentId.
・If this person will be put into a new department, please specify the TempId.

For example:
For a new department:tempId:xxxxxxxxxx
For an existing department:0000000001
UserId string
(required)
This is the identifier for display that uniquely identifies a user in Sansan.

Input rules
・Only one-byte alphanumerics and symbols (.-_&)
・Must be 20 characters or less
・After adding, this cannot be changed.
UserName string
(required)
This is the user’s name.

Input rules
・Must be 60 characters or less
AlternativeName string
(optional)
This can use be used for alternative names or foreign language names (e.g. Chinese names). Foreign alphabets and characters may be used. This name can be used for searching and will appear on profiles.

Input rules
・Must be 256 characters or less
Email string
(required)
This is the user’s email address.

Input rules
・Only one-byte alphanumerics and symbols
・Must be 60 characters or less
・The same email address cannot be specified more than once in one company.
SubEmail string
(optional)
This is the user’s sub-email address.

Input rules
・Only one-byte alphanumerics and symbols
・Must be 60 characters or less
EffectiveDateFrom string
(Required when adding users)
This is the date when Sansan usage started.

Input rules
・This must be the present day or a day in the future.
・This must conform to RFC3339
・This cannot be changed after usage has begun.
・When this is acquired with the Acquire user API, hyphens (-) will be used as separators.
・If this is blank when editing users, no change will be made.
Culture int
(optional)
This is the display language when using Sansan.

Input rules
・For Japanese, input 0.
・For English, input 1.
・For Chinese (simplified), input 2.
・If this is blank when adding users, the display language of the user executing the API will be input.
・If this is blank when editing users, no change will be made.
MailFormat int
(optional)
This is the format for receiving emails.

Input rules
・For HTML, input 0.
・For Text, input 1.
・If this is blank when adding users, it will be set to HTML.
・If this is blank when editing users, no change will be made.
SamlNameId string
(optional)
This is the identifier for SAML authentication

Input rules
・You cannot duplicate the SAML Name ID within your company.
UserType int
(optional)
This is the user type.

Input rules
・To give regular user permission, input 0.
・To give system administrator permission, input 1.
・To give sectional administrator permission, input 2.
・If this is blank when adding users, regular user permission will be given.
・If this is blank when editing users, no change will be made.
CanUpdateData int
(optional)
This is the permission to update all data.

Input rules
・Input 1 to give this permission.
・Input 0 to not give this permission.
・If this is blank when adding users, permission will not be given.
・If this is blank when editing users, no change will be made.
DataDownloadPrivilege int
(optional)
This is the permission to download business cards and reports.

Input rules
・Input 1 to set as ‘own data’.
・Input 2 to set as ‘all data’.
・Input 3 to set as ‘custom’.
・Input 0 to disable downloads.
・If this is blank when adding users, permission will not be given.
・If this is blank when editing users, no change will be made.
・When a user’s download permission is to ‘custom’, the user will only have download permissions for specific departments.
EmailDeliveryPrivilege int
(optional)
This is the permission to use email delivery.

Input rules
・Input 1 to give this permission.
・Input 0 to not give this permission.
・If this is blank when adding users, permission will not be given.
・If this is blank when editing users, no change will be made.
SalesforceIntegrationPrivilege - This is the permission to link business card data with Salesforce.
(This permission has been removed. As it will not be processed, input will be ignored. However, please do not delete the column in the csv.)
DealPrivilege int
(optional)
This is the permission to use Deal management.

Input rules
・To given usage permission as a regular user, input 1.
・To give administrator permission, input 2.
・Input 0 to not give this permission.
・If this is blank when adding users, permission will not be given.
・If this is blank when editing users, no change will be made.
ApiIntegrationPrivilege int
(optional)
This is the permission to use API linking.

Input rules
・Input 1 to give this permission.
・Input 0 to not give this permission.
・If this is blank when adding users, permission will not be given.
・If this is blank when editing users, no change will be made.
UsageStatisticsPrivilege int
(optional)
This is the permission to check actual usage of Sansan.

Input rules
・Input 1 to give this permission.
・Input 0 to not give this permission.
・If this is blank when adding users, permission will not be given.
・If this is blank when editing users, no change will be made.
OrganizationTreeDownloadPrivilege int
(optional)
Input “1” to give this permission.

Input rules
・Input 1 to give this permission.
・Input 0 to not give this permission.
・If this is blank when adding users, permission will not be given.
・If this is blank when editing users, no change will be made.
DeleteFlag int
(optional)
This is the flag used to delete users.

Input rules
・To delete a user, input 1.
・If this is blank when adding users, the user will not be deleted.
・If this is blank when editing users, no change will be made.

Department object

This is an object used in the organization API that represents a department.

Item name Data type Explanation, input rules
TempId string
(Required when adding departments)
This is the temporary identifier used when adding departments.

Input rules
・Must be 256 characters or less
・One-byte alphanumerics only
・The same TempId cannot be used more than once in one CSV.
・When acquiring departments, this will be output as blank.
・When editing departments, this will be blank.
DepartmentId string
(Required when editing departments)
This is the department identifier.

Input rules
・When editing departments, this will specify the ID generated when the department was added.
・When adding departments, this will be blank.
DepartmentName string
(required)
This is the department’s name.

Input rules
・Must be 30 characters or less
DepartmentNamePhonetic string
(optional)
If the department’s name is not written alphabetically (e.g. in Chinese), you can enter the phonetic alphabetic reading of the name here.

Input rules
・Must be 256 characters or less
ParentDepartmentId string
(optional)
This is the identifier for a parent department (a department that is placed higher in a hierarchy).

Input rules
・If an existing department will be made into a parent department, please specify the DepartmentId.
・If a new department will be made into a parent department, please specify the TempId.
・If there is no parent department, this will be blank.

For example:
For a new department:tempId:xxxxxxxxxx
For an existing department:0000000001
Order int
(optional)
This is the display order of the department.
DeleteFlag int
(optional)
This is the flag used to delete departments.

Input rules
・To delete a department, input 1.
・If there is a department under this department, it cannot be deleted.
・If there is a user in the department, the department cannot be deleted.

Organization import result object

This is an object that represents the results of an organization import.

Item name Data type Explanation, input rules
Type int
(required)
Type of result

Input rules
・If this is a department, input 0.
・If this is a user, input 1.
Id string
(optional)
This is the identifier that specifies the original data.

Input rules
・If this is a department, then DepartmentId
・If this is a user, then UserUuid
・If this is an existing department or user, the requested value will be set.
・If this is a new department or user, the ID generated when Completed is true will be set.
TempId string
(optional)
This is the temporary identifier used when adding users or departments.

Input rules
・The requested value will be set.
Completed bool
(required)
This is the result of the organization import.

Input rules
・If the organization import is successful, then true.
・If the organization import failed, then false.
ErrorMessage string
(optional)
Error message

Input rules
・If Completed is false, then the details of the error will be set.
・If multiple errors occur in one department or one user, the details of the errors will be set, separated by semicolons (;).

Organization API

With the Organization API, you can access department information and user information of your own company in Sansan.
This can only be used by system administrators.

Acquire user

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

The user object will be returned in CSV format.

Headers
Content-Type: text/csv

For more detail please see Error Code Chart

Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "required field not found.",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Acquire user
GET/organization/users{?delimiter}

This will acquire users registered in Sansan. The response will be returned in CSV format (without headers).

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

Separator in the CSV format response

Choices: comma semicolon tab space


Acquire department

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

The department object will be returned in CSV format.

Headers
Content-Type: text/csv

For more detail please see Error Code Chart

Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "required field not found.",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Acquire department
GET/organization/departments{?delimiter}

This will acquire departments registered in Sansan. The response will be returned in CSV format (without headers).

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

Separator in the CSV format response

Choices: comma semicolon tab space


Organization import reservation

POST https://api.sansan.com/v2.5/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": "Unique UUID to specify the reservation"
    }
  }
}

For more detail please see Error Code Chart

Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "required field not found.",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Organization import reservation
POST/organization/jobs{?encoding,delimiter}

This will make a reservation to import departments and users.
Departments and users can be imported separately.

When the import begins, the department data and user data will be checked, and if there is an error in even one line, then the import processing will not be executed.

When a department is added, a DepartmentId is generated.
When a user is added, a UserUuid is generated.
When editing departments or users, the above IDs that were generated are necessary, so when the import is complete, do not forget to use Acquire organization import results to acquire the IDs.

To specify the Organization import reservation generated by this API, please keep track of the importID.

  • HTTP Request Header

    X-Sansan-Api-Key: (API key)
    Content-Length: (request body size)
    Content-Type: multipart/form-data; boundary="(optional boundary charater string)"
  • HTTP Request Body

    The CSV file will be sent as multi-part.

    --(optional boundary charater string)
    Content-Disposition: form-data; name="(data type)"; filename="(Optional file name)"
    
    (Contents of CSV)
    --(optional boundary charater string)--
    • The same discretionary boundary character string will be set for the request header and the request body. This will comply with RFC7578.
      However, a line feed code (CR+LF) is always required at the end of the request body.

    • For data types, department data will be set as department, and user data will be set as user.

    • The contents of the CSV for the department data will be a department object, and for the user data will be a user object.

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

Character code of the CSV file for the department data and user data of the request body

Choices: utf8 sjis

delimiter
string (optional) Default: comma Example: comma

Delimiter in the CSV file for the department data and user data of the request body

Choices: comma semicolon tab space


Organization import data check

POST https://api.sansan.com/v2.5/organization/check?encoding=utf8&delimiter=comma
Responses200400
  • If all of the data is correct, the response body will be returned blank.

  • If there is an error, the Organization import result object will be returned in CSV format.

Headers
Content-Type: text/csv

For more detail please see Error Code Chart

Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "required field not found.",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Organization import data check
POST/organization/check{?encoding,delimiter}

This will check, in advance, the department data and the user data to be imported.
It is possible to check the department data and the user data separately.

If there is an error in the department data, the user data cannot be checked.

  • HTTP Request Header

    X-Sansan-Api-Key: (API key)
    Content-Length: (request body size)
    Content-Type: multipart/form-data; boundary="(optional boundary charater string)"
  • HTTP Request Body

    The CSV file will be sent as multi-part.

    --(optional boundary charater string)
    Content-Disposition: form-data; name="(data type)"; filename="(Optional file name)"
    
    (Contents of CSV)
    --(optional boundary charater string)--
    • The same discretionary boundary character string will be set for the request header and the request body. This will comply with RFC7578.
      However, a line feed code (CR+LF) is always required at the end of the request body.

    • For data types, department data will be set as department, and user data will be set as user.

    • The contents of the CSV for the department data will be a department object, and for the user data will be a user object.

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

Character code of the CSV file for the department data and user data of the request body

Choices: utf8 sjis

delimiter
string (optional) Default: comma Example: comma

Delimiter in the CSV file for the department data and user data of the request body

Choices: comma semicolon tab space


Confirming status of the organization import

GET https://api.sansan.com/v2.5/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": "This value shows the status. '0' is reserved, '1' is currently being done, '2' is complete, and '9' is error."
    }
  }
}

For more detail please see Error Code Chart

Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "required field not found.",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Confirming status of the organization import
GET/organization/jobs/{importId}

This will check the status of the organization import. If the status is 2 (complete) or 9 (error), please use Acquire organization import results to acquire the results.

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

The UUID generated by the organization import reservation.


Acquiring organization import results

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

If there is an error, the Organization import result object will be returned in CSV format.

Headers
Content-Type: text/csv

For more detail please see Error Code Chart

Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "required field not found.",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Acquiring organization import results
GET/organization/jobs/{importId}/result

This will acquire the results of the organization import.
The will results can only be acquired if the organization import status is 2 (complete) or 9 (error).
The response will be a CSV file (without headers).

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

The UUID generated by the organization import reservation.


Management API

The Management API enables access to individual users’ Settings, Admin Settings, and other information.
This function is only available to the system administrator.

Departments

GET https://api.sansan.com/v2.5/admin/departments
Responses200400

List object with a data property containing Department objects. If more than 1,000 departments exists the data is paginated.

Headers
Content-Type: application/json
Body
{
  "hasMore": true,
  "nextPageToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkA",
  "data": [
    {
      "id": "E4BE95AF6211CD96BE7E5A1F4BF864D2",
      "name": "Sales Department",
      "parentId": "6A17AA48A0B28F2F02DCF87B72C87EA9"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "hasMore": {
      "type": "boolean"
    },
    "nextPageToken": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  }
}

For more detail please see Error Code Chart

Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "required field not found.",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Get department list
GET/admin/departments

Get a list of departments.


Access Privilege Settings

PUT https://api.sansan.com/v2.5/admin/accessControl/department/D5A1B659661A2D278E3488931007CA41
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "objectDepartmentIds": [
    "6A17AA48A0B28F2F02DCF87B72C87EA9",
    "E857D8C0F942869316436B58E4C087F9"
  ],
  "accessControlPattern": "ALL"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "objectDepartmentIds": {
      "type": "array",
      "description": "Department ID"
    },
    "accessControlPattern": {
      "type": "string",
      "description": "Access privileges pattern. If not specified, no privileges will be given."
    }
  },
  "required": [
    "objectDepartmentIds"
  ]
}
Responses200400409

The set privilieges will be returned.

Headers
Content-Type: application/json
Body
{
  "objectDepartmentIds": [
    "6A17AA48A0B28F2F02DCF87B72C87EA9",
    "E857D8C0F942869316436B58E4C087F9"
  ],
  "accessControlPattern": "ALL"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "objectDepartmentIds": {
      "type": "array",
      "description": "Department ID"
    },
    "accessControlPattern": {
      "type": "string",
      "description": "Access privileges pattern. If not specified, no privileges will be given."
    }
  },
  "required": [
    "objectDepartmentIds"
  ]
}

For more detail please see Error Code Chart

Headers
Content-Type: application/json
Body
{
  "statusCode": 400,
  "message": "required field not found.",
  "error": [
    {
      "Code": "required",
      "field": "email"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Temporarily unavailable until user import or organization import is complete.

For more detail please see Error Code Chart

Headers
Content-Type: application/json
Body
{
  "statusCode": 409,
  "message": "Conflict with UserImport.",
  "error": [
    {
      "Code": "conflict"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "number",
      "description": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Set access privilege settings
PUT/admin/accessControl/department/{id}

Specify the department ID of the department to set access privileges for.

URI Parameters
HideShow
id
string (required) Example: D5A1B659661A2D278E3488931007CA41

Department ID


Email software

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

For emailClient, specify clientSoftware, gmail, or office365.
After selecting clientSoftware, in the encoding request, choose UTF8 (recommended), SJIS, ISO2022JP, or none. This setting is not needed for Gmail or Office365.

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": "Email software"
    },
    "encoding": {
      "type": "string",
      "description": "Character code"
    }
  }
}
Responses200400

The specific settings are returned.

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": "Email software"
    },
    "encoding": {
      "type": "string",
      "description": "Character code"
    }
  }
}

For more detail please see Error Code Chart

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": "Error Status Code"
    },
    "message": {
      "type": "string",
      "description": "Error Message"
    },
    "error": {
      "type": "array",
      "description": "Error Details"
    }
  }
}

Email software settings
PUT/organizationSettings/emailClient

Defaults for email software can be set to be applied to new users after initial setup.
These are the initial settings, which users can later change.


GET https://api.sansan.com/v2.5/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": "Email software"
    },
    "encoding": {
      "type": "string",
      "description": "Character code"
    }
  }
}

Specific settings are returned when the initial settings are not established for the email software.

Acquiring email settings
GET/organizationSettings/emailClient

The current email software settings will be used as initial values.


Guidance to the Group Partner Program

The Partner Program is a program for companies that provide “Business applications” integrated with the Sansan API. If you would like to become a partner, please contact us from partner-inquiry@sansan.com.

Generated by aglio on 19 Jun 2023