Skip to main content

User Management

Teams GET​

Gets all teams the 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 / Team Invites GET​

This endpoint is used to get the users and pending users for a team. Pending users are users who have an invite to the team but have not yet joined.

API key holder must be an admin for 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?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
    "team_id": <str, UUID>, // ID of team that user was invited to
    "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; alternatively, set emails for multiple emails

emails: String
List of emails of users to add to team; all will have the same permissions. Alternatively, set email for a single email. NOTE For now, please use /team_user2 instead of /team_user in the API request URL to use the emails argument. This will be resolved in a future release.

is_admin: Optional Boolean
If the added user will be an 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​

Dictionary of the form:

{
  "added": [...],
  "invited": [...],
  "errors": [...],
  "already_exists": [...]
}

where added is a list of {'email': email, 'team_user': team_user_entry}, invited is a list of {'email': email}, errors is a list of {'email', email, 'reason': error_reason}, and already_exists is a list of {'email': email}.

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, but only if the user is already part of the team (otherwise, there is no team_user_id).

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 Users Bulk DELETE​

API key holder must be an admin for the team. This endpoint allows for bulk deletion of users from a team by providing a list of emails. It will attempt to delete each user specified and report which users were successfully deleted and which were not found. Users cannot delete themselves using this endpoint.

Request Parameters​

import requests

key = '<api-key>'
team_id = '<TEAM_ID>'
emails_to_delete = ['user1@example.com', 'user2@example.com']

url = f'https://api.sapling.ai/api/v1/team/{team_id}/team_users/bulk_delete'
data = {
    'key': key,
    'emails': emails_to_delete,
}

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

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

HTTP method: DELETE

<team_id>: String (UUID)
ID of the Sapling team from which users will be deleted.

key: String
32-character API key (must belong to a team admin).

emails: List of Strings
A list of email addresses for the users to be deleted from the team.

Response Parameters​

JSON dictionary containing the results of the bulk delete operation.

Success status code: 200

{
    "deleted_users": [
        {"id": "<UUID>", "email": "<user1@example.com>"},
        // ... other deleted users
    ],
    "not_found_users": [
        "<user_not_in_team@example.com>"
        // ... other users not found
    ],
    "warning": "" // Reserved for future use
}

deleted_users: List
List of dictionaries, each containing the id (Team User ID) and email of a user successfully deleted from the team.

not_found_users: List
List of emails that were provided in the request but did not correspond to any user in the specified team.

Error status codes:

  • 400: Bad Request (e.g., missing/invalid emails list, invalid team_id, attempt to delete self).
  • 401/403: Unauthorized (API key holder is not an admin for the team).

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

Team User Invite DELETE​

API key holder must be an admin for the team. This deletes outstanding invites for the team-email pair, if any exist, even if the user has not joined the team.

Request Parameters​

import requests

key = '<api-key>'
email = '<EMAIL>'

url = f'https://api.sapling.ai/api/v1/team_user_invite/{team_id}'
data = {
    'key': key,
    'email': email,
}

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_invite/<team_id>

HTTP method: DELETE

<email>: String
Email of invited user.

key: String
32-character API key

Response Parameters​

Empty, HTTP status code 204.

Suppressed Emails GET​

This endpoint is used to get the list of emails that were invited but were unreachable. You must request access to this endpoint for your organization. Suppressed emails must also have a domain matching the domain of the requester.

Request Parameters​

import requests

key = '<api-key>'

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

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

https://api.sapling.ai/api/v1/organization/<organization_id>/suppressed_emails?key=<key>

HTTP method: GET

organization_id: String (UUID)
ID of a Sapling organization.

key: String
32-character API key

Response Parameters​

JSON list of suppressed emails.

{
    "suppressed_emails": ["<EMAIL1>", "<EMAIL2>"]
}