Users

Use this endpoint to obtain details on Mautic’s Users.

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

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

Get User

<?php

//...
$user = $userApi->get($id);

Get an individual User by ID.

HTTP Request

GET /users/ID

Response

Expected Response Code: 200

{
  "user":{
    "isPublished":true,
    "dateAdded":"2016-11-09T14:23:44+00:00",
    "createdBy":1,
    "createdByUser":"John Doe",
    "dateModified":null,
    "modifiedBy":null,
    "modifiedByUser":null,
    "id":6,
    "username":"apitest",
    "firstName":"John",
    "lastName":"Doe",
    "email":"john@doe.com",
    "position":null,
    "role":{
      "createdByUser":null,
      "modifiedByUser":null,
      "id":1,
      "name":"Administrator",
      "description":"Full system access",
      "isAdmin":true,
      "rawPermissions":null
    },
    "timezone":null,
    "locale":null,
    "lastLogin":null,
    "lastActive":null,
    "onlineStatus":"offline",
    "signature":null
  }
}

User Properties

Name	Type	Description
`id`	int	ID of the User
`dateAdded`	`datetime`	User creation date/time
`createdBy`	int	ID of the User that created the User
createdByUser	string	Name of the User that created the User
`dateModified`	datetime/null	Date/time User was last modified
`lastActive`	datetime/null	Date/time when the User last active
`modifiedBy`	int	ID of the User that last modified the User
`modifiedByUser`	string	Name of the User that last modified the User
`username`	string	Username that’s used to log into Mautic.
`firstName`	string	First Name of the User
`lastName`	string	Last Name of the User
`email`	string	Email of the User
`position`	string	User’s position title
`role`	object	Role details
`timezone`	string	Timezone of the User
`onlineStatus`	string	Online status of the User
`signature`	string	Signature of the User for use in Emails

List Contact Users

<?php

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

HTTP Request

GET /users

Response

Expected Response Code: 200

{
  "total":2,
  "users":[
    {
      "isPublished":true,
      "dateAdded":"2016-08-01T11:52:15+00:00",
      "createdBy":null,
      "createdByUser":" ",
      "dateModified":"2016-09-26T15:02:32+00:00",
      "modifiedBy":null,
      "modifiedByUser":" ",
      "id":2,
      "username":"test",
      "firstName":"John",
      "lastName":"Doe",
      "email":"john@doe.com",
      "position":null,
      "role":{
        "createdByUser":"John Doe",
        "modifiedByUser":null,
        "id":4,
        "name":"edit own Contacts",
        "description":null,
        "isAdmin":false,
        "rawPermissions":{
          "lead:leads":[
            "viewown",
            "editown",
            "create",
            "deleteown"
          ],
          "lead:lists":[
            "viewother"
          ]
        }
      },
      "timezone":null,
      "locale":null,
      "lastLogin":"2016-09-26T15:03:25+00:00",
      "lastActive":"2016-09-26T15:19:15+00:00",
      "onlineStatus":"offline",
      "signature":"Best regards,&#10;Yours&#10;|FROM_NAME|"
    }
  ]
}

User Properties

Name	Type	Description
`id`	int	ID of the User
`dateAdded`	`datetime`	User creation date/time
`createdBy`	int	ID of the User that created the User
`createdByUser`	string	Name of the User that created the User
`dateModified`	datetime/null	Date/time User was last modified
`lastActive`	datetime/null	Date/time when the User last active
`modifiedBy`	int	ID of the User that last modified the User
`modifiedByUser`	string	Name of the User that last modified the User
`username`	string	Username that’s used to log into Mautic.
`firstName`	string	First Name of the User
`lastName`	string	Last Name of the User
`email`	string	Email of the User
`position`	string	User’s position title
`role`	array	List of Roles of the User
`timezone`	string	Timezone of the User
`onlineStatus`	string	Online status of the User
`signature`	string	Signature of the User for use in Emails

Create User

<?php

$data = array(
    'username' => 'apitest',
    'firstName' => 'John',
    'lastName' => 'Doe',
    'email' => 'john@doe.com',
    'plainPassword' => array(
        'password' => 'topSecret007',
        'confirm' => 'topSecret007',
    ),
    'role' => 1,
);

$user = $userApi->create($data);

Create a new User.

HTTP Request

POST /users/new

POST Parameters

Name	Type	Description
`username`	string	Username that’s used to log into Mautic.
`firstName`	string	First Name of the User
`lastName`	string	Last Name of the User
`email`	string	Email of the User
`position`	string	User’s position title
`role`	int	Role ID
`timezone`	string	Timezone of the User
`onlineStatus`	string	Online status of the User
`signature`	string	Signature of the User for use in Emails
`plainPassword`	array	array of plain password as in the example

Response

Expected Response Code: 201

Properties

Same as Get User.

Edit User

<?php

$id   = 1;
$data = array(
    'lastName' => 'Doeboe',
);

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

$user = $userApi->edit($id, $data, $createIfNotFound);

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

PUT creates a User if the given ID doesn’t exist and clears all the User information, adds the information from the request.

PATCH fails if the User with the given ID doesn’t exist and updates the User field values with the values from the request.

HTTP Request

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

PATCH /users/ID/edit

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

PUT /users/ID/edit

POST Parameters

Name	Type	Description
`username`	string	Username that’s used to log into Mautic.
`firstName`	string	First Name of the User
`lastName`	string	Last Name of the User
`email`	string	Email of the User
`position`	string	User’s position title
`role`	int	Role ID
`timezone`	string	Timezone of the User
`signature`	string	Signature of the User for use in Emails

Response

If PUT, the expected response code is 200 if editing a User or 201 if creating a new one.

If PATCH, the expected response code is 200.

Properties

Same as Get User.

Delete User

<?php

$user = $userApi->delete($id);

Delete a User.

HTTP Request

DELETE /users/ID/delete

Response

Expected Response Code: 200

Properties

Same as Get User.

Get Self User

<?php

$user = $userApi->getSelf();

Get a self User.

HTTP Request

GET /users/self

Response

Expected Response Code: 200

Properties

Same as Get User.

Check User Permissions

<?php
$permissions = ['user:users:create', 'user:users:edit'];
$user = $userApi->checkPermission($id, $permissions);

Use this endpoint to validate whether a User has the provided permissions or not.

HTTP Request

POST /users/ID/permissioncheck

POST Parameters

The POST body should contain a permissions property. The value can either be a string in case of a single permission or an array in case you want to validate multiple permissions:

{
  "permissions": ["user:users:create", "user:users:edit"]
}

Response

Expected Response Code: 200

{
  "user:users:create": true,
  "user:users:edit": true
}

Properties

This endpoint returns on object where the requested permissions, for example, user:users:create, are the keys. Each entry has a boolean value, indicating whether the User has the permission or not.