Platio Management API is a set of endpoints in the Platio API that facilitate programmatically creating, browsing, updating and deleting Users, and so on, in an Application you’ve created with Platio Studio.
This document assumes you’ve read Platio API Programming Guide. If you haven’t, we recommend reading that guide, creating a MinApp with Platio Studio and using it first.
To use the Platio Management API, you need to create and deliver a Application first. Once you’ve delivered your Application, add a User and configure them to have access to the Platio API. You can do this by checking “Allow accessing records and attachments via API” while creating/activating and updating a User. After that, check “Allow managing users via API”. You also need to check “Allow managing shared users via API” to manage shared users.
Please refer to Platio API Programming Guide about the endpoints and authentication.
Please refer to Platio API Programming Guide about limitations other than the number of requests.
There are some limits on how many API requests you can make in a certain period. The current limitations are listed below, but they may change. These limitations are applied to each Application.
| APIs | Limit for Premium Plan | Limit for Enterprise Plan |
|---|---|---|
| Get Users, a User, Shared Users, a Shared User | N/A | 2,000 requests / hour |
| Create, Update, Delete a User or a Shared User | N/A | 1,000 requests / hour |
Note that the limit applies to all requests in a group. The counter will be reset every hour.
When it reaches the limit, an API returns 429 response with
TOO_MANY_REQUESTS.
This section describes how you can use the Platio Management API with examples. Please see Platio API References for details of each API.
The APIs to manipulate users behave differently based on whether Shared Users mode is enabled and/or whether Team mode is enabled. Please confirm your Organization’s settings before calling these APIs.
To get Users in an Application, send a GET request. This API returns the first 100 Users in an Application, sorted by their name, in ascending order.
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users'To get the next 100 Users, use the skip parameter.
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users?skip=100'To get all Users, call this API multiple times by increasing
skip parameter until it returns an empty array of
Users.
You can also use limit parameter to specify how many
Users it returns.
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users?limit=30'You can search Users. The search parameter will match
case-insensitively against the User’s name, email address, profile name
or team name.
Note that this API returns only activated Users if your Organization has enabled Shared Users mode.
This API returns an array of Users.
[
{
"id": "u37367df",
"name": "User",
"email": "user@example.com",
"admin": false,
"apiAccess": true,
"managementApiAccess": true,
"organizationManagementApiAccess": false,
"profile": {
"name": "Default"
},
"disabled": false
},
{
"id": "u2cc0613",
"name": "User2",
"email": "user2@example.com",
"admin": false,
"managementApiAccess": false,
"organizationManagementApiAccess": false,
"apiAccess": false,
"profile": {
"name": "Default"
},
"disabled": false
}
]If your Application has enabled Team mode, Team details for each User will be included.
[
{
"id": "u4d6a6dd",
"name": "User",
"email": "user@example.com",
"admin": false,
"apiAccess": true,
"managementApiAccess": true,
"organizationManagementApiAccess": false,
"profile": {
"name": "Default"
},
"team": {
"name": "Default"
},
"teamLeader": false,
"disabled": false
},
{
"id": "u1ee8203",
"name": "User2",
"email": "user2@example.com",
"admin": false,
"apiAccess": true,
"managementApiAccess": true,
"organizationManagementApiAccess": false,
"profile": {
"name": "Default"
},
"team": {
"name": "Default"
},
"teamLeader": false,
"disabled": false
}
]To get a User in an Application, send a GET request with the ID of that User.
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users/u37367df'This API returns a specified User.
{
"id": "u37367df",
"name": "User",
"email": "user@example.com",
"admin": false,
"apiAccess": true,
"managementApiAccess": true,
"organizationManagementApiAccess": false,
"profile": {
"name": "Default"
},
"disabled": false
}If your Application has enabled Team mode, Team details for the specified User will be included.
{
"id": "u37367df",
"name": "User",
"email": "user@example.com",
"admin": false,
"apiAccess": true,
"managementApiAccess": true,
"organizationManagementApiAccess": false,
"profile": {
"name": "Default"
},
"team": {
"name": "Default"
},
"teamLeader": false,
"disabled": false
}To create a User in an Application, send a POST request.
Send a request like this if your Organization hasn’t enabled Shared Users mode.
curl -u uf598c3f:mypassword \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"name": "User3",
"email": "user3@example.com",
"password": "Abcd1234",
"admin": false,
"apiAccess": true,
"managementApiAccess": false,
"profile": {
"name": "Default"
}
}' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users'Include a Team name if your Application has enabled Team mode.
curl -u uf598c3f:mypassword \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"name": "User3",
"email": "user3@example.com",
"password": "Abcd1234",
"admin": false,
"apiAccess": true,
"managementApiAccess": false,
"profile": {
"name": "Default"
},
"team": {
"name": "Default"
},
"teamLeader: true
}' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users'Note that you need to specify all the properties except
organizationManagementApiAccess including a Profile name
and a Team name.
Some properties have restrictions on the values that can be sent.
name property should not be empty, should be 64
characters long at most, and not start with “_“.password property should be a minimum of 8
characters long and should contain at least one of each of the
following: a lowercase character, an uppercase character and a
number.profile.name property should be the name of an
existing profile.team.name property should be the name of an
existing team.If your Organization has enabled Shared Users mode, this API activates a User in the application rather than creating a new User. Because of this, there are some differences when you call this API:
name property must match an existing deactivated
Shared User’s name.password and email properties cannot
be used.curl -u uf598c3f:mypassword \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"name": "User3",
"admin": false,
"apiAccess": true,
"managementApiAccess": false,
"profile": {
"name": "Default"
}
}' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users'This API returns the created User.
{
"id": "u37367df",
"name": "User3",
"email": "user3@example.com",
"admin": false,
"apiAccess": true,
"managementApiAccess": false,
"organizationManagementApiAccess": false,
"profile":{
"name": "Default"
},
"disabled": false
}If your Application has enabled Team mode, Team details for the specified User will be included.
{
"id": "u37367df",
"name": "User",
"email": "user@example.com",
"admin": false,
"apiAccess": true,
"managementApiAccess": false,
"organizationManagementApiAccess": false,
"profile": {
"name": "Default"
},
"team": {
"name": "Default"
},
"teamLeader": false,
"disabled": false
}To update an existing User, send a PUT request.
curl -u uf598c3f:mypassword \
-H 'Content-Type: application/json' \
-X PUT \
-d '{
"email": "new-email@example.com",
"admin": true,
"apiAccess": true,
"managementApiAccess": false,
"profile": {
"name": "Default"
},
"disabled": false
}' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users/u37367df'Include a Team name if your Application has enabled Team mode.
curl -u uf598c3f:mypassword \
-X PUT \
-H 'Content-Type: application/json' \
-d '{
"email": "new-email@example.com",
"admin": true,
"apiAccess": true,
"managementApiAccess": false,
"profile": {
"name": "Default"
},
"team": {
"name": "Default"
},
"teamLeader: true,
"disabled": false
}' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users/u37367df'Note that you need to specify all the properties except
password and organizationManagementApiAccess
including a Profile name and a Team name.
Similar to the API to create a User, this request has some restrictions if your Organization has enabled Shared Users mode:
password and email properties cannot
be used.curl -u uf598c3f:mypassword \
-X PUT \
-H 'Content-Type: application/json' \
-d '{
"admin": true,
"apiAccess": true,
"managementApiAccess": false,
"profile": {
"name": "Default"
},
"disabled": false
}' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users/u37367df'This API returns the updated User.
{
"id": "u37367df",
"name": "User",
"email": "new-email@example.com",
"admin": true,
"apiAccess": true,
"managementApiAccess": false,
"organizationManagementApiAccess": false,
"profile": {
"name": "Default"
},
"disabled": false
}If your Application has enabled Team mode, Team details for the specified User will be included.
{
"id": "u37367df",
"name": "User",
"email": "new-email@example.com",
"admin": true,
"apiAccess": true,
"managementApiAccess": false,
"organizationManagementApiAccess": false,
"profile": {
"name": "Default"
},
"team": {
"name": "Default"
},
"teamLeader": false,
"disabled": false
}To delete an existing User, send a DELETE request. If your Organization is in Shared Users mode, calling this API will result in an error.
curl -u uf598c3f:mypassword \
-X DELETE \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users/u37367df'This API returns a 204 status code with an empty body when it succeeds.
The APIs to manipulate shared users allow you to fetch and manage shared users. You can use these APIs only when you’ve enabled shared users in your Organization. Please confirm your Organization’s settings before calling these APIs.
Note that you need to check “Allow managing shared users via API” to manage shared users while configuring a user to call the APIs.
To get Shared Users, send a GET request. This API returns the first 100 Shared Users, sorted by their name, in ascending order.
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/sharedUsers'To get the next 100 Shared Users, use the skip
parameter.
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/sharedUsers?skip=100'To get all Shared Users, call this API multiple times by increasing
skip parameter until it returns an empty array of Shared
Users.
You can also use limit parameter to specify how many
Shared Users it returns.
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/sharedUsers?limit=30'You can search Shared Users. The search parameter will
match case-insensitively against the User’s name and email address.
This API returns an array of Shared Users.
[
{
"id": "ucyhe5rnilvbcvd5336lvp7szay",
"name": "User",
"email": "user@example.com",
"disabled": false
},
{
"id": "umeyumwmfsfbzjbo3gr5tsc5ukm",
"name": "User2",
"email": "user2@example.com",
"disabled": false
}
]To get a Shared User, send a GET request with the ID of that Shared User.
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/sharedUsers/ucyhe5rnilvbcvd5336lvp7szay'This API returns a specified Shared User.
{
"id": "ucyhe5rnilvbcvd5336lvp7szay",
"name": "User",
"email": "user@example.com",
"disabled": false
}To create a Shared User, send a POST request.
curl -u uf598c3f:mypassword \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"name": "User3",
"email": "user3@example.com",
"password": "Abcd1234"
}' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/sharedUsers'Note that you need to specify all the properties.
Some properties have restrictions on the values that can be sent.
name property should not be empty, should be 64
characters long at most, and not start with “_“.password property should be a minimum of 8
characters long and should contain at least one of each of the
following: a lowercase character, an uppercase character and a
number.This API returns the created Shared User.
{
"id": "u55ruf3stmjhzjjqmqkuirw4p34",
"name": "User3",
"email": "user3@example.com",
"disabled": false
}To update an existing Shared User, send a PUT request.
curl -u uf598c3f:mypassword \
-X PUT \
-H 'Content-Type: application/json' \
-d '{
"email": "new-email@example.com",
"disabled": false
}' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/sharedUsers/ucyhe5rnilvbcvd5336lvp7szay'Note that you need to specify all the properties except
password.
This API returns the updated Shared User.
{
"id": "ucyhe5rnilvbcvd5336lvp7szay",
"name": "User",
"email": "new-email@example.com",
"disabled": false
}To delete an existing Shared User, send a DELETE request.
curl -u uf598c3f:mypassword \
-X DELETE \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/sharedUsers/ucyhe5rnilvbcvd5336lvp7szay'This API returns a 204 status code with an empty body when it succeeds.