Document Notes API permissions and endpoints

[promptless-for-oss]

Note: This PR replaces mautic/user-documentation#425. All commits from mautic/user-documentation#425 are preserved.

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. Fresh branch from 7.2 as requested by reviewer.

---

Review round (@adiati98 — Google.Parens Vale warnings): Both flagged parentheses in docs/rest_api/notes.rst have been replaced with dashes, as requested — applied verbatim.

• Permissions intro (line 13): lead:leads (Contact) permission set → lead:leads—Contact—permission set.
• Create Note .. note:: (line 260): view the associated Contact (``lead:leads:viewown`` or ``lead:leads:viewother``) → `view the associated Contact—lead:leads:viewown or ``lead:leads:viewother```.

Vale now reports 0 errors, 0 warnings, and 0 suggestions on the file (both Google.Parens findings cleared, no new Google.EmDash/Google.EnDash introduced — the dashes are unspaced em dashes per the repo convention).

---

Review round (@adiati98 — 2026-07-28): All four review comments addressed.

• docs/rest_api/contacts.rst (List Contact Notes note) — "Don't use parentheses": applied. against the Note's creator (``createdBy``). → against the Note's creator—the ``createdBy`` field. (unspaced em dash, consistent with this repo's dash convention).
• docs/rest_api/notes.rst Permissions intro — suggestion block: applied verbatim. Reworded to 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.
• docs/rest_api/notes.rst Create Note note — suggestion block: applied verbatim. Reworded to 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.
• docs/rest_api/notes.rst Delete Note response — "There's no code-block here?": applied. The empty .. code-block:: json under the Delete Note "Response" section is now populated with the deleted-Note JSON object, mirroring the Get Note response and the delete-returns-full-entity convention used by the Delete Company and Delete Contact endpoints in this repo.

Vale reports 0 errors, 0 warnings, and 0 suggestions on docs/rest_api/notes.rst; the contacts.rst edit introduced no new findings at the changed line.

---

Review round (@adiati98 — 2026-07-28, suggestion block on docs/rest_api/contacts.rst): the single actionable suggestion has been applied verbatim.

• docs/rest_api/contacts.rst (List Contact Notes .. note::) — suggestion block: applied verbatim. against the Note's creator—the ``createdBy`` field. → against the Note's creator - the ``createdBy`` field. (em dash replaced with a spaced hyphen per the reviewer's suggested text). No wording or technical meaning changed; the claim remains verified against Mautic PR #16067.

The changed line introduces no new Vale findings, and Google.Parens stays clear.

---

Tip: Filter the Dashboard by labels or assignees to focus on what matters to you 🔎

[adiati98]

@promptless-for-oss please address the suggestions

[promptless-for-oss]

Thanks for the review, @adiati98!

I've removed the redundant "Available permissions:" label as suggested. The table now follows directly after the introductory paragraph.

[adiati98]

@promptless-for-oss please address the suggestions

[promptless-for-oss]

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

1. Professional text example — Changed from "Jim is super cool!" to "Discussed product demo requirements. Follow-up scheduled for next week."
2. Total count — Updated from 1 to 2 to better illustrate list responses
3. List continuation — Added // ... after the first object to indicate additional items

The changes have been pushed to this PR.

[adiati98]

/aside @escopecz, this PR replaces #425 that's closed due to issues with resolving conflicts. All commits and contents from that PR are preserved.

I have a question. Is "Note" introduced in version 7.2 or earlier version? If from earlier, can you advise from which version?

I need this info to know whether we need to backport this PR to other branches and add "Note" and "Notes" to the Mautic feature list in other branches than 7.2.

TIA! ✨

[escopecz]

Notes are there from the very beginning (version 1.0.0) I couldn't find any older PR regarding notes than this fix for note API: mautic/mautic#716 from Mautic 1.2.0. So the notes feature itself must have been there before that.

[promptless-for-oss]

Thanks for the historical context! You're right that Notes have been a core Mautic feature since version 1.0.0.

This documentation PR focuses specifically on the new lead:notes permission set introduced in PR #16067, which adds dedicated permissions for Notes management. The Notes API endpoints themselves have existed, but now they have their own permission controls separate from the general Contact permissions.

No changes needed to the documentation based on this feedback - just wanted to acknowledge the helpful context about the feature's history.

[shinde-rahul]

@promptless-for-oss The documentation is useful and covers the new Notes API endpoints well, but some permission details need correction before merging.

Notes permissions don’t grant access to the associated Contact. Creating a Note requires lead:notes:create, but the User must also have permission to view the Contact being associated with the Note. Please clarify this in the general permissions section and under the Create Note endpoint.

There is also an important difference between the standalone Notes endpoints and GET /contacts/ID/notes:

• The standalone /notes endpoints evaluate own/other permissions using the User who created the Note.
• GET /contacts/ID/notes currently evaluates viewown and viewother using the Contact owner.

Please document this distinction accurately, unless the implementation is going to be aligned separately.

A few additional fixes are needed:

• Change “Edits an Note” to “Edits a Note.”
• Avoid suggesting that Notes permissions can be used without Contact access. They are separate permissions, but Contact access is still required for operations involving the associated Contact.

Please update the documentation based on these points.

[promptless-for-oss]

Thanks for the detailed review, @shinde-rahul — all four points have been applied and verified against the merged code in mautic/mautic#16067:

1. Notes permissions don't grant Contact access — the Permissions section no longer implies lead:notes confers Contact access; Contact operations still require the relevant lead:leads permissions.
2. Create Note requires Contact view access — documented under both the general permissions section and the Create Note endpoint.
3. own/other evaluation distinction — the standalone /notes endpoints evaluate viewown/viewother against the Note's creator (createdBy), while GET /contacts/ID/notes evaluates against the Contact owner. Documented accurately in both notes.rst and contacts.rst.
4. Grammar — "Edits an Note" → "Edits a Note."

Vale passes on the changed content. PR #516 is updated and ready for another look.

[shinde-rahul]

LGTM!

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks — we'll address the two Google.Parens Vale warnings by switching the flagged parentheses to a normal dash, per the house convention, and push the update to this PR shortly.

[promptless-for-oss]

Done, @adiati98 — both Google.Parens warnings in docs/rest_api/notes.rst are resolved by switching the two parenthetical asides to dashes (line 13 and the permission aside on line 260), per the house convention. Vale now passes cleanly (0/0/0) on the file. Pushed to PR #516 — ready for another look.

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks — we'll apply your two suggested rewordings for the permission descriptions (using dashes, no parentheses), address the remaining parentheses, and look into the 'no code-block here?' point. We'll verify against the source and push the update shortly.

[promptless-for-oss]

All four addressed and pushed, @adiati98:

• Removed the parentheses in the List Contact Notes permission note (contacts.rst) — now reads "the createdBy field".
• Applied your two suggested rewordings verbatim: the lead:notes vs lead:leads permissions intro (line 13) and the Create Note view-access note (line 260).
• Filled the empty Delete Note response code block with the deleted-Note JSON, mirroring the Get Note response and the delete-returns-full-entity convention used by Delete Company/Contact.

Vale passes cleanly on the Notes API page (both Google.Parens findings cleared), and the contacts.rst edit added no new findings. Ready for another look.

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks — we'll apply your suggested clarification distinguishing how viewown/viewother is evaluated for this endpoint (against the Contact owner) versus the standalone /notes endpoints (against the Note's createdBy), and push the update shortly.

[promptless-for-oss]

Applied, @adiati98 — the "List Contact Notes" note now uses a spaced hyphen instead of an em dash ("the Note's creator - the createdBy field"), exactly as your suggestion specified. Nothing else changed, the permission behavior described is unchanged and still verified against the source PR, and Vale is clean at the changed line. Pushed to PR #516 — ready for another look.

[adiati98]

@all-contributors please add @shinde-rahul for review.

[allcontributors]

@adiati98

I've put up a pull request to add @shinde-rahul! 🎉