Skip to main content

User Management

Team GET​

Gets all teams current user is a member of.

Request Parameters​

import requests

key = '<api-key>'

url = f'https://api.sapling.ai/api/v1/team?key={key}'

try:
    resp = requests.get(url)
    resp_json = resp.json()
    if 200 <= resp.status_code < 300:
        print('Entries: ', resp_json)
    else:
        print('Error: ', resp_json)
except Exception as e:
    print('Error: ', e)

https://api.sapling.ai/api/v1/team?key=<key>

HTTP method: GET

key: String
32-character API key

Response Parameters​

JSON array of team entries under key teams.

Team entry structure:

{
  "id": <str, UUID>, // Opaque id, used for team management
  "name": <str>,     // Team name
}

Team Users GET​

API key holder must be an admin for the team.

Request Parameters​

import requests

key = '<api-key>'

url = f'https://api.sapling.ai/api/v1/team/<team_id>/team_user?key={key}'

try:
    resp = requests.get(url)
    if 200 <= resp.status_code < 300:
        print('Success')
    else:
        resp_json = resp.json()
        print('Error: ', resp_json)
except Exception as e:
    print('Error: ', e)

https://api.sapling.ai/api/v1/team/<team_id>/team_user?key=<key>

HTTP method: GET

API key holder must be an admin for the team.

<key>: String
32-character API key

Response Parameters​

{
    "users": <Team User>[], // Array of Team Users
    "pending_users": <Pending User>[], // Array of Pending Users / Invites
}

Team User Structure:​

{
  "id": <str, UUID>,              // Opaque ID, used for management; each user has a unique id per team
  "login_email": <str, email>,
  "is_admin": <bool>,
  "is_manager": <bool>,
  "edit_permission": <bool>,      // If user has edit permissions
  "inspect_permission": <bool>,   // If user has inspect permissions
  "created_at": <str, date>,      // e.g. "Wed, 07 Oct 2020 21:15:47 GMT"
  "updated_at": <str, date>,      // e.g. "Wed, 07 Oct 2020 21:15:47 GMT"
}

Pending User / Invite Structure:​

Pending Users have not joined the team yet. Once a user has registered an account and accepted the team invite they will appear as a Team User.

{
    "email": <str, email>,  // Email that was invited
    "registered": <bool>,   // If the email has registered for a Sapling account
    "confirmed": <bool>,    // If the Sapling account created has confirmed their email
    "permissions": <str>,   // Team permissions to be granted when user joins team
}

Team User POST​

API key holder must be an admin for the team.

If adding to teams without invites is allowed:

  • API key holder also must be a superuser.
  • An invite will still be sent if an account for the email has not been registered. Upon registration and email confirmation, the account will be automatically associated with the team.

Request Parameters​

import requests

key = '<api-key>'
team_id = '<TEAM_ID>'

url = f'https://api.sapling.ai/api/v1/team/{team_id}/team_user'
data = {
    'key': key,
    'email': '<user_email>',
}

try:
    resp = requests.post(url, json=data)
    if 200 <= resp.status_code < 300:
        print('Success')
    else:
        resp_json = resp.json()
        print('Error: ', resp_json)
except Exception as e:
    print('Error: ', e)

https://api.sapling.ai/api/v1/team/<team_id>/team_user

HTTP method: POST

<team_id>: String (UUID)
ID of a Sapling team.

key: String
32-character API key

email: String
Email of user to add to team

is_admin: Optional Boolean
If the added user will be admin for the team. Only available if adding to teams without invites is allowed. If the email provided does not have a user account (and an invite is sent) this argument is ignored.

is_manager: Optional Boolean
If the added user will be a manager for the team. Only available if adding to teams without invites is allowed. If the email provided does not have a user account (and an invite is sent) this argument is ignored.

edit_permission: Optional Boolean
If the added user will have edit permissions (dictionary, custom errors, snippets) for the team. Only available if adding to teams without invites is allowed. If the email provided does not have a user account (and an invite is sent) this argument is ignored.

inspect_permission: Optional Boolean
If the added user will have inspect permissions (can view reporting) for the team. Only available if adding to teams without invites is allowed. If the email provided does not have a user account (and an invite is sent) this argument is ignored.

Response Parameters​

Team User entry, under key team_user for direct adding to teams, or 'Invite Sent' status under key msg if invite was sent.

Team User Entry Structure:

{
  "id": <str, UUID>,            // Opaque ID, used for management; each user has a unique id per team
  "login_email": <str>,
  "is_admin": <bool>
  "is_manager": <bool>
  "edit_permission": <bool>,    // If user has edit permissions
  "inspect_permission": <bool>, // If user has inspect permissions
  "created_at": <str, date>     // e.g. "Wed, 07 Oct 2020 21:15:47 GMT"
  "updated_at": <str, date>     // e.g. "Wed, 07 Oct 2020 21:15:47 GMT"
}

Team User DELETE​

API key holder must be an admin for the team. This also deletes outstanding invites for the team-email pair, if any exist.

Request Parameters​

import requests

key = '<api-key>'
team_user_id = '<TEAM_USER_ID>'

url = f'https://api.sapling.ai/api/v1/team_user/{team_user_id}'
data = {
    'key': key,
}

try:
    resp = requests.delete(url, json=data)
    if 200 <= resp.status_code < 300:
        print('Success')
    else:
        resp_json = resp.json()
        print('Error: ', resp_json)
except Exception as e:
    print('Error: ', e)

https://api.sapling.ai/api/v1/team_user/<team_user_id>

HTTP method: DELETE

<team_user_id>: String (UUID)
ID of a Sapling team user.

key: String
32-character API key

Response Parameters​

Empty, HTTP status code 204.

Team User PATCH​

API key holder must be an admin for the team.

Request Parameters​

import requests

key = '<api-key>'
team_user_id = '<TEAM_USER_ID>'

url = f'https://api.sapling.ai/api/v1/team_user/{team_user_id}'
data = {
    'key': key,
    'is_admin': True,
}

try:
    resp = requests.patch(url, json=data)
    if 200 <= resp.status_code < 300:
        print('Success')
    else:
        resp_json = resp.json()
        print('Error: ', resp_json)
except Exception as e:
    print('Error: ', e)

https://api.sapling.ai/api/v1/team_user/<team_user_id>

HTTP method: PATCH

<team_user_id>: String (UUID)
ID of a Sapling team user.

key: String
32-character API key

is_admin: Optional Boolean
If the added user will be admin for the team.

is_manager: Optional Boolean
If the added user will be a manager for the team.

edit_permission: Optional Boolean
If the added user will have edit permissions (dictionary, custom errors, snippets) for the team.

inspect_permission: Optional Boolean
If the added user will have inspect permissions (can view reporting) for the team.

Response Parameters​

Empty, HTTP status code 204.