ISVapp REST API Documentation
Please let us know if a section needs clarification, better examples or if you have general feedback via [email protected]
Authentication
Every API request must be signed via the Authorization header using the Bearer keyword. Example:
Authorization: Bearer [token]
The bearer token can be obtained via one of two authentication mechanisms:
Option 1: OAuth2
OAuth2 is a modern authentication protocol. ISVapp supports the Client Credentials flow, in which you use a client ID and secret to request access tokens that can be used to access API resources. Compared to static API keys, OAuth2 allows for a more fine-grained access control. You can obtain client ID and secret from within ISVapp under Setup > REST API.
You can implement the OAuth2 flow yourself or leverage a client library. In both cases, please use POST https://api.isvapp.com/api/oauth2/token as your token endpoint. Below is the required payload:
scope=identity&grant_type=client_credentials
The request body must be encoded using application/x-www-form-urlencoded. The request must be authenticated using your client ID and secret, via the HTTP Basic authentication. Please use the client ID as username and the client secret as password. A successful response looks like this and is encoded using application/json:
{
"access_token": "...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "identity"
}
Please refer to the individual endpoints in order to pick the correct scope for your tokens. We recommend to only select the minimum required scope.
Option 2: API Keys
API Keys can be created from within ISVapp under Setup > REST API. In order to generate a new key, click the “Generate new API key” button (you need Owner permissions in order to create API keys).
Ensure that you select the correct permission scope for your API key. The necessary permission scopes are documented for each API endpoint below. For example, in order to retrieve metrics from ISVapp, select the ISVapp metrics retrieval scope.
Note: all endpoints in this API are rate-limited. You can perform a maximum of two requests per second. Please adjust your integration code accordingly.
Response structure
All responses of successful requests are wrapped into an envelope structure:
{ data: [response], success: true }
All responses of failed requests follow the error schema:
{ error: "error message", success: false }
Show the currently authenticated ISVapp account
Note: use this endpoint to verify a successful API connection.
https://api.isvapp.com/api/v1/account
identity
ISVapp metrics retrieval
none
id - The internal ISVapp account ID
company_name - The company name associated with your ISVapp account
Request a data export from ISVapp
This endpoint allows you to request usage data exports from ISVapp. It handles exports asynchronously, allowing you to track progress and download the results once the export is complete. The process is outlined below:
Request a data export: Send a request to this endpoint to initiate the export. A unique export URL will be generated, which you can use to track its progress.
Track export progress: The export process typically takes 30 seconds to 10 minutes, depending on the data size. Use the generated URL to monitor the status.
Download the export file: Once the export is complete, use the provided URL to download the file.
Decompress the downloaded file: All export files are gzip-compressed to optimize download speed and bandwidth usage. Most HTTP clients handle decompression automatically.
Process each row of the file: The downloaded file contains one JSON object per row. The structure of each row depends on the requested data type. Refer to the "Download and Process an Export File" section for more details.
Supported Data Types
Taxonomy items: Individual entries within a taxonomy, aggregating usage across multiple features or child taxonomy items. Learn more about ISVapp Feature Taxonomies.
We plan to expand this endpoint to support additional data export types in the future. If you have a specific use case you'd like us to consider, please contact us at [email protected]. Our support team is also available to discuss your use case in more detail.
/api/v1/exports
exports
ISVapp metrics retrieval
Based on the data you wish to export, use one of the following request payloads:
Exporting Taxonomy Items
Please provide the following fields in the request JSON body:
type - The data type (required). Possible values: TAXONOMY_ITEM
aggregation - The aggregation level (required). Possible values: MONTHLY
timeframe - The timeframe for the data to be exported (required). This attribute accepts a specific timeframe as well as the keywords described below:
A month in the format YYYY-MM (e.g., 2024-02). The API currently allows you to request any completed month that is visible in the ISVapp user interface. You cannot specify a month where data retrieval has not yet been fully completed (e.g. month-to-date usage).
LATEST_COMPLETED_MONTH - This will select the most recent month for which ISVapp has fully completed data retrieval. Typically, ISVapp completes data retrieval for a month by around the 5th of the following month, as Salesforce may continue providing data after the month has ended.
LATEST_12_COMPLETED_MONTHS - This will return data for the most recent 12-month period, ending with the most recent month for which ISVapp has fully completed data retrieval. For example, if data is requested on April 15, 2024, the response will include data from April 1, 2023, through March 31, 2024.
taxonomy_ids - Array of taxonomy IDs (optional). All taxonomy items included in the provided taxonomies will be exported.
taxonomy_level_ids - Array of taxonomy level IDs (optional). All taxonomy items included in the provided taxonomy levels will be exported.
taxonomy_item_ids - Array of taxonomy item IDs (optional)
salesforce_account_ids - Array of Salesforce 15 or 18 digit account IDs (optional). If provided, the exported data will be limited to those accounts.
Note: exactly one of the following fields is required:
taxonomy_ids
taxonomy_level_ids
taxonomy_item_ids
Here is an example request body:
{
"type": "TAXONOMY_ITEM",
"aggregation": "MONTHLY",
"timeframe": "2024-02",
"taxonomy_ids": ["c9d7ddb..."]
}
Here is an example response that you'll see immediately after requesting an export:
{
"id": "dd8eea7b-bd22-4422-8ea9-8315fcf04622",
"type": "TAXONOMY_ITEM",
"status": "PENDING",
"url": "https://api.isvapp.com/api/v1/exports/dd8eea...",
...
}
Use the url field above to monitor the export status. See the "Show export details" endpoint for a full list of export fields.
Show export details
/api/v1/exports/:id
exports
ISVapp metrics retrieval
none
The response contains the following fields:
id - Internal ID of the export
type - Data type as requested
status - The current processing status. Can be one of PENDING, COMPLETED or ERRORED.
url - The URL that you can use to query (using GET) the details of this export.
download_url - Available once status is COMPLETED. Use this URL to download the request.
created_at - The time at which this export was created.
completed_at - The time at which the export finished.
expires_at - The time at which the export expires.
is_expired - Whether the export is expired (meaning it cannot be downloaded anymore).
download_size_compressed_bytes - The compressed download file size in bytes.
download_size_uncompressed_bytes - The uncompressed download file size in bytes.
error_message - Contains an error message in case the export errored.
errored_at - The time at which the export errored.
Here is an example response for a completed export:
{
"completed_at": "2023-10-01T08:42:22.100005Z",
"created_at": "2023-10-01T08:38:31.711005Z",
"download_size_compressed_bytes": 1010000,
"download_size_uncompressed_bytes": 12600000,
"download_url": "https://api.isvapp.com/api/v1/exports/dd8eea...",
"error_message": null,
"errored_at": null,
"expires_at": "2023-10-01T09:42:22.100005Z",
"id": "dd8eea..."
"is_expired": false,
"status": "COMPLETED",
"type": "TAXONOMY_ITEM"
}
Once the export is complete, you can use the download_url field above, to download the export file. Please refer to the "Download and process an export file" endpoint.
List recent exports
This endpoint returns a list of the 1000 most recent exports.
/api/v1/exports
exports
ISVapp metrics retrieval
none
An array of exports. Please refer to the "Show export details" endpoint for a list of fields.
Download and process an export file
Refer to the two endpoints above in order to create an export download URL.
/api/v1/exports/:id/download/:token
exports
ISVapp metrics retrieval
none
The download file for an export is gzip-compressed. The file content is formatted in ndjson (newline delimited JSON format) and contains one JSON-object per row. Here is a structural example of the download file once decompressed (omitting specific details):
{ "type": "...", < other fields > }
{ "type": "...", }
...
The structure of each JSON row depends on the requested data type.
Taxonomy item exports
Each JSON-row in a taxonomy item export has the following structure:
{ "type": "TAXONOMY_ITEM",
{ "type": "TAXONOMY_ITEM",
...
For enhanced readability, here is one row formatted using line breaks:
{
"type": "TAXONOMY_ITEM",
"aggregation": "MONTHLY",
"reference_date": "2024-03",
"salesforce_account_id": "0014x000FVCAPXFAY5",
"salesforce_account_name": "...",
"taxonomy_id": "dd8eea7b...",
"taxonomy_item_id": "8315fcf...",
"taxonomy_item_label": "Player Management",
"taxonomy_item_parent_item_id": null,
"taxonomy_label": "Main Product Taxonomy",
"taxonomy_level_id": "5fcf827...",
"taxonomy_level_label": "Product Area",
"unique_users": "455",
"unique_users_external": "400",
"unique_users_internal": "55",
"operations": "16700",
"operations_external": "16000",
"operations_internal": "700"
}
Show a list of active Salesforce accounts
This endpoint is intended to query all active Salesforce accounts that ISVapp has identified in your partner business organization (PBO).
Optional Parameters
You can customize the response to include additional information by using the following query parameters:
?includeHealthScores=1 - Append this query parameter in order to include all health scores. Use this option in order to sync health scores with third party systems (e.g. Pendo, Gainsight, ChurnZero or another Salesforce Organization).
?includeSubscriberOrgs=1 - Append this query parameter in order to include subscriber organizations.
Endpoint details
https://api.isvapp.com/api/v1/salesforce_accounts
salesforce_accounts
ISVapp metrics retrieval
none
A successful response contains an array of objects with the following attributes:
isvapp_id - Internal ISVapp ID (for debugging purposes only)
salesforce_id - ID of the record in your Salesforce PBO
name - Name of the record in your Salesforce PBO (for debugging purposes)
If requested, it includes an array of health scores:
health_scores - Array, each element contains:
score - The health score, e.g. 42
is_primary - Whether this is the primary score
label - Label of the score
If requested, it includes an array of subscriber organizations:
subscriber_orgs - Array, each element contains:
name - The subscriber organizations name
salesforce_id - Salesforce Organization ID