Skip to main content

Team Reporting

Sapling's API endpoint for exporting team user activity and analytics. See Team Management for getting the IDs for a particular team.

Organization Teams POST​

Request Parameters​

Note that key and return_names should be part of the request body, while organization_id should be part of the request URL.

https://api.sapling.ai/api/v1/reporting/organization/<organization_id>/teams

key: String
32-character API key

return_names: Optional Boolean
Default is false. If true, result have extra field containing team names along with the ids.

<organization_id>: String (UUID)
ID of a Sapling organization. API key holder must have manager or admin permissions for the organization.

Response Parameters​

JSON array of team IDs of teams under the organization if return_names is false, else JSON array of {"id": "team_id", "name": "team_name"} entries.

Organization Usage POST​

API endpoint for retrieving the usage health of teams in an organization.

API key holder must have reporting permissions for the organization.

Request Parameters​

import requests

key = '<api-key>'

url = 'https://api.sapling.ai/api/v1/reporting/organization/<organization_id>/usage'
data = {
    'key': key,
    'start_date': '2021-12-01',
    'end_date': '2021-12-08',
}

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

https://api.sapling.ai/api/v1/reporting/organization/<organization_id>/usage

HTTP method: POST

key: String
32-character API key

organization_id: String (UUID)
ID of a Sapling organization. You can get this information from the URL of the Sapling organization.

start_date: String, UTC timezone ISO 8601 date or datetime
The maximum time range for reporting is 1 year. Example: 2021-12-01 or 2021-12-01 03:29.

end_date: String, UTC timezone ISO 8601 date or datetime
The maximum time range for reporting is 1 year. Example: 2021-12-08 or 2021-12-08 13:59.

If a date without time is specified (like 2021-12-08), only actions up to previous day (2021-12-07 23:59:59) will be included.

Response Parameters​

List of organization usage statistics. This corresponds to https://sapling.ai/organizations/<organization_id>/usage.

{
    "assigned_seats": <int>,
    "active_seats": <int>,
    "capacity": <int>,
    "teams": [
        ...
    ]
}

Each item under teams has the following structure:

{
    "team_id": "<team_id>",
    "team_name": "<team_name>",
    "assigned_seats": <int>,
    "active_seats": <int>,
    "capacity": <int>,
    "usage_data": {
        ...
    }
}

The usage_data field currently has:

{
    "edit_accepts": <int>,
    "completions": <int>,
    "rephrases": <int>,
    "snippets": <int>
}

where these are the number of times the user has accepted an edit suggestion, used an autocompletion, accepted a rephrased text, or used a snippet, respectively. Please contact us if you need more information included.

By default, a user is considered active if they've accepted an edit suggestion, used an autocompletion, or used a snippet. However, you can use the usage_data field to customize this.

User Reporting GET​

API key holder must have reporting permissions for the team.

Request Parameters​

import requests

key = '<api-key>'

url = 'https://api.sapling.ai/api/v1/reporting/team/dashboard_user_data'
data = {
    'key': key,
    'team_ids': ['<team_id1>', '<team_id2>'],
    'start_date': '2021-12-01',
    'end_date': '2021-12-08',
}

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

https://api.sapling.ai/api/v1/reporting/team/dashboard_user_data

HTTP method: POST

key: String
32-character API key

team_ids: Array of Strings (UUID)
Array of IDs of Sapling Teams.

start_date: String, UTC timezone ISO 8601 date or datetime
The maximum time range for reporting is 1 year. Example: 2021-12-01 or 2021-12-01 03:29.

end_date: String, UTC timezone ISO 8601 date or datetime
The maximum time range for reporting is 1 year. Example: 2021-12-08 or 2021-12-08 13:59.

If a date without time is specified (like 2021-12-08), only actions up to previous day (2021-12-07 23:59:59) will be included.

Response Parameters​

List of user reporting statistics.

If a user is part of multiple teams there will be multiple reporting structures for that user with a different team_id field value.

User Reporting Structure:

