Create a conversion goalMenu

Create a conversion goal

POST/v1/conversion-goals

Requires an API key with the conversion-goals:write scope. About keys and scopes

Works with integration, agent and partner keys.

A repeat after success is refused with 409 ALREADY_EXISTS: read the one the first created. About idempotency

Counts an event as a conversion when the contact was sent the campaign or journey within the attribution window before it. Narrow which events count with where (property conditions, all must hold) and occurrence (first or repeat of the contact's events of that name), as a workspace goal's event step does. Set valueProperty to sum an event property (such as total) as revenue, and currency to label it; an event whose own currency property names another currency converts without a value, since amounts are never converted, and so does one whose value is negative, not numeric, or too large. Events from the goal's creation on are matched as they are processed; the retained history before it is matched in the background from countedFrom, so the goal's results fill in shortly after it is created. A campaign or journey can count one event under several goals with different filters; a second goal with the same event and filter is refused with 409 ALREADY_EXISTS, since it would count every conversion twice. Goals count the workspace's own events, so the Free plan is refused with 403 PLAN_FEATURE_UNAVAILABLE.

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

campaignIdstringoptional

The campaign it measures.

uuid

journeyIdstringoptional

The journey it measures.

uuid

eventNamestringrequired

The event that counts as a conversion.

1–128 characters

whereobject[]optional

Property conditions the event must meet, up to 5; with several names, each of them must meet them.

at least 1 item · at most 5 items

3 child attributes

propertystringrequired

The event property key.

1–64 characters

operatorstringrequired

notEquals also matches an event without the property. equals and notEquals compare the property as text, ignoring case and accents.

one of equals, notEquals, gt, gte, lt, lte

valuestringrequired

What to compare with, as text ("pro", "true"); a number ("50") for gt, gte, lt and lte.

up to 255 characters

occurrencestringoptional

first: only the contact's first event of these names; repeat: any after it. Read from the event history, so a contact whose earlier ones predate it counts as first seen (coverageFrom on progress says where the history starts); a property the customer sends (first_order) is the stricter signal. Absent: every one.

one of first, repeat

attributionWindowDurationInputoptional

How long after a message the event still counts: 1 to 3,650 whole days, default 30 days.

2 child attributes

valueintegerrequired: min > 0
unitstringrequired: one of seconds, minutes, hours, days

valuePropertystringoptional

The event property summed as revenue, such as total.

1–64 characters

currencystringoptional

The revenue's currency, an ISO 4217 code; needs valueProperty.

pattern ^[A-Z]{3}$

Returns

Returns 201 Created with a ConversionGoal 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.

201 CreatedThe new goal.
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).

idstringrequired

uuid

campaignIdstring | nullrequired

The campaign it measures.

uuid

journeyIdstring | nullrequired

The journey it measures.

uuid

eventNamestringrequired

The event that counts as a conversion.

whereobject[] | nullrequired

Property conditions the event must meet; null counts every one.

at least 1 item · at most 5 items

3 child attributes

propertystringrequired

The event property key.

1–64 characters

operatorstringrequired

notEquals also matches an event without the property. equals and notEquals compare the property as text, ignoring case and accents.

one of equals, notEquals, gt, gte, lt, lte

valuestringrequired

What to compare with, as text ("pro", "true"); a number ("50") for gt, gte, lt and lte.

up to 255 characters

occurrencestring | nullrequired

first: only the contact's first event of this name; repeat: any after it; null: every one.

one of first, repeat

attributionWindowDurationrequired

How long after a message the event still counts, in days.

2 child attributes

valueintegerrequired: min > 0
unitstringrequired: one of seconds, minutes, hours, days

windowChangedAtstring | nullrequired

When the attribution window was last changed; null if never. A change applies to events processed after it: conversions counted before keep the window they were counted under.

date-time

valuePropertystring | nullrequired

The event property summed as revenue; null counts no value.

currencystring | nullrequired

The revenue's currency, if named.

countedFromstringrequired

The earliest events the goal can count: when it was created, the start of the event history then retained. Events from then on are matched to the sends before them, those tracked before the goal existed included; older ones are gone.

date-time

createdAtstringrequired

date-time

Headers on `201 Created`

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/conversion-goals \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "journeyId": "0192f3a4-3d5e-7a7f-8c43-6b8c9d0e1f2a",
    "eventName": "Order Completed",
    "valueProperty": "total",
    "currency": "USD"
  }'

