Contacts

Export a contact's data

GET/v1/contacts/{id}/data-export

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

Everything held about one contact, for answering a right-of-access request: profile, consent history, events, messages, groups, segments, topics, journeys, push devices (without tokens), form submissions, conversions and suppressions. Data past the retention periods is no longer held, so it is not included. The response is streamed as it is read, so a long history arrives without a length. Each export is recorded in the audit log. Owners and admins in the dashboard; contacts:read over the API.

Path parameters

idstringrequired: uuid

Returns

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

exportedAtstringrequired

When this export was produced.

date-time

contactContactDetailrequired

15 child attributes

idstringrequired

uuid

externalIdstring | nullrequired

Your own id for the contact, if set.

emailstring | nullrequired

firstNamestring | nullrequired

lastNamestring | nullrequired

phonestring | nullrequired

Phone number in E.164 format.

timezonestring | nullrequired

IANA timezone, e.g. Europe/London.

countrystring | nullrequired

ISO 3166-1 alpha-2 code: as written, or inferred from the phone, else the timezone.

datesobjectrequired

Named calendar dates, e.g. birthday, as YYYY-MM-DD or --MM-DD.

attributesobjectrequired

Custom attributes, keyed by attribute name.

emailConsentbooleanrequired

Whether the contact has consented to email.

pushConsentbooleanrequired

Whether the contact has consented to push.

createdAtstringrequired

date-time

updatedAtstringrequired

date-time

emailSuppressionobjectrequired

2 child attributes

suppressedbooleanrequired: Whether email to this contact is blocked.
reasonstring | nullrequired: Why email to this contact is suppressed: bounced, complained, complained_transactional, unsubscribed, manual, imported, or other_workspace (a bounce or complaint in another workspace with the same owner or partner).

consentHistoryobject[]required

13 child attributes

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

eventsobject[]required

4 child attributes

idstringrequired: uuid
eventNamestringrequired
propertiesobjectrequired
occurredAtstringrequired: date-time

messagesobject[]required

12 child attributes

idstringrequired: uuid
campaignIdstring | nullrequired: uuid
channelstringrequired: one of email, push
messageTypestringrequired: one of marketing, transactional
statusstringrequired: one of queued, sending, skipped, sent, failed, delivered, bounced, complained
recipientAddressstring | nullrequired: The address or device it was sent to.
sentAtstring | nullrequired: date-time
deliveredAtstring | nullrequired: date-time
openedAtstring | nullrequired: date-time
clickedAtstring | nullrequired: date-time
unsubscribedAtstring | nullrequired: date-time
createdAtstringrequired: date-time

groupsobject[]required

3 child attributes

idstringrequired: uuid
namestringrequired
addedAtstringrequired: date-time

segmentsobject[]required

3 child attributes

idstringrequired: uuid
namestringrequired
enteredAtstringrequired: date-time

topicsobject[]required

4 child attributes

idstringrequired: uuid
namestringrequired
subscribedbooleanrequired: Whether the contact is subscribed to the topic.
updatedAtstringrequired: date-time

journeysobject[]required

5 child attributes

idstringrequired: uuid
namestringrequired
statusstringrequired: one of active, completed, exited
enrolledAtstringrequired: date-time
completedAtstring | nullrequired: date-time

pushDevicesobject[]required

5 child attributes

kindstringrequired

one of apns_token, fcm_token, web_push_subscription

permissionstringrequired

Notification permission on the device.

one of granted, denied

activebooleanrequired

Whether the device can still receive push.

lastSeenAtstringrequired

date-time

createdAtstringrequired

date-time

formSubmissionsobject[]required

6 child attributes

formIdstringrequired: uuid
formNamestringrequired
outcomestringrequired: one of created, updated, honeypot, pending
createdAtstringrequired: date-time
confirmedAtstring | nullrequired: date-time
pendingContactobject | nullrequired: What an unconfirmed signup entered, held until confirmed or for 7 days.

