Groups

Add contacts to a group

POST/v1/groups/{id}/contacts

Requires an API key with the groups:write scope. About keys and scopes

Adds up to 500 contacts to a group in one batch, named by exactly one of contactIds, externalIds or emails. Contacts already in the group are skipped rather than rejected, so the call is safe to repeat; the response reports how many were actually added, and lists in notFound the identifiers that name no contact in this workspace (no contact is created). Agent keys are refused with 403.

Path parameters

idstringrequired: uuid

Request body

By contact ids

1 child attribute

contactIdsstring[]required

Kirora's ids for the contacts.

at least 1 item · at most 500 items

By external ids

1 child attribute

externalIdsstring[]required

Your own ids for the contacts, as set with identify.

at least 1 item · at most 500 items

By emails

1 child attribute

emailsstring[]required

Email addresses, matched trimmed and without case.

at least 1 item · at most 500 items

Returns

Returns 200 OK with a AddedGroupMembers in data. Otherwise returns an error; Errors lists every code and which to retry.

addedintegerrequired

Contacts newly added to the group.

min 0 · max 9007199254740991

notFoundstring[]required

Identifiers as sent (emails normalised) that name no contact in the workspace.

curl -X POST https://api.kirora.io/v1/groups/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/contacts \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": [
      "018f2a4e-6b1c-7d3e-9f40-149f1e875a6b"
    ]
  }'

const response = await fetch('https://api.kirora.io/v1/groups/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/contacts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contactIds": [
      "018f2a4e-6b1c-7d3e-9f40-149f1e875a6b"
    ]
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/groups/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/contacts",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "contactIds": [
            "018f2a4e-6b1c-7d3e-9f40-149f1e875a6b",
        ],
    },
)
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "contactIds": [
	    "018f2a4e-6b1c-7d3e-9f40-149f1e875a6b"
	  ]
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/groups/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/contacts", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

Response · 200

{
  "data": {
    "added": 0,
    "notFound": [
      "notFound_example"
    ]
  }
}

Example values are generated from the schema.