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 

The bearer token can be obtained from within ISVapp > 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: , success: true }

All responses of failed requests follow the error schema:

{ error: "error message", success: false }

Table of contents
Here is what you can do with the REST API

Show the account associated with the used API key (for testing)

Note: this is an endpoint intended to verify a successful API connection only. The response data cannot be used for any other purpose.

Endpoint
GET 
https://api.isvapp.com/api/v1/account
Request

none

Response

  • id - The internal ISVapp account ID

  • company_name - The company name associated with your ISVapp account

Back to top

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). You may use this endpoint to retrieve Salesforce IDs of records that you can then feed into the salesforce_account_summary endpoint.

Endpoint
GET 
https://api.isvapp.com/api/v1/salesforce_accounts
Request

none

Response

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)

Back to top

Show the summary metrics for a given account record by ID

Note: this endpoint assumes that you know the (Salesforce) IDs of account records that you like to query ISVapp-specific metrics for.

Endpoint
GET 
https://api.isvapp.com/api/v1/salesforce_account_summary
Request

One of the following is required:

  • salesforce_account_id - The 15 or 18 digit Salesforce ID of the account

  • isvapp_id - The ISVapp account UUID

Example request URL:

https://api.isvapp.com/api/v1/salesforce_account_summary?salesforce_account_id=0014x00VZKSLZITA25

Response

A successful response contains an object and the following attributes:

  • account_name - Name of the account

  • activation_date - Earliest activation date of the account

  • custom_object_record_counts (array):

    • count - Total record count on reference date

    • custom_object_isvapp_id - Internal ISVapp ID of the custom object

    • custom_object_name - Name of the custom object

    • growth_per_day_avg_last_7days - Daily average growth (can be negative)

    • package_name - Name of the package

  • custom_object_records_reference_date - Most recent date for which record counts are available

  • isvapp_id - Internal ISVapp ID

  • main_org_id - Salesforce Organization ID of the primary license

  • main_org_instance_key - Salesforce instance key (e.g. NA21) of the primary license

  • main_org_mau_most_recent - Most recent monthly active users of the primary license organization

  • main_package_version - Installed package version of the primary license

  • salesforce_id - Account ID in Salesforce

  • seats_assigned - No. of seats assigned

  • seats_total - No. of seats used

Back to top

Generate signed download URLs for a set of requests

A common use case for this endpoint is a monthly or daily download of raw request files:

  1. Request a list of requests for a specified range (e.g. one month) using the /requests endpoint

  2. Request download URLs by passing the request IDs from (1) to the /requests/downloads endpoint

Endpoint
POST 
https://api.isvapp.com/api/v1/requests/downloads
Request

The endpoint requires an application/json body containing the following attributes:

  • request_ids - Array of request IDs (min: 1, max: 1000 IDs)

Response

A successful response contains an array of objects with the following attributes:

  • request_id

  • original_file_url

Notes:

  • URLs are valid for 15 minutes

  • Request files are GZIP-compressed

Back to top

Show all package usage log requests within a given range

Endpoint
GET 
https://api.isvapp.com/api/v1/requests?from=&to=
Request

The following parameters are required:

  • from - Timestamp; format YYYY-MM-DD

  • to - Timestamp; format YYYY-MM-DD; cannot be in the future

Notes: from and to cannot span more than 31 days

Response

A successful response contains an array of objects with the following attributes:

  • id - Required to initiate downloads

  • original_file_size

  • original_file_size_compressed

  • sf_data_type

  • sf_start_time

  • sf_end_time

Back to top