API Reference

Public API

Introduction

Welcome to this comprehensive guide for the Systeme.io Public API. Our API serves as a bridge, enabling developers to interact with Systeme's core functionalities programmatically. It is meticulously designed to offer a seamless integration experience, allowing you to manage contacts, tags, and a variety of other operations integral to our platform. Adhering to RESTful conventions, our API ensures an intuitive and consistent interaction pattern for all users.

Getting Started

To begin using the Systeme.io Public API, you must first obtain an authentication key. This key is your ticket to unlocking the API's capabilities. Simply navigate to the profile settings within your Systeme.io dashboard, and generate a new key under the "Public API keys" section. Once you have your key, you're all set to embark on your first API request journey!

Authentication

To authenticate with the Systeme.io Public API, your only option right now is to attach your API key to the X-API-Key header of each request. Let us know which authentication methods you would like to see implemented next!

Rate-Limiting

Our Public API implements a rate-limiting system to maintain service stability and availability for all users. Here's how it works:

  • Refill Rate: Your request quota is periodically replenished. The X-RateLimit-Refill header indicates when the next quota refill will occur.
  • Limit Ceiling: There is a maximum quota limit, which is the total number of requests you can make within a given time frame. The X-RateLimit-Limit header shows this maximum number.
  • Shared Quota: The request limit is collectively applied across all your API keys and tokens. The X-RateLimit-Remaining header informs you of the number of requests left in your current rate limit window.

If you exceed the rate limit, you will receive a 429 Too Many Requests response status code. This indicates that you have sent too many requests in a given time frame. Along with this response, you will receive a Retry-After header indicating the number of seconds to wait before making a new request. We advise implementing appropriate error handling strategies in your application to manage these responses effectively.

Using the API

Our documentation is your roadmap to the Systeme.io Public API. It details the endpoints available, their respective URLs, the expected formats for requests and responses, and outlines the basic constraints to be aware of.

Collection Pagination

Understanding Cursor-Based Pagination: Our API employs a cursor-based pagination system for efficiently navigating through large collections of resources. A cursor acts as a reference point, indicating the position in the dataset from which to retrieve the next set of results.

How to Use Pagination:

  • Starting Point: Use the startingAfter parameter to specify the ID of the last item you received. This sets the cursor for the next page of data.
  • Control Record Count: The limit parameter allows you to control the number of records returned in each request. Tailor this to suit your data handling needs.
  • Ordering: Specify the order of the data using the order parameter, with options for ascending (asc) or descending (desc) order. The default setting is descending (desc).

Response Structure:

  • Items Key: The response will include the retrieved data under the items key.
  • Has More: A hasMore key is also provided, indicating whether additional pages of data are available.

Efficient Data Retrieval: This pagination method ensures efficient and manageable data retrieval, especially when dealing with large datasets. It allows for seamless navigation through your resource collections, providing a user-friendly and intuitive way to access the data you need.

Updating Resources with PATCH

Efficient Updates with Merge Patch: Our API supports the PATCH method with application/merge-patch+json content type for efficiently updating resources. This method allows partial updates to a resource, modifying only specified fields without the need to resend the entire resource.

Example - Updating a Contact: To update a contact's details, you can send a PATCH request with a payload like the following:

{
    "locale": "en",
    "fields": [
        {
            "slug": "country",
            "value": "US"
        },
        {
            "slug": "phone_number",
            "value": null
        }
    ]
}

In this example:

  • The country field is updated to US.
  • The phone_number is set to null, effectively removing any previously set value.

Selective Modification: This approach is particularly useful for selectively modifying specific attributes of a resource, such as a contact, without affecting other existing data. It streamlines the update process, making it more efficient and user-friendly.

Code Examples

Creating a Tag with curl

To create a new tag, use the following curl command as a template:

curl -X POST 'https://api.systeme.io/api/tags'\
-H 'Content-Type: application/json'\
-H 'X-API-Key: your_api_key'\
-d '{"name": "NewTagName"}'

Retrieving Contacts with JavaScript

To retrieve a list of contacts, you can use the JavaScript fetch function as shown in the following example:

fetch('https://api.systeme.io/api/contacts', {
    headers: {
        'X-API-Key': 'your_api_key'
    }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

In the next sections, you'll find more detailed examples and explanations to guide you through how to leverage our API's full potential. Whether you're looking to automate processes, integrate with existing systems, or build something entirely new, our API is designed to provide the flexibility and control you need.