Document Notes API permissions and endpoints by promptless-for-oss · Pull Request #425 · mautic/developer-documentation-new

promptless-for-oss · 2026-05-01T07:00:53Z

Open this suggestion in Promptless to view citations and reasoning process

Documents the new lead:notes permission set introduced in Mautic PR #16067. Adds comprehensive Notes API endpoint documentation and updates the List Contact Notes endpoint to specify the new permission requirements.

Trigger Events

mautic/mautic PR #16067: [LeadBundle] Add dedicated notes permissions, migrate existing roles, and fix note ownership edit visibility

Tip: Planning a big docs refactor? Use Deep Analysis to get help with the heavy lifting 🔍

- Add comprehensive Notes API documentation with all CRUD endpoints - Document new lead:notes permission set (viewown, viewother, editown, editother, create, deleteown, deleteother, full) - Update List Contact Notes endpoint in contacts.rst to specify required permissions

promptless-for-oss · 2026-05-01T07:00:54Z

+
+The Notes API uses the ``lead:notes`` permission set. This permission set is separate from ``lead:leads`` permissions, allowing administrators to grant note-specific access without full Contact access.
+
+Available permissions:


Permission documentation based on PR #16067 which adds the lead:notes permission set via LeadPermissions.php using addExtendedPermissions('notes', false) - the extended pattern without publish capability.

Source: mautic/mautic#16067

promptless-for-oss · 2026-05-01T07:00:55Z

 ``GET /contacts/ID/notes``

+**Required permissions:** ``lead:notes:viewown`` or ``lead:notes:viewother``
+


Permission requirement changed from lead:leads:viewown/lead:leads:viewother to lead:notes:viewown/lead:notes:viewother in LeadApiController.php per PR #16067.

Source: mautic/mautic#16067

escopecz

Looks good 👍

adiati98

@promptless-for-oss please address the suggestions.

adiati98 · 2026-05-13T19:25:44Z

+Using the Mautic API library
+****************************
+
+You can interact with this API using the :xref:`Mautic API Library` as below, or the various HTTP endpoints described in this document.


Let's wrap this in vale off/on statements.

Suggested change

You can interact with this API using the :xref:`Mautic API Library` as below, or the various HTTP endpoints described in this document.

.. vale off

You can interact with this API using the :xref:`Mautic API Library` as below, or the various HTTP endpoints described in this document.

.. vale on

adiati98 · 2026-05-13T19:30:01Z

+.. vale off
+
+Get Note
+********
+
+.. vale on


Suggested change

.. vale off

Get Note

********

.. vale on

Get note

********

adiati98 · 2026-05-13T19:30:52Z

+.. vale off
+
+List Notes
+**********
+
+.. vale on


Suggested change

.. vale off

List Notes

**********

.. vale on

List notes

**********

adiati98 · 2026-05-13T19:55:50Z

+.. vale off
+
+Delete Note
+***********
+
+.. vale on


Suggested change

.. vale off

Delete Note

***********

.. vale on

Delete note

***********

adiati98 · 2026-05-13T19:58:38Z

+.. code-block:: json

-.. vale on
+   {
+       "note": {
+           "id": null,
+           "text": "<p>Jim is super cool!</p>",
+           "type": "general",
+           "dateTime": "2015-07-23T13:14:00-05:00",
+           "lead": {
+               "id": 47
+           }
+       }
+   }


Suggested change

.. code-block:: json

.. vale on

\ No newline at end of file

{

"note": {

"id": null,

"text": "<p>Jim is super cool!</p>",

"type": "general",

"dateTime": "2015-07-23T13:14:00-05:00",

"lead": {

"id": 47

}

}

}

Properties

----------

Refer to :ref:`note properties <get note properties>`.

adiati98

@promptless-for-oss please address the suggestions.

