Quickstart

This walkthrough is for developers, and it runs in a terminal. If you are here to understand what Boom does rather than to integrate it, read start here instead.

Set your key and base URL:

export BOOM_KEY="boom_org_YOUR_KEY_HERE"
export BASE="https://www.useboom.ai/api/v1/cdp"

Upsert a person

curl -X POST "$BASE/people" \
  -H "Authorization: Bearer $BOOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalId":"user_123","email":"a@b.com","phoneNumber":"+523333333333","attributes":{"plan":"pro","mrr":49}}'

Returns { "externalId": "user_123", "created": true }.Send a reachable channel, email and/or phoneNumber (E.164 format), as top-level fields. They populate the person’s typed contact columns, which is what lets event-triggered journeys reach them. Anything else goes in attributes.

Make sure the object type exists

List your types, and create one if you need to. Objects can only be upserted against a type that already exists.

curl "$BASE/custom-objects/types" -H "Authorization: Bearer $BOOM_KEY"

# create one if it's missing:
curl -X POST "$BASE/custom-objects/types" \
  -H "Authorization: Bearer $BOOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"order","displayName":"Order"}'

Upsert a custom object

curl -X POST "$BASE/custom-objects" \
  -H "Authorization: Bearer $BOOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"order","externalId":"ord_998","displayName":"Order #998","attributes":{"total":120.5,"status":"paid"}}'

curl -X POST "$BASE/relationship-types" \
  -H "Authorization: Bearer $BOOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"person_to_co","role":"placed","customObjectType":"order","cardinality":"ONE_TO_MANY"}'

Returns the type with a relationshipTypeId (e.g. rt_2hk9). Keep it for the next step. See relationship types for the full field and cardinality catalog.

Link them

curl -X POST "$BASE/relationships" \
  -H "Authorization: Bearer $BOOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"personExternalId":"user_123","customObjectExternalId":"ord_998","relationshipTypeId":"rt_2hk9"}'

Returns { "created": true, "relationshipTypeId": "rt_2hk9" }. The relationshipTypeId is required: it fixes the role and object type, so you don’t repeat them here.

Record an event

Log a behavioral event for the person you created:

curl -X POST "$BASE/events" \
  -H "Authorization: Bearer $BOOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"payment_made","externalId":"evt_1","personExternalId":"user_123","properties":{"amount":120.5}}'

Read it back with GET /events/evt_1, or list a person’s events with GET /events?personExternalId=user_123. See Events for the full model.

Run any upsert twice: the first returns created: true, the second created: false. That’s the upsert working as intended.

Already have this data in a PostgreSQL or MySQL database? Skip the API and connect your database. Boom syncs people, objects, and relationships from a read-only query on a schedule.

Authentication

Create an API key and authenticate your requests.

Events

Record behavioral events and read them back.

Relationship types

Connect your database

Sync the same data from your database instead of pushing it.

Overview

Initiatives

Journeys

Segments

WhatsApp

Authentication

Events

Relationship types

Connect your database

​Related

Authentication

Events

Relationship types

Connect your database

Related