Notes

Use this endpoint to manipulate and obtain details on Contact Notes in Mautic.

Permissions

The Notes API uses the lead:notes permission set, which is separate from the lead:leads - Contact on UI - permission set. However, lead:notes permissions don’t grant access to the associated Contact: any operation involving a Contact still requires the appropriate lead:leads permission.

For the standalone /notes endpoints, Mautic evaluates viewown/viewother, editown/editother, and deleteown/deleteother against the User who created the Note, not the owner of the associated Contact. The Note’s createdBy field determines ownership.

Permission	Description
`lead:notes:viewown`	View Notes created by the authenticated User
`lead:notes:viewother`	View Notes created by other Users
`lead:notes:editown`	Edit Notes created by the authenticated User
`lead:notes:editother`	Edit Notes created by other Users
`lead:notes:create`	Create new Notes
`lead:notes:deleteown`	Delete Notes created by the authenticated User
`lead:notes:deleteother`	Delete Notes created by other Users
`lead:notes:full`	Full access to all Note operations

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

Get Note

Retrieves an individual Note.

<?php

//...
$note = $noteApi->get($id);

HTTP request

GET /notes/ID

Required permissions: lead:notes:viewown or lead:notes:viewother

Response

Returns 200 OK when the request successfully retrieves the Note.

{
    "note": {
        "id": 1,
        "text": "<p>Discussed product demo requirements. Follow-up scheduled for next week.</p>",
        "type": "general",
        "dateTime": "2015-07-23T13:14:00-05:00",
        "lead": {
            "id": 47
        },
        "dateAdded": "2015-07-23T13:14:00-05:00",
        "createdBy": 1,
        "createdByUser": "Joe Smith"
    }
}

Properties

Name	Type	Description
`id`	integer	ID of the Note
`text`	string	Body content of the Note - supports HTML
`type`	string	Type of Note: `general`, `email`, `call`, or `meeting`
`dateTime`	datetime	Date and time associated with the Note
`lead`	object	The Contact associated with this Note
`dateAdded`	datetime	Note creation date and time
`createdBy`	integer	ID of the User who created the Note
`createdByUser`	string	Name of the User who created the Note

List Notes

Retrieves a list of Notes.

<?php

//...
$notes = $noteApi->getList($searchFilter, $start, $limit, $orderBy, $orderByDir);

HTTP request

GET /notes

Required permissions: lead:notes:viewown or lead:notes:viewother

Query parameters

Name	Description
`search`	String or search command to filter entities by
`start`	Starting row for the entities returned - defaults to `0`
`limit`	Limit number of entities to return - defaults to the system configuration for pagination
`orderBy`	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`	Sort direction - `asc` or `desc`

Response

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

{
    "total": 2,
    "notes": [
        {
            "id": 1,
            "text": "<p>Discussed product demo requirements. Follow-up scheduled for next week.</p>",
            "type": "general",
            "dateTime": "2015-07-23T13:14:00-05:00",
            "lead": {
                "id": 47
            }
        },
        // ...
    ]
}

Create Note

Creates a new Note for a Contact.

<?php

$data = [
    'lead' => 47,
    'text' => 'Note content here',
    'type' => 'general',
];

$note = $noteApi->create($data);

HTTP request

POST /notes/new

Required permissions: lead:notes:create

Note

In addition to lead:notes:create, the User must have permission to view the associated Contact - lead:leads:viewown or lead:leads:viewother. Mautic checks view access against the Contact owner before creating the Note.

POST parameters

Name	Required	Description
`lead`	Yes	ID of the Contact to associate the Note with
`text`	Yes	Body content of the Note - supports HTML
`type`	No	Type of Note: `general` - default, `email`, `call`, or `meeting`
`dateTime`	No	Date and time associated with the Note - auto-set to current time if not provided

Response

Returns 201 Created when the Note is successfully created.

The response is a JSON object similar to Get Note.

Edit Note

Edits a Note. This operation supports PUT or PATCH depending on the desired behavior:

PUT: full replacement. The request creates a new Note 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 Note ID doesn’t exist.

<?php

$id   = 1;
$data = [
    'text' => 'Updated note content',
    'type' => 'call',
];

// Using PATCH - update specific fields only
$note = $noteApi->edit($id, $data);

// Using PUT - create or completely replace
$note = $noteApi->edit($id, $data, true);

HTTP request

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

Required permissions: lead:notes:editown or lead:notes:editother

POST parameters

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

Response

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

The response is a JSON object similar to Get Note.

Delete Note

Deletes a Note.

<?php

$note = $noteApi->delete($id);

HTTP request

DELETE /notes/ID/delete

Required permissions: lead:notes:deleteown or lead:notes:deleteother

Response

Returns 200 OK when the Note is successfully deleted.

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

{
    "note": {
        "id": 1,
        "text": "<p>Discussed product demo requirements. Follow-up scheduled for next week.</p>",
        "type": "general",
        "dateTime": "2015-07-23T13:14:00-05:00",
        "lead": {
            "id": 47
        },
        "dateAdded": "2015-07-23T13:14:00-05:00",
        "createdBy": 1,
        "createdByUser": "Joe Smith"
    }
}

Properties

Refer to Note properties.