Segments

Use this endpoint to manipulate and obtain details on Mautic’s Segments (also known as Lists).

Using Mautic’s API Library

You can interact with this API through the Mautic API Library as follows, or use the various http endpoints as described in this document.

<?php
use Mautic\MauticApi;
use Mautic\Auth\ApiAuth;

// ...
$initAuth   = new ApiAuth();
$auth       = $initAuth->newAuth($settings);
$apiUrl     = "https://example.com";
$api        = new MauticApi();
$segmentApi = $api->newApi("segments", $auth, $apiUrl);

Get Segment

<?php

//...
$segment = $segmentApi->get($id);

Get an individual Segment by ID.

HTTP Request

GET /segments/ID

Response

Expected Response Code: 200

{
    "list": {
        "id": 1,
        "isPublished": true,
        "dateAdded": "2015-07-15T15:06:02-05:00",
        "createdBy": 1,
        "createdByUser": "Joe Smith",
        "dateModified": "2015-07-20T13:11:56-05:00",
        "modifiedBy": 1,
        "modifiedByUser": "Joe Smith",
        "name": "VIP Customers",
        "alias": "vip-customers",
        "description": "High-value customers",
        "publicName": "VIP List",
        "filters": [
            {
                "glue": "and",
                "field": "points",
                "object": "lead",
                "type": "number",
                "operator": "gte",
                "properties": {
                    "filter": "100"
                }
            }
        ],
        "isGlobal": true,
        "isPreferenceCenter": false,
        "category": {
            "id": 1,
            "title": "Customer Segments",
            "alias": "customer-segments",
            "color": "4e5d9d",
            "bundle": "lead"
        }
    }
}

Segment Properties

Name	Type	Description
`id`	int	ID of the Segment
`isPublished`	boolean	`true` if the Segment is published
`dateAdded`	`datetime`	Date/time Segment was created
`createdBy`	int	ID of the User that created the Segment
`createdByUser`	string	Name of the User that created the Segment
`dateModified`	datetime/null	Date/time Segment was last modified
`modifiedBy`	int	ID of the User that last modified the Segment
`modifiedByUser`	string	Name of the User that last modified the Segment
`name`	string	Name of the Segment
`alias`	string	Alias of the Segment used for searches and URLs
`description`	string/null	Description of the Segment
`publicName`	string/null	Public name of the Segment (displayed to contacts)
`filters`	array	Array of filter criteria that define the Segment
`isGlobal`	boolean	`true` if the Segment is global (visible to all users)
`isPreferenceCenter`	boolean	`true` if the Segment can be used in preference centers
`category`	object/null	Category object that contains the Segment

List Segments

<?php

//...
$segments = $segmentApi->getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

Get a list of Segments.

HTTP Request

GET /segments

Query Parameters

Name	Description
`search`	String or search command to filter entities by.
`start`	Starting row for the entities returned. Defaults to 0.
`limit`	Limit number of entities to return. Defaults to the system configuration for pagination, which is 30 by default.
`orderBy`	Column to sort by. Can use any column listed in the response. However, you need to change all properties in the response written in `camelCase` a bit. Before every capital, add an underscore `_` and then change the capital letters to non-capital letters. So `dateAdded` becomes `date_added`, `modifiedByUser` becomes `modified_by_user`, etc.
`orderByDir`	Sort direction: `asc` or `desc`.
`publishedOnly`	Only return currently published entities.
`minimal`	Return only array of entities without additional lists in it.
`where`	An array of advanced where conditions
`order`	An array of advanced order statements

Response

Expected Response Code: 200

{
    "total": 1,
    "lists": {
        "1": {
            "id": 1,
            "isPublished": true,
            "dateAdded": "2015-07-15T15:06:02-05:00",
            "createdBy": 1,
            "createdByUser": "Joe Smith",
            "dateModified": "2015-07-20T13:11:56-05:00",
            "modifiedBy": 1,
            "modifiedByUser": "Joe Smith",
            "name": "VIP Customers",
            "alias": "vip-customers",
            "description": "High-value customers",
            "publicName": "VIP List",
            "filters": [
                {
                    "glue": "and",
                    "field": "points",
                    "object": "lead",
                    "type": "number",
                    "operator": "gte",
                    "properties": {
                        "filter": "100"
                    }
                }
            ],
            "isGlobal": true,
            "isPreferenceCenter": false,
            "category": {
                "id": 1,
                "title": "Customer Segments",
                "alias": "customer-segments",
                "color": "4e5d9d",
                "bundle": "lead"
            }
        }
    }
}

Properties

Same as Get Segment.

Create Segment

<?php

$data = array(
    'name' => 'VIP Customers',
    'alias' => 'vip-customers',
    'description' => 'High-value customers',
    'isPublished' => true,
    'isGlobal' => true,
    'filters' => array(
        array(
            'glue' => 'and',
            'field' => 'points',
            'object' => 'lead',
            'type' => 'number',
            'operator' => 'gte',
            'properties' => array(
                'filter' => '100'
            )
        )
    )
);

$segment = $segmentApi->create($data);

Create a new Segment.

HTTP Request

POST /segments/new

POST Parameters

Name	Type	Description
`name`	string	Segment name (required)
`alias`	string	Segment alias used for URLs and searches
`description`	string	Segment description
`publicName`	string	Public name displayed to contacts
`isPublished`	boolean	Whether the Segment is published (defaults to `false`)
`isGlobal`	boolean	Whether the Segment is global (defaults to `true`)
`isPreferenceCenter`	boolean	Whether the Segment can be used in preference centers (defaults to `false`)
`filters`	array	Array of filter criteria that define the Segment
`category`	int	ID of the Category to assign to the Segment

