Tags

Use this endpoint to manipulate and obtain details on Mautic’s Tags.

Using the Mautic API library

You can interact with this API using the Mautic API Library as below, or the various HTTP endpoints 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();
$tagApi   = $api->newApi("tags", $auth, $apiUrl);

Get Tag

Retrieves an individual Tag.

<?php

//...
$tag = $tagApi->get($id);

HTTP request

GET /tags/ID

Response

• Returns 200 OK when the request successfully retrieves the Tag.

{
    "tag": {
        "id": 34,
        "tag": "tagA",
        "description": "A tag for grouping contacts"
    }
}

Tag properties

Name	Type	Description
id	int	ID of the Tag
tag	string	Title of the Tag
description	string/null	Description of the Tag

List Tags

Retrieves a list of Tags.

<?php

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

HTTP request

GET /tags

Query parameters

Name	Description
search	String or search command to filter entities. The search matches against both the Tag name and description.
start	Starting row for the returned entities - defaults to 0
limit	Maximum number of entities to return - defaults to 30
orderBy	Column to sort by. Any column in the response is valid.
orderByDir	Order direction - asc or desc
publishedOnly	Returns only currently published entities
minimal	Returns only a simple mapped object of entities without additional lists in it

Response

• Returns 200 OK when the request successfully retrieves the Tags list.

{
    "total": 1,
    "tags": [
        {
            "id": 34,
            "tag": "tagA",
            "description": "A tag for grouping contacts"
        }
    ]
}

Properties

Name	Type	Description
total	integer	Total count of Tags
tags	array	A mapped collection of Tags indexed by their ID

For the rest of the properties, refer to Tag properties.

The search parameter behavior

The search parameter matches against both the Tag name and description. This lets you find Tags by keywords in their description, even if the keyword isn’t in the Tag name.

For example, GET /tags?search=test returns Tags where either:

• The Tag name contains ‘test’, OR

• The Tag description contains ‘test’

Create Tag

Creates a new Tag.

<?php

$data = [
    'tag' => 'Tag A',
    'description' => 'Description of Tag A',
];

$tag = $tagApi->create($data);

HTTP request

POST /tags/new

POST parameters

Name	Type	Description
tag	string	Required. Title of the Tag
description	string	Description of the Tag

Response

• Returns 201 Created when the request successfully creates a Tag.

Properties

Refer to Tag properties.

Edit Tag

Edits a Tag.

This operation supports PUT or PATCH depending on the desired behavior:

• PUT: full replacement. The request creates a new Tag if the ID doesn’t exist. If the ID exists, the request clears all existing data and replaces it with the provided values.

• PATCH: partial update. The request only updates field values based on the request data. The request fails when the Tag ID doesn’t exist.

<?php

$id   = 1;
$data = [
    'tag' => 'Tag B',
    'description' => 'Updated description',
];

// Create new Tag if ID 1 isn't found?
$createIfNotFound = true;

$tag = $tagApi->edit($id, $data, $createIfNotFound);

HTTP request

• PUT /tags/ID/edit: updates an existing Tag or creates a new one when the ID doesn’t exist.

• PATCH /tags/ID/edit: updates an existing Tag. The request fails when the ID doesn’t exist.

POST parameters

Name	Type	Description
tag	string	Title of the Tag
description	string	Description of the Tag

Response

• PUT: returns 200 OK when the request successfully updates the Tag or 201 Created when the request creates a Tag.

• PATCH: returns 200 OK when the request successfully updates the Tag or 404 Not Found error when the Tag ID doesn’t exist.

The response is a JSON object similar to Get Tag.

Properties

Refer to Tag properties.

Delete Tag

Deletes a Tag.

<?php

$tag = $tagApi->delete($id);

HTTP request

DELETE /tags/ID/delete

Response

• Returns 200 OK when the request successfully deletes the Tag.

Properties

Refer to Tag properties.