Contacts

Create or update a contact

POST/v1/contacts/identify

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

Upsert keyed on identity rather than id: the contact is resolved by externalId, then email, then phone, and created if none matches. Consent flags that are omitted keep their current value rather than resetting to false. attributes merge as on update: null removes a key. This is the endpoint to use for ingestion. Agent keys are refused with 403.

Request body

externalIdstring | nulloptional

Your own id for the contact, up to 255 characters. Identify matches on it first.

1–255 characters

emailstring | nulloptional

firstNamestring | nulloptional

1–100 characters

lastNamestring | nulloptional

1–100 characters

phonestring | nulloptional

Phone number; normalised to E.164 (a leading + and country code).

timezonestring | nulloptional

IANA timezone, e.g. Europe/London; used for send-time scheduling.

up to 100 characters

countrystring | nulloptional

ISO 3166-1 alpha-2 code. Omitted, it is inferred from the phone, else the timezone.

datesContactDatesInputoptional

Named calendar dates, merged key by key; null removes one.

attributesobjectoptional

Custom attributes, merged key by key; null removes one. At most 50 keys and 16 KB.

emailConsentbooleanoptional

Consent to email. Omitted, the current value is kept.

pushConsentbooleanoptional

Consent to push. Omitted, the current value is kept.

consentStatementConsentStatementInputoptional

How the contact agreed, recorded with any consent this request grants.

2 child attributes

basisstringrequired

The legal basis the contacts agreed under.

one of opted_in, existing_customer

evidencestringrequired

Where and how they agreed, e.g. "Checkout opt-in on shop.example.com".

1–500 characters

Returns

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

200 OKThe existing contact, updated.
201 CreatedA new contact was created.

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

curl -X POST https://api.kirora.io/v1/contacts/identify \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_8812",
    "email": "amaka@juniperkitchen.com",
    "firstName": "Amaka",
    "lastName": "Eze",
    "phone": "+447700900123",
    "timezone": "Europe/London",
    "country": "GB",
    "dates": {},
    "attributes": {},
    "emailConsent": true,
    "pushConsent": true,
    "consentStatement": {
      "basis": "opted_in",
      "evidence": "evidence_example"
    }
  }'

const response = await fetch('https://api.kirora.io/v1/contacts/identify', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "externalId": "user_8812",
    "email": "amaka@juniperkitchen.com",
    "firstName": "Amaka",
    "lastName": "Eze",
    "phone": "+447700900123",
    "timezone": "Europe/London",
    "country": "GB",
    "dates": {},
    "attributes": {},
    "emailConsent": true,
    "pushConsent": true,
    "consentStatement": {
      "basis": "opted_in",
      "evidence": "evidence_example"
    }
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/contacts/identify",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "externalId": "user_8812",
        "email": "amaka@juniperkitchen.com",
        "firstName": "Amaka",
        "lastName": "Eze",
        "phone": "+447700900123",
        "timezone": "Europe/London",
        "country": "GB",
        "dates": {},
        "attributes": {},
        "emailConsent": True,
        "pushConsent": True,
        "consentStatement": {
            "basis": "opted_in",
            "evidence": "evidence_example",
        },
    },
)
data = response.json()["data"]

package main

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

func main() {
	body := []byte(`{
	  "externalId": "user_8812",
	  "email": "amaka@juniperkitchen.com",
	  "firstName": "Amaka",
	  "lastName": "Eze",
	  "phone": "+447700900123",
	  "timezone": "Europe/London",
	  "country": "GB",
	  "dates": {},
	  "attributes": {},
	  "emailConsent": true,
	  "pushConsent": true,
	  "consentStatement": {
	    "basis": "opted_in",
	    "evidence": "evidence_example"
	  }
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/contacts/identify", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	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",
    "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"
    }
  },
  "meta": {
    "created": true
  }
}

Example values are generated from the schema.