Initiatives

Add or replace a success metric

Configure what counts as success for an initiative: a customer-data event, a record on a custom object, or a value extracted from the conversation, measured within 48 hours of the first message. Omit rootId to add a metric; pass an existing metric’s rootId to replace it with a new version. This is not a patch — send the metric’s complete configuration, because omitted fields are cleared. Successes are recalculated on every read, so replacing a metric also changes what the dashboard reports for past conversations. Use success_metrics_catalog to find the event, object type or variable to point at.

POST

api

initiatives

{id}

success-metrics

Add or replace a success metric

curl --request POST \
  --url https://www.useboom.ai/api/v1/initiatives/{id}/success-metrics \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "rootId": "<string>",
  "signalType": "CDP_EVENT",
  "aggregation": "COUNT",
  "eventName": "<string>",
  "valueProperty": "<string>",
  "valueSource": "EVENT_PROPERTY",
  "valueObjectTypeId": "<string>",
  "valueRefProperty": "<string>",
  "variableId": "<string>",
  "objectTypeId": "<string>",
  "objectAttributeFilter": {},
  "objectTimeAttribute": "<string>",
  "objectValueAttribute": "<string>",
  "linkagePath": [
    {
      "role": "<string>",
      "objectTypeId": "<string>"
    }
  ]
}
'

import requests

url = "https://www.useboom.ai/api/v1/initiatives/{id}/success-metrics"

payload = {
    "name": "<string>",
    "rootId": "<string>",
    "signalType": "CDP_EVENT",
    "aggregation": "COUNT",
    "eventName": "<string>",
    "valueProperty": "<string>",
    "valueSource": "EVENT_PROPERTY",
    "valueObjectTypeId": "<string>",
    "valueRefProperty": "<string>",
    "variableId": "<string>",
    "objectTypeId": "<string>",
    "objectAttributeFilter": {},
    "objectTimeAttribute": "<string>",
    "objectValueAttribute": "<string>",
    "linkagePath": [
        {
            "role": "<string>",
            "objectTypeId": "<string>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    rootId: '<string>',
    signalType: 'CDP_EVENT',
    aggregation: 'COUNT',
    eventName: '<string>',
    valueProperty: '<string>',
    valueSource: 'EVENT_PROPERTY',
    valueObjectTypeId: '<string>',
    valueRefProperty: '<string>',
    variableId: '<string>',
    objectTypeId: '<string>',
    objectAttributeFilter: {},
    objectTimeAttribute: '<string>',
    objectValueAttribute: '<string>',
    linkagePath: [{role: '<string>', objectTypeId: '<string>'}]
  })
};

