> ## 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.

# List relationships

> List relationship edges of one kind, anchored on a person or custom object, newest first.



## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/cdp/relationships
openapi: 3.1.0
info:
  title: Boom API
  version: 1.0.0
  description: >-
    Boom's public REST API — one uniform surface over every platform capability.
    CDP: upsert people and custom objects, define object and relationship types,
    link and unlink relationships, and record behavioral events — one record per
    request or up to 1000 per request via the `/batch` endpoints. Segments: read
    (list, read, membership) and full authoring — discover the filterable
    catalog, validate a filter, create and update segments, preview match
    counts, and trigger evaluation. Initiatives: create and configure outreach
    initiatives, link WhatsApp templates, drive the lifecycle (launch, cancel,
    archive), and read collected-data summaries. Participants: enroll people
    into an active initiative, track their status, read conversation
    transcripts, and stop outreach. Journeys: read-only access to always-on
    message flows and their metrics. WhatsApp templates: list your WhatsApp
    numbers and list, read, and create message templates. The same capabilities
    are exposed as MCP tools with identical schemas.
servers:
  - url: https://www.useboom.ai
    description: Production
  - url: https://dev.useboom.ai
    description: Development (sandbox — use a development organization API key)
security:
  - bearerAuth: []
paths:
  /api/v1/cdp/relationships:
    get:
      tags:
        - CDP Relationships
      summary: List relationships
      description: >-
        List relationship edges of one kind, anchored on a person or custom
        object, newest first.
      operationId: cdp_relationships_list
      parameters:
        - name: kind
          in: query
          required: true
          schema:
            $schema: https://json-schema.org/draft/2020-12/schema
            type: string
            enum:
              - person_to_co
              - co_to_co
            description: Which edge set to list.
        - name: personExternalId
          in: query
          required: false
          schema:
            $schema: https://json-schema.org/draft/2020-12/schema
            description: 'Anchor: person externalId (kind ''person_to_co'').'
            type: string
            minLength: 1
        - name: customObjectType
          in: query
          required: false
          schema:
            $schema: https://json-schema.org/draft/2020-12/schema
            description: >-
              Anchor: custom object type name. Required with
              customObjectExternalId.
            type: string
            minLength: 1
        - name: customObjectExternalId
          in: query
          required: false
          schema:
            $schema: https://json-schema.org/draft/2020-12/schema
            description: 'Anchor: custom object externalId (scoped by customObjectType).'
            type: string
            minLength: 1
        - name: direction
          in: query
          required: false
          schema:
            $schema: https://json-schema.org/draft/2020-12/schema
            description: >-
              For kind 'co_to_co': list the anchor's children (default) or
              parents.
            type: string
            enum:
              - children
              - parents
        - name: include_removed
          in: query
          required: false
          schema:
            $schema: https://json-schema.org/draft/2020-12/schema
            description: Include soft-deleted (unlinked) edges. Defaults to false.
            type: boolean
        - name: relationshipTypeId
          in: query
          required: false
          schema:
            $schema: https://json-schema.org/draft/2020-12/schema
            description: Filter by relationship type id.
            type: string
            minLength: 1
        - name: role
          in: query
          required: false
          schema:
            $schema: https://json-schema.org/draft/2020-12/schema
            description: Filter by edge role.
            type: string
            minLength: 1
        - name: limit
          in: query
          required: false
          schema:
            $schema: https://json-schema.org/draft/2020-12/schema
            description: Max items to return, 1-1000 (default 100).
            type: integer
            minimum: 1
            maximum: 1000
        - name: cursor
          in: query
          required: false
          schema:
            $schema: https://json-schema.org/draft/2020-12/schema
            description: >-
              Opaque pagination token from a previous response's `next_cursor`.
              Omit for the first page.
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  data:
                    type: array
                    items:
                      anyOf:
                        - type: object
                          properties:
                            kind:
                              type: string
                              const: person_to_co
                            personExternalId:
                              type: string
                            customObjectType:
                              type: string
                            customObjectExternalId:
                              type: string
                            relationshipTypeId:
                              anyOf:
                                - type: string
                                - type: 'null'
                            role:
                              anyOf:
                                - type: string
                                - type: 'null'
                            attributes:
                              type: object
                              propertyNames:
                                type: string
                              additionalProperties: {}
                            createdAt:
                              type: string
                              description: ISO 8601 timestamp.
                            updatedAt:
                              type: string
                              description: ISO 8601 timestamp.
                          required:
                            - kind
                            - personExternalId
                            - customObjectType
                            - customObjectExternalId
                            - relationshipTypeId
                            - role
                            - attributes
                            - createdAt
                            - updatedAt
                          additionalProperties: false
                        - type: object
                          properties:
                            kind:
                              type: string
                              const: co_to_co
                            parentCustomObjectType:
                              type: string
                            parentExternalId:
                              type: string
                            childCustomObjectType:
                              type: string
                            childExternalId:
                              type: string
                            relationshipTypeId:
                              anyOf:
                                - type: string
                                - type: 'null'
                            role:
                              anyOf:
                                - type: string
                                - type: 'null'
                            attributes:
                              type: object
                              propertyNames:
                                type: string
                              additionalProperties: {}
                            createdAt:
                              type: string
                              description: ISO 8601 timestamp.
                            updatedAt:
                              type: string
                              description: ISO 8601 timestamp.
                          required:
                            - kind
                            - parentCustomObjectType
                            - parentExternalId
                            - childCustomObjectType
                            - childExternalId
                            - relationshipTypeId
                            - role
                            - attributes
                            - createdAt
                            - updatedAt
                          additionalProperties: false
                  next_cursor:
                    anyOf:
                      - type: string
                      - type: 'null'
                required:
                  - data
                  - next_cursor
                additionalProperties: false
        '400':
          description: Validation failed or the request cannot proceed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - error
        '401':
          description: Missing, malformed, or revoked API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - error
        '404':
          description: The resource does not exist in this organization.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - error
        '409':
          description: >-
            Conflicts with the current state (duplicates, wrong lifecycle
            state).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - error
        '422':
          description: The request is well-formed but semantically invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - error
        '429':
          description: Rate limit exceeded — retry after `Retry-After`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - error
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - error
        '503':
          description: Transient error — retry with a narrower request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: Stable machine-readable error code (snake_case).
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - error
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Organization API key, sent as `Authorization: Bearer boom_org_...`.'

````