Delete a listMenu

Delete a list

DELETE/v1/lists/{id}

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

Works with integration, agent and partner keys.

A repeat after success returns 404 or 409: treat that as done. About idempotency

Deletes the list and its membership records. The contacts themselves are not deleted. Refused with one 409 IN_USE naming everything that blocks it, in the shape of getListUsage: campaigns not yet sent or cancelled (A/B tests included) whose audience, rules or exclusions name it, or whose content has a block shown only to, or hidden from, its members (details.campaigns), published forms not archived that add submitters to it or name it in a field (details.forms): without the list a form refuses every submission. Also goals not retired (details.goals), active or paused journeys (details.journeys), segments whose rules name it (details.segments), and templates (the draft or the published version) and shared blocks with such a block (details.templates, details.sharedBlocks): a "not in this list" rule must not outlive the list. Change or end those first. A sent or cancelled campaign does not block it: the campaign keeps its recipients and messages, the list leaves its listIds (null once none is left) and audienceName keeps the names of the lists it went to.

Path parameters

idstringrequired

The list's id.

uuid

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 204 No Content with an empty body. It can also return 409 Conflict; see the statuses below. Otherwise returns an error; Errors lists every code and which to retry.

204 No ContentThe list was deleted.
409 ConflictThe request conflicts with current state — a duplicate unique value, or a resource whose status does not allow this operation.

curl -X DELETE https://api.kirora.io/v1/lists/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/lists/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);

import os

import requests

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

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("DELETE", "https://api.kirora.io/v1/lists/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b", 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))
	}
}

using System.Net.Http.Headers;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Delete, "https://api.kirora.io/v1/lists/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b");
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()}");