Revolutionizing Experimentation: The Game-Changing Impact of an API (+ How the Convert API Works)

What is there to gain from using the Convert API in your experimentation program? As convenient as the user interface may be, leveraging an API can revolutionize your experimentation efforts.

In this article, we will explore the game-changing impact an API can have and show you how to use the Convert API. (For more advanced data scientists and programmers, the Convert API Documentation may offer a more technical learning experience.)

If you’re a Convert power user, you’ve undoubtedly tried to do one of the following:

• obtaining and adding performance data to your personal dashboards
• developing a results widget for your CMS
• setting up email notifications for yourself to notify you when a milestone is reached (e.g., the number of visitors)
• creating a customized experiment results page
• making a spreadsheet using previous experiment results
• changing traffic distribution over time
• creating feature flags from an automated script
• scheduling data exports to BigQuery, Excel, etc.
• simplifying data extraction, integration, and creation of visualizations.

All of these things are now easier thanks to Convert API 2.0. The new API allows you to easily access account information as well as reporting information.

But first, the basics: what are APIs and what do they mean for your A/B testing analysis journey?

What Is an API?

If you’ve ever worked with techies, you know they love throwing around the terms like “API”. But, just like how you might use “AFAIK” without even realizing it, they often use the term without fully explaining what it means.

API stands for:

Application Programming Interface

That didn’t really help, did it?

In layman’s terms, an API is essentially a structured protocol that enables computer software to communicate with users and respond to their unique requests.

The two most widely used APIs are REST (Representational State Transfer) and SOAP (Simple Object Access Protocol).

Convert uses a REST API to manage all of its requests and interactions.

Within the REST API protocol, these four tasks can be performed using one or more specific request types:

1. When attempting to retrieve data from a server, the GET (read) method is used. Through a URL, such as http://www.getadditionaldata.com?requestParameter1=data, additional data can be sent to augment this request.
2. Advanced Read and Create: The POST method, which can be applied to almost anything, is arguably the most useful of the four. Often, POST is preferable to GET because it enables you to attach a file with a request that explicitly describes what your request is.
3. PUT (update): The main purpose of this method is to update data records on your server, such as account details, conversions, etc.
4. We won’t use the DELETE (delete) method very often in the Convert API because it is generally used to delete records.

To obtain data and manage your accounts with Convert, you will largely use POST and PUT queries, but more on that later.

APIs for Experimentation: Why Use Them?

Using an API gives you advantages in three key areas:

1. Automaticity
2. Flexibility
3. Potential

The first advantage is automaticity, which is the ability to perform multiple tasks automatically with little to no human supervision.

Using Convert for extended periods of time inevitably requires manually copying and pasting data into Excel sheets for reporting and analysis.

With the Convert API, you can set up an automated data pipeline to send the data directly to where you need it. In the long run, this will save you tons of time and keep you sane.

Flexibility, or the ability to perform specialized analysis on Convert data, is the second benefit.

Although Convert Experiences offers a lot of features, it lacks data cleaning capabilities.

By developing those utilities on top of your Convert data, you can make your experimentation journey much more powerful and tailored.

The third advantage is potential. It’s no secret that artificial intelligence is the next big thing.

Using the API, you can aggregate data from several accounts. Since Convert already offers a large and organized dataset, it enables you to build machine learning algorithms from it. In this way, you can virtually automate insights development in Convert and gain access to a vast business insight and action knowledge base.

Let’s see how you can accomplish all of these things using the Convert API.

Convert API: How Does it Work?

Postman

To explore the Convert REST API, we recommend using Postman. With this API client, you can import an API collection with example requests for each endpoint.

Download the OpenAPI specification to access a sample collection file and import it into Postman. To import a file, open the Postman app, click the Import button, then Import File. Select the json file that you downloaded from the Convert API official page. Click the Collections button, then select the folder you need from the list.

By default, this collection links to a sample Convert project. You need to update the “Pre-request script” with your own ApplicationID and ApplicationSecretKey, as well as the project, experience, goal, audiences, report IDs.

If you want to integrate the API directly into your application, you will need to get the API keys from your Convert account settings:

Google Apps Scripts

Another way to play with the Convert API is to write your own Google Apps script and then decide where to send your data. In the example below, I’ll show you how to send your data to Google Sheets.

First, create a new Google Sheet and click on Extensions > Apps Script; this will open a new tab with a URL starting with https://script.google.com/.

Click on the “Untitled project” default name in the top left corner to name your script.

Create your own API keys in your Convert account first (see above).

Write the script code and pull the Convert data you want, like so:

What Kind of Data Can You Retrieve with the Convert API?

Almost everything!

