Stages

使用此端点来操作并获取有关 Mautic 的联系人阶段的详细信息。

使用 Mautic API 库

您可以使用 Mautic API 库与此 API 进行交互，如下所示，也可以使用本文档中描述的各种 HTTP 端点。

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

// ...
$initAuth = new ApiAuth();
$auth     = $initAuth->newAuth($settings);
$apiUrl   = "https://your-mautic.com";
$api      = new MauticApi();
$stageApi = $api->newApi("stages", $auth, $apiUrl);

获取阶段

检索单个阶段。

<?php

//...
$stage = $stageApi->get($id);

HTTP 请求

GET /stages/ID

响应

当请求成功检索到阶段时，返回 200 OK。

{
   "stage": {
       "isPublished": true,
       "dateAdded": "2026-02-13T16:11:07+00:00",
       "dateModified": null,
       "createdBy": 1,
       "createdByUser": "John Doe",
       "modifiedBy": 1,
       "modifiedByUser": "John Doe",
       "id": 7,
       "name": "Stage A",
       "category": null,
       "weight": 0,
       "description": "This is my first stage created via API.",
       "publishUp": "2026-02-13T17:00:00+00:00",
       "publishDown": "2026-02-20T17:00:00+00:00"
   }
}

阶段属性

名称	类型	描述
`isPublished`	boolean	阶段发布状态
`dateAdded`	datetime	阶段记录创建日期和时间
`dateModified`	datetime	阶段记录上次修改的日期和时间
`createdBy`	integer	创建该阶段的用户 ID
`createdByUser`	string	创建该阶段用户的姓名
`modifiedBy`	integer	最后修改该阶段的用户 ID
`modifiedByUser`	string	最后修改该阶段用户的姓名
`id`	integer	阶段 ID
`name`	string	阶段名称
`category`	object	分配给该阶段的类别
`weight`	integer	阶段权重
`description`	string	阶段描述
`publishUp`	datetime	阶段激活日期和时间
`publishDown`	datetime	阶段停用日期和时间

列出阶段

检索阶段列表。

<?php

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

HTTP request

GET /stages

Query parameters

Name	Type	Description
`searchFilter`	string	String or search command to filter entities
`start`	integer	Starting row for the returned entities - defaults to 0
`limit`	integer	Maximum number of entities to return - defaults to 30
`orderBy`	string	Column to sort by. Any column in the response is valid. Note: convert `camelCase` properties to `snake_case`. For example, `dateAdded` becomes `date_added`, `webhookUrl` becomes `webhook_url`, and so on
`orderByDir`	string	Order direction - `asc` or `desc`
`publishedOnly`	boolean	Returns only currently published entities
`minimal`	boolean	Returns only a simple mapped object of entities without additional lists in it

Response

Returns 200 OK when the request successfully retrieves the Stages list.

{
  "total": 4,
  "stages": [
    {
       "isPublished": true,
       "dateAdded": "2026-02-13T16:11:07+00:00",
       "dateModified": null,
       "createdBy": 1,
       "createdByUser": "John Doe",
       "modifiedBy": 1,
       "modifiedByUser": "John Doe",
       "id": 7,
       "name": "Stage A",
       "category": null,
       "weight": 0,
       "description": "This is my first stage created via API.",
       "publishUp": "2026-02-13T17:00:00+00:00",
       "publishDown": "2026-02-20T17:00:00+00:00"
    },
    //...
  ]
}

Properties

Name	Type	Description
`total`	integer	Total count of Stages
`stages`	object	A mapped collection of Stages indexed by their ID

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

Create Stage

Creates a new Stage.

<?php

$data = array(
    'name'        => 'Stage A', // Required
    'weight'      => 5,
    'description' => 'This is my first stage created via API.',
    'isPublished' => 1,
    'category'    => 2,
    'publishUp'   => '2026-01-01T00:00:00+00:00',
    'publishDown' => '2026-02-01T23:59:59+00:00',
);

$stage = $stageApi->create($data);

HTTP request

POST /stages/new

POST parameters

Name	Type	Description
`name`	string	Required.

Stage name

- weight
- integer
- Stage weight
- description
- string
- Description of the Stage
- isPublished
- boolean
- Stage publication status - set to 0 or false to inactive. When not set, it defaults to active.
- category
- integer
- ID of the Category assigned to the Stage
- publishUp
- datetime
- Activation date and time for the Stage
- publishDown
- datetime
- Deactivation date and time for the Stage

Response

Returns 201 Created when the request successfully creates a Stage.

The response is a JSON object similar to Get Stage.

Properties

Refer to Get Stage.

Edit Stage

Edits a Stage.

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

PUT: full replacement. The request creates a new Stage if the ID is missing. 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 ID doesn’t exist.

<?php

$id   = 1;
$data = array(
  'name'        => 'New stage name',
  'isPublished' => 0
);

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

$stage = $stageApi->edit($id, $data, $createIfNotFound);

HTTP request

PUT /stages/ID/edit: updates an existing Stage or creates a new one when the ID doesn’t exist.
PATCH /stages/ID/edit: updates an existing Stage. The request fails when the ID doesn’t exist.

POST parameters

Accepts the same parameters as those described in Create Stage. All parameters are optional.

Response

PUT: returns 200 OK when the request successfully updates the Stage or 201 Created when the request creates a Stage.
PATCH: returns 200 OK when the request successfully updates the Stage or 404 Not Found when the ID doesn’t exist.

The response is a JSON object similar to Get Stage.

Properties

Refer to Stage properties.

Delete Stage

Deletes a Stage.

<?php

$stage = $stageApi->delete($id);

HTTP request

DELETE /stages/ID/delete

Response

Returns 200 OK when the request successfully deletes the Stage.

The response is a JSON object containing the data of the deleted Stage, similar to Get Stage.

Properties

Refer to Stage properties.

Add Contact to Stage

将联系人添加到阶段。

<?php

//...
$response = $stageApi->addContact($stageId, $contactId);
if (!isset($response['success'])) {
  // handle error
}

HTTP 请求

POST /stages/STAGE_ID/contact/CONTACT_ID/add

响应

当请求成功将联系人添加到阶段时，返回 200 OK。

{
  "success": 1
}

从阶段移除联系人

从阶段移除一个联系人。

<?php

//...
$response = $stageApi->removeContact($stageId, $contactId);
if (!isset($response['success'])) {
  // handle error
}

HTTP 请求

POST /stages/STAGE_ID/contact/CONTACT_ID/remove

响应

当请求成功从阶段移除联系人时，返回 200 OK。

{
  "success": 1
}