docs: Document Batch add Contacts to Companies REST API endpoint by promptless-for-oss · Pull Request #593 · mautic/developer-documentation-new

promptless-for-oss · 2026-07-10T11:43:12Z

Adds a "Batch add Contacts to Companies" section to the Companies REST API reference for the new POST /companies/batch/addcontacts endpoint (mautic/mautic PR #16512). Covers the assignments request body, per-pair results, the summary object, per-pair status values, the batch size limit, and change-log behavior. Targets the 7.3 docs branch (source base 7.x).

Latest revision (review feedback from @adiati98)

Applied verbatim: the The ``results`` entry properties, The ``summary`` object properties, and Per-pair ``status`` values heading suggestions. The underlines now match the title lengths.
Applied with a change: the status row now links to the per-pair status values section instead of saying "below", and has no trailing period, like the other description cells. To make the link work, I added a .. _per-pair status values: label above that section.
Applied with a change: the rewritten change-log paragraph is in, including splitting the event-name clause into its own sentence. The facts match the source PR (LOG_TYPE = 'api', the Lead added to the company, prefix, and the API batch assignment and API assignment event names). I formatted the stored action value as a literal, Lead added to the company, {company name}, and used the style guide's curly-brace placeholder. Without that, Vale flagged Lead and company (Mautic.FeatureList) inside the system string, which can't be reworded.

Validation

Vale: no findings on any line changed in this PR. The one remaining suggestion is at line 441, which predates this PR.
Sphinx build: the new section adds no warnings, and the :ref: to the status values section resolves.

Trigger Events

Add reference for POST /companies/batch/addcontacts (mautic/mautic PR #16512), covering the assignments request body, per-pair results, summary object, status values, batch size limit, and change-log behavior.

promptless-for-oss · 2026-07-10T11:43:14Z

+HTTP request
+============
+
+.. vale on


Documented the new POST /companies/batch/addcontacts endpoint and its purpose from this PR. The route is defined in app/bundles/LeadBundle/Config/config.php (mautic_api_companybatchaddcontacts, POST only) and handled by CompanyApiController::batchAddContactsAction, which reads the assignments array from the request body.

Source: mautic/mautic#16512

promptless-for-oss · 2026-07-10T11:43:15Z

+     - object
+     - Overall counts for the batch
+
+Each entry in ``results`` contains the following properties.


The per-pair status/message values and the summary counts (total, succeeded, failed) come from BatchCompanyContactAssignmentModel in this PR (hard-coded message constants; succeeded counts status-200 pairs, failed counts all others). Overall 200 on processed batches, 400/403 request-level errors, and the 500 returned when the batch exceeds api_batch_max_limit (default 200) via the inherited validateBatchPayload() are all verified against the PR's functional tests.

Source: mautic/mautic#16512

adiati98

@promptless-for-oss please address the suggestions.

… heading

promptless-for-oss · 2026-07-11T12:06:04Z

Thanks @adiati98! Addressed all three points:

Capitalized 'Integrations' and reworded the 'reports the outcome' verb to 'includes the outcome' to clear the Mautic.FeatureList Vale warnings.
The 'company' warning was on the literal API response message Contact added to company — that's the exact string this endpoint returns (const MESSAGE_ADDED), so rather than change the API's wording I formatted all the per-pair status message values as inline code literals, which is accurate and clears the warning.
Renamed the request-body heading to 'POST parameters' to match the convention used elsewhere on this page and in forms.rst.

Vale now runs clean on all changed lines. (There's one pre-existing Vale suggestion on line 441 about published → 'Active or Available', but it's on the publishedOnly query parameter outside this PR's section, so I left it untouched.)

adiati98

@promptless-for-oss please address the suggestions.

promptless-for-oss · 2026-07-11T16:59:43Z

Thanks @adiati98! These property tables describe the results array entries and the summary object, which are both sub-groups under the h4 "Properties" section (not nested inside summary itself). I've turned the two intro sentences into proper h5 headings — The results entry properties and The summary object properties — consistent with the h5 subsections already used elsewhere on this page (e.g. "Core fields"/"Professional fields"). Vale is clean on the changed lines.

adiati98

@promptless-for-oss please address the suggestions.

@adiati98

Convert the plain-sentence 'Per-pair ``status`` values:' intro into a proper h5 (~) heading 'Per-pair ``status`` values', a peer of the existing 'The ``results`` entry properties' and 'The ``summary`` object properties' subsections under the h4 'Properties' section. Addresses @adiati98's review on PR mautic#593.

promptless-for-oss · 2026-07-11T18:27:44Z

Thanks @adiati98! Addressed the remaining comment. The plain-sentence Per-pair ``status`` values: intro is now a proper h5 heading — Per-pair status values — a peer of the existing The results entry properties and The summary object properties subsections under the h4 "Properties" section.

To clarify the question in your comment: that table describes the status field of each results entry, not the summary object, so it belongs directly under "Properties" as an h5 rather than nested inside summary. Vale is clean on the changed lines.

adiati98

@promptless-for-oss please address the suggestions.

@adiati98

Address @adiati98's review on PR mautic#593: trim excess tildes on the three property-table h5 headings so each underline matches its heading text length.

promptless-for-oss · 2026-07-11T18:57:39Z

@adiati98 Thanks for the review — done. I shortened the three heading underlines to match the reviewer suggestions exactly:

The ``results`` entry properties → 30 ~
The ``summary`` object properties → 31 ~
Per-pair ``status`` values → 22 ~

The changes are pushed to this branch. Vale is clean on the changed lines.

…ies-api

…-log note Fix two factual errors surfaced by re-checking merged mautic/mautic PR #16512: - Over-limit batch requests return HTTP 400, not 500 (validateBatchPayload returns HTTP_BAD_REQUEST; testBatchAddContactsExceedsBatchLimit asserts 400). - The single-add 'Add Contact to Company' endpoint now also writes to the Company change log for each new assignment (event name 'API assignment' vs the batch endpoint's 'API batch assignment').

promptless-for-oss · 2026-09-11T14:13:57Z

I noticed that some CI checks failed for this PR. I'm investigating whether the failures are caused by this suggestion. If they're unrelated or pre-existing, I'll leave this suggestion unchanged and create a separate suggestion if a standalone docs fix is needed.

…tions Lengthen the three h5 subsection underlines under Properties to match their title text (including the literal backtick characters RST counts): 'The ``results`` entry properties' (32), 'The ``summary`` object properties' (33), and 'Per-pair ``status`` values' (26). The prior lengths were shorter than the titles, which Sphinx flags as malformed section markup. Verified with rst2html: no 'Title underline too short' warnings remain.

…t subsections" This reverts commit be4345d.

adiati98 · 2026-09-16T07:07:07Z

@promptless-for-oss please rebase to 7.3 branch.

promptless-for-oss · 2026-09-16T07:08:32Z

In reply to this discussion

Thanks @adiati98 — on it. I'll rebase this onto the 7.3 branch and update the PR, then follow up here once it's done.

promptless-for-oss · 2026-09-16T07:11:44Z

In reply to this discussion

Done, @adiati98 — PR #593 now targets the 7.3 branch. Since 7.3 and 7.2 currently point to the same commit, no rebase was needed and there were no conflicts. The PR still shows its intended single-file change to docs/rest_api/companies.rst and is mergeable pending your review. Let us know if you'd like anything else adjusted.

…ies-api

adiati98 · 2026-09-17T05:22:41Z

@promptless-for-oss please create a PR to cherry-pick the changes here for 8.0 branch.

promptless-for-oss · 2026-09-17T05:23:51Z

In reply to this discussion

On it — I'll prepare a PR that cherry-picks these Batch add Contacts to Companies REST API docs onto the 8.0 branch and follow up here with the link.

promptless-for-oss · 2026-09-17T05:28:59Z

In reply to this discussion

Done — I've opened a PR that cherry-picks these Batch add Contacts to Companies REST API docs onto the 8.0 branch: #673

It reproduces the approved content from this PR onto 8.0 (one file, +167 lines) and applied cleanly with no conflicts.

…ies-api

adiati98

@promptless-for-oss please address the suggestions and Vale warnings.

adiati98 · 2026-09-25T06:11:40Z

+The ``results`` entry properties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Suggested change

The ``results`` entry properties

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``results`` entry properties

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Applied as written in 992d0c8. The heading is now "The results entry properties", and its underline matches the title length. An earlier commit had reverted this underline fix, which is why it still looked unaddressed.

adiati98 · 2026-09-25T06:11:49Z

+The ``summary`` object properties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Suggested change

The ``summary`` object properties

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``summary`` object properties

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Applied as written in 992d0c8. The heading is now "The summary object properties", and its underline matches the title length.

adiati98 · 2026-09-25T06:12:03Z

+Per-pair ``status`` values
+~~~~~~~~~~~~~~~~~~~~~~


Suggested change

Per-pair ``status`` values

~~~~~~~~~~~~~~~~~~~~~~

Per-pair ``status`` values

~~~~~~~~~~~~~~~~~~~~~~~~~~

Applied as written in 992d0c8. The heading is now "Per-pair status values", and its underline matches the title length. I also added a .. _per-pair status values: label above it, so the status row can link to this section.

adiati98 · 2026-09-25T06:13:06Z

+     - ``An unexpected error occurred``
+     - Mautic couldn't process the pair
+
+Mautic records each new assignment made through this endpoint in the Contact's Company change log. It doesn't add a log entry when the Contact already belongs to the Company, and a pair for an existing link still returns a ``200`` status in its result. The 'Add Contact to Company' endpoint also writes to this log for each new assignment. Both endpoints record a ``type`` of ``api`` and an action of 'Lead added to the company, <company name>', and differ only in the event name: this endpoint records 'API batch assignment', while the 'Add Contact to Company' endpoint records 'API assignment'.


Suggested change

Mautic records each new assignment made through this endpoint in the Contact's Company change log. It doesn't add a log entry when the Contact already belongs to the Company, and a pair for an existing link still returns a ``200`` status in its result. The 'Add Contact to Company' endpoint also writes to this log for each new assignment. Both endpoints record a ``type`` of ``api`` and an action of 'Lead added to the company, <company name>', and differ only in the event name: this endpoint records 'API batch assignment', while the 'Add Contact to Company' endpoint records 'API assignment'.

Mautic records each new assignment made through this endpoint in the Contact's Company change log. It doesn't add a log entry when the Contact already belongs to the Company, and a pair for an existing link still returns a ``200`` status in its result. The 'Add Contact to Company' endpoint also writes to this log for each new assignment. Both endpoints record a ``type`` of ``api`` and an action of 'Lead added to the company, <company name>', and differ only in the event name. This endpoint records 'API batch assignment', while the 'Add Contact to Company' endpoint records 'API assignment'.

Applied in 992d0c8, using your wording and sentence split. I checked the facts against the source PR: the api type, the action text, both event names, and the unchanged 200 for an existing link.

I made one small change. The stored action value is now formatted as code: Lead added to the company, {company name}. Vale flagged Lead and company inside that string, but Mautic generates it, so the wording can't change. The placeholder uses curly braces, following the style guide.

adiati98 · 2026-09-25T06:16:34Z

+     - ID of the Company in the pair
+   * - ``status``
+     - integer
+     - Per-pair status code. See the status values below.


There are a couple of things here:

Link the 'status values' because 'below' isn't clear. The 'below' isn't directly the status values.

Replace 'below' with 'section', and the period for consistency.

Suggested change

- Per-pair status code. See the status values below.

- Per-pair status code. See the status values section

Done in 992d0c8, with the link added. The row now reads: Per-pair status code. See the :ref:status values section <per-pair status values>

It links to the "Per-pair status values" section instead of saying "below". There's no trailing period, which matches the other description cells. The link resolves in a local Sphinx build.

promptless-for-oss · 2026-09-25T06:19:45Z

In reply to this discussion

Thanks, @adiati98. I'm applying your five inline suggestions and fixing the Vale warnings now, and I'll reply in each thread when the update is on the branch.

…tion Fix h5 heading underlines, link the per-pair status values section, and apply the reviewer's change-log paragraph with the action value as a literal to clear Vale FeatureList findings.

promptless-for-oss · 2026-09-25T06:23:54Z

In reply to this discussion

@adiati98 I've applied all five inline suggestions and fixed the Vale warnings in commit 992d0c8. Vale now shows no findings on any line this PR changes. The only remaining suggestion is on line 441, which this PR doesn't touch. I've replied in each thread with the details, including the two suggestions I applied with a small change.

The 8.0 version of this page (PR #673) still has the old 'See the status values below.' wording and change-log sentence. I can make the same edits there if you'd like.

GitHub wouldn't let me re-request your review, so please take another look when you have a moment.

Docs PR: #593

Document Batch add Contacts to Companies REST API endpoint

cea94d9

Add reference for POST /companies/batch/addcontacts (mautic/mautic PR #16512), covering the assignments request body, per-pair results, summary object, status values, batch size limit, and change-log behavior.

promptless-for-oss commented Jul 10, 2026

View reviewed changes

promptless-for-oss mentioned this pull request Jul 10, 2026

Add batch contact-to-company assignment & add logging mautic/mautic#16512

Merged

adiati98 added this to the 7.2 milestone Jul 10, 2026

adiati98 added the pending-pr-merge label Jul 10, 2026

adiati98 requested changes Jul 11, 2026

View reviewed changes

Comment thread docs/rest_api/companies.rst Outdated

Comment thread docs/rest_api/companies.rst Outdated

Comment thread docs/rest_api/companies.rst Outdated

Address review: fix FeatureList Vale findings and use POST parameters…

9ef352e

… heading

adiati98 requested changes Jul 11, 2026

View reviewed changes

Comment thread docs/rest_api/companies.rst Outdated

Comment thread docs/rest_api/companies.rst Outdated

Address review: convert results/summary property intros to h5 headings

5c3b1c9

adiati98 requested changes Jul 11, 2026

View reviewed changes

Comment thread docs/rest_api/companies.rst Outdated

Comment thread docs/rest_api/companies.rst Outdated

adiati98 requested changes Jul 11, 2026

View reviewed changes

Comment thread docs/rest_api/companies.rst Outdated

Comment thread docs/rest_api/companies.rst Outdated

Comment thread docs/rest_api/companies.rst Outdated

docs: Shorten RST heading underlines to match title length

452b5bd

Address @adiati98's review on PR mautic#593: trim excess tildes on the three property-table h5 headings so each underline matches its heading text length.

Merge branch '7.2' into promptless/pr-16512-batch-add-contacts-compan…

7f5f2a9

…ies-api

adiati98 modified the milestones: 7.2, 7.3 Sep 9, 2026

Merge branch '7.2' into promptless/pr-16512-batch-add-contacts-compan…

e37dd0d

…ies-api

promptless-for-oss marked this pull request as ready for review September 11, 2026 13:49

promptless-for-oss requested review from a team, adiati98 and favour-chibueze September 11, 2026 13:49

promptless-for-oss commented Sep 11, 2026

View reviewed changes

Comment thread docs/rest_api/companies.rst Outdated

promptless-for-oss commented Sep 11, 2026

View reviewed changes

Comment thread docs/rest_api/companies.rst

promptless Bot added 2 commits September 11, 2026 14:22

Revert "docs: fix Sphinx 'Title underline too short' on batch endpoin…

8255ed6

…t subsections" This reverts commit be4345d.

promptless-for-oss changed the base branch from 7.2 to 7.3 September 16, 2026 07:10

Merge branch '7.3' into promptless/pr-16512-batch-add-contacts-compan…

cea6c5d

…ies-api

adiati98 added needs-backport and removed pending-pr-merge labels Sep 17, 2026

promptless-for-oss mentioned this pull request Sep 17, 2026

docs: Document Batch add Contacts to Companies REST API endpoint (8.0) #673

Open

Merge branch '7.3' into promptless/pr-16512-batch-add-contacts-compan…

ca5906c

…ies-api

adiati98 requested changes Sep 25, 2026

View reviewed changes

docs: apply review suggestions to batch add Contacts to Companies sec…

992d0c8

…tion Fix h5 heading underlines, link the per-pair status values section, and apply the reviewer's change-log paragraph with the action value as a literal to clear Vale FeatureList findings.

		The ``results`` entry properties
		~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

		The ``summary`` object properties
		~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	- Per-pair status code. See the status values below.
	- Per-pair status code. See the status values section

Conversation

promptless-for-oss commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adiati98 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

promptless-for-oss commented Jul 11, 2026

Uh oh!

adiati98 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

promptless-for-oss commented Jul 11, 2026

Uh oh!

adiati98 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

promptless-for-oss commented Jul 11, 2026

Uh oh!

adiati98 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

promptless-for-oss commented Jul 11, 2026

Uh oh!

Uh oh!

Uh oh!

promptless-for-oss commented Sep 11, 2026

Uh oh!

adiati98 commented Sep 16, 2026

Uh oh!

promptless-for-oss commented Sep 16, 2026

Uh oh!

promptless-for-oss commented Sep 16, 2026

Uh oh!

adiati98 commented Sep 17, 2026

Uh oh!

promptless-for-oss commented Sep 17, 2026

Uh oh!

promptless-for-oss commented Sep 17, 2026

Uh oh!

adiati98 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

promptless-for-oss commented Sep 25, 2026

Uh oh!

promptless-for-oss commented Sep 25, 2026

promptless-for-oss commented Jul 10, 2026 •

edited

Loading