Platio Management API Programming Guide

Platio Management API is a set of endpoints in the Platio API that facilitate programmatically creating, browsing, updating and deleting Users 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.

Overview

Prerequisite

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”.

Please refer to Platio API Programming Guide about the endpoints and authentication.

Limitations

Please refer to Platio API Programming Guide about limitations other than the number of requests.

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	N/A	2,000 requests / hour
Create, Update, Delete a 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.

Using Platio Management API

This section describes how you can use the Platio Management API with examples. Please see Platio API References for details of each API.

Manipulating Users

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.

Getting Users

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,
    "profile": {
      "name": "Default"
    },
    "disabled": false
  },
  {
    "id": "u2cc0613",
    "name": "User2",
    "email": "user2@example.com",
    "admin": false,
    "managementApiAccess": 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,
    "profile": {
      "name": "Default"
    },
    "team": {
      "name": "Default"
    },
    "teamLeader": false,
    "disabled": false
  },
  {
    "id": "u1ee8203",
    "name": "User2",
    "email": "user2@example.com",
    "admin": false,
    "apiAccess": true,
    "managementApiAccess": true,
    "profile": {
      "name": "Default"
    },
    "team": {
      "name": "Default"
    },
    "teamLeader": false,
    "disabled": false
  }
]

Getting a User

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,
  "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,
  "profile": {
    "name": "Default"
  },
  "team": {
    "name": "Default"
  },
  "teamLeader": false,
  "disabled": false
}

Creating a User

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 including a Profile name and a Team name.

Some properties have restrictions on the values that can be sent.

The name property should not be empty, should be 64 characters long at most, and not start with “_“.
The 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.
The profile.name property should be the name of an existing profile.
The 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:

The name property must match an existing deactivated Shared User’s name.
The 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,
  "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,
  "profile": {
    "name": "Default"
  },
  "team": {
    "name": "Default"
  },
  "teamLeader": false,
  "disabled": false
}

Updating a User

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 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:

The 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": "email@example.com",
  "admin": true,
  "apiAccess": true,
  "managementApiAccess": 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": "email@example.com",
  "admin": true,
  "apiAccess": true,
  "managementApiAccess": false,
  "profile": {
    "name": "Default"
  },
  "team": {
    "name": "Default"
  },
  "teamLeader": false,
  "disabled": false
}

Deleting a User

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.