openapi: 3.0.1
info:
  title: cdp-api
  description: >-
    Welcome to the API documentation for Milwaukee Tool's Customer Data Platform
    (CDP). This comprehensive guide is designed to help developers, partners,
    and stakeholders understand how to interact with the CDP programmatically.
    By leveraging our API, you can seamlessly integrate and access the wealth of
    customer data stored in our platform, enabling you to build custom
    applications, automate processes, and extract valuable insights.  <br/>
    **NOTE:** In places where the documentation states either an API key **OR**
    access token is required, both should be included. The documentation
    framework being used does not support specifying multiple authorization
    types for a single resource. Please reach out to
    dan.mcmanus@milwaukeetool.com to obtain Authentication credentials.
  version: v1
servers:
  - url: https://cdp-api-test.milwaukeetool.com
    description: Test API Environment
  - url: https://cdp-api.milwaukeetool.com
    description: Production API Environment
paths:
  /v1/address/{id}:
    get:
      operationId: get_address_by_id_api
      security:
        - access_token: []
        - api_key: []
      tags:
        - /v1/address
      summary: Get Address By Id
      description: Supports querying for an address by an existing address id.
      parameters:
        - in: path
          required: true
          name: id
          schema:
            type: string
            format: uuid
          description: A unique identifier of the address you wish to retrieve
          example: >-
            https://cdp-api-test.milwaukeetool.com/v1/address/00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: 200 Success Response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAddressByIdResponse'
              example:
                data:
                  id: 00000000-0000-0000-0000-000000000000
                  address1: 123 Fake Street
                  address2: Apt 456
                  city: Faketown
                  state: WI
                  country: US
                  postalCode: '12345'
                  alias: Home
                  default: true
                  addressType: residential
                  status: active
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                BadRequest:
                  value:
                    error:
                      code: ERR0003
                      message: Invalid address id. Must be a valid UUID.
                      context: '12345'
                      retryable: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
              examples:
                Unauthorized:
                  value:
                    message: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Address not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                MissingRequiredQueryParameter:
                  value:
                    error:
                      code: ERR0001
                      message: No address found
                      retryable: false
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                InternalServerError:
                  value:
                    error:
                      code: ERR0002
                      message: An unknown error occurred while processing the event
                      context: An unknown error occurred while processing the event
                      retryable: true
    post:
      operationId: create_address_api
      security:
        - access_token: []
        - api_key: []
      tags:
        - /v1/address
      summary: Create a new address
      description: This endpoint creates a new address with the provided details.
      requestBody:
        description: Details of the new address to be created.
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAddressRequest'
            example:
              address1: 123 Fake Street
              address2: Apt 456
              city: Faketown
              state: WI
              postalCode: '12345'
              country: US
              alias: Home
              default: true
              addressType: residential
      responses:
        '201':
          description: Address created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAddressResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                BadRequest:
                  value:
                    error:
                      code: ERR0003
                      message: Missing required field
                      context: '''address1'' is required'
                      retryable: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
              examples:
                Unauthorized:
                  value:
                    message: Unauthorized
        '403':
          description: Forbidden
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                DuplicateAddress:
                  value:
                    error:
                      code: ERR0007
                      message: Address already exists.
                      retryable: false
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                InternalServerError:
                  value:
                    error:
                      code: ERR0002
                      message: An unknown error occurred while processing the request
                      context: An unknown error occurred while processing the request
                      retryable: true
  /v1/service/address:
    post:
      operationId: create_service_address_api
      security:
        - access_token: []
        - api_key: []
      tags:
        - /v1/service/address
      summary: Create a new service address
      description: >-
        This endpoint creates a new service address moment with the provided
        details.
      requestBody:
        description: Details of the new service address to be created.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServiceAddressRequest'
            example:
              addressId: 00000000-0000-0000-0000-000000000000
              userId: 00000000-0000-0000-0000-000000000001
              address1: 123 Service Street
              address2: Suite 100
              city: Faketown
              state: CA
              postalCode: '90210'
              country: US
              alias: Service Location
      responses:
        '201':
          description: Service Address created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateServiceAddressResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                BadRequest:
                  value:
                    error:
                      code: ERR0003
                      message: Missing required field
                      context: '''addressId'' is required'
                      retryable: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
              examples:
                Unauthorized:
                  value:
                    message: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                InternalServerError:
                  value:
                    error:
                      code: ERR0002
                      message: An unknown error occurred while processing the request
                      context: An unknown error occurred while processing the request
                      retryable: true
    get:
      operationId: get_service_address_by_id_api
      security:
        - access_token: []
        - api_key: []
      tags:
        - /v1/service/address
      summary: Get Service Address By Id
      description: Retrieve a specific service address moment by its service address Id.
      parameters:
        - in: query
          required: true
          name: id
          schema:
            type: string
          description: The ID of the service address to retrieve.
      responses:
        '200':
          description: Address retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetServiceAddressByIdResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                MissingRequiredQueryParameter:
                  value:
                    error:
                      code: ERR0006
                      message: No id parameter was provided or it is invalid
                      retryable: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
              examples:
                Unauthorized:
                  value:
                    message: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                AddressNotFound:
                  value:
                    error:
                      code: ERR0001
                      message: No address found
                      retryable: false
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                InternalServerError:
                  value:
                    error:
                      code: ERR0002
                      message: An unknown error occurred while processing the request
                      context: An unknown error occurred while processing the request
                      retryable: true
  /v1/user:
    get:
      operationId: get_user_api
      security:
        - access_token: []
        - api_key: []
      tags:
        - /v1/user
      summary: Get User Profile
      description: Supports querying for an end user by any id.
      parameters:
        - in: query
          required: false
          name: id
          schema:
            type: string
          description: >-
            A unique identifier of the user profile you wish to retrieve (e.g.
            email, identity vertex id, auth0 account id, etc.)
          example: >-
            https://cdp-api-test.milwaukeetool.com/v1/user?id=john.doe@example.com
      responses:
        '200':
          description: 200 Success Response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUserProfileResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                MissingRequiredQueryParameter:
                  value:
                    error:
                      code: ERR0006
                      message: No id was provided
                      retryable: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
              examples:
                Unauthorized:
                  value:
                    message: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                MissingRequiredQueryParameter:
                  value:
                    error:
                      code: ERR0006
                      message: No user found
                      retryable: false
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                InternalServerError:
                  value:
                    error:
                      code: ERR0002
                      message: An unknown error occurred while processing the event
                      context: An unknown error occurred while processing the event
                      retryable: true
    post:
      operationId: create_user_api
      security:
        - access_token: []
        - api_key: []
      tags:
        - /v1/user
      summary: Create a new user
      description: >-
        This endpoint creates a new user with the provided details. Calling this
        endpoint should be followed by sending an identify event to Rudderstack
        with the 'userId' field set to the newly created user's identityId.
      requestBody:
        description: Details of the new user to be created.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                emailAddress:
                  type: string
                  format: email
                firstName:
                  type: string
                lastName:
                  type: string
                phoneNumber:
                  type: string
                address1:
                  type: string
                address2:
                  type: string
                city:
                  type: string
                state:
                  type: string
                postalCode:
                  type: string
                country:
                  $ref: '#/components/schemas/CountryCode'
                jobTitle:
                  type: string
                languagePreference:
                  type: string
                trade:
                  type: string
                tradeSector:
                  type: string
                secondaryTradeSectors:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUserResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                MissingRequiredQueryParameter:
                  value:
                    error:
                      code: ERR0003
                      message: Invalid email address
                      context: user@test
                      retryable: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
              examples:
                Unauthorized:
                  value:
                    message: Unauthorized
        '403':
          description: Forbidden
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                DuplicateEmail:
                  value:
                    error:
                      code: ERR0002
                      retryable: false
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                InternalServerError:
                  value:
                    error:
                      code: ERR0002
                      message: An unknown error occurred while processing the event
                      context: An unknown error occurred while processing the event
                      retryable: true
  /v1/user/{id}/addresses:
    get:
      operationId: get_addresses_by_user_id_api
      security:
        - access_token: []
        - api_key: []
      tags:
        - /v1/user/addresses
      summary: Get Addresses By User Id
      description: >-
        Supports querying for all addresses associated with a user by their
        identityId.
      parameters:
        - in: path
          required: true
          name: id
          schema:
            type: string
          description: >-
            A unique identifier of the user profile you wish to retrieve
            addresses for
          example: 00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: 200 Success Response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAddressesByUserIdResponse'
              example:
                data:
                  - id: 00000000-0000-0000-0000-000000000000
                    address1: 123 Fake Street
                    address2: Apt 456
                    city: Faketown
                    state: WI
                    country: US
                    postalCode: '12345'
                    alias: Home
                    default: true
                    addressType: residential
                    status: active
                  - id: 00000000-0000-0000-0000-000000000001
                    address1: 456 Fake Street
                    city: Faketown
                    state: WI
                    country: US
                    postalCode: '12345'
                    alias: Work
                    default: false
                    addressType: commercial
                    status: active
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                MissingRequiredQueryParameter:
                  value:
                    error:
                      code: ERR0006
                      message: No id parameter was provided
                      retryable: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
              examples:
                Unauthorized:
                  value:
                    message: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                UserNotFound:
                  value:
                    error:
                      code: ERR0001
                      message: No user found
                      retryable: false
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                InternalServerError:
                  value:
                    error:
                      code: ERR0002
                      message: An unknown error occurred while processing the request
                      context: An unknown error occurred while processing the request
                      retryable: true
  /v1/user/search:
    get:
      operationId: user_search_api
      summary: >-
        Search for users by name or phone number. Returns a list of matching
        users. Maximum of 100 results returned.
      security:
        - access_token: []
        - api_key: []
      tags:
        - /v1/user/search
      parameters:
        - name: phone
          in: query
          description: Phone number to query by.
          required: false
          schema:
            type: string
        - name: name
          in: query
          description: >-
            Full name to query by, in the format of {first_name}%20{last_name}.
            The client *MUST* remove all spaces from each name part, as well as
            URL encode the parameter. For example, John Doe would be encoded as
            John%20Doe.
          required: false
          schema:
            type: string
            example: John%20Doe
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSearchResponse'
              examples:
                SearchByPhone:
                  value:
                    data:
                      - identityId: 00000000-0000-0000-0000-000000000000
                        emailAddress: john@example.com
                        firstName: John
                        lastName: Doe
                        address1: 123 Fake Street
                        address2: Apt 456
                        city: Faketown
                        state: WI
                        country: US
                        postalCode: '12345'
                        phoneNumber: '1234567890'
                      - identityId: 00000000-0000-0000-0000-000000000001
                        emailAddress: jane@example.com
                        firstName: Jane
                        lastName: Doe
                        address1: 123 Fake Street
                        address2: Apt 456
                        city: Faketown
                        state: WI
                        country: US
                        postalCode: '12345'
                        phoneNumber: '1234567890'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                MissingRequiredQueryParameter:
                  value:
                    error:
                      code: ERR0003
                      message: 'Invalid request: "name" or "phone" must be provided'
                      context: '{"abc":"123"}'
                      retryable: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
              examples:
                Unauthorized:
                  value:
                    message: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                InternalServerError:
                  value:
                    error:
                      code: ERR0002
                      message: An unknown error occurred while processing the event
                      context: An unknown error occurred while processing the event
                      retryable: true
  /v1/strategic-attributes/trades:
    get:
      operationId: get_trades_api
      security:
        - api_key: []
      tags:
        - /v1/strategic-attributes
      summary: Get Trades
      description: >-
        Returns a list of all trades and their corresponding specialties. The
        response is localized based on the `Accept-Language` header. (en-US by
        default)
      parameters:
        - name: Accept-Language
          in: header
          schema:
            type: string
          description: >-
            Language code (e.g., en-US, es-MX). Used for localization. If value
            is not provided or language is unsupported, en-US is assumed.
          required: false
      responses:
        '200':
          description: 200 Success Response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllTradesResponse'
              examples:
                en-US:
                  value:
                    data:
                      language: en-US
                      trades:
                        - tradeName: Carpentry
                          tradeId: 00000000-0000-0000-0000-000000000001
                          displayName: Carpentry
                          specialties:
                            - specialtyId: 00000000-0000-0000-0000-000000000002
                              displayName: Framing
                              specialtyName: Framing
                            - specialtyId: 00000000-0000-0000-0000-000000000003
                              displayName: Finish Carpentry - Onsite
                              specialtyName: Finish Carpentry - Onsite
                        - tradeName: Plumbing
                          tradeId: 00000000-0000-0000-0000-000000000004
                          displayName: Plumbing
                          specialties:
                            - specialtyId: 00000000-0000-0000-0000-000000000005
                              displayName: Commercial / Industrial Plumber
                              specialtyName: Commercial / Industrial Plumber
                            - specialtyId: 00000000-0000-0000-0000-000000000006
                              displayName: Residential Plumber
                              specialtyName: Residential Plumber
                es-MX:
                  value:
                    data:
                      language: es-MX
                      trades:
                        - tradeName: Carpentry
                          tradeId: 00000000-0000-0000-0000-000000000001
                          displayName: Carpintería
                          specialties:
                            - specialtyId: 00000000-0000-0000-0000-000000000002
                              displayName: Enmarcado
                              specialtyName: Framing
                            - specialtyId: 00000000-0000-0000-0000-000000000003
                              displayName: Carpintería de acabado - En el sitio
                              specialtyName: Finish Carpentry - Onsite
                        - tradeName: Plumbing
                          tradeId: 00000000-0000-0000-0000-000000000004
                          displayName: Fontanería
                          specialties:
                            - specialtyId: 00000000-0000-0000-0000-000000000005
                              displayName: Fontanero comercial / industrial
                              specialtyName: Commercial / Industrial Plumber
                            - specialtyId: 00000000-0000-0000-0000-000000000006
                              displayName: Fontanero residencial
                              specialtyName: Residential Plumber
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
              examples:
                Unauthorized:
                  value:
                    message: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
              examples:
                Forbidden:
                  value:
                    message: Forbidden
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                InternalServerError:
                  value:
                    error:
                      code: ERR0002
                      message: An unknown error occurred while processing the event
                      context: An unknown error occurred while processing the event
                      retryable: true
  /v1/moments:
    get:
      operationId: get_moments_api
      security:
        - access_token: []
        - api_key: []
      tags:
        - /v1/moments
      summary: Get Moments
      description: >
        Returns moments for a single user. By default, returns all moments
        filtered by type and sorted/paginated as requested. If
        `view=latestPerCase` is provided, moments are first filtered by type,
        then grouped by `caseId`, then the latest moment per case is selected.
        Sorting and pagination are applied to the selected per-case moments.
      parameters:
        - name: userId
          in: query
          required: true
          description: A unique identifier of the user for which to retrieve moments.
          schema:
            type: string
        - name: types
          in: query
          description: Filter by one or more moment types.
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: view
          in: query
          description: >
            Selects the result mode. Omit for default behavior (all moments).
            Use `latestPerCase` to return exactly one latest moment per
            `caseId`.
          required: false
          schema:
            type: string
            enum:
              - latestPerCase
        - name: orderby
          in: query
          description: >
            Sort direction. Supported directions: `asc`, `desc`. Defaults to
            `desc`. In `view=latestPerCase`, sorting is applied to the selected
            per-case moments.
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            example: desc
        - name: page
          in: query
          required: false
          description: The page number (1-based). Defaults to 1.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: resultsperpage
          in: query
          required: false
          description: >-
            Number of items per page. Defaults to 25. In `view=latestPerCase`,
            this is the number of cases returned.
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 25
      responses:
        '200':
          description: 200 Success Response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMomentsResponse'
              examples:
                default_all_moments:
                  summary: Default (all moments) - pagination over raw moments
                  value:
                    data:
                      userId: 00000000-0000-0000-0000-000000000005
                      email: john@example.com
                      phoneNumber: '4141112222'
                      firstName: John
                      lastName: Doe
                      moments:
                        - caseId: CASE-001
                          type: status.updated
                          contextEventTimestamp: 1696277269279
                          createdAt: 1696277270292
                          contextSystemOfRecord: OnePoint
                          userId: 00000000-0000-0000-0000-000000000005
                        - caseId: CASE-002
                          type: note.added
                          contextEventTimestamp: 1696277265300
                          createdAt: 1696277266300
                          contextSystemOfRecord: OnePoint
                          userId: 00000000-0000-0000-0000-000000000005
                      page: 1
                      pageSize: 10
                      totalCount: 100
                      totalPages: 10
                latest_per_case:
                  summary: >-
                    view=latestPerCase (one moment per case) - pagination over
                    cases
                  value:
                    data:
                      userId: 00000000-0000-0000-0000-000000000005
                      email: john@example.com
                      phoneNumber: '4141112222'
                      firstName: John
                      lastName: Doe
                      moments:
                        - caseId: CASE-001
                          status: Out for delivery
                          contextEventTimestamp: 1696277269279
                          createdAt: 1696277270292
                          contextSystemOfRecord: OnePoint
                          userId: 00000000-0000-0000-0000-000000000005
                        - caseId: CASE-002
                          status: Baking
                          contextEventTimestamp: 1696278269000
                          createdAt: 1696278270000
                          contextSystemOfRecord: OnePoint
                          userId: 00000000-0000-0000-0000-000000000005
                      page: 1
                      pageSize: 1
                      totalCount: 2
                      totalPages: 2
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
              examples:
                Unauthorized:
                  value:
                    message: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
              examples:
                Forbidden:
                  value:
                    message: Forbidden
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
              examples:
                InternalServerError:
                  value:
                    error:
                      code: ERR0002
                      message: An unknown error occurred while processing the request
                      context: An unknown error occurred while processing the request
                      retryable: true
  /v1/moments/{momentType}:
    get:
      operationId: get_moments_by_type
      security:
        - access_token: []
        - api_key: []
      tags:
        - /v1/moments/{momentType}
      summary: Get moments by type
      description: >
        Returns raw moments of the specified `momentType`. Results can be
        filtered using the supported query parameters (for example, `userId` and
        `caseId`) and paginated with `page` and `resultsperpage`. Used for
        retrieving user timelines, case-based workflows, and general type-based
        moment retrieval.
      parameters:
        - name: momentType
          in: path
          required: true
          description: >-
            The type of moment to retrieve (e.g. cx_case_management_v2,
            auth0_log_in_v1).
          schema:
            type: string
        - name: userId
          in: query
          required: false
          description: A unique identifier of the user for which to retrieve moments.
          schema:
            type: string
        - name: caseId
          in: query
          required: false
          description: Filter moments by case ID.
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        - name: resultsperpage
          in: query
          required: false
          schema:
            type: integer
            default: 25
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMomentsResponse'
              examples:
                filtered_by_case:
                  summary: All raw moments for a case (CSR details view)
                  value:
                    data:
                      userId: 00000000-0000-0000-0000-000000000005
                      email: john@example.com
                      firstName: John
                      lastName: Doe
                      phoneNumber: '4141112222'
                      moments:
                        - caseId: CASE-001
                          status: Preparing
                          createdAt: 1696277265300
                          userId: 00000000-0000-0000-0000-000000000005
                        - caseId: CASE-001
                          status: Baking
                          createdAt: 1696277266300
                          userId: 00000000-0000-0000-0000-000000000005
                        - caseId: CASE-001
                          status: Out for delivery
                          createdAt: 1696277270292
                          userId: 00000000-0000-0000-0000-000000000005
                      page: 1
                      pageSize: 25
                      totalCount: 3
                      totalPages: 1
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server Error
components:
  schemas:
    CountryCode:
      type: string
      pattern: ^[A-Z]{2}$
      minLength: 2
      maxLength: 2
      description: >-
        ISO 3166-1 alpha-2 country code. A two-letter uppercase code
        representing a country (e.g., "US" for United States, "CA" for Canada,
        "MX" for Mexico). See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
        for the complete list of codes.
      example: US
    ErrorCodes:
      type: string
      enum:
        - ERR0001
        - ERR0002
        - ERR0003
        - ERR0004
        - ERR0005
        - ERR0006
        - ERR0007
    UnauthorizedError:
      type: object
      properties:
        message:
          type: string
    ForbiddenError:
      type: object
      properties:
        message:
          type: string
    ResponseError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              $ref: '#/components/schemas/ErrorCodes'
              description: A unique error code for the error.
            message:
              type: string
              description: A human-readable message describing the error.
            context:
              type: string
              description: Additional context for the error.
            retryable:
              type: boolean
              description: Indicates whether the request can be retried.
    CreateUserResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            identityId:
              type: string
              format: uuid
    CreateAddressRequest:
      type: object
      properties:
        address1:
          type: string
          required: true
        address2:
          type: string
          required: false
        city:
          type: string
          required: false
        state:
          type: string
          required: false
        postalCode:
          type: string
          format: postal-code
          required: false
        country:
          $ref: '#/components/schemas/CountryCode'
          required: false
        alias:
          type: string
          required: false
        default:
          type: boolean
          required: false
        addressType:
          type: string
          enum:
            - residential
            - commercial
          required: false
    CreateServiceAddressRequest:
      type: object
      properties:
        addressId:
          type: string
        userId:
          type: string
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
        state:
          type: string
        postalCode:
          type: string
        country:
          $ref: '#/components/schemas/CountryCode'
        alias:
          type: string
      required:
        - addressId
    CreateAddressResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              format: uuid
    CreateServiceAddressResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              format: uuid
    GetServiceAddressByIdResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            addressId:
              type: string
            userId:
              type: string
            address1:
              type: string
            address2:
              type: string
            city:
              type: string
            state:
              type: string
            postalCode:
              type: string
            country:
              $ref: '#/components/schemas/CountryCode'
            alias:
              type: string
          required:
            - addressId
    GetAddressByIdResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              format: uuid
            address1:
              type: string
            address2:
              type: string
            city:
              type: string
            state:
              type: string
            country:
              $ref: '#/components/schemas/CountryCode'
            postalCode:
              type: string
              format: postal-code
            alias:
              type: string
            default:
              type: boolean
            addressType:
              type: string
              enum:
                - residential
                - commercial
            status:
              type: string
              enum:
                - active
                - disabled
                - deleted
    GetAddressesByUserIdResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              address1:
                type: string
              address2:
                type: string
              city:
                type: string
              state:
                type: string
              country:
                $ref: '#/components/schemas/CountryCode'
              postalCode:
                type: string
                format: postal-code
              alias:
                type: string
              default:
                type: boolean
              addressType:
                type: string
                enum:
                  - residential
                  - commercial
              status:
                type: string
                enum:
                  - active
                  - disabled
                  - deleted
    UserSearchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              emailAddress:
                type: string
                format: email
              auth0Id:
                type: string
              legacyUserId:
                type: string
              firstName:
                type: string
              lastName:
                type: string
              address1:
                type: string
              address2:
                type: string
              city:
                type: string
              state:
                type: string
              country:
                $ref: '#/components/schemas/CountryCode'
              postalCode:
                type: string
                format: postal-code
              phoneNumber:
                type: string
    GetUserProfileResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            identity:
              type: object
              properties:
                emailAddress:
                  type: string
                  example: john@example.com
                firstName:
                  type: string
                  example: John
                lastName:
                  type: string
                  example: Doe
                address1:
                  type: string
                  example: 456 S. Main St
                address2:
                  type: string
                  example: '#101'
                city:
                  type: string
                  example: Milwaukee
                state:
                  type: string
                  example: Wisconsin
                country:
                  $ref: '#/components/schemas/CountryCode'
                postalCode:
                  type: string
                  example: '53211'
                phoneNumber:
                  type: string
                  example: '4141112222'
                jobTitle:
                  type: string
                  example: superintendent
                trade:
                  type: string
                  example: carpentry
                tradeSector:
                  type: string
                  example: commercial
                secondaryTradeSectors:
                  type: array
                  items:
                    type: string
                  example:
                    - residential
                    - industrial
                languagePreference:
                  type: string
                  example: English
                createdAt:
                  type: integer
                  example: 1691774580629
                updatedAt:
                  type: integer
                  example: 1691774580629
            axId:
              type: string
              example: 00000000-0000-0000-0000-000000000005
            hubspotId:
              type: string
              example: 00000000-0000-0000-0000-000000000001
            oneKeyId:
              type: string
              example: 00000000-0000-0000-0000-000000000003
            rudderId:
              type: string
              example: de305d54-75b4-431b-adb2-eb6b9e546014
            brazeId:
              type: string
              example: 00000000-0000-0000-0000-000000000002
            d365ContactId:
              type: string
              example: 00000000-0000-0000-0000-000000000004
            d365ContactGroup:
              type: string
              example: marketing
            d365ContactType:
              type: string
              example: distributor
            auth0Accounts:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    example: auth0|1234567890
                  legacyUserId:
                    type: string
                    example: 00000000-0000-0000-0000-000000000009
                  emailVerified:
                    type: boolean
                    example: true
                  connection:
                    type: string
                    example: accounts-db-proxy
            marketingPreferences:
              type: object
              properties:
                cookieOptIn:
                  type: boolean
                  example: false
                subscribedHDNewsEmail:
                  type: boolean
                  example: false
                subscribedOneKeyNewsletterEmail:
                  type: boolean
                  example: false
                subscribedConnectEmail:
                  type: boolean
                  example: false
                subscribedGridEmail:
                  type: boolean
                  example: false
                subscribedResearchEmail:
                  type: boolean
                  example: false
                subscribedHDNewsText:
                  type: boolean
                  example: false
                subscribedHDCenterEmail:
                  type: boolean
                  example: false
                subscribedHDCenterText:
                  type: boolean
                  example: false
                subscribedGridText:
                  type: boolean
                  example: false
                createdAt:
                  type: integer
                  example: 1691774580629
                updatedAt:
                  type: integer
                  example: 1691774580629
            company:
              type: object
              properties:
                name:
                  type: string
                  example: Acme Corp
                address1:
                  type: string
                  example: 123 Fake Street
                address2:
                  type: string
                  example: Apt 456
                city:
                  type: string
                  example: Faketown
                state:
                  type: string
                  example: WI
                postalCode:
                  type: string
                  example: '12345'
                country:
                  $ref: '#/components/schemas/CountryCode'
                size:
                  type: string
                  example: '1000'
                createdAt:
                  type: integer
                  example: 1691774580629
                updatedAt:
                  type: integer
                  example: 1691774580629
            products:
              type: array
              items:
                type: string
              example:
                - 48-11-1850
                - 48-11-1852
            hdaAccount:
              type: object
              properties:
                number:
                  type: string
                  example: '123456789'
                name:
                  type: string
                  example: Acme Corp
                partnerClassification:
                  type: string
                  example: transactional
                hdaStatus:
                  type: string
                  example: hda status
                hdaPceNumber:
                  type: string
                  example: hda pce number
                hdaEffectiveDate:
                  type: string
                  example: 1/1/24
                hdaEndDate:
                  type: string
                  example: 1/1/25
    GetAllTradesResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            language:
              type: string
              description: Language code (e.g., en-US, es-MX)
            trades:
              type: array
              items:
                type: object
                properties:
                  tradeName:
                    type: string
                    description: Human-readable trade name
                  tradeId:
                    type: string
                    format: uuid
                    description: Unique identifier (UUID) for the trade
                  displayName:
                    type: string
                    description: Translated or localized name of the trade
                  specialties:
                    type: array
                    description: >-
                      List of specialties for this trade in the specified
                      language
                    items:
                      type: object
                      properties:
                        specialtyId:
                          type: string
                          format: uuid
                          description: Unique identifier (UUID) for the specialty
                        displayName:
                          type: string
                          description: Translated or localized specialty name
                        specialtyName:
                          type: string
                          description: Specialty name. Unique across all languages.
                      required:
                        - specialtyId
                        - displayName
                        - specialtyName
                required:
                  - tradeName
                  - tradeId
                  - displayName
                  - specialties
    GetMomentsResponse:
      type: object
      properties:
        data:
          type: object
          description: >
            User information and associated moment records. `moments` is the
            only array and contains raw moment objects.
          properties:
            userId:
              type: string
              example: 00000000-0000-0000-0000-000000000005
            email:
              type: string
              format: email
              example: john@example.com
            phoneNumber:
              type: string
              example: '4141112222'
            firstName:
              type: string
              example: John
            lastName:
              type: string
              example: Doe
            moments:
              type: array
              description: >
                Raw moment objects returned by the query. Depending on the
                request, this may include: - all moments for the user - latest
                moment per case (summary mode) - all moments for a case
                (case-details mode) - moments filtered by type and fields
                (generic mode)
              items:
                type: object
                properties:
                  caseId:
                    type: string
                    nullable: true
                    example: CASE-001
                  status:
                    type: string
                    nullable: true
                    example: Out for delivery
                  contextEventTimestamp:
                    type: integer
                    format: int64
                    example: 1696277269279
                  createdAt:
                    type: integer
                    format: int64
                    example: 1696277270292
                  contextSystemOfRecord:
                    type: string
                    example: auth0
                  userId:
                    type: string
                    example: 00000000-0000-0000-0000-000000000005
            page:
              type: integer
              example: 1
            pageSize:
              type: integer
              example: 10
            totalCount:
              type: integer
              example: 100
            totalPages:
              type: integer
              example: 10
    GetMomentsByTypeResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            firstName:
              type: string
              example: John
            lastName:
              type: string
              example: Doe
            email:
              type: string
              example: john.doe@milwaukeetool.com
            moments:
              type: array
              items:
                type: object
                properties:
                  eventDate:
                    type: integer
                    example: 1696277269279
                  status:
                    type: string
                    example: Resolved
                  assignmentGroup:
                    type: string
                    example: Support
            page:
              type: integer
              example: 1
            pageSize:
              type: integer
              example: 10
            totalCount:
              type: integer
              example: 100
            totalPages:
              type: integer
              example: 10
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header
    access_token:
      type: apiKey
      name: Authorization
      in: header
      description: |
        A bearer token for accessing protected resources.