API Usage

The following two APIs let you work with segments in different ways:

• Real-Time Segments API – Lets you create, delete, list, and get segments. For more information, see the Real-Time Segments API reference.
• GraphQL API – Lets you view the results of existing segments. For more information, see the Query real-time segments section.

The Real-Time Segments API expands on what the GraphQL API lets you do. This section focuses on the Real-Time Segments API. You can use the Real-Time Segments API to create new segments, delete existing segments, list all segments, and view segment definitions.

The hostname for the API is region-specific. See the API reference to find your region's hostname.

📘

Note

This documentation uses the US region hostname (https://api.zaius.com).

These requests require authentication with private API token. See Authentication for more information.

The data type for segment-id is string, but they must always conform to case insensitive regexp pattern [a-z][a-z0-9_]*.

Operations

The possible operations are:

• List segments (GET)
• Get segment (GET)
• Delete segment (DELETE)
• Create segment (POST)
• Update segment (PUT)

List segments

GET https://{hostname}/v3/segments

Responses

Example request

$ curl -H'x-api-key: your-private-key' \
https://api.zaius.com/v3/segments
{segment_ids: ["is_active"]}

Get segment

Gets a previously defined segment.

GET https://{hostname}/v3/segments/{segment-id}

Responses

Delete segment

Deletes a previously defined segment. Returns all segmentIds that exist after the delete.

DELETE https://{hostname}/v3/segments/{segment-id}

Responses

Example request

Assuming there are three installed segments with segmentIds "example_one", "example_two" and "example_three":

$ curl -H'x-api-key: your-private-key' \
https://api.zaius.com/v3/segments/example_two
{segment_ids: ["example_one", "example_three"]}

$ curl -H'x-api-key: your-private-key' \
https://api.zaius.com/v3/segments/example_two
{"status": 404,"request_id":null,"message"Segment not found."}

Create segment

PUT https://{hostname}/v3/segments/{segment-id}

{
    "description": "total revenue less than 25",
    "definition": {
        "root_condition": {
          "customer_condition": {
            "customer_filter": {
              "comparison": {
                  "lhs": {
                      "path_reference": {
                          "value": "customer.observations.total_revenue_percentile"
                      }
                  },
                  "comparator": "LESS_THAN",
                  "rhs": {
                      "number_literal": {
                          "value": "25"
                      }
                  }
              }
            }
          }
        }
    }
}

Responses

Example request

curl -XPUT -H 'x-api-key: your-private-key' \
-H 'Content-Type': 'application/json' \
https://api.zaius.com/v3/segments/is_active \
-d '{
  "description": "Users who were active in the last 7 days",
  "definition": {
    "root_condition": {
      "sequence_condition": {
        "sequence": {
          "entry_event_filter": {
            "path_reference": {
              "value": "event.active_event"
            }
          },
          "max_age_seconds": 604800
        },
        "min_count": 1
      }
    }
  }
}'

Update segment

Updating a segment is similar to creating a segment. If you issue a PUT with a segment-id that already exists and a new segment definition, then that segment-id is updated with the new segment definition and the revision number is incremented.

Example request

Assume you have two variables with segment definitions. The first one is ${ACTIVE_7_DAYS} and matches the Create segment example body. The second one is ${ACTIVE_1_DAY}, which looks the same, except it has "max_age_seconds": 86400. This requires the user to have an active event within the last 86400 seconds (1 day).

The following requests would then:

1. Create the segment is_active, including users that were active in the last 7 days. This returns {"revision":0}.
2. Update the description for segment is_active. This returns {"revision":1}.
3. Update the definition for segment is_active. This returns {"revision":2}.

$ curl -XPUT -H'x-api-key: your-private-key' \
    https://api.zaius.com/v3/segments/is_active \
    -d @- << EOF
    {
      "description": "User was active in the last week.",
      "definition": ${ACTIVE_7_DAYS}
    }
    EOF
    {"revision":0}
    
    $ curl -XPUT -H'x-api-key: your-private-key' \
    https://api.zaius.com/v3/segments/is_active \
    -d @- << EOF
    {
      "description": "User was recently active",
      "definition": ${ACTIVE_7_DAYS}
    }
    EOF
    {"revision":1}

    $ curl -XPUT -H'x-api-key: your-private-key' \
    https://api.zaius.com/v3/segments/is_active \
    -d @- << EOF
    {
      "description": "User was recently active",
      "definition": ${ACTIVE_1_DAY}
    }
    EOF
    {"revision":2}