const response = await fetch('https://api.kirora.io/v1/conversion-goals', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "journeyId": "0192f3a4-3d5e-7a7f-8c43-6b8c9d0e1f2a",
    "eventName": "Order Completed",
    "valueProperty": "total",
    "currency": "USD"
  }),
});
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/conversion-goals",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "journeyId": "0192f3a4-3d5e-7a7f-8c43-6b8c9d0e1f2a",
        "eventName": "Order Completed",
        "valueProperty": "total",
        "currency": "USD",
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

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

func main() {
	body := []byte(`{
	  "journeyId": "0192f3a4-3d5e-7a7f-8c43-6b8c9d0e1f2a",
	  "eventName": "Order Completed",
	  "valueProperty": "total",
	  "currency": "USD"
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/conversion-goals", 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/conversion-goals");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));
request.Content = new StringContent(
    """
    {
      "journeyId": "0192f3a4-3d5e-7a7f-8c43-6b8c9d0e1f2a",
      "eventName": "Order Completed",
      "valueProperty": "total",
      "currency": "USD"
    }
    """,
    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 · 201

{
  "data": {
    "id": "0192f3d0-7a1b-7c2d-8e3f-4a5b6c7d8e9f",
    "campaignId": null,
    "journeyId": "0192f3a4-3d5e-7a7f-8c43-6b8c9d0e1f2a",
    "eventName": "Order Completed",
    "where": null,
    "occurrence": null,
    "attributionWindow": {
      "value": 30,
      "unit": "days"
    },
    "windowChangedAt": null,
    "valueProperty": "total",
    "currency": "USD",
    "countedFrom": "2026-07-03T09:30:00.000Z",
    "createdAt": "2026-10-01T09:30:00.000Z"
  }
}

curl -X POST https://api.kirora.io/v1/conversion-goals \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "journeyId": "0192f3a4-3d5e-7a7f-8c43-6b8c9d0e1f2a",
    "eventName": "Order Completed",
    "where": [
      {
        "property": "total",
        "operator": "gte",
        "value": "50"
      }
    ],
    "occurrence": "first",
    "valueProperty": "total",
    "currency": "USD"
  }'

const response = await fetch('https://api.kirora.io/v1/conversion-goals', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "journeyId": "0192f3a4-3d5e-7a7f-8c43-6b8c9d0e1f2a",
    "eventName": "Order Completed",
    "where": [
      {
        "property": "total",
        "operator": "gte",
        "value": "50"
      }
    ],
    "occurrence": "first",
    "valueProperty": "total",
    "currency": "USD"
  }),
});
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/conversion-goals",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "journeyId": "0192f3a4-3d5e-7a7f-8c43-6b8c9d0e1f2a",
        "eventName": "Order Completed",
        "where": [
            {
                "property": "total",
                "operator": "gte",
                "value": "50",
            },
        ],
        "occurrence": "first",
        "valueProperty": "total",
        "currency": "USD",
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

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

func main() {
	body := []byte(`{
	  "journeyId": "0192f3a4-3d5e-7a7f-8c43-6b8c9d0e1f2a",
	  "eventName": "Order Completed",
	  "where": [
	    {
	      "property": "total",
	      "operator": "gte",
	      "value": "50"
	    }
	  ],
	  "occurrence": "first",
	  "valueProperty": "total",
	  "currency": "USD"
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/conversion-goals", 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/conversion-goals");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));
request.Content = new StringContent(
    """
    {
      "journeyId": "0192f3a4-3d5e-7a7f-8c43-6b8c9d0e1f2a",
      "eventName": "Order Completed",
      "where": [
        {
          "property": "total",
          "operator": "gte",
          "value": "50"
        }
      ],
      "occurrence": "first",
      "valueProperty": "total",
      "currency": "USD"
    }
    """,
    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 · 201

{
  "data": {
    "id": "0192f3d0-7a1b-7c2d-8e3f-4a5b6c7d8ea0",
    "campaignId": null,
    "journeyId": "0192f3a4-3d5e-7a7f-8c43-6b8c9d0e1f2a",
    "eventName": "Order Completed",
    "where": [
      {
        "property": "total",
        "operator": "gte",
        "value": "50"
      }
    ],
    "occurrence": "first",
    "attributionWindow": {
      "value": 30,
      "unit": "days"
    },
    "windowChangedAt": null,
    "valueProperty": "total",
    "currency": "USD",
    "countedFrom": "2026-07-03T09:30:00.000Z",
    "createdAt": "2026-10-01T09:30:00.000Z"
  }
}

Create a conversion goal

Header parameters

Request body

Returns

Headers on 201 Created

Headers on `201 Created`