Skip to main content

Results Data API

Updated

SHOEBOX Online's Results Data API allows organizations to automatically pull their participants’ test results data from SHOEBOX Online and send it to other software applications, such as customer relationship management software or an email marketing system.

A graphical diagram showing how the API fetches data from SHOEBOX Online and transfers it to a thir-party application.

In this article:

Limitations

  • Only admin users can access the API settings in the Data Management Portal.
  • The Results Data API can only be used to fetch data from SHOEBOX Online’s secure cloud storage. It does not support sending data back to SHOEBOX Online or making changes to existing data in SHOEBOX Online.
  • The Results Data API can only be used to send data directly to its destination application. It will not function properly if the data is passed through middleware or any other intermediary software.
  • Test results are only stored in the API queue once and remain available in the queue for a maximum of four days before being removed. After the test results have been pulled from the queue via the API, they’re no longer in the queue and cannot be pulled again. However, your participants’ test results are always available in the SHOEBOX Data Management Portal.

Setting up the API

To begin setting up an API connection, you’ll need to configure your API settings in the Data Management Portal. Only users with an admin role can access these settings. If you’re an admin user, but aren’t familiar with working with APIs, we recommend getting assistance from your organization’s development team to configure the API settings.

In the API settings, you’ll need to:

  1. Enable the API.
  2. Create your organization’s API key.
  3. Obtain your organization’s API endpoint.

Optionally, you can also configure a notification webhook. For more detailed descriptions of these settings, see API Settings.

To configure the API settings

  1. Sign in to the SHOEBOX Data Management Portal.

  2. In the sidebar, hover over the Settings tab.

    A screenshot of the Settings menu in the Data Management Portal with the Advanced option highlighted.

  3. Under the SHOEBOX Online heading, click Advanced.
  4. In the top-right corner of the Advanced page, click Edit.

  5. To enable the API, turn the toggle switch to ON in the top-right corner of the SHOEBOX Online results API section.

    A screenshot of the toggle switch to enable the SHOEBOX Online Results Data API.

  6. To create a new API key, click the Create a new API key button.

    A screenshot of the button in the API settings that generates the API key.
    • Important: API keys are only generated once. If you create a new API key after you’ve already generated one, the previous API key will be revoked and disrupt your API connection.
  7. To obtain your API endpoint, click the Copy button next to the API endpoint field. Your development team will need this endpoint to connect to the API.
  8. After making your changes, click Save in the top-right corner.

Your development team will then need to add your organization’s endpoint URL to your third-party application. For additional documentation and examples, see Developer Resources. Once connected to the API, new test results will automatically populate in your third-party application.

API settings

This section describes the settings for the Results Data API.

A screenshot of SHOEBOX Online's API settings.
  1. Documentation: Links to an open API document containing technical documentation that your development team can use to set up your automated data transfer.
  2. API Key: Clicking the Create a new API key button will generate a new API key that is unique to your organization. The API key is required to connect to the Results Data API.
  3. API Endpoint: This is the directory where your development team will tell the Results Data API to send your data. The API endpoint is required to connect to the Results Data API.
  4. Notification Webhook URL: Here, you can toggle the notification webhook on or off. By enabling a notification webhook, you can immediately pull lead data into your third-party application after each test is completed instead of scheduling data pulls. This is important if you're using SHOEBOX Online to generate leads because contacting leads within a few hours significantly increases conversion success. To properly enable your notification webhook, you will need to correspond with your development team to ensure that the correct URL is placed in the URL field.

Developer resources

API resources for developers can be found below:

Github quickstart project

An example project that demonstrates how to successfully call the Results Data API and fetch participant data. To view the example project, see SHOEBOX Online API quickstart node.

Technical documentation

An open API document containing technical information including an endpoint, parameter descriptions, and a sample response. To view the API document, see SHOEBOX Online customer API.

Related to

Related articles