conversionsobject[]required

3 child attributes

goalIdstringrequired: uuid
valuenumber | nullrequired: Value recorded with the conversion, if any.
convertedAtstringrequired: date-time

suppressionsobject[]required

4 child attributes

channelstringrequired: one of email, push
addressstring | nullrequired: Set when the block is on the address itself, not the contact.
reasonstringrequired: Why the channel is blocked.
createdAtstringrequired: date-time

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

const response = await fetch('https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/data-export', {
  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/data-export",
    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/data-export", 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": {
    "exportedAt": "2030-03-14T09:30:00Z",
    "contact": {
      "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
      "externalId": "user_8812",
      "email": "amaka@juniperkitchen.com",
      "firstName": "Amaka",
      "lastName": "Eze",
      "phone": "+447700900123",
      "timezone": "Europe/London",
      "country": "GB",
      "dates": {},
      "attributes": {},
      "emailConsent": true,
      "pushConsent": true,
      "createdAt": "2030-03-14T09:30:00Z",
      "updatedAt": "2030-03-14T09:30:00Z",
      "emailSuppression": {
        "suppressed": true,
        "reason": "reason_example"
      }
    },
    "consentHistory": [
      {
        "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"
      }
    ],
    "events": [
      {
        "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
        "eventName": "Order Completed",
        "properties": {},
        "occurredAt": "2030-03-14T09:30:00Z"
      }
    ],
    "messages": [
      {
        "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
        "campaignId": "018f2a4e-6b1c-7d3e-9f40-3478765e5a6b",
        "channel": "email",
        "messageType": "marketing",
        "status": "queued",
        "recipientAddress": "recipientAddress_example",
        "sentAt": "2030-03-14T09:30:00Z",
        "deliveredAt": "2030-03-14T09:30:00Z",
        "openedAt": "2030-03-14T09:30:00Z",
        "clickedAt": "2030-03-14T09:30:00Z",
        "unsubscribedAt": "2030-03-14T09:30:00Z",
        "createdAt": "2030-03-14T09:30:00Z"
      }
    ],
    "groups": [
      {
        "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
        "name": "Weekend specials",
        "addedAt": "2030-03-14T09:30:00Z"
      }
    ],
    "segments": [
      {
        "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
        "name": "Weekend specials",
        "enteredAt": "2030-03-14T09:30:00Z"
      }
    ],
    "topics": [
      {
        "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
        "name": "Weekend specials",
        "subscribed": true,
        "updatedAt": "2030-03-14T09:30:00Z"
      }
    ],
    "journeys": [
      {
        "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
        "name": "Weekend specials",
        "status": "active",
        "enrolledAt": "2030-03-14T09:30:00Z",
        "completedAt": "2030-03-14T09:30:00Z"
      }
    ],
    "pushDevices": [
      {
        "kind": "apns_token",
        "permission": "granted",
        "active": true,
        "lastSeenAt": "2030-03-14T09:30:00Z",
        "createdAt": "2030-03-14T09:30:00Z"
      }
    ],
    "formSubmissions": [
      {
        "formId": "018f2a4e-6b1c-7d3e-9f40-b962ee2a5a6b",
        "formName": "formName_example",
        "outcome": "created",
        "createdAt": "2030-03-14T09:30:00Z",
        "confirmedAt": "2030-03-14T09:30:00Z",
        "pendingContact": {}
      }
    ],
    "conversions": [
      {
        "goalId": "018f2a4e-6b1c-7d3e-9f40-91ddf3eb5a6b",
        "value": 1,
        "convertedAt": "2030-03-14T09:30:00Z"
      }
    ],
    "suppressions": [
      {
        "channel": "email",
        "address": "address_example",
        "reason": "reason_example",
        "createdAt": "2030-03-14T09:30:00Z"
      }
    ]
  }
}

Example values are generated from the schema.