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

Open this suggestion in Promptless to view citations and reasoning process

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, summary object, per-pair status values, the batch size limit, and change-log behavior. Targets the 7.2 docs branch per branch-targeting rules (source base 7.x).

Trigger Events

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

Tip: Enable auto-create PR in your Configuration to review suggestions directly in GitHub 🤖

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.

adiati98 · 2026-07-11T16:52:46Z

+     - string
+     - Human-readable outcome for the pair
+
+The ``summary`` object contains the following properties.


Suggested change

The ``summary`` object contains the following properties.

The ``summary`` object properties

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

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 · 2026-07-11T18:53:21Z

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


Remove the excess ~ here.

Suggested change

The ``results`` entry properties

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

The ``results`` entry properties

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

adiati98 · 2026-07-11T18:53:30Z

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


Suggested change

The ``summary`` object properties

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

The ``summary`` object properties

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

adiati98 · 2026-07-11T18:53:40Z

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


Suggested change

Per-pair ``status`` values

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

Per-pair ``status`` values

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

@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.

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

Open

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

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

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.

	The ``summary`` object contains the following properties.
	The ``summary`` object properties
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

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

Uh oh!

Conversation

promptless-for-oss commented Jul 10, 2026

Uh oh!

promptless-for-oss Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

promptless-for-oss Jul 10, 2026

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!

adiati98 Jul 11, 2026

Choose a reason for hiding this comment

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!

adiati98 Jul 11, 2026

Choose a reason for hiding this comment

Uh oh!

adiati98 Jul 11, 2026

Choose a reason for hiding this comment

Uh oh!

adiati98 Jul 11, 2026

Choose a reason for hiding this comment

Uh oh!

promptless-for-oss commented Jul 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants