Skip to content

Latest commit

 

History

History
378 lines (265 loc) · 6.79 KB

categories.rst

File metadata and controls

378 lines (265 loc) · 6.79 KB
Raw

Categories

Use this endpoint to obtain details on Mautic's Categories, or to manipulate Category memberships.

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();
$categoryApi = $api->newApi("categories", $auth, $apiUrl);

Get Category

<?php

//...
$category = $categoryApi->get($id);
{  
  "category":{  
    "id":221,
    "title":"test",
    "alias":"test4",
    "description":null,
    "color":null,
    "bundle":"asset"
  }
}

Get an individual Category by ID.

HTTP Request

GET /categories/ID

Response

Expected Response Code: 200

See JSON code example.

Category properties

Name Type Description
id int ID of the Category
isPublished boolean Published status of the Category
dateAdded datetime Category creation date/time
createdBy int ID of the User that created the Category
createdByUser string Name of the User that created the Category
dateModified datetime/null Category modified date/time
modifiedBy int ID of the User that last modified the Category
modifiedByUser string Name of the User that last modified the Category
title string The Category title
alias string The Category alias
description string The Category description
color string The Category color
bundle string The bundle where the Category is available

List Contact Categories

<?php

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

Returns a list of Contact Categories available to the User. This list isn't filterable.

HTTP Request

GET /categories

Response

Expected Response Code: 200

{  
  "total":8,
  "categories":[  
    {  
      "id":1,
      "title":"Bold",
      "alias":"bold",
      "description":null,
      "color":"b36262",
      "bundle":"point"
    },
  ]
}

Category properties

Name Type Description
id int ID of the Category
isPublished boolean Published status of the Category
dateAdded datetime Category creation date/time
createdBy int ID of the User that created the Category
createdByUser string Name of the User that created the Category
dateModified datetime/null Category modified date/time
modifiedBy int ID of the User that last modified the Category
modifiedByUser string Name of the User that last modified the Category
title string The Category title
alias string The Category alias
description string The Category description
color string The Category color
bundle string The bundle where the Category is available

Create Category

<?php 

$data = array(
    'categoryname' => 'test',
    'categoryemail' => 'test@example.com',
    'categorycity' => 'Raleigh',
);

$category = $categoryApi->create($data);

Create a new Category.

HTTP Request

POST /categories/new

POST parameters

Name Type Description
title string The Category title
bundle string The bundle where the Category is available

Response

Expected Response Code: 201

Properties

Same as Get Category.

Edit Category

<?php

$id   = 1;
$data = array(
    'title' => 'test',
    'bundle' => 'asset'
);

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

$category = $categoryApi->edit($id, $data, $createIfNotFound);

Edit a new Category. Note that this supports PUT or PATCH depending on the desired behavior.

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

HTTP Request

To edit a Category and return a 404 if the Category isn't found:

PATCH /categories/ID/edit

To edit a Category and create a new one if the Category isn't found:

PUT /categories/ID/edit

POST parameters

Name Type Description
title string The Category title
bundle string The bundle where the Category is available

Response

If using PUT, the expected response code is 200 if editing the Category or 201 if creating the Category.

If PATCH, the expected response code is 200.

Properties

Same as Get Category.

Delete Category

<?php

$category = $categoryApi->delete($id);

Delete a Category.

HTTP Request

DELETE /categories/ID/delete

Response

Expected Response Code: 200

Properties

Same as Get Category.

Assign a Category

To assign a Category to an entity, set category = [ID] to the payload. For example, this is how you can assign Category 123 to a new Asset:

$data = array(
    'title' => 'PDF sent as a API request',
    'storageLocation' => 'remote',
    'file' => 'https://www.mautic.org/media/logos/logo/Mautic_Logo_DB.pdf'
    'category' => 123
);

$asset = $assetApi->create($data);

The Category must exist in the Mautic instance, and the entity must support Categories.