fetch('https://www.useboom.ai/api/v1/initiatives/{id}/success-metrics', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.useboom.ai/api/v1/initiatives/{id}/success-metrics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'rootId' => '<string>',
    'signalType' => 'CDP_EVENT',
    'aggregation' => 'COUNT',
    'eventName' => '<string>',
    'valueProperty' => '<string>',
    'valueSource' => 'EVENT_PROPERTY',
    'valueObjectTypeId' => '<string>',
    'valueRefProperty' => '<string>',
    'variableId' => '<string>',
    'objectTypeId' => '<string>',
    'objectAttributeFilter' => [
        
    ],
    'objectTimeAttribute' => '<string>',
    'objectValueAttribute' => '<string>',
    'linkagePath' => [
        [
                'role' => '<string>',
                'objectTypeId' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://www.useboom.ai/api/v1/initiatives/{id}/success-metrics"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"rootId\": \"<string>\",\n  \"signalType\": \"CDP_EVENT\",\n  \"aggregation\": \"COUNT\",\n  \"eventName\": \"<string>\",\n  \"valueProperty\": \"<string>\",\n  \"valueSource\": \"EVENT_PROPERTY\",\n  \"valueObjectTypeId\": \"<string>\",\n  \"valueRefProperty\": \"<string>\",\n  \"variableId\": \"<string>\",\n  \"objectTypeId\": \"<string>\",\n  \"objectAttributeFilter\": {},\n  \"objectTimeAttribute\": \"<string>\",\n  \"objectValueAttribute\": \"<string>\",\n  \"linkagePath\": [\n    {\n      \"role\": \"<string>\",\n      \"objectTypeId\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.useboom.ai/api/v1/initiatives/{id}/success-metrics")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"rootId\": \"<string>\",\n  \"signalType\": \"CDP_EVENT\",\n  \"aggregation\": \"COUNT\",\n  \"eventName\": \"<string>\",\n  \"valueProperty\": \"<string>\",\n  \"valueSource\": \"EVENT_PROPERTY\",\n  \"valueObjectTypeId\": \"<string>\",\n  \"valueRefProperty\": \"<string>\",\n  \"variableId\": \"<string>\",\n  \"objectTypeId\": \"<string>\",\n  \"objectAttributeFilter\": {},\n  \"objectTimeAttribute\": \"<string>\",\n  \"objectValueAttribute\": \"<string>\",\n  \"linkagePath\": [\n    {\n      \"role\": \"<string>\",\n      \"objectTypeId\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.useboom.ai/api/v1/initiatives/{id}/success-metrics")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"rootId\": \"<string>\",\n  \"signalType\": \"CDP_EVENT\",\n  \"aggregation\": \"COUNT\",\n  \"eventName\": \"<string>\",\n  \"valueProperty\": \"<string>\",\n  \"valueSource\": \"EVENT_PROPERTY\",\n  \"valueObjectTypeId\": \"<string>\",\n  \"valueRefProperty\": \"<string>\",\n  \"variableId\": \"<string>\",\n  \"objectTypeId\": \"<string>\",\n  \"objectAttributeFilter\": {},\n  \"objectTimeAttribute\": \"<string>\",\n  \"objectValueAttribute\": \"<string>\",\n  \"linkagePath\": [\n    {\n      \"role\": \"<string>\",\n      \"objectTypeId\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "rootId": "<string>",
  "version": 0,
  "status": "ACTIVE",
  "name": "<string>",
  "signalType": "CDP_EVENT",
  "aggregation": "COUNT",
  "eventName": "<string>",
  "valueProperty": "<string>",
  "valueSource": "EVENT_PROPERTY",
  "valueObjectTypeId": "<string>",
  "valueRefProperty": "<string>",
  "variableId": "<string>",
  "objectTypeId": "<string>",
  "objectAttributeFilter": {},
  "objectTimeAttribute": "<string>",
  "objectValueAttribute": "<string>",
  "linkagePath": [
    {
      "kind": "PERSON_OBJECT",
      "role": "<string>",
      "objectTypeId": "<string>",
      "direction": "PARENT_TO_CHILD"
    }
  ],
  "windowHours": 0,
  "createdAt": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Organization API key, sent as Authorization: Bearer boom_org_....

Path Parameters

string

required

The initiative id.

Minimum string length: 1

Body

application/json

name

string

required

The metric label, shown in the dashboard picker.

Required string length: 1 - 255

rootId

string

Omit to add a new metric. Pass an existing metric's rootId to replace it with a new version.

signalType

enum<string>

default:CDP_EVENT

What counts as success: a customer-data event, a record on a custom object, or a value extracted from the conversation. Default CDP_EVENT.

Available options:

CDP_EVENT,

CUSTOM_OBJECT,

EXTRACTED_VARIABLE

aggregation

enum<string>

default:COUNT

How matched values roll up. COUNT needs no value field; SUM, AVERAGE and MAX each require one. Default COUNT.

Available options:

COUNT,

SUM,

AVERAGE,

MAX

eventName

string | null

Required when signalType is CDP_EVENT: the event name that marks success.

valueProperty

string | null

The numeric event property to aggregate. Required when signalType is CDP_EVENT and aggregation is not COUNT.

valueSource

enum<string>

default:EVENT_PROPERTY

Whether the aggregated value lives on the event itself or on a custom object the event points at. Default EVENT_PROPERTY.

Available options:

EVENT_PROPERTY,

RELATED_OBJECT

valueObjectTypeId

string | null

Required when valueSource is RELATED_OBJECT: the custom-object type to read the value from.

valueRefProperty

string | null

Required when valueSource is RELATED_OBJECT: the event property holding the object's external id.

variableId

string | null

Required when signalType is EXTRACTED_VARIABLE: the extracted variable that defines success.

objectTypeId

string | null

Required when signalType is CUSTOM_OBJECT: the custom-object type a qualifying record belongs to.

objectAttributeFilter

object | null

Optional equality filter on the object's attributes, e.g. {"status":"SUCCEEDED"}.

Show child attributes

objectTimeAttribute

string | null

Required when signalType is CUSTOM_OBJECT: the attribute holding the business timestamp to measure against.

objectValueAttribute

string | null

The numeric object attribute to aggregate. Required when signalType is CUSTOM_OBJECT and aggregation is not COUNT.

linkagePath

object[] | null

How the object is linked to a person. Omit or send an empty array when it is linked directly.

Show child attributes

Response

Success

rootId

string

required

Stable id for this metric across versions. Pass it back to edit the metric.

version

integer

required

Version number; every edit creates a new one.

Required range: -9007199254740991 <= x <= 9007199254740991

status

enum<string>

required

Available options:

ACTIVE,

SUPERSEDED

name

string

required

signalType

enum<string>

required

Available options:

CDP_EVENT,

CUSTOM_OBJECT,

EXTRACTED_VARIABLE

aggregation

enum<string>

required

Available options:

COUNT,

SUM,

AVERAGE,

MAX

eventName

string | null

required

valueProperty

string | null

required

valueSource

enum<string>

required

Available options:

EVENT_PROPERTY,

RELATED_OBJECT

valueObjectTypeId

string | null

required

valueRefProperty

string | null

required

variableId

string | null

required

objectTypeId

string | null

required

objectAttributeFilter

object | null

required

Show child attributes

objectTimeAttribute

string | null

required

objectValueAttribute

string | null

required

linkagePath

object[] | null

required

Show child attributes

windowHours

integer

required

Hours after the first outbound message in which a signal still counts. Fixed at 48.

Required range: -9007199254740991 <= x <= 9007199254740991

createdAt

string

required

ISO 8601 timestamp of this version.

Add or replace a success metric

curl --request POST \
  --url https://www.useboom.ai/api/v1/initiatives/{id}/success-metrics \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "rootId": "<string>",
  "signalType": "CDP_EVENT",
  "aggregation": "COUNT",
  "eventName": "<string>",
  "valueProperty": "<string>",
  "valueSource": "EVENT_PROPERTY",
  "valueObjectTypeId": "<string>",
  "valueRefProperty": "<string>",
  "variableId": "<string>",
  "objectTypeId": "<string>",
  "objectAttributeFilter": {},
  "objectTimeAttribute": "<string>",
  "objectValueAttribute": "<string>",
  "linkagePath": [
    {
      "role": "<string>",
      "objectTypeId": "<string>"
    }
  ]
}
'

import requests

url = "https://www.useboom.ai/api/v1/initiatives/{id}/success-metrics"

payload = {
    "name": "<string>",
    "rootId": "<string>",
    "signalType": "CDP_EVENT",
    "aggregation": "COUNT",
    "eventName": "<string>",
    "valueProperty": "<string>",
    "valueSource": "EVENT_PROPERTY",
    "valueObjectTypeId": "<string>",
    "valueRefProperty": "<string>",
    "variableId": "<string>",
    "objectTypeId": "<string>",
    "objectAttributeFilter": {},
    "objectTimeAttribute": "<string>",
    "objectValueAttribute": "<string>",
    "linkagePath": [
        {
            "role": "<string>",
            "objectTypeId": "<string>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    rootId: '<string>',
    signalType: 'CDP_EVENT',
    aggregation: 'COUNT',
    eventName: '<string>',
    valueProperty: '<string>',
    valueSource: 'EVENT_PROPERTY',
    valueObjectTypeId: '<string>',
    valueRefProperty: '<string>',
    variableId: '<string>',
    objectTypeId: '<string>',
    objectAttributeFilter: {},
    objectTimeAttribute: '<string>',
    objectValueAttribute: '<string>',
    linkagePath: [{role: '<string>', objectTypeId: '<string>'}]
  })
};

fetch('https://www.useboom.ai/api/v1/initiatives/{id}/success-metrics', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.useboom.ai/api/v1/initiatives/{id}/success-metrics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'rootId' => '<string>',
    'signalType' => 'CDP_EVENT',
    'aggregation' => 'COUNT',
    'eventName' => '<string>',
    'valueProperty' => '<string>',
    'valueSource' => 'EVENT_PROPERTY',
    'valueObjectTypeId' => '<string>',
    'valueRefProperty' => '<string>',
    'variableId' => '<string>',
    'objectTypeId' => '<string>',
    'objectAttributeFilter' => [
        
    ],
    'objectTimeAttribute' => '<string>',
    'objectValueAttribute' => '<string>',
    'linkagePath' => [
        [
                'role' => '<string>',
                'objectTypeId' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://www.useboom.ai/api/v1/initiatives/{id}/success-metrics"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"rootId\": \"<string>\",\n  \"signalType\": \"CDP_EVENT\",\n  \"aggregation\": \"COUNT\",\n  \"eventName\": \"<string>\",\n  \"valueProperty\": \"<string>\",\n  \"valueSource\": \"EVENT_PROPERTY\",\n  \"valueObjectTypeId\": \"<string>\",\n  \"valueRefProperty\": \"<string>\",\n  \"variableId\": \"<string>\",\n  \"objectTypeId\": \"<string>\",\n  \"objectAttributeFilter\": {},\n  \"objectTimeAttribute\": \"<string>\",\n  \"objectValueAttribute\": \"<string>\",\n  \"linkagePath\": [\n    {\n      \"role\": \"<string>\",\n      \"objectTypeId\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.useboom.ai/api/v1/initiatives/{id}/success-metrics")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"rootId\": \"<string>\",\n  \"signalType\": \"CDP_EVENT\",\n  \"aggregation\": \"COUNT\",\n  \"eventName\": \"<string>\",\n  \"valueProperty\": \"<string>\",\n  \"valueSource\": \"EVENT_PROPERTY\",\n  \"valueObjectTypeId\": \"<string>\",\n  \"valueRefProperty\": \"<string>\",\n  \"variableId\": \"<string>\",\n  \"objectTypeId\": \"<string>\",\n  \"objectAttributeFilter\": {},\n  \"objectTimeAttribute\": \"<string>\",\n  \"objectValueAttribute\": \"<string>\",\n  \"linkagePath\": [\n    {\n      \"role\": \"<string>\",\n      \"objectTypeId\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.useboom.ai/api/v1/initiatives/{id}/success-metrics")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"rootId\": \"<string>\",\n  \"signalType\": \"CDP_EVENT\",\n  \"aggregation\": \"COUNT\",\n  \"eventName\": \"<string>\",\n  \"valueProperty\": \"<string>\",\n  \"valueSource\": \"EVENT_PROPERTY\",\n  \"valueObjectTypeId\": \"<string>\",\n  \"valueRefProperty\": \"<string>\",\n  \"variableId\": \"<string>\",\n  \"objectTypeId\": \"<string>\",\n  \"objectAttributeFilter\": {},\n  \"objectTimeAttribute\": \"<string>\",\n  \"objectValueAttribute\": \"<string>\",\n  \"linkagePath\": [\n    {\n      \"role\": \"<string>\",\n      \"objectTypeId\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "rootId": "<string>",
  "version": 0,
  "status": "ACTIVE",
  "name": "<string>",
  "signalType": "CDP_EVENT",
  "aggregation": "COUNT",
  "eventName": "<string>",
  "valueProperty": "<string>",
  "valueSource": "EVENT_PROPERTY",
  "valueObjectTypeId": "<string>",
  "valueRefProperty": "<string>",
  "variableId": "<string>",
  "objectTypeId": "<string>",
  "objectAttributeFilter": {},
  "objectTimeAttribute": "<string>",
  "objectValueAttribute": "<string>",
  "linkagePath": [
    {
      "kind": "PERSON_OBJECT",
      "role": "<string>",
      "objectTypeId": "<string>",
      "direction": "PARENT_TO_CHILD"
    }
  ],
  "windowHours": 0,
  "createdAt": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Overview

Initiatives

Journeys

Segments

WhatsApp

Add or replace a success metric

Authorizations

Path Parameters

Body

Response