Delete contactsMenu

Delete contacts

POST/v1/contacts/delete

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

Works with integration and partner keys, not agent keys.

Safe to retry: a repeat sets the same values again. About idempotency

Deletes up to 100 contacts, each named by contactId, externalId or email, and reports an outcome per contact. For each one deleted, its events, list memberships, consent changes and journey enrollments go with it. Journey messages go with the enrollments; campaign and transactional messages are kept for campaign totals but anonymised: the address, content and provider ids are removed and nothing links them to the person. Address suppressions are kept, so a deleted address that is imported again is still not mailed. send_in_progress means a message was being handed to the provider; retry that one shortly. Requires contacts:delete; agent keys are refused.

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}$

Idempotency-Keystringoptional

Makes a retry safe: a repeat with the same key and body within 24 hours gets the first response again, with Idempotency-Replay: true. The same key with another request is 409 IDEMPOTENCY_KEY_REUSED; while the first is still running, 409 IDEMPOTENCY_KEY_IN_USE; after an unsafe first request failed or never returned, 409 IDEMPOTENCY_KEY_OUTCOME_UNKNOWN. Use a new key, such as a UUID, for each new request.

8–255 characters

Request body

contactsobject[]required

at least 1 item · at most 100 items

Any of 3 shapes

By contact id

1 child attribute

contactIdstringrequired

Kirora's id for the contact.

uuid

By external id

1 child attribute

externalIdstringrequired

Your own id for the contact, as set with identify.

1–255 characters

By email

1 child attribute

emailstringrequired: The contact's email address, matched trimmed and without case.

Returns

Returns 200 OK with a DeleteContactsResult in data. It can also return 409 Conflict, 413 Payload Too Large or 415 Unsupported Media Type; see the statuses below. Otherwise returns an error; Errors lists every code and which to retry.

200 OKOne result per contact named, in request order.
409 ConflictThe request conflicts with current state — a duplicate unique value, or a resource whose status does not allow this operation.
413 Payload Too LargeThe body is larger than this operation accepts (PAYLOAD_TOO_LARGE).
415 Unsupported Media TypeThe body is not JSON, or not the upload the operation takes (UNSUPPORTED_MEDIA_TYPE).

resultsobject[]required

2 child attributes

contactobjectrequired

The contact as named in the request.

Any of 3 shapes

By contact id

1 child attribute

contactIdstringrequired

Kirora's id for the contact.

uuid

By external id

1 child attribute

externalIdstringrequired

Your own id for the contact, as set with identify.

1–255 characters

By email

1 child attribute

emailstringrequired

The contact's email address, matched trimmed and without case.

email · up to 320 characters

outcomestringrequired

send_in_progress: a message is being handed to the provider; retry shortly.

one of deleted, not_found, send_in_progress

Headers on `200 OK`

Idempotency-Replaystringoptional

true when this is the stored response to an earlier request with the same key.

one of true

curl -X POST https://api.kirora.io/v1/contacts/delete \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "email": "[email protected]"
      },
      {
        "externalId": "customer-0000"
      }
    ]
  }'

const response = await fetch('https://api.kirora.io/v1/contacts/delete', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contacts": [
      {
        "email": "[email protected]"
      },
      {
        "externalId": "customer-0000"
      }
    ]
  }),
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/contacts/delete",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "contacts": [
            {
                "email": "[email protected]",
            },
            {
                "externalId": "customer-0000",
            },
        ],
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

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

func main() {
	body := []byte(`{
	  "contacts": [
	    {
	      "email": "[email protected]"
	    },
	    {
	      "externalId": "customer-0000"
	    }
	  ]
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/contacts/delete", 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()
	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;
using System.Text.Json;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.kirora.io/v1/contacts/delete");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));
request.Content = new StringContent(
    """
    {
      "contacts": [
        {
          "email": "[email protected]"
        },
        {
          "externalId": "customer-0000"
        }
      ]
    }
    """,
    Encoding.UTF8,
    "application/json");

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": {
    "results": [
      {
        "contact": {
          "email": "[email protected]"
        },
        "outcome": "deleted"
      },
      {
        "contact": {
          "externalId": "customer-0000"
        },
        "outcome": "not_found"
      }
    ]
  }
}

Delete contacts

Header parameters

Request body

Returns

Headers on 200 OK

Headers on `200 OK`