- Change "Notes API" to "notes API" (lowercase) - Wrap API library section in vale off/on statements - Use lowercase for section headers (Get note, List notes, Create note, Edit note, Delete note) - Simplify "Retrieves an individual note by ID" to "Retrieves an individual note" - Convert response descriptions to bullet point format - Add reference anchors (get note response, get note properties, create note POST parameters) - Change "Note properties" to "Properties" and rename the header section - Update type description format to use colons - Change "Query parameters" and "Data parameters" to proper header format with underlines - Rewrite PUT/PATCH explanation for consistency with clearer behavior descriptions - Update HTTP request format for Edit note to bullet list format - Update response references to use new anchor format - Add Properties section at end of Delete note referencing get note properties

promptless-for-oss · 2026-05-13T20:28:56Z

@adiati98 Thanks for the detailed review! I've addressed all of your suggestions:

Lowercase "notes API" and all section headers (Get note, List notes, Create note, Edit note, Delete note)
Wrapped API library section in vale off/on statements
Simplified "Retrieves an individual note by ID" to "Retrieves an individual note"
Converted response descriptions to bullet point format
Added RST anchors for cross-references: get note response, get note properties, create note POST parameters
Changed "Note properties" to "Properties" section
Updated type descriptions to use colons
Changed "Query parameters" and "Data parameters" to proper header format with underlines
Rewrote PUT/PATCH explanation with clearer behavior descriptions
Updated HTTP request format for Edit note to bullet list
Added Properties section at end of Delete note referencing get note properties

Please let me know if there's anything else you'd like adjusted.

adiati98

@promptless-for-oss there are a couple of suggestions that you still need to address.

Split the response description into a bullet point and separate paragraph as requested by reviewer.

adiati98

@promptless-for-oss please address the rest of the suggestions

Addresses reviewer feedback to wrap the API library content line within vale off/on block, not just the section header.

promptless-for-oss requested review from a team, adiati98 and favour-chibueze May 1, 2026 07:00

promptless-for-oss commented May 1, 2026

View reviewed changes

promptless-for-oss mentioned this pull request May 1, 2026

[LeadBundle] Add dedicated notes permissions, migrate existing roles, and fix note ownership edit visibility mautic/mautic#16067

Open

escopecz previously approved these changes May 11, 2026

View reviewed changes

adiati98 requested changes May 13, 2026

View reviewed changes

adiati98 and others added 2 commits May 13, 2026 22:03

Merge branch '7.0' into promptless/pr-16067-notes-permissions

f0af5c9

promptless-for-oss dismissed escopecz’s stale review via b7789f7 May 13, 2026 20:28

adiati98 requested changes May 14, 2026

View reviewed changes

Address reviewer feedback on Delete note response formatting

3f13094

Split the response description into a bullet point and separate paragraph as requested by reviewer.

adiati98 requested changes May 14, 2026

View reviewed changes

Move vale on statement after API library content

3014009

Addresses reviewer feedback to wrap the API library content line within vale off/on block, not just the section header.


		The Notes API uses the ``lead:notes`` permission set. This permission set is separate from ``lead:leads`` permissions, allowing administrators to grant note-specific access without full Contact access.

		Available permissions:

		``GET /contacts/ID/notes``

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

Conversation

promptless-for-oss commented May 1, 2026

Uh oh!

promptless-for-oss May 1, 2026

Choose a reason for hiding this comment

Uh oh!

promptless-for-oss May 1, 2026

Choose a reason for hiding this comment

Uh oh!

escopecz left a comment

Choose a reason for hiding this comment

Uh oh!

adiati98 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adiati98 May 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

adiati98 May 13, 2026

Choose a reason for hiding this comment

Uh oh!

adiati98 May 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

adiati98 May 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

adiati98 May 13, 2026

Choose a reason for hiding this comment

Uh oh!

adiati98 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

promptless-for-oss commented May 13, 2026

Uh oh!

adiati98 left a comment

Choose a reason for hiding this comment

Uh oh!

adiati98 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

adiati98 left a comment •

edited

Loading

adiati98 left a comment •

edited

Loading