Topics

Set a contact's topic choice

PUT/v1/contacts/{id}/topics/{topicId}

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

Any member, or a key with contacts:write (never an agent key), as for consent. Recorded in consent history with the member or key as actor. With channel, the choice is for that channel only (keep Product updates by email, not by push); without it, it holds for every channel and clears channel choices.

Path parameters

idstringrequired: uuid
topicIdstringrequired: uuid

Request body

subscribedbooleanrequired

True to join the topic, false to leave it.

channelstringoptional

One channel's choice; omitted, the choice holds for every channel.

one of email, push

Returns

Returns 200 OK. Otherwise returns an error; Errors lists every code and which to retry.

idstringrequired

uuid

namestringrequired

descriptionstring | nullrequired

modestringrequired

opt_out reaches everyone who has not left; opt_in only those who joined.

one of opt_out, opt_in

createdAtstringrequired

date-time

updatedAtstringrequired

date-time

subscribedbooleanrequired

Whether campaigns and journey steps on this topic reach the contact.

channelsobjectrequired

The same per channel: a channel's own choice wins over subscribed there.

2 child attributes

emailbooleanrequired
pushbooleanrequired

curl -X PUT https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/topics/018f2a4e-6b1c-7d3e-9f40-84e01f695a6b \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscribed": true
  }'

const response = await fetch('https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/topics/018f2a4e-6b1c-7d3e-9f40-84e01f695a6b', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "subscribed": true
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.put(
    "https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/topics/018f2a4e-6b1c-7d3e-9f40-84e01f695a6b",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "subscribed": True,
    },
)
data = response.json()["data"]

package main

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

func main() {
	body := []byte(`{
	  "subscribed": true
	}`)
	req, err := http.NewRequest("PUT", "https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/topics/018f2a4e-6b1c-7d3e-9f40-84e01f695a6b", 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": {
    "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
    "name": "Weekend specials",
    "description": "description_example",
    "mode": "opt_out",
    "createdAt": "2030-03-14T09:30:00Z",
    "updatedAt": "2030-03-14T09:30:00Z",
    "subscribed": true,
    "channels": {
      "email": true,
      "push": true
    }
  }
}

Example values are generated from the schema.