List a contact's consent changesMenu

List a contact's consent changes

GET/v1/contacts/{id}/consent-changes

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

Works with integration, agent and partner keys.

Lists every grant and withdrawal of consent for this contact, per channel or per topic, newest first: where it came from (dashboard, API, import, form, unsubscribe link), who made it, and the IP it came from. Append-only. It tells apart a contact never asked from one who withdrew, which both read as false in consent.

Path parameters

idstringrequired

Kirora's id for the contact, your own with idType=externalId, or its email address with idType=email, URL-encoded (@ as %40).

1–255 characters

Query parameters

limitintegeroptional

How many items a page holds: 1 to 100, 20 by default.

min > 0 · max 100 · default 20

cursorstringoptional

Where the page starts: the previous page's meta.pagination.nextCursor. Omit it for the first page, and send the same filters with it.

1–2,048 characters

idTypestringoptional

What {id} is: Kirora's id for the contact (id, the default), your own (externalId, as set with identify) or its email address (email, matched trimmed and without case).

one of id, externalId, email · default "id"

Header parameters

Kirora-Workspacestringoptional

Partner keys only: the child workspace to act in, by the external id the partner gave it. Without it, a partner key acts in its own workspace. Any other key that sends it is refused with 403, and an unknown workspace is 404.

pattern ^[A-Za-z0-9._:-]{1,128}$

Returns

Returns 200 OK with a list of ConsentChange objects in data, and the next page's cursor in meta (see pagination). Otherwise returns an error; Errors lists every code and which to retry.

idstringrequired

uuid

channelstring | nullrequired

The channel consented to. With topicId null: consent to the channel; with both set: a per-channel topic choice.

one of email, push

topicIdstring | nullrequired

The topic consented to, if any.

uuid

grantedbooleanrequired

True for a grant, false for a withdrawal.

sourcestringrequired

one of dashboard, api, import, form, unsubscribe, system, sdk

sourceIdstring | nullrequired

The form, when source is form.

uuid

actorTypestringrequired

one of user, api_key, contact, system

actorIdstring | nullrequired

Member or API key id; null for the contact themselves and the system.

uuid

ipstring | nullrequired

IP address the change came from.

reasonstring | nullrequired

Why it changed, when one was given.

basisstring | nullrequired

How the person agreed, as the workspace stated it; null when nobody did.

one of opted_in, existing_customer

evidencestring | nullrequired

Where and how they agreed, as stated.

consentedAtstring | nullrequired

When they agreed, as stated; null means at occurredAt.

date-time

wordingstring | nullrequired

The words they agreed to, as stated.

occurredAtstringrequired

date-time

actorNamestring | nullrequired

The member's or API key's name now; null for the contact, the system, or one deleted.

curl https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/consent-changes \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/consent-changes', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data, meta } = await response.json();
// meta.pagination.nextCursor is the next page's `cursor`, and null on the last page.

import os

import requests

response = requests.get(
    "https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/consent-changes",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
)
response.raise_for_status()
body = response.json()
data = body["data"]
next_cursor = body["meta"]["pagination"]["nextCursor"]
# next_cursor is the next page's `cursor`, and None on the last page.

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/consent-changes", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("Kirora API %d: %s", res.StatusCode, msg))
	}

	var out struct {
		Data json.RawMessage `json:"data"`
		Meta struct {
			Pagination struct {
				NextCursor *string `json:"nextCursor"`
			} `json:"pagination"`
		} `json:"meta"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
	// out.Meta.Pagination.NextCursor is the next page's `cursor`, and nil on the last page.
}

using System.Net.Http.Headers;
using System.Text.Json;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/consent-changes");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));

using var response = await http.SendAsync(request);
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"Kirora API {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var data = document.RootElement.GetProperty("data");
var nextCursor = document.RootElement.GetProperty("meta").GetProperty("pagination").GetProperty("nextCursor");
// nextCursor is the next page's `cursor`, and null on the last page.

Response · 200

{
  "data": [
    {
      "id": "0192f3a5-6081-7da2-9f76-9e1f2a3b4c5d",
      "channel": "email",
      "topicId": null,
      "granted": false,
      "source": "unsubscribe",
      "sourceId": null,
      "actorType": "contact",
      "actorId": null,
      "ip": "203.0.113.7",
      "reason": null,
      "basis": null,
      "evidence": null,
      "consentedAt": null,
      "wording": null,
      "occurredAt": "2026-10-05T12:00:00.000Z",
      "actorName": null
    },
    {
      "id": "0192f3a5-5f70-7c91-8e65-8d0e1f2a3b4c",
      "channel": "email",
      "topicId": null,
      "granted": true,
      "source": "api",
      "sourceId": null,
      "actorType": "api_key",
      "actorId": null,
      "ip": null,
      "reason": null,
      "basis": "opted_in",
      "evidence": "Checkout opt-in on shop.example.com",
      "consentedAt": null,
      "wording": "Send me offers and news by email",
      "occurredAt": "2026-09-12T08:15:00.000Z",
      "actorName": "Shop backend"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 20,
      "nextCursor": null
    }
  }
}