Contacts

Update a contact

PATCH/v1/contacts/{id}

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

Merges the supplied fields into an existing contact; omitted fields are left alone, and attributes is merged key by key rather than replaced; a key set to null is removed (JSON Merge Patch). Agent keys cannot mutate contacts or consent and are refused with 403.

Path parameters

idstringrequired: uuid

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.

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 PATCH https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b \
  -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/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b', {
  method: 'PATCH',
  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.patch(
    "https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
    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("PATCH", "https://api.kirora.io/v1/contacts/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b", 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"
    }
  }
}

Example values are generated from the schema.