But here, we will show you a few of the most interesting endpoints.

Collaborators

An Account Owner can invite collaborators to projects and assign them different levels of access (Browse, Edit, Publish, Administrator) through the Account Settings > Collaborators menu in Convert.

It is also possible to add collaborators through a simple POST method without touching the Convert UI:

https://api.convert.com/api/v2/accounts/{account_id}/users-accesses/add

Projects

You can use projects to organize your experiences across multiple sites (or sections of large sites).

In Convert Experiences, each project has its own tracking script, experiences, collaborators, settings, and so on.

Your organization can group tests by using projects. For example, if you run experiences across multiple domains, each domain can be assigned its own project. Also, you can invite users to collaborate on a project without granting them full access to your account.

With the Convert API, you can programmatically list, create, update, and delete projects, but you can also see recent live data for each of them. The following are two of the most interesting endpoints that can be used in your project.

See Project Configuration Settings

You can access all your project configuration settings, which include:

• General Settings
  The project name, as well as the time zone, allowed tested visitors, running time, DNT (Do Not Track) settings, etc.
• Global Project Javascript
  Convert allows you to include a JS snippet in your Project. This means that all the pages that have the Convert tracking code installed will have this snippet included as well.
• Convert Tracking Code (JavaScript)
  The code you need to add to your site so that experiences can run.
• Active Websites
  The domains you would like to use inside the project.
• Blocked IPs
  Blocking IPs prevents counting stats (visitors and conversions) but allows users to see experiments or previews.
• Opt Out Link
  If you would like to exclude yourself or your team from also seeing the experiments, you would need to opt out of Convert Experiments.
• Integrations
  Convert has many out-of-the-box integrations.

Here is what these settings look like inside the app:

Similarly, via the Convert API, you can quickly get the same information by using this GET method:

https://api.convert.com/api/v2/accounts/{account_id}/projects/{project_id}

Recent Live Data for a Project

In order to view Live Logs via the UI for a specific project, you need to navigate to Projects > Live Logs on the top panel.

Click on a row for more details on the activity, such as the experiment name, browser and device used, country of the user, and goals triggered.

Similarly, via the Convert API, you can quickly get the same information by using this POST method:

https://api.convert.com/api/v2/accounts/{account_id}/projects/{project_id}/livedata

Domains

To start running A/B tests on your site, you’ll need to add a small snippet of code to the <head> tag of your site’s source code. This snippet contains your unique Project ID, and it allows the experiments you create in Convert to execute on your site.

Go to your Project Configuration, add the URL of the page that contains the Convert code, and click the Verify icon to verify the code is properly installed.

Or you can do that programmatically via the POST method:

https://api.convert.com/api/v2/accounts/{account_id}/projects/{project_id}/domains/{domain_id}/check_code

Hypotheses

A solid hypothesis will maximize chances of success, rather than randomly testing ideas you ‘feel’ are good. It is an assumption that a proposed change in your website will lead visitors to take the action you want.

For example, if you notice that the sign-up button—visible only when a user scrolls down the page—is not fetching enough clicks, you can build a hypothesis that moving the sign-up button above the fold should attract more clicks.

In Convert, you build hypotheses manually, through the Compass menu, or programmatically via this POST endpoint:

https://api.convert.com/api/v2/accounts/{account_id}/projects/{project_id}/hypotheses

Experiences

With the Convert API, you can handle the experiences just like would via the app. You can get a list of all your experiences, create new ones, clone them, update their settings, delete them, see their live data and change history.

See Experience Change History

The Change History shows a record of user activity for each test.

You can troubleshoot an experiment by checking the change history, which shows when and what changes were made. Individuals and teams with multiple collaborators can keep track of change histories through this detailed activity trail.

Each experience change history contains the following changes:

• A/B and MVT Experiments: Archive, Create, Delete, Start/Pause, Update, Modify name or description, Add/remove Variation.
• Split test: Archive, Create, Delete, Start/Pause, Update, Modify name or description, Add/remove Variation.
• Variation (not specifically what was changed but that there was a change): Change, Insert HTML or Image, Change Variation CSS or JavaScript

The POST method may be used for this as well:

https://api.convert.com/api/v2/accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/change-history

Variations

You can use the API to update a variation using the PUT method:

https://api.convert.com/api/v2/accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/variations/{variation_id}/update

You can even change the variation status (stopped/running) or its traffic distribution.

Goals

To evaluate the success of your tests, you must set up specific criteria, called Goals, within the Convert environment. This is a crucial step as it allows you to collect and analyze data to measure conversions on your website.

The POST method to use in this case is:

https://api.convert.com/api/v2/accounts/{account_id}/projects/{project_id}/goals

Audiences

Audiences let you segment your users, by event (e.g., session_start or level_up) and by user property (e.g., Browser/OS, Geo, Language), and combine events, parameters, and properties to include practically any subset of users.

With the Convert API, you can create, update, delete and list all your existing audiences.

Use this POST method to list all your current audiences:

https://api.convert.com/api/v2/accounts/{account_id}/projects/{project_id}/audiences

Reports

The ultimate goal of your experiences is to gain valuable insights and use them to increase your website conversion rate. Experience reports aid in this by allowing you to confirm your hypotheses and gain a better understanding of visitor behavior on your website.

To access your test report in the app, select the experience for which you want to view the report, and go to the REPORT tab.

The API can also be used to do that programmatically.

Aggregated Report

The aggregated report endpoint returns the full aggregated report for a given experience. Data for all the goals connected to that experience will be returned.

Daily Report

The daily report endpoint returns the full daily report for a given experience.

Experience Raw Data

The experience raw data endpoint generates an export of raw tracking data of the given experience and returns back a link where the export can be downloaded from.

Unlocking the Potential of the Convert API: Real-World Applications for Experimentation Success

Now that you know what the Convert API is capable of, you might be wondering what you can do with the data. Here are a few examples to inspire you.

Implement an Automatic Experience Scheduler

There might be instances when you would like an experience to begin or pause automatically at regular intervals without your involvement, such as launching a new experiment on Saturdays and pausing it during the week. You can accomplish this by using a cron job in your application to start/pause the experiment by instructing it to use the experiences API.

You can use the ‘start_time’ and ‘end_time’ query parameters with the specific timestamps and send a POST request to the Convert API:

POST – http://api.convert.com/doc/v2/#tag/Experiences/operation/createExperience?start_time=1672554823&end_time=1672554867

Create a Notification Center

As Convert’s UI does not support a notification center right now, using the API you can build one on your own.

This notification center can serve the following use cases:Alert the user if the experience visitors limit is reached. In your project configuration, you can set the maximum number of experience visitors and send an API alert when it is reached.

1. Alert the user if the experience visitors limit is reached. In your project configuration, you can set the maximum number of experience visitors and send an API alert when it is reached

2.Alert the user when the tracking code is removed from the website. Suppose you are an agency and your client unexpectedly removes the tracking code, causing experiments not to be tracked. Knowing that the tracking code is removed and adding it back quickly will ensure you avoid losing data.

3. Alert the user of an experience with SRM so our support team can figure out what is causing it and fix any issues as soon as possible.

4. Alert the account owner when over-quota settings are reached to prevent extra charges.

Build Your Own Reporting Dashboard

While Convert provides a detailed experience report, sometimes you may require a more personalized approach. For instance, when sharing the report with different teams within your organization. It’s important to keep in mind the nature of the business, organization or question that the report is intended to address.

• Conversions: Website owners want to know how many people are converting on their website, and having a clear, easy-to-use dashboard that shows the total number of conversions is useful. You can choose a dashboard that displays various conversions, such as e-commerce, or a more specific one that only shows conversions from your AdWords campaigns.
• Marketing: Your email campaigns, organic search, sponsored search, and other marketing may fall under this category. The performance of your top-tier marketing channels may be paired with more detailed information in your dashboard.
• Technical: A technical dashboard is essential for anyone responsible for maintaining and improving your website on a technical level. This can contain things like the various devices users use to access your website.

With Convert’s API, you can easily create the above dashboards using data from your account.

Adjust Traffic Distribution Automatically Over Time

This relates to the percentage of your visitor traffic that you will put through your experiment.

Imagine you’ve allocated 75% of your traffic to an experiment that includes the original version and 3 variations. By default, 25% of visitors will see the original, 25% will see the first variation, 25% will be assigned to the second variation, and the remaining 25% will be directed to the third variation.

This can also be changed for an uneven traffic distribution between variations.

This 75% will be used to gather statistics and goal conversions. The rest of the 25% of visitors will be shown the original without collecting any statistics on them.

Using the Convert API and a POST method, you can adjust this traffic distribution over time:

POST – http://api.convert.com/doc/v2/#tag/Experiences/operation/updateExperience?traffic_distribution=50

Summary

The use of an API in experimentation programs can have a significant impact on the efficiency and effectiveness of the results. The Convert API, in particular, offers a unique set of features that can streamline the experimentation process and provide valuable insights to data analysts. With the Convert API, automation of data processing becomes easier, improving the productivity of such procedures, allowing for greater A/B testing flexibility.

Now that you know what the Convert API is and what it can do for you, it’s time to start using it.

Sign up for a free developer account.