Response

Expected Response Code: 201

Properties

Same as Get Segment.

Edit Segment

<?php

$id   = 1;
$data = array(
    'name' => 'Updated VIP Customers',
    'description' => 'Updated high-value customers segment',
);

// Create new a Segment of ID 1 isn't found?
$createIfNotFound = true;

$segment = $segmentApi->edit($id, $data, $createIfNotFound);

Edit an existing Segment. Note that this supports PUT or PATCH depending on the desired behavior.

PUT creates a Segment if the given ID doesn’t exist and clears all the Segment information, adds the information from the request. PATCH fails if the Segment with the given ID doesn’t exist and updates the Segment field values with the values from the request.

HTTP Request

To edit a Segment and return a 404 if the Segment isn’t found:

PATCH /segments/ID/edit

To edit a Segment and create a new one if the Segment isn’t found:

PUT /segments/ID/edit

POST Parameters

Name	Type	Description
`name`	string	Segment name
`alias`	string	Segment alias used for URLs and searches
`description`	string	Segment description
`publicName`	string	Public name displayed to contacts
`isPublished`	boolean	Whether the Segment is published
`isGlobal`	boolean	Whether the Segment is global
`isPreferenceCenter`	boolean	Whether the Segment can be used in preference centers
`filters`	array	Array of filter criteria that define the Segment
`category`	int	ID of the Category to assign to the Segment

Response

If PUT, the expected response code is 200 if the Segment was edited or 201 if created. If PATCH, the expected response code is 200.

Properties

Same as Get Segment.

Delete Segment

<?php

$segment = $segmentApi->delete($id);

Delete a Segment.

HTTP Request

DELETE /segments/ID/delete

Response

Expected Response Code: 200

Properties

Same as Get Segment.

Add Contact to Segment

<?php

$segmentApi->addContact($segmentId, $contactId);

Add a Contact to a Segment.

HTTP Request

POST /segments/SEGMENT_ID/contact/CONTACT_ID/add

Response

Expected Response Code: 200

{
    "success": 1
}

Add Contacts to Segment

<?php

$contactIds = array(1, 2, 3);
$segmentApi->addContacts($segmentId, $contactIds);

Add multiple Contacts to a Segment.

HTTP Request

POST /segments/SEGMENT_ID/contacts/add

POST Parameters

Name	Type	Description
`ids`	array	Array of Contact IDs to add to the Segment

Response

Expected Response Code: 200

{
    "success": 1,
    "details": {
        "1": {
            "success": true
        },
        "2": {
            "success": true
        },
        "3": {
            "success": false
        }
    }
}

Remove Contact from Segment

<?php

$segmentApi->removeContact($segmentId, $contactId);

Remove a Contact from a Segment.

HTTP Request

POST /segments/SEGMENT_ID/contact/CONTACT_ID/remove

Response

Expected Response Code: 200

{
    "success": 1
}

Get User Segments

<?php

$segments = $segmentApi->getUserSegments();

Get a list of Segments available to the current user.

HTTP Request

GET /contacts/list/segments

Response

Expected Response Code: 200

{
    "1": {
        "id": 1,
        "name": "VIP Customers",
        "alias": "vip-customers"
    },
    "2": {
        "id": 2,
        "name": "Newsletter Subscribers",
        "alias": "newsletter-subscribers"
    }
}

Segment Properties

Name	Type	Description
`id`	int	ID of the Segment
`name`	string	Name of the Segment
`alias`	string	Alias of the Segment

Segment Filters

Segments use filters to define which Contacts should be included. Filters support various field types and operators.

Filter Structure

{
    "glue": "and",
    "field": "email",
    "object": "lead",
    "type": "email",
    "operator": "like",
    "properties": {
        "filter": "%@gmail.com"
    }
}

Filter Properties

Name	Type	Description
`glue`	string	Logic operator to connect with previous filter: `and` or `or`
`field`	string	Contact field to filter on, for example `email`, `firstname`, `points`
`object`	string	Object type, typically `lead` for Contact fields
`type`	string	Field type, for example `text`, `number`, `email`, `date`, `select`
`operator`	string	Comparison operator, for example `=`, `!=`, `like`, `!like`, `gt`, `gte`, `lt`, `lte`, `in`, `!in`
`properties`	object	Additional filter properties including the `filter` value

Common Operators by Field Type

Text Fields: - = (equals) - != (not equals) - like (contains) - !like (does not contain) - empty (is empty) - !empty (is not empty)

Number Fields: - = (equals) - != (not equals) - gt (greater than) - gte (greater than or equal) - lt (less than) - lte (less than or equal)

Date Fields: - = (equals) - != (not equals) - gt (after) - gte (on or after) - lt (before) - lte (on or before)

Select/Multi-Select Fields: - = (equals) - != (not equals) - in (in list) - !in (not in list)

Example Filters

Email domain filter:

{
    "glue": "and",
    "field": "email",
    "object": "lead",
    "type": "email",
    "operator": "like",
    "properties": {
        "filter": "%@company.com"
    }
}

Points range filter:

{
    "glue": "and",
    "field": "points",
    "object": "lead",
    "type": "number",
    "operator": "gte",
    "properties": {
        "filter": "100"
    }
}

Date range filter:

{
    "glue": "and",
    "field": "date_added",
    "object": "lead",
    "type": "datetime",
    "operator": "gte",
    "properties": {
        "filter": "2023-01-01 00:00:00"
    }
}