POST/v1/groups/{group_id}/contactsbeta

Add contacts to a group

Needs: Create and edit contacts, tags, contact groups and custom fields (crm:write)
Plan: Any plan with API access
Limits: 60 a minute per key
Dry run: Yes — every check runs with ?dry_run=true, nothing changes
Undo: Remove them again with Remove contacts from a group.

Adds up to 500 contacts to a group in one background job. Contacts keep their other groups; adding twice is harmless. Ids that are not in your workspace are skipped and listed in failures.

The change applies within seconds: check it with Count contacts and group_ids.

Try it

Path

group_idrequired

The group id.

Edit as JSON

contact_idsrequiredlist

Contact ids (1–500).

Idempotency-Keyoptional — made for you if empty

Protects against doing it twice if you retry: a retry with the same key gets the first answer back instead of running again.

Test mode (dry run): nothing will change

Run liveTurns test mode off for this page only. It switches back when you leave the page.

curl -X POST 'https://mcp.wa-api.cloud/v1/groups/6/contacts?dry_run=true' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "contact_ids": [
    "48213",
    "48214"
  ]
}'

The code reads your key from $API_KEY.

Parameters

Parameters
Field	Type	What it is
group_idrequired	string \| integer · path	The group id.pattern `^[1-9]\d{0,18}$`

Body

Body fields
Field	Type	What it is
contact_idsrequired	array of string \| integer	Contact ids (1–500).1–500 itemsSigned in? Pick one from your data with “My data”.

Headers

Headers
Field	Type	What it is
Authorizationrequired	header	`Bearer $API_KEY` — your API key.
Api-Version	header	The API version to use, e.g. `2026-10-01`. Default: the version your key is pinned to.one of: `2026-10-01` · pattern `^\d{4}-\d{2}-\d{2}$`
Idempotency-Key	header	Any unique string (8–128 characters). A retry with the same key returns the first answer instead of running twice. Kept 24 hours.pattern `^[A-Za-z0-9._:-]+$` · 8–128 characters

Response `202`

Accepted: how many contacts the job took, and the ids it skipped.

Response fields
Field	Type	What it is
requestedrequired	integer	-9007199254740991–9007199254740991
acceptedrequired	integer	Contacts handed to the background job.-9007199254740991–9007199254740991
failedrequired	integer	-9007199254740991–9007199254740991
failuresrequired	array of object
idrequired	string
coderequired	string
messagerequired	string
job_idrequired	string or null	The platform background job id; membership changes apply within seconds to minutes.
job_statusrequired	string or null
matched	integer or null	By filter: the contacts that matched when the change started (the ones handed to the job).-9007199254740991–9007199254740991
dry_run	boolean	`true` when this was a dry run: every check ran and nothing changed.

Errors

Errors are application/problem+json. Branch on code.

Status	Code	When
400	invalid_input	A field is missing or has the wrong format. `errors[]` points at each field. More than 500 contact ids, or the group does not exist.
401	unauthenticated	The Authorization header is missing, the key is unknown, expired or revoked.
403	entitlement_required	The workspace's plan does not include API access (`api_access`).
403	insufficient_scope	The key does not have the permission this operation needs.
409	conflict	Also returned while a request with the same Idempotency-Key is still running.
429	rate_limited	The key or workspace went over its rate limit. Wait for `Retry-After` seconds.
503	upstream_unavailable	A service behind the API is briefly unavailable. Safe to retry with backoff.
504	timeout	The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.

Examples

Add two contacts to a group

Request body

{
  "contact_ids": [
    "48213",
    "48214"
  ]
}

Response 202

{
  "requested": 2,
  "accepted": 2,
  "failed": 0,
  "failures": [],
  "job_id": "88121",
  "job_status": "pending"
}

Operation path

The same operation is also at POST /v1/ops/crm_add_to_group, with every field in the JSON body.