Conversions API

SplitLab runs A/B tests on your landing pages. A conversion is counted for the variant the visitor saw. When the conversion happens on your side (a thank-you page, a booking, a sale, an audit completed in your own tool), your server can report it to SplitLab with a single HTTP call instead of loading our script.

You need two things: an API key from SplitLab, and the three visitor values SplitLab hands to your site.

1. A visitor lands on a SplitLab page and is shown one variant of the test.
2. When they move on to your site or your tool, SplitLab passes three values along with them: sl_tid, sl_vid and sl_vh.
3. Your site keeps those values with the lead.
4. When the conversion happens, your server sends them to the Conversions API.
5. SplitLab counts the conversion for the variant that visitor saw.

There are no goals to create. Name each conversion with event_name (for example Lead or Purchase). The first time a test receives a name, SplitLab creates a goal for it on that test, and every later conversion with that name is counted under it, the way Facebook's Conversions API works. See Events and goals.

When a visitor leaves the SplitLab page for your domain, through a link, a button or a form, SplitLab adds the values to the URL automatically. Nothing to set up:

https://yoursite.com/thank-you?sl_tid=…&sl_vid=…&sl_vh=…

• Forms that post to your server: the values are on that POST's URL as well. Read them there, because a redirect to your thank-you page may drop them.
• Forms sent with JavaScript (AJAX): the values are added to the form's action URL, so send the request to the form's action rather than a URL written into your script.
• Thank-you page on the same domain as the SplitLab page: the values are only added when the visitor moves to a different domain. Use the email / phone fallback.

If your tool opens inside the SplitLab page instead, see Embedded tools (iframes).

A booking widget, quiz, calculator or audit tool that opens inside the SplitLab page (an iframe) is never navigated to, so SplitLab cannot add the values to its URL automatically. And because sl_vh is different for every visitor, the values cannot be typed into the page either.

Instead, write placeholders into the iframe's URL. Every time SplitLab serves the page, it replaces them with that visitor's values:

<iframe src="https://yourtool.com/start?sl_tid={{sl_tid}}&sl_vid={{sl_vid}}&sl_vh={{sl_vh}}"></iframe>

<iframe src="https://yourtool.com/start?sl_tid=4b8f0c1e-…&sl_vid=9a2d7e55-…&sl_vh=c3f1a9d2-…"></iframe>

Inside your tool

1. Read sl_tid, sl_vid and sl_vh from the URL your tool was loaded with.
2. Keep them with the visitor's session or lead.
3. When the visitor converts, send them from your server to the Conversions API.

const params = new URLSearchParams(window.location.search);
const splitlab = {
  sl_tid: params.get('sl_tid'),
  sl_vid: params.get('sl_vid'),
  sl_vh: params.get('sl_vh'),
};
// Send these to your server with the lead; your server calls the Conversions API.

Put the placeholders in the attribute the iframe really loads from. If the iframe has a data-src that the page's script copies into src when a popup opens, the placeholders go in data-src.

<iframe data-src="https://yourtool.com/start?sl_tid={{sl_tid}}&sl_vid={{sl_vid}}&sl_vh={{sl_vh}}"></iframe>

Add them on every variant of the test. Each variant is its own page.

Rules

• Write the placeholders exactly as shown: {{sl_tid}}, {{sl_vid}}, {{sl_vh}}, with no spaces inside the braces.
• They work anywhere in the page's HTML, including src, data-src and links, and in embeds added to the page in SplitLab.
• They are filled when SplitLab serves the test page. In the page editor they stay as written, which is expected.
• Only the iframes you add placeholders to receive the values; other embeds on the page get nothing.

Every request carries your API key as a Bearer token. Create one in SplitLab: open the client, go to API Keys → New API key and give it a name. Keys look like sl_live_xxxxxxxx_… and are shown only once, so copy it straight away.

Authorization: Bearer YOUR_API_KEY

• Keep the key on your server. Requests from a browser are rejected.
• A key only works for your own tests.
• Creating and revoking keys needs manager access to the client; anyone with access can see the list and when each key was last used.
• If a key is lost or exposed, create a new one, switch your server to it, then revoke the old one on the same page. A revoked key stops working at once. You can hold several keys at a time, so no conversions are lost in between.

If the sl_* values were lost, send the email address or phone number the visitor entered in the form on the SplitLab page. SplitLab looks up their form submission from the last 90 days and counts the conversion for the variant they saw.

{ "email": "[email protected]" }

{ "phone": "+1 (404) 555-0142" }

This only works when the visitor filled in a form on the SplitLab page itself. Use it for the cases where the values cannot reach you, for example when your thank-you page is on the same domain as the SplitLab page (the values are only added when the visitor moves to a different domain).

Send an event_name and SplitLab does the rest. The first conversion with a new name creates a goal of that name on the test; later conversions with the same name are counted under it. Nothing has to be set up in SplitLab first.

{ "sl_vid": "…", "sl_vh": "…", "event_name": "Lead" }
{ "sl_vid": "…", "sl_vh": "…", "event_name": "Purchase" }

• Each name becomes its own goal, shown in the test's goals with an API event label. Names are matched ignoring letter case, so Lead and lead are the same goal.
• Without event_name, conversions are counted on a goal called API conversion.
• A goal is created per test. Sending Lead for two tests gives each test its own Lead goal.
• The same visitor is counted once per event: a repeat returns duplicate: true. A visitor can still count for Lead and later Purchase.
• In the results, conversions are counted once per visitor, whichever events they reached. The Goals column shows every event reached.
• To count a conversion on a goal that already exists instead (for example one set up in SplitLab), send its goal_id, copied with the button next to the goal under Settings → Conversion Goals. A click or form goal is also recorded in the visitor's browser, so if the visitor already clicked, the API call returns duplicate: true.

Every response is JSON. Errors include an error message saying what was wrong.

• Retries are safe. The same visitor and event are counted once; a repeat returns duplicate: true.
• Report late if you need to. The values stay valid, so a conversion that happens days later can still be sent.
• Where it shows. API conversions appear in the test's results in SplitLab. They don't add a row to the Leads list, because the visitor's form submission is already there.
• Server only. The API sends no CORS headers, so a call from browser code fails by design.

Still stuck? Contact us with the request body (without the key) and the response.