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
/
v1
/
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",
"roiEnabled": false,
"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",
"roiEnabled": False,
"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',
roiEnabled: false,
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',
'roiEnabled' => false,
'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 \"roiEnabled\": false,\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 \"roiEnabled\": false,\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 \"roiEnabled\": false,\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",
"roiEnabled": true,
"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
Organization API key, sent as Authorization: Bearer boom_org_....
Path Parameters
The initiative id.
Minimum string length:
1Body
application/json
The metric label, shown in the dashboard picker.
Required string length:
1 - 255Omit to add a new metric. Pass an existing metric's rootId to replace it with a new version.
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 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 Whether this metric's dashboard shows ROI — attributed sales over what the journey's messages cost, at Boom's fixed average rates. Only meaningful when the metric sums a money value, so it is forced off for COUNT. Default false.
Required when signalType is CDP_EVENT: the event name that marks success.
The numeric event property to aggregate. Required when signalType is CDP_EVENT and aggregation is not COUNT.
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 Required when valueSource is RELATED_OBJECT: the custom-object type to read the value from.
Required when valueSource is RELATED_OBJECT: the event property holding the object's external id.
Required when signalType is EXTRACTED_VARIABLE: the extracted variable that defines success.
Required when signalType is CUSTOM_OBJECT: the custom-object type a qualifying record belongs to.
Optional equality filter on the object's attributes, e.g. {"status":"SUCCEEDED"}.
Show child attributes
Show child attributes
Required when signalType is CUSTOM_OBJECT: the attribute holding the business timestamp to measure against.
The numeric object attribute to aggregate. Required when signalType is CUSTOM_OBJECT and aggregation is not COUNT.
How the object is linked to a person. Omit or send an empty array when it is linked directly.
Show child attributes
Show child attributes
Response
Success
Stable id for this metric across versions. Pass it back to edit the metric.
Version number; every edit creates a new one.
Required range:
-9007199254740991 <= x <= 9007199254740991Available options:
ACTIVE, SUPERSEDED Available options:
CDP_EVENT, CUSTOM_OBJECT, EXTRACTED_VARIABLE Available options:
COUNT, SUM, AVERAGE, MAX Available options:
EVENT_PROPERTY, RELATED_OBJECT Show child attributes
Show child attributes
Show child attributes
Show child attributes
Hours after the first outbound message in which a signal still counts. Fixed at 48.
Required range:
-9007199254740991 <= x <= 9007199254740991ISO 8601 timestamp of this version.
Was this page helpful?
⌘I
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",
"roiEnabled": false,
"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",
"roiEnabled": False,
"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',
roiEnabled: false,
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',
'roiEnabled' => false,
'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 \"roiEnabled\": false,\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 \"roiEnabled\": false,\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 \"roiEnabled\": false,\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",
"roiEnabled": true,
"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>"
}
}