Stages

Use this endpoint to obtain details on Mautic’s Contact Stages.

<?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);

Get Stage

<?php

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

Get an individual Stage by ID.

HTTP request

GET /stages/ID

Response

Expected Response Code: 200

{
   "stage": {
   "id": 47,
   "isPublished": 1,
   "dateAdded": "2015-07-21T12:27:12-05:00",
   "createdBy": 1,
   "createdByUser": "Joe Smith",
   "dateModified": "2015-07-21T14:12:03-05:00",
   "modifiedBy": 1,
   "modifiedByUser": "Joe Smith",
   "name": "Stage A",
   "category": null,
   "description": "This is my first stage created via API.",
   "weight": 0,
   "publishUp": "2015-07-21T14:12:03-05:00",
   "publishDown": "2015-07-21T14:12:03-05:00"
}

Stage Properties

Name	Type	Description
`id`	int	ID of the Stage
`isPublished`	boolean	Whether the Stage is published
`dateAdded`	datetime	Date/time Stage was created
`createdBy`	int	ID of the User that created the Stage
`createdByUser`	string	Name of the User that created the Stage
`dateModified`	datetime/null	Date/time Stage was last modified
`modifiedBy`	int	ID of the User that last modified the Stage
`modifiedByUser`	string	Name of the User that last modified the Stage
`name`	string`	Stage name
`category`	int	Stage category ID
`description`	string	Stage description
`weight`	int	Stage’s weight
`publishUp`	datetime	Date/time Stage should be published
`publishDown`	datetime	Date/time Stage should be unpublished

List Contact Stages

<?php

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

HTTP request

GET /stages

Response

Expected Response Code: 200

{
"total": 4,
"stages": [
  {
      "id": 47,
      "isPublished": 1,
      "dateAdded": "2015-07-21T12:27:12-05:00",
      "createdBy": 1,
      "createdByUser": "Joe Smith",
      "dateModified": "2015-07-21T14:12:03-05:00",
      "modifiedBy": 1,
      "modifiedByUser": "Joe Smith",
      "name": "Stage A",
      "category": null,
      "description": "This is my first stage created via API.",
      "weight": 0,
      "publishUp": "2015-07-21T14:12:03-05:00",
      "publishDown": "2015-07-21T14:12:03-05:00"
  },
  // ...
]

}

Stage Properties

Name	Type	Description
`total`	int	Count of all Stages
`id`	int	ID of the Stage
`isPublished`	boolean	Whether the Stage is published
`dateAdded`	datetime	Date/time Stage was created
`createdBy`	int	ID of the User that created the Stage
`createdByUser`	string	Name of the User that created the Stage
`dateModified`	datetime	Date/time Stage was last modified
`modifiedBy`	int	ID of the User that last modified the Stage
`modifiedByUser`	string	Name of the User that last modified the Stage
`name`	string`	Stage name
`category`	int	Stage category ID
`description`	string	Stage description
`weight`	int	Stage’s weight
`publishUp`	datetime	Date/time Stage should be published
`publishDown`	datetime	Date/time Stage should be unpublished

Create Stage

Create a new Stage.

<?php

$data = array(
  'name'        => 'Stage A',
  'weight'      => 5,
  'description' => 'This is my first stage created via API.',
  'isPublished' => 1
);

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

HTTP request

POST /stages/new

POST Parameters

Name	Description
`name`	Stage name is the only required field
`weight`	int
`description`	A description of the Stage.
`isPublished`	A value of 0 or 1

Response

Expected Response Code: 201

Properties

Same as Get Stage

Edit Stage

<?php

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

// Create new a stage of ID 1 is not found?
$createIfNotFound = true;

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

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

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

HTTP request

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

PATCH /stages/ID/edit

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

PUT /stages/ID/edit

POST Parameters

Name	Description
`name`	Stage name is the only required field
`alias`	Name alias generated automatically if not set
`description`	A description of the Stage
`isPublished`	A value of 0 or 1.
`weight`	int

Response

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

Properties

Same as Get Stage

Delete Stage

<?php

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

Delete a Stage.

HTTP Request

DELETE /stages/ID/delete

Response

Expected Response Code: 200

Properties

Same as Get Stage

Add Contact to a Stage

<?php

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

Manually add a Contact to a specific Stage.

HTTP request

POST /stages/STAGE_ID/contact/CONTACT_ID/add

Response

Expected Response Code: 200

{
  "success": true
}

Remove Contact from a Stage

<?php

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

Manually remove a Contact from a specific Stage.

HTTP request

POST /stages/STAGE_ID/contact/CONTACT_ID/remove

Response

Expected Response Code: 200

{
  "success": true
}