> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useboom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create a person, an object type, an object, a relationship type, and a link.

<Note>
  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](/start-here) instead.
</Note>

Set your key and base URL:

```bash theme={null}
export BOOM_KEY="boom_org_YOUR_KEY_HERE"
export BASE="https://www.useboom.ai/api/v1/cdp"
```

<Steps>
  <Step title="Upsert a person">
    ```bash theme={null}
    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`.
  </Step>

  <Step title="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.

    ```bash theme={null}
    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"}'
    ```
  </Step>

  <Step title="Upsert a custom object">
    ```bash theme={null}
    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"}}'
    ```
  </Step>

  <Step title="Register a relationship type">
    ```bash theme={null}
    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](/relationship-types) for
    the full field and cardinality catalog.
  </Step>

  <Step title="Link them">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Record an event">
    Log a behavioral event for the person you created:

    ```bash theme={null}
    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](/events) for the
    full model.
  </Step>
</Steps>

<Tip>
  Run any upsert twice: the first returns `created: true`, the second
  `created: false`. That's the upsert working as intended.
</Tip>

<Note>
  Already have this data in a PostgreSQL or MySQL database? Skip the API and
  [connect your database](/connect-your-database). Boom syncs people, objects,
  and relationships from a read-only query on a schedule.
</Note>

## Related

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Create an API key and authenticate your requests.
  </Card>

  <Card title="Events" icon="bolt" href="/events">
    Record behavioral events and read them back.
  </Card>

  <Card title="Relationship types" icon="shapes" href="/relationship-types">
    Register the link shapes you need before creating relationships.
  </Card>

  <Card title="Connect your database" icon="database" href="/connect-your-database">
    Sync the same data from your database instead of pushing it.
  </Card>
</CardGroup>