{
    "accepts":  <int>,                         // Number of Sapling edit suggestions accepted
    "completion_char_counts": <int>,           // Character count of autocompletions, for estimating time saved
    "completion_counts": <int>,                // Number of times autocompletion was used
    "hours_saved": <int>,                      // Estimate of time saved
    "id": <str, UUID>,                         // Opaque user id, used for management
    "is_admin": <bool>,                        // This allows for excluding admins from reporting
    "is_manager": <bool>,                      // This allows for excluding managers from reporting
    "login_email": <str, email>,               // Login email of user
    "mean_response_time": <int>,               // Mean agent response time in seconds
    "median_response_time": <int>,             // Median agent response time in seconds
    "rejects": <int>,                          // Number of Sapling edit suggestions rejected
    "snippet_char_counts": <int>,              // Character count of snippets used, for estimating time saved
    "snippet_counts": <int>,                   // Number of snippets used
    "suggest_helper_selects": <int, optional>, // If Sapling Suggest is enabled for team.
    "suggest_selects": <int, optional>,        // If Sapling Suggest is enabled for team
    "suggest_views": <int,  optional>,         // If Sapling Suggest is enabled for team
    "word_count": <int>,                       // Total words
    "team_id": <str, UUID>,
}

Suggest Reporting GET​

DEPRECATED

API key holder must have reporting permissions for the team. Team must have Sapling Suggest enabled.

Request Parameters​

import requests

key = '<api-key>'

url = 'https://api.sapling.ai/api/v1/reporting/team/dashboard_user_suggest_data'
data = {
    'key': key,
    'team_id': '<team_id>',
    'start_date': '2021-12-01',
    'end_date': '2021-12-08',
}

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

https://api.sapling.ai/api/v1/reporting/team/dashboard_user_suggest_data

HTTP method: POST

key: String
32-character API key

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

start_date: String, UTC timezone ISO 8601 date or datetime
The maximum time range for reporting is 1 year. Example: 2021-12-01 or 2021-12-01 03:29.

end_date: String, UTC timezone ISO 8601 date or datetime
The maximum time range for reporting is 1 year. Example: 2021-12-08 or 2021-12-08 13:59.

If a date without time is specified (like 2021-12-08), only actions up to previous day (2021-12-07 23:59:59) will be included.

Response Parameters​

JSON list of Sapling Suggest reporting stats.

Each item in the list has the following structure:

{
    "adjusted_views": <int>,          // Responses shown excluding ones within 4 seconds of previous
    "helper_selects": <int>,
    "id": <str, UUID>,                // Opaque user id, used for management
    "is_admin": <bool>,               // This allows for excluding admins from reporting
    "is_manager": <bool>,             // This allows for excluding managers from reporting
    "login_email": <str, email>,
    "mean_response_time": <float>,    // Mean agent response time in seconds
    "median_response_time": <float>,  // Median agent response time in seconds
    "suggest_selects": <int>,         // Number of suggested responses selected
    "suggest_views": <int>,           // Number of suggested responses shown
}

Documents Reporting GET​

API key holder must have reporting permissions for the team.

This endpoint is only applicable to enterprise teams with the Documents dashboard enabled for their team. The endpoint summarizes edit activity per document.

Request Parameters​

https://api.sapling.ai/api/v1/reporting/team/dashboard_docs_data

HTTP method: POST

key: String
32-character API key

team_id: String
ID of a Sapling team.

start_date: String, UTC timezone ISO 8601 date or datetime
The maximum time range for reporting is 30 days. Example: 2021-12-01 or 2021-12-01 03:29.

end_date: String, UTC timezone ISO 8601 date or datetime
The maximum time range for reporting is 30 days. Example: 2021-12-08 or 2021-12-08 13:59.

If a date without time is specified (like 2021-12-08), only actions up to previous day (2021-12-07 23:59:59) will be included.

Response Parameters​

JSON list of documents and Sapling usage information for each document.

Each item in the list has the following structure:

{
    "doc_name": <str>,         // Unique string identifying the document
    "edit_views": <int>,       // Number of edits viewed/applied
    "edit_accepts": <int>,     // Number of edits accepted in document
    "edit_ignores": <int>,     // Number of edits ignored in document
    "doc_timestamp": <int>,    // Timestamp that document was created
    "edit_users": <Array<str, emails[]>>, // Users who performed edit actions
}