Docs
kirora.ioGet started
Contacts overviewMenu
On this page

API reference

Contacts

A contact is one person you can message, with their profile, custom attributes, consent on each channel and topic choices. identify creates or updates a contact by your externalId, then email, then phone, so use it for every sync rather than looking contacts up by id first. Being on a list or in a segment is not consent: marketing reaches a contact only with consent on its channel. A contact's own records sit under it too: its lists, segments, topic choices, events, journeys, messages and push installations, each a device or browser registered by your own stable externalInstallationId. See IDs and identity.

Endpoints

EndpointRequest
List contactsGET /v1/contacts
Create or update a contactPOST /v1/contacts/identify
Identify contacts in a batchPOST /v1/contacts/batch
Retrieve a contactGET /v1/contacts/{id}
Update a contactPATCH /v1/contacts/{id}
Delete a contactDELETE /v1/contacts/{id}
Delete contactsPOST /v1/contacts/delete
Merge a contact into anotherPOST /v1/contacts/{id}/merge
List a contact's consent changesGET /v1/contacts/{id}/consent-changes
Export a contact's dataGET /v1/contacts/{id}/export
List a contact's listsGET /v1/contacts/{id}/lists
List a contact's segmentsGET /v1/contacts/{id}/segments
List a contact's topicsGET /v1/contacts/{id}/topics
Set a contact's topic choicePUT /v1/contacts/{id}/topics/{topicId}
List a contact's eventsGET /v1/contacts/{id}/events
List a contact's journey enrollmentsGET /v1/contacts/{id}/journeys
List a contact's messagesGET /v1/contacts/{id}/messages
List a contact's push installationsGET /v1/contacts/{id}/installations
Register a push installationPOST /v1/contacts/{id}/installations
Delete a push installationDELETE /v1/contacts/{id}/installations/{externalInstallationId}

The ContactDetail object

ContactDetail example
{
  "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"
  ]
}
idstringrequired

uuid

externalIdstring | nullrequired

Your own id for the contact, if set.

emailstring | nullrequired

email

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.