Unipos Provisioning API ("API") can manage the following three resources:
Groups / Members / Positions
Index
・Common factors
┗ Requests
┗ Responses
┗ See below for the definitions of error codes when a transaction is failed.
┗ Limitations
・Groups
┗ Methods
┗ Group properties
┗ group.create Creating a group
┗ group.get Obtaining a group
┗ group.list Obtaining a list of groups
┗ group.delete Deleting a group
┗ group.update Updating a group
・Members
┗ Methods
┗ Member properties
┗ member.invite Inviting a member
┗ member.get Obtaining a member
┗ member.list Obtaining a list of members
┗ member.pause Suspending a member
┗ member.unpause Unsuspending a member
┗ member.delete Deleting a member
┗ member.update Updating a member
・Positions
┗ Methods
┗ Position properties
┗ position.create Creating a position
┗ position.get Obtaining a position
┗ position.list Obtaining a list of positions
┗ position.delete Deleting a position
┗ position.update Updating a position
Common factors
Requests
・HTTP Method
POST requests are always used.
・HTTP Header
HTTP Header must include the following:
Context-Type: application/json
Authorization: Bearer {API token}
※To issue an API token, access this link: https://unipos.me/management/provisioning_app_key
※The person who issues an API token will be considered as an API executor.
※There is no expiration date for an API token. However, an API token will become invalid after it is deleted, reissued, or when the Unipos account of the admin who issues an API token is deleted.
Responses
The HTTP status code is '200."
Check the value of the "ok" in the response body.
【Examples of a "successful" response body】
{
"ok": true,
"result": {
"id": "xxxxxxxx"
}
}
【Examples of a "failed" response body】
{
"ok": false,
"errors": [
{
"code": 100,
"message": "Invalid bearer token"
}
]
}
See below for the definitions of error codes when a transaction is failed.
Error code | Message | Details |
100 | Internal server error | A server is experiencing an internal error. |
101 | Bad request | The content of the request is invalid. |
200 | Invalid ApiToken | The API token is invalid. |
300 | Member id does not exist | The member ID doesn't exist in the team. |
301 | Invalid display name | A member's name must be between 1 and 80 letters long. |
302 | Invalid email address | An email address must be between 1 and 256 letters long and must follow an email address format. |
303 | Invalid employee code | An employee number must be between 1 and 10 letters. |
304 | Employment type does not exist | An employment type does not exist. |
305 | Some group id does not exist | A group ID does not exist. |
306 | Position id does not exist | A position ID does not exist. |
307 | - | ※This error code is currently not in use. |
308 | Email address must be a unique | You can't register the same email address twice. |
309 | Too many group to belong to | You can register up to 10 groups. |
310 | Invalid limit | The maximum number of limit is 50. |
311 | At least one more parameter must be set | You didn't designate a parameter to update. |
312 | Invalid status change | A status change is invalid. |
313 | Invalid cursor | A cursor is invalid. |
400 | Group id does not exist | A group ID does not exist. |
401 | Invalid name | A group name must be between 1 and 25 letters. |
402 | Name must be unique | You can't register the same group name twice. |
403 | Invalid limit | The maximum number of limit is 50. |
404 | Invalid cursor | A cursor is invalid. |
500 | Position id does not exist | A position ID does not exist. |
501 | Invalid name | A position name must be between 1 and 25 letters. |
502 | Name must be unique | You can't register the same position name twice. |
503 | Invalid limit | The maximum number of limit is 50. |
504 | Invalid cursor | A cursor is invalid. |
If the content of your request is unexpected, you may receive a response: '100' Internal server error.
Limitations
When too many requests are received simultaneously, you may receive a response: '500' HTTP status code.
Groups
Methods
Method | Description |
group.create | Creating a group |
group.get | Obtaining a group |
group.list | Obtaining a list of groups |
group.update | Updating a group |
group.delete | Deleting a group |
Group properties
Property | Description |
id | Group ID |
name | Name (between 1 and 25 letters) |
code | Group code |
parent_id | Parent group ID (Output only if parent group exists) |
group.create Creating a group
Method URL: https://unipos.me/api/v1/group.create
Preferred HTTP method: POST
【Header】
FieldName | Example | Required | Description |
Content-Type | application/json | Required | Media type |
Authorization | Bearer xxxx-xxxxxxxx-xxxx | Required | Authentication token |
【Argument】
Argument | Example | Required | Description |
name | "Information Systems Department" | Required | Name |
【Response】
When a request is processed successfully
{
"ok": true,
"result": {
"id" : "1111-2222-3333"
}
}
group.get Obtaining a group
Method URL: https://unipos.me/api/v1/group.get
Preferred HTTP method: POST
【Header】
FieldName | Example | Required | Description |
Content-Type | application/json | Required | Media type |
Authorization | Bearer xxxx-xxxxxxxx-xxxx | Required | Authentication token |
【Argument】
Argument | Example | Required | Description |
id | "1111-2222-3333" | Required | Group ID |
When a request is processed successfully
{
"ok": true,
"result": {
"id" : "1111-2222-3333",
"name" : "Information Systems Department"
"code" : "xxxx",
"parent_id": "xxx-xxx-xxx",
}
}
group.list Obtaining a list of groups
Method URL: https://unipos.me/api/v1/group.list
Preferred HTTP method: POST
【Header】
FieldName | Example | Required | Description |
Content-Type | application/json | Required | Media type |
Authorization | Bearer xxxx-xxxxxxxx-xxxx | Required | Authentication token |
【Argument】
Argument | Example | Required | Description |
cursor | "111-abc-efg" | Optional | Specify the value of next_cursor included in the cursor response. |
limit | 20 | Optional | The maximum number of limit is 50. If this field is left blank, it is deemed that 50 is designated. |
*If you don't want to add any information to the optional fields, please leave the bodies as blank JSON.
When a request is processed successfully
{
"ok": true,
"result": {
"groups": [
{
"id" : "1111-2222-3333",
"name" : "Information Systems Department"
}, ...(省略)
],
"next_cursor": "222-abc-efg"
}
}
group.delete Deleting a group
Method URL: https://unipos.me/api/v1/group.delete
Preferred HTTP method: POST
【Header】
FieldName | Example | Required | Description |
Content-Type | application/json | Required | Media type |
Authorization | Bearer xxxx-xxxxxxxx-xxxx | Required | Authentication token |
【Argument】
Argument | Example | Required | Description |
id | "1111-2222-3333" | Required | Group ID |
When a request is processed successfully
{
"ok": true,
"result": {
"id" : "1111-2222-3333"
}
}
group.update Updating a group
Method URL: https://unipos.me/api/v1/group.update
Preferred HTTP method: POST
【Header】
FieldName | Example | Required | Description |
Content-Type | application/json | Required | Media type |
Authorization | Bearer xxxx-xxxxxxxx-xxxx | Required | Authentication token |
【Argument】
Argument | Example | Required | Description |
id | "1111-2222-3333" | Required | Group ID |
name | "Information Systems Department" | Required | Name |
When a request is processed successfully
{
"ok": true,
"result": {
"id" : "1111-2222-3333"
}
}
Members
Methods
Method | Description |
member.invite | Inviting a member |
member.get | Obtaining a member |
member.list | Obtaining a list of members |
member.update | Updating a member |
member.pause | Suspending a member |
member.unpause | Unsuspending a member |
member.delete | Deleting a member |
Member properties
Property | Description |
id | Member ID |
display_name | Name between 1 and 80 letters |
email_address | Email address between 1 and 256 letters in the format of an email address |
employment_type | Employment type (Specify a number from the following. 0: unselected, 1: Executive, 2: Permanent staff, 3: Contract staff, 4: Agency temporary staff, 5: Part-time staff, 6: Subcontractor, or 7 Other) |
employee_code | Employee number between 0 and 10 letters |
status |
Status(Specify a number from the following. 1: Inviting / Awaiting sign-up, 2: Active, 3: Suspended, or 4: Deleted) |
group_ids | Group ID. Up to 10 Group ID's can be selected. |
position_id | Position ID |
* Groups can be created via Group API.
* Positions can be created via Position API.
member.invite Inviting a member
Method URL: https://unipos.me/api/v1/member.invite
Preferred HTTP method: POST
【Header】
FieldName | Example | Required | Description |
Content-Type | application/json | Required | Media type |
Authorization | Bearer xxxx-xxxxxxxx-xxxx | Required | Authentication token |
【Argument】
Argument | Example | Required | Description |
display_name | "Sato Taro" | Required | Name |
email_address | "taro@example.com" | Optional | Email address |
login_id | “taro_login_id” | Optional | loginID |
employment_type | 1 | Optional | Employment type |
employee_code | "xxxx" | Optional | Employee number |
group_ids | ["xxx-xxx-xxx", "yyy-yyy-yyy"] | Optional | Groups ID (multiple ID's can be selected) |
position_id | "xxxx" | Optional | Position ID |
※One of email_address and login_id is required. Entering both will result in an error.
* If "Optional" information is not provided, a default value will be applied.
【Response】
When a request is processed successfully
{
"ok": true,
"result": {
"id" : "1111-2222-3333"
}
}
member.get Obtaining a member
Method URL: https://unipos.me/api/v1/member.get
Preferred HTTP method: POST
【Header】
FieldName | Example | Required | Description |
Content-Type | application/json | Required | Media type |
Authorization | Bearer xxxx-xxxxxxxx-xxxx | Required | Authentication token |
【Argument】
Argument | Example | Required | Description |
id | "1111-2222-3333" | Required | User ID |
When a request is processed successfully
{
"ok": true,
"result": {
"id" : "1111-2222-3333",
"display_name" : "Sato Taro",
"email_address" : "taro@example.com",
"employment_type" : 1,
"employee_code" : "xxxxxxxx",
"status" : 2,
"group_ids" : ["xxx-xxx-xxx", "xxx-xxx-xxx"],
"position_id" : "xxxx"
}
}
※Please refer to Account Status for the number of “status” (1-4).
※For login ID members, email_address is returned as an empty string.
member.list Obtaining a list of members
Method URL: https://unipos.me/api/v1/member.list
Preferred HTTP method: POST
【Header】
FieldName | Example | Required | Description |
Content-Type | application/json | Required | Media type |
Authorization | Bearer xxxx-xxxxxxxx-xxxx | Required | Authentication token |
【Argument】
Argument | Example | Required | Description |
cursor | "111-abc-efg" | Optional | Specify the value of next_cursor included in the cursor response. |
limit | 20 | Optional |
The maximum number of limit is 50. If this field is left blank, it is deemed that 50 is designated. |
* If you don't want to add any information to the optional fields, please leave the bodies as blank JSON.
When a request is processed successfully
{
"ok": true,
"result": {
"members": [
{
"id" : "1111-2222-3333",
"display_name" : "Sato Taro",
"email_address" : "taro@example.com",
"employment_type" : 1,
"employee_code" : "xxxxxxxx",
"status" : 2,
"group_ids" : ["xxx-xxx-xxx", "xxx-xxx-xxx"],
"position_id" : "xxxx",
},
{
"id" : "1111-2222-3333",
"display_name" : "Sato Taro",
"email_address" : "",
"login_id": "taro_login_id"
"employment_type" : 1,
"employee_code" : "xxxxxxxx",
"status" : 2,
"group_ids" : ["xxx-xxx-xxx", "xxx-xxx-xxx"],
"position_id" : "xxxx",
},
],
"next_cursor": "222-abc-efg"
}
}
※Next_cursor will not be displayed when coming to the end of the page.
※Please refer to Account Status for the number of “status” (1-4).
※For login ID members, email_address is returned as an empty string.
member.pause Suspending a member
*You can't suspend a member whose account is in the "Inviting / Awaiting sign-up" status.
Method URL: https://unipos.me/api/v1/member.pause
Preferred HTTP method: POST
【Header】
FieldName | Example | Required | Description |
Content-Type | application/json | Required | Media Type |
Authorization | Bearer xxxx-xxxxxxxx-xxxx | Required | Authentication token |
【Argument】
FieldName | Example | Required | Description |
id | "1111-2222-3333" | Required | Member ID |
When a request is processed successfully
{
"ok": true,
"result": {
"id" : "1111-2222-3333"
}
}
member.unpause Unsuspending a member
Method URL: https://unipos.me/api/v1/member.unpause
Preferred HTTP method: POST
【Header】
FieldName | Example | Required | Description |
Content-Type | application/json | Required | Media type |
Authorization | Bearer xxxx-xxxxxxxx-xxxx | Required | Authentication token |
【Argument】
Argument | Example | Required | Description |
id | "1111-2222-3333" | Required | Member ID |
When a request is processed successfully
{
"ok": true,
"result": {
"id" : "1111-2222-3333"
}
}
member.delete Deleting a member
Method URL: https://unipos.me/api/v1/member.delete
Preferred HTTP method: POST
【Header】
FieldName | Example | Required | Description |
Content-Type | application/json | Required | Media type |
Authorization | Bearer xxxx-xxxxxxxx-xxxx | Required | Authentication token |
【Argument】
Argument | Example | Required | Description |
id | "1111-2222-3333" | Required | Member ID |
When a request is processed successfully
{
"ok": true,
"result": {
"id" : "1111-2222-3333"
}
}
member.update Updating a member
Method URL: https://unipos.me/api/v1/member.update
Preferred HTTP method: POST
【Header】
FieldName | Example | Required | Description |
Content-Type | application/json | Required | Media type |
Authorization | Bearer xxxx-xxxxxxxx-xxxx | Required | Authentication token |
【Argument】
Argument | Example | Required | Descriptio |
id | "1111-2222-3333" | Required | Member ID |
display_name | "Sato Taro" | Optional | Name |
email_address | "taro@example.com" | Optional | Email address |
employment_type | 1 | Optional | Employment type |
employee_code | "xxxx" | Optional | Employee number |
group_ids | "xxx-xxx-xxx", "yyy-yyy-yyy" | Optional | Group ID Multiple Group ID's can be selected. |
position_id | "xxxx" | Optional | Position ID |
* At least one of the "optional" information must be registered.
When a request is processed successfully
{
"ok": true,
"result": {
"id" : "1111-2222-3333"
}
}
Positions
Methods
Method | Description |
position.create | Creating a position |
position.get | Obtaining a position |
position.list | Obtaining a list of positions |
position.update | Updating a position |
position.delete | Deleting a position |
Position properties
Property | Description |
id | Position ID |
name | Name (between 1 and 25 letters) |
position.create Creating a position
Method URL: https://unipos.me/api/v1/position.create
Preferred HTTP method: POST
【Header】
FieldName | Example | Required | Description |
Content-Type | application/json | Required | Media type |
Authorization | Bearer xxxx-xxxxxxxx-xxxx | Required | Authentication token |
【Argument】
Argument | Example | Required | Description |
name | "Executive" | Required | Name |
【Response】
When a request is processed successfully
{
"ok": true,
"result": {
"id" : "1111-2222-3333"
}
}
position.get Obtaining a position
Method URL: https://unipos.me/api/v1/position.get
Preferred HTTP method: POST
【Header】
FieldName | Example | Required | Description |
Content-Type | application/json | Required | Media type |
Authorization | Bearer xxxx-xxxxxxxx-xxxx | Required | Authentication token |
【Argument】
Argument | Example | Required | Description |
id | ""1111-2222-3333"" | Required | Position ID |
When a request is processed successfully
{
"ok": true,
"result": {
"id" : "1111-2222-3333",
"name" : "Executive"
}
}
position.list Obtaining a list of positions
Method URL: https://unipos.me/api/v1/position.list
Preferred HTTP method: POST
【Header】
FieldName | Example | Required | Description |
Content-Type | application/json | Required | Media type |
Authorization | Bearer xxxx-xxxxxxxx-xxxx | Required | Authentication token |
【Argument】
Argument | Example | Required | Description |
cursor | ""111-abc-efg"" | Optional | Specify the value of next_cursor included in the cursor response. |
limit | 20 | Optional | Specify the value of next_cursor included in the cursor response. |
* If you don't want to add any information to the optional fields, please leave the bodies as blank JSON.
When a request is processed successfully
{
"ok": true,
"result": {
"positions": [
{
"id" : "1111-2222-3333",
"name" : "Executive"
},
],
"next_cursor": "222-abc-efg"
}
}
position.delete Deleting a position
Method URL: https://unipos.me/api/v1/position.delete
Preferred HTTP method: POST"
【Header】
FieldName | Example | Required | Description |
Content-Type | application/json | Required | Media type |
Authorization | Bearer xxxx-xxxxxxxx-xxxx | Required | Authentication token" |
【Argument】
Argument | Example | Required | Description |
id | ""1111-2222-3333"" | Required | Position ID |
When a request is processed successfully
{
"ok": true,
"result": {
"id" : "1111-2222-3333"
}
}
position.update Updating a position
Method URL: https://unipos.me/api/v1/position.update
Preferred HTTP method: POST
【Header】
FieldName | Example | Required | Description |
Content-Type | application/json | Required | Media type |
Authorization | Bearer xxxx-xxxxxxxx-xxxx | Required | Authentication token |
【Argument】
Argument | Example | Required | Description |
id | ""1111-2222-3333"" | Required | Position ID |
name | ""Executive"" | Required | Name |
When a request is processed successfully
{
"ok": true,
"result": {
"id" : "1111-2222-3333"
}
}