Statistics
The number of messages sent, the number of active users and other statistics worth knowing.
Dashboard statistics
Return data of interest for a dashboard
GET /v<api_version>/admin/stats/dashboard/
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. Information is returned as a JSON object as described below. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because the calling admin’s organisation has been disabled. |
If the request was successful, the JSON structure returned is a JSON object with the following elements:
| Name | Type | Visible to | Description |
|---|---|---|---|
settings |
String | All admins | The organisation’s active privacy mode. |
users_count |
Number | All admins | The number of active users, that is, users that have used a Teamwire client at least once and are currently not disabled. |
pending_users_count |
Number | All admins | The number of users that haven’t used a Teamwire client yet. |
groups_count |
Number | All admins | The number of groups in the organisation. |
domains_count |
Number | All admins | The number of domains in the organisation. |
admins_count |
Number | All admins | The number of admins in the organisation. |
company |
String | All admins | The company name as stored in the admin’s profile. |
license_count |
Number | All admins | The number of licenses in the organisation. |
admins |
Array | All admins | An array of objects with information on the organisation’s admins as described below. |
Each admins object has the following elements:
| Name | Type | Description |
|---|---|---|
first_name |
String | The admin’s first name. |
last_name |
String | The admin’s last name. |
super |
Boolean | Whether the admin is a Superadmin. |
Statistics about the number of active users
Return the number of active users
GET /v<api_version>/admin/stats/active_users/<organisation_id>/
Active users are users that have sent at least one message in the given organisation and time period. This endpoint returns the number of active users in the given organisation and time period.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| organisation_id | Number | Yes | Superadmins | The ID of the organisation whose users are to be analysed. |
GET parameters
The following parameters are passed as part of the URL according to GET conventions, i.e. ?name1=value1&name2=value2:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
month |
Number | Yes | All admins | Restricts the analysis to users in this month. |
year |
Number | No | All admins | Restricts the analysis to users in this year. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. API key information is returned as a JSON object as described below. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) the admin is not a Superadmin and an organisation_id was specified that does not match the admin’s organisation. |
| 404 (Not Found) | The request failed because the specified organisation could not be found. |
Statistics are returned as a JSON list of objects, each representing a single interval in the past. Each object has the following elements:
| Name | Type | Description |
|---|---|---|
keys |
String | Describes what is being returned, i.e. “Active Users”. |
min_year |
Number | The oldest year for which data is available (for use in subsequent requests). |
min_month |
Number | The oldest month within min_year for which data is available (for use in subsequent requests). |
data |
Array | An array of objects with the actual data. See below for details. |
Each data object has the following elements:
| Name | Type | Description |
|---|---|---|
date |
String | Describes a single interval within the chosen time period. The format used is YYYY-MM-DD if month was specified and YYYY-MM otherwise. |
count |
Number | The number of active users in this interval. |
Statistics about the number of activated connectors
Return the number of activated connectors #### noqa
GET /v<api_version>/admin/stats/activated_connectors/<organisation_id>/
Each Teamwire client application uses a connector to communicate with the backend. This endpoint returns the number of connectors that were activated the given organisation and time period.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| organisation_id | Number | Yes | Superadmins | The ID of the organisation whose connectors are to be analysed. |
GET parameters
The following parameters are passed as part of the URL according to GET conventions, i.e. ?name1=value1&name2=value2:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
month |
Number | Yes | All admins | Restricts the analysis to connectors in this month. |
year |
Number | No | All admins | Restricts the analysis to connectors in this year. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. API key information is returned as a JSON object as described below. |
| 400 (Bad Request) | The request failed because server cannot or will not process the request due to something that is wrong with params. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) the admin is not a Superadmin and an organisation_id was specified that does not match the admin’s organisation. |
| 404 (Not Found) | The request failed because the specified organisation could not be found. |
Statistics are returned as a JSON list of objects, each representing a single interval in the past. Each object has the following elements:
| Name | Type | Description |
|---|---|---|
keys |
String | Describes what is being returned, i.e. “Activated Connectors”. |
min_year |
Number | The oldest year for which data is available (for use in subsequent requests). |
min_month |
Number | The oldest month within min_year for which data is available (for use in subsequent requests). |
data |
Array | An array of objects with the actual data. See below for details. |
Each data object has the following elements:
| Name | Type | Description |
|---|---|---|
date |
String | Describes a single interval within the chosen time period. The format used is YYYY-MM-DD if month was specified and YYYY-MM otherwise. |
count |
Number | The number of activated connectors in this interval. |
Statistics about the number of messages sent
Return the number of messages sent in the given organisation and time period
GET /v<api_version>/admin/stats/sent_messages/<organisation_id>/
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| organisation_id | Number | Yes | Superadmins | The ID of the organisation whose messages are to be analysed. |
GET parameters
The following parameters are passed as part of the URL according to GET conventions, i.e. ?name1=value1&name2=value2:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
month |
Number | Yes | All admins | Restricts the analysis to messages in this month. |
year |
Number | No | All admins | Restricts the analysis to messages in this year. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. API key information is returned as a JSON object as described below. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) the admin is not a Superadmin and an organisation_id was specified that does not match the admin’s organisation. |
| 404 (Not Found) | The request failed because the specified organisation could not be found. |
Statistics are returned as a JSON list of objects, each representing a single interval in the past. Each object has the following elements:
| Name | Type | Description |
|---|---|---|
keys |
String | Describes what is being returned, i.e. “Messages”. |
min_year |
Number | The oldest year for which data is available (for use in subsequent requests). |
min_month |
Number | The oldest month within min_year for which data is available (for use in subsequent requests). |
data |
Array | An array of objects with the actual data. See below for details. |
Each data object has the following elements:
| Name | Type | Description |
|---|---|---|
date |
String | Describes a single interval within the chosen time period. The format used is YYYY-MM-DD if month was specified and YYYY-MM otherwise. |
count |
Number | The number of messages sent in this interval. |
Statistics about the last usages of Teamwire clients
Return the distribution of last usages of Teamwire clients
GET /v<api_version>/admin/stats/last_usages/<organisation_id>/
This endpoint returns a monthly distribution of last Teamwire client usages for the given organisation, i.e. for each month the number of users that used a Teamwire client for the last time in that particular month.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| organisation_id | Number | Yes | Superadmins | The ID of the organisation whose usages are to be analysed. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. API key information is returned as a JSON object as described below. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) the admin is not a Superadmin and an organisation_id was specified that does not match the admin’s organisation. |
| 404 (Not Found) | The request failed because the specified organisation could not be found. |
Statistics are returned as a JSON list of objects, each representing a single interval in the past. Each object has the following elements:
| Name | Type | Description |
|---|---|---|
key |
Object | The interval for which data is being returned. See below for details. |
y |
Number | The number of Teamwire users that were using a Teamwire client in this interval. |
Each key object has the following elements:
| Name | Type | Description |
|---|---|---|
month |
Number | The month for which data is being returned. |
year |
Number | The year for which data is being returned. |
Provides statistics about devices
Return device statistics
GET /v<api_version>/admin/stats/device/<discriminator>/
GET /v<api_version>/admin/stats/device/<discriminator>/<organisation_id>/
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| discriminator | String | No | All admins | The type of statistics to return: one of os (Client OS statistics), client (Teamwire client statistics), is_managed (Managed devices statistics) and locale (Locale statistics). |
| organisation_id | Number | Yes | Superadmins | The ID of the organisation whose usages are to be analysed. |
GET parameters
The following parameters are passed as part of the URL according to GET conventions, i.e. ?name1=value1&name2=value2:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
os |
String | Yes | All admins | If discriminator is os, this can be used to limit the statistics to an individual operating system. |
client |
String | Yes | All admins | If discriminator is client, this can be used to limit the statistics to individual client versions. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. API key information is returned as a JSON object as described below. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) the admin is not a Superadmin and an organisation_id was specified that does not match the admin’s organisation. |
| 404 (Not Found) | The request failed because the specified organisation could not be found. |
If the request was successful, a JSON object is returned with the following elements:
| Name | Type | Visible to | Description |
|---|---|---|---|
keys |
String | All admins | Describes what is being returned: one of Client OS Statistics, Client Statistics, Client Managed Statistics or Client Locale Statistics. Suitable for display to the admin. |
data |
Array | All admins | An array of JSON objects as described below. |
In case of a discriminator of os (Client OS statistics),
each JSON object will have the following elements:
| Name | Type | Description |
|---|---|---|
os |
String | The client’s OS, e.g. “Windows” or “Android”. |
os_v |
String | The client OS’s version. This will only be present if the os GET parameter has been specified to limit stats to a certain client operating system. |
total |
Number | Total number of devices for this os or os_v. |
In case of a discriminator of client (Teamwire client statistics),
each JSON object will have the following elements:
| Name | Type | Description |
|---|---|---|
client |
String | The Teamwire client type, e.g. “Desktop” or “Android”. |
client_v |
String | The Teamwire client’s version. This will only be present if the client GET parameter has been specified to limit stats to a certain Teamwire client type. |
total |
Number | Total number of devices for this given client or client_v. |
In case of a discriminator of is_managed (Managed devices statistics),
each JSON object will have the following elements:
| Name | Type | Description |
|---|---|---|
client |
String | The Teamwire client type, e.g. “Desktop” or “Android”. |
os |
String | The client’s OS, e.g. “Windows” or “Android”. |
In case of a discriminator of locale (Locale statistics),
each JSON object will have the following elements:
| Name | Type | Description |
|---|---|---|
locale |
String | The client locale, e.g. “de” or “en”. |
total |
Number | Total number of devices for this locale. |