Export a contact's dataMenu

Export a contact's data

GET/v1/contacts/{id}/export

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

Works with integration, agent and partner keys.

Returns everything held about one contact, for answering a right-of-access request: profile, consent changes, events, messages, lists, 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.

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

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 ContactDataExport in data. Otherwise returns an error; Errors lists every code and which to retry.

exportedAtstringrequired

When this export was produced.

date-time

contactContactDetailrequired

17 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.

localestring | nullrequired

BCP 47 tag (fr, fr-CA): the language the contact reads (its first subtag), and how merge tags format numbers, dates and money for them.

rfmobject | nullrequired

The contact's RFM (recency, frequency and monetary value) group among the workspace's customers, from its purchase events (the workspace's purchaseEvent: an order, a paid invoice, a booking, a donation), each score from 1 to 5 (a fifth of the customers each; 5 is the most recent, most frequent or highest spend), and their purchase totals. Spend counts only purchases in the workspace's main currency; when the purchase carries no amount, monetary follows frequency. Recomputed daily, so a purchase today shows tomorrow; null for someone who has never purchased.

7 child attributes

groupstringrequired

one of champions, loyal, cant_lose_them, potential_loyalists, new_customers, need_attention, about_to_sleep, at_risk, hibernating, lost

recencyintegerrequired

min 1 · max 5

frequencyintegerrequired

min 1 · max 5

monetaryintegerrequired

min 1 · max 5

purchaseCountintegerrequired

Their purchase events (the workspace's purchaseEvent), in any currency.

min > 0

totalSpentobject | nullrequired

What their purchases' amounts (purchaseValueProperty) add up to, in the workspace's main currency (currency on GET /v1/reports/rfm); purchases in other currencies and refunds are left out. null when the purchase carries no amount.

2 child attributes

currencystring | nullrequired: The currency, an ISO 4217 code; null when none was named.
valuenumberrequired: The amount in that currency.

lastPurchasedAtstringrequired

When their latest purchase happened.

date-time

datesmap<string, string>required

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

attributesmap<string, object>required

Custom attributes, keyed by attribute name.

consentContactConsentrequired

Consent on each channel.

2 child attributes

emailbooleanrequired: Whether the contact has consented to email.
pushbooleanrequired: 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).

listIdsstring[]required

Ids of the lists the contact is in.

consentChangesobject[]required

15 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.

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

eventsobject[]required

4 child attributes

idstringrequired: uuid
eventNamestringrequired
propertiesmap<string, any>required
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
recipientEmailstring | nullrequired: The email address it went to; null for push.
sentAtstring | nullrequired: date-time
deliveredAtstring | nullrequired: date-time
openedAtstring | nullrequired: date-time
clickedAtstring | nullrequired: date-time
unsubscribedAtstring | nullrequired: date-time
createdAtstringrequired: date-time

listsobject[]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

journeyIdstring | nullrequired

Null once the journey has been deleted.

uuid

journeyNamestring | nullrequired

Null once the journey has been deleted.

statusstringrequired

one of active, completed, exited

enteredAtstringrequired

date-time

endedAtstring | 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, expired
createdAtstringrequired: date-time
confirmedAtstring | nullrequired: date-time
pendingContactmap<string, any> | nullrequired: What an unconfirmed signup entered, held until confirmed or for 7 days.

conversionsobject[]required

3 child attributes

conversionGoalIdstringrequired

uuid

valueobject | nullrequired

Value recorded with the conversion, in its conversion goal's currency, if any.

2 child attributes

currencystring | nullrequired: The currency, an ISO 4217 code; null when none was named.
valuenumberrequired: The amount in that currency.

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

const response = await fetch('https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/export', {
  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 } = await response.json();

import os

import requests

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

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/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()
	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"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

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/export");
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");

Response · 200

{
  "data": {
    "exportedAt": "2026-10-02T10:00:00.000Z",
    "contact": {
      "id": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
      "externalId": "customer-4821",
      "email": "[email protected]",
      "firstName": "Amaka",
      "lastName": "Obi",
      "phone": "+447700900123",
      "timezone": "Europe/London",
      "country": "GB",
      "locale": "en-NG",
      "rfm": {
        "group": "loyal",
        "recency": 3,
        "frequency": 4,
        "monetary": 5,
        "purchaseCount": 6,
        "totalSpent": {
          "currency": "USD",
          "value": 412.5
        },
        "lastPurchasedAt": "2026-03-02T18:20:00.000Z"
      },
      "dates": {
        "birthday": "1992-03-14"
      },
      "attributes": {
        "plan": "pro",
        "favourite_spice": "smoked paprika",
        "orders": 3
      },
      "consent": {
        "email": true,
        "push": false
      },
      "createdAt": "2026-09-12T08:15:00.000Z",
      "updatedAt": "2026-10-01T09:30:00.000Z",
      "emailSuppression": {
        "suppressed": false,
        "reason": null
      },
      "listIds": [
        "0192f3a2-1b3c-7e5d-8a21-4f6a7b8c9d0e"
      ]
    },
    "consentChanges": [
      {
        "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"
      }
    ],
    "events": [
      {
        "id": "0192f3c0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
        "eventName": "Order Completed",
        "properties": {
          "order_id": "1001",
          "total": 46.5,
          "currency": "USD"
        },
        "occurredAt": "2026-10-01T09:30:00.000Z"
      }
    ],
    "messages": [
      {
        "id": "0192f3b0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
        "campaignId": "0192f3d3-5e6f-7071-8c83-9e0f1a2b3c4d",
        "channel": "email",
        "messageType": "marketing",
        "status": "delivered",
        "recipientEmail": "[email protected]",
        "sentAt": "2026-10-01T09:31:00.000Z",
        "deliveredAt": "2026-10-01T09:31:04.000Z",
        "openedAt": null,
        "clickedAt": null,
        "unsubscribedAt": null,
        "createdAt": "2026-10-01T09:30:58.000Z"
      }
    ],
    "lists": [
      {
        "id": "0192f3a2-1b3c-7e5d-8a21-4f6a7b8c9d0e",
        "name": "Newsletter",
        "addedAt": "2026-09-12T08:16:00.000Z"
      }
    ],
    "segments": [
      {
        "id": "0192f3a3-2c4d-7f6e-9b32-5a7b8c9d0e1f",
        "name": "Lapsed customers",
        "enteredAt": "2026-10-01T00:00:00.000Z"
      }
    ],
    "topics": [
      {
        "id": "0192f3b0-6a1b-7c2d-8e3f-4a5b6c7d8e9f",
        "name": "Weekly offers",
        "subscribed": true,
        "updatedAt": "2026-09-12T08:15:00.000Z"
      }
    ],
    "journeys": [
      {
        "journeyId": "0192f3a4-3d5e-7a7f-8c43-6b8c9d0e1f2a",
        "journeyName": "Welcome series",
        "status": "completed",
        "enteredAt": "2026-09-12T08:16:00.000Z",
        "endedAt": "2026-09-19T08:16:00.000Z"
      }
    ],
    "pushDevices": [],
    "formSubmissions": [],
    "conversions": [],
    "suppressions": []
  }
}