Contacts

List a contact's consent history

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

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

Every grant and withdrawal of consent, 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. Changes made before this history existed are not in it.

Path parameters

idstringrequired: uuid

Query parameters

limitintegeroptional: min > 0 · max 100 · default 20
cursorstringoptional: 1–2048 characters

Returns

Returns 200 OK. 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.

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-history \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/consent-history', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
const { data } = await response.json();

import os

import requests

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

package main

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

func main() {
	req, err := http.NewRequest("GET", "https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/consent-history", 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()

	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",
      "channel": "email",
      "topicId": "018f2a4e-6b1c-7d3e-9f40-84e01f695a6b",
      "granted": true,
      "source": "dashboard",
      "sourceId": "018f2a4e-6b1c-7d3e-9f40-dee8fa655a6b",
      "actorType": "user",
      "actorId": "018f2a4e-6b1c-7d3e-9f40-3c94fe175a6b",
      "ip": "ip_example",
      "reason": "reason_example",
      "basis": "opted_in",
      "evidence": "evidence_example",
      "occurredAt": "2030-03-14T09:30:00Z",
      "actorName": "actorName_example"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 1,
      "nextCursor": "nextCursor_example"
    }
  }
}

Example values are generated from the schema.