The Split Administration API is a tool that sends events via HTTP based API calls. This allows for calculating metrics and computing significance as part of experimentation without needing to use the track methods of the individual SDKs.

You may want to do this if you already have an external system that tracks events and are interested in passing that data to Split directly. 

Prerequisites

To run these API calls, there are a few pieces of information that are needed. 

• First, download cURL. This application is a free HTTP API client that we use to make API calls in this document. It should be installed already if you are on a Mac or a Linux machine. If you are more comfortable with other ways to call HTTP endpoints or other HTTP clients, you should still be able to follow along. It is a command line tool, so you need to have basic familiarity with the CMD.exe Command Prompt on Windows or Terminal emulators on Mac or Linux machines.
• You need a server-side SDK API key. You can create this key in the Split UI by clicking the square button at the bottom of the left navigation pane and selecting Admin Settings. In Project settings click API Keys. At the top right, click the Actions button and select Create Admin API key. The Create SDK API key page displays.

Select Server-side Type, give the key a name, and restrict it to the environments and projects that you are using the API key for. Click Create to generate the API key. 

This API key will be used for sending events.

Note: For this document, we are using $apiKey to replace the actual API key and that we gathered previously. Be sure to replace this with what you have copied down from the Prerequisites section.

Sending events

If you are not using the SDK track method, then events need to be imported in some other way, such as using the Admin API, as documented here. 

In order to send event data to Split, it must be a properly formatted JSON array that contains a series of objects. Refer to the format description below and an example with two event record objects.

[
   {
      "eventTypeId": "page_latency",
      "trafficTypeName": "user",
      "key": "Liam",
      "timestamp": "1645557823",
      "value": 3.85,
      "properties": {
         "country": "CA"
       }
   },
   {
     "eventTypeId": "page_load",
     "trafficTypeName": "user",
     "key": "Ava",
     "timestamp": "1645557824",
     "value": 1.31,
     "properties": {
       "country": "CA"
       }
   }
]

To send these events to Split via the Admin API, use the following cURL command: 

curl --location --request POST 'https://events.split.io/api/events/bulk' \

--header 'Content-Type: application/json' \

--header 'Authorization: Bearer $apiKey \
--data-raw '[
  {
     "eventTypeId": "page_latency",
     "trafficTypeName": "user",
     "key": "Liam",
     "timestamp": "1645557823",
     "value": 3.85,
     "properties": {
        "country": "CA"
      }
  },
  {
    "eventTypeId": "page_load",
    "trafficTypeName": "user",
    "key": "Ava",
    "timestamp": "1645557824",
    "value": 1.31,
    "properties": {
      "country": "CA"
      }
  }
]
'

Note: This is a POST command. It creates new events in Split. It cannot be used to edit or update existing events. It is not idempotent. Sending the same data multiple times will create multiple events.

The Split endpoint returns a 202 code, which indicates that the events have been accepted. 

Considerations

There are some things to keep in mind when using the API to track events:

• Do not track the same events that are already being tracked by the SDK track methods.
• Check for the 202 response code to ensure that events have been imported successfully.
• Unlike other Admin API functions, sending event data requires a Server Side or Client Side SDK key.
• If using a supported language; such as Java, Ruby, Python, or PHP; you can accelerate your development by using one of the Split provided Admin API wrappers.
• It cannot be stressed enough how important it is to ensure that the key used in the event records matches the key used in the getTreatment() SDK calls. If they do not match then metrics cannot be calculated properly.
• Be mindful that API calls are rate limited as mentioned in the rate limiting guide.

External references

For more information, visit the Events overview section of the API Guide.

There are also wrappers for multiple programming languages that have already been built for your convenience. For more information about API wrappers, refer to the Admin API examples.

A Postman API collection for the public Admin API endpoints is available for those who are interested in using the free Postman tool for API testing and development.

To learn more about event attribution as part of metrics and experimentation, review the Attribution and exclusion guide.