Sansan Open API
API Endpoint
https://api.sansan.com/v2.3
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.3 |
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.
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.
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 |
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 |
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) ¶
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
}
]
}
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": "InternalServerError",
"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.
- updatedFrom
string
(required) Example: 2015-08-21T11:29:39+09:00Data Card Registered, format: “YYYY-MM-DDThh:mm:ssTZD”
- updatedTo
string
(required) Example: 2015-08-22T11:29:39+09:00Data Card Registered, format: “YYYY-MM-DDThh:mm:ssTZD”
- nextPageToken
string
(optional) Default: null Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkAThis 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.
- includePastBizCards
boolean
(optional) Default: false Example: falseThis includes previous business card information.
Choices:
true
false
- range
string
(optional) Default: me Example: meRange of holders for acquisition
Choices:
me
all
- entryStatus
array[enum]
(optional) Default: completed Example: completedSpecify 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: updatedAtProperties to be used for the order of business cards included in the response.
Choices:
registeredAt
completedAt
updatedAt
- orderDirection
string
(optional) Default: asc Example: ascOrder of business cards included in the response
Choices:
asc
desc
- limit
number
(optional) Default: 100 Example: 100Upper limit for list to be acquired from 1 to 300 can be specified.
Business Card Set(Conditions Specified) ¶
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
}
]
}
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": "InternalServerError",
"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.
- nextPageToken
string
(optional) Default: null Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkAThis 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.
- includePastBizCards
boolean
(optional) Default: false Example: falseThis includes previous business card information.
Choices:
true
false
- range
string
(optional) Default: me Example: meRange 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 BrownPrefix match search for person in Sansan.
string
(optional) Example: brown@example.comComplete match search for Email in Sansan.
- tel
string
(optional) Example: 0120-000-0000Partial match search for Telephone Number in Sansan.
- mobile
string
(optional) Example: 080-0000-0000Partial match search for Mobile Phone Number in Sansan.
- tagId
string
(optional) Example: DLED3O4OE0MA78DQLWO21DBGE5GG8HYVMultiple 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: completedSpecify 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: registeredAtProperties to be used for the order of business cards included in the response.
Choices:
registeredAt
completedAt
updatedAt
- orderDirection
string
(optional) Default: desc Example: descOrder of business cards included in the response.
Choices:
asc
desc
- limit
number
(optional) Default: 100 Example: 100Upper limit for list to be acquired from 1 to 300 can be specified.
Business Card ¶
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
}
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."
}
}
}
For more detail please see Error Code Chart
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": "Error Status Code"
},
"message": {
"type": "string",
"description": "Error Message"
},
"error": {
"type": "array",
"description": "Error Details"
}
}
}
Business CardGET/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.
- id
string
(required) Example: DLED3O4OE0MA78DQLWO21DBGE5GG8HYVIdentify a business card in Sansan
Business Card Image ¶
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": "InternalServerError",
"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 ImageGET/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.
- id
string
(required) Example: DLED3O4OE0MA78DQLWO21DBGE5GG8HYVIdentify a business card in Sansan
- side
string
(optional) Default: front Example: frontSpecify the front or reverse of the business card image
Choices:
front
back
Tag Set Assigned to a Business Card ¶
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": "InternalServerError",
"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 CardGET/bizCards/{id}/tags{?nextPageToken,limit}
This will acquire a set of tag assigned to a specified business card.
- id
string
(required) Example: DLED3O4OE0MA78DQLWO21DBGE5GG8HYVIdentify a business card in Sansan
- nextPageToken
string
(optional) Default: null Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkAThis 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: 100Upper 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 ¶
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
}
}
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."
}
},
"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": "InternalServerError",
"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"
}
}
}
PersonGET/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.
- id
string
(required) Example: F11E1A1B94EE2B4AB3F01A30C17527C7Identify a business card in Sansan
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 ¶
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": "InternalServerError",
"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 SetGET/tags{?nextPageToken,range,type,limit}
Acquires a tag list in Sansan.
- nextPageToken
string
(optional) Default: null Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJTbmFwc2hvdElkIjoiZDJjN2RmMGYtYmNhMy00YmZkLThiNTMtMmY0MmNjN2I2YTJlIiwiQ2h1bmtJZCI6IjAiLCJPZmZzZXQiOiIwIiwiZXhwIjoxNTE3MjIyNzI3LCJpc3MiOiJzYW5zYW4ifQ.tt2WABELFuZFmYUosxsiwK6deK36w-zUnL75T0vntkAThis 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: meRange of holders for acquisition
Choices:
me
all
- type
array[enum]
(optional) Default: private Example: privateMultiple specifications for tag types. Multiple specifications are possible.
Choices:
private
public
shared
- limit
number
(optional) Default: 100 Example: 100Upper 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 |
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 ¶
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": "InternalServerError",
"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 userGET/organization/users{?delimiter}
This will acquire users registered in Sansan. The response will be returned in CSV format (without headers).
- delimiter
string
(optional) Default: comma Example: commaSeparator in the CSV format response
Choices:
comma
semicolon
tab
space
Acquire department ¶
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": "InternalServerError",
"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 departmentGET/organization/departments{?delimiter}
This will acquire departments registered in Sansan. The response will be returned in CSV format (without headers).
- delimiter
string
(optional) Default: comma Example: commaSeparator in the CSV format response
Choices:
comma
semicolon
tab
space
Organization import reservation ¶
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": "InternalServerError",
"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 reservationPOST/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 asuser
. -
The contents of the CSV for the department data will be a
department object
, and for the user data will be auser object
.
-
- encoding
string
(optional) Default: utf8 Example: utf8Character 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: commaDelimiter in the CSV file for the department data and user data of the request body
Choices:
comma
semicolon
tab
space
Organization import data check ¶
-
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": "InternalServerError",
"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 checkPOST/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 asuser
. -
The contents of the CSV for the department data will be a
department object
, and for the user data will be auser object
.
-
- encoding
string
(optional) Default: utf8 Example: utf8Character 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: commaDelimiter 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 ¶
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": "InternalServerError",
"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 importGET/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.
- importId
string
(required) Example: 00000000-0000-0000-0000-000000000000The UUID generated by the
organization import reservation
.
Acquiring organization import results ¶
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": "InternalServerError",
"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 resultsGET/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).
- importId
string
(required) Example: 00000000-0000-0000-0000-000000000000The 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.
Email software ¶
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"
}
}
}
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 settingsPUT/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.
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 settingsGET/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 16 Apr 2024