---
title: "Invite people to a group by phone number or contact id"
method: POST
path: "/v2/groups/{id}/invites"
tags: ["WhatsApp Groups"]
---

# Invite people to a group by phone number or contact id

`POST /v2/groups/{id}/invites`

## Request

- Base URL: `https://api.spurnow.com`
- URL: `https://api.spurnow.com/v2/groups/{id}/invites`
- Auth: HTTP bearer

Sends each person a 1:1 utility template message carrying the group invite link (Meta resolves the group id to the link at delivery). The template is auto-provisioned from Meta's Template Library on first use per channel. Joins arrive asynchronously on the group_participants_update webhook, so someone invited will not appear in `participants` until they accept.

Identify people by `phones` or by `contactIds`, but not both in the same request. Numbers must be in international format including the country code (`+919958135900`); bare local digits will not match a contact. Every number must already be a WhatsApp contact in this workspace. Nothing is sent unless all of them resolve, and the response names any that did not, so you can create those contacts with `POST /contacts` and invite again. Creating a contact raises `new_contact_created`, so any workflow listening for a new contact will run. The group must be `active`.

Each result carries the `contactId` it applies to, plus the `phone` it came from when the request used `phones`, so a failure can be traced back to the number you sent. The number is echoed normalised, without the leading `+`, so match on digits rather than on the exact string you sent.

## Path parameters

- `id` number, required

## Request body

- InviteParticipantsBody
  - `contactIds` number[]: Existing WhatsApp contact ids to invite. Each receives a 1:1 utility template message carrying the group invite link. Provide this or `phones`.
  - `phones` string[]: Phone numbers to invite, in international format including the country code. Each must already be a WhatsApp contact in this workspace; nothing is sent unless all of them resolve, and the response names any that did not, so you can create the contact and invite again. Provide this or `contactIds`, not both.

## Response `201`

- GroupInviteResponseDto
  - `results` GroupInviteResultDto[], required
    - `contactId` number, required
    - `phone` string: The number this result is for, echoed back when the request identified people by `phones`, so a failure can be matched to the number you sent.
    - `status` 'sent' | 'failed', required
    - `error` string: Human-readable failure reason when status is failed.

## Other responses

- `400`: Neither `phones` nor `contactIds` was provided, or both were; a value is not a valid phone number; a number or contact is not a WhatsApp contact in this workspace; the group is not active; or the selection exceeds the remaining participant slots.
- `404`: Group conversation not found in this workspace.
- `409`: The group-invite template is still pending WhatsApp approval.

---

[API](https://skmtc.dev/spurnow/apis/spur-apis.md) - [All operations](https://skmtc.dev/spurnow/apis/spur-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/spurnow/apis/spur-apis/revisions/27ca7bf002cb?raw)