leadboxer-com Segment Preference API

openapi: 3.2.0
info:
  title: Leadboxer Segment Preference API
  description: '# LeadBoxer API Documentation


    Here you can find the technical documentation needed for using the LeadBoxer API, including the option to generate requests and review the outcomes.


    ## Getting Started


    To get started, please have a look at these pages that include introductions, use-cases, and additional information for the LeadBoxer API: LeadBoxer API Documentation


    These documents are intended for LeadBoxer CUSTOMERS that have a valid API license & Key. Please contact us before using the LeadBoxer API.


    ## Warning


    Please be aware that any actions you perform through this reference testing functionality will involve operations with your production data. To test your applications against some sandbox data, we recommend creating a new, separate LeadBoxer account for sandboxing purposes.


    This API is under active maintenance, and we are constantly adding new functionality to this version.


    [**All requests to the API must be made over SSL (https, not http).**]'
  termsOfService: https://www.leadboxer.com/resources/terms
  contact:
    name: Wart Fransen
    url: wart@leadboxer.com
    email: hello@leadboxer.com
  license:
    name: ''
    url: https://www.leadboxer.com/resources/privacy
  version: 0.0.1
servers:
- url: https://api.leadboxer.com
  description: Production Server
security:
- ApiKeyAuth: []
tags:
- name: Segment Preference
  description: 'Defines and manages which segment is set as default for a given combination of User ID and Dataset ID.

    A user can have multiple segments under a dataset, but only one of them can be designated as the default at any time.

    These APIs handle creation, retrieval, and updates of that default segment.'
paths:
  /v1/segment/preference:
    get:
      tags:
      - Segment Preference
      summary: Get Default Segment Users
      description: Get the list of User IDs for whom the specified segment is set as the default under the given Dataset ID.
      operationId: getUsersBySegmentIdAndDatasetId
      parameters:
      - name: email
        in: query
        description: Email associated with the account.
        required: true
        schema:
          type: string
      - name: segmentId
        in: query
        description: Segment ID for which you want to retrieve the list of users who have this segment set as default.
        required: true
        schema:
          type: integer
          format: int32
      - name: datasetId
        in: query
        description: Dataset ID under which the segment’s default users should be retrieved.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/GetAllResponseLong'
        '400':
          description: 'Bad Request: The request is invalid or malformed (missing/incorrect parameters).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1BadRequestResponse'
        '402':
          description: 'Payment Required: The client has exceeded credit limits.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1InternalServerError'
        '403':
          description: 'Forbidden: The authenticated user does not have permission to access this resource.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1PermissionDenied'
        '404':
          description: 'Not Found: The requested resource does not exist.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1NotFoundResponse'
        '409':
          description: 'Conflict: The request could not be completed due to a resource state conflict.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1ConflictResponse'
        '429':
          description: 'Too Many Requests: Rate limit exceeded. The client has sent too many requests in a given time period'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
        '500':
          description: 'Interval Server Error: An unexpected error occurred on the server.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1InternalServerError'
    put:
      tags:
      - Segment Preference
      summary: Add/Update Default Segment for Users
      description: 'Sets the given Segment ID as the default segment for the provided list of User IDs under the specified Dataset ID.

        Users included in the list will have their default segment added or updated accordingly.

        Any users not included in the list will have their existing default-segment association under this dataset removed.'
      operationId: saveDefaultSegment
      parameters:
      - name: email
        in: query
        description: Email associated with the account.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentPreferenceRequest'
        required: true
      responses:
        '204':
          description: Segment Preference updated successfully. No content returned.
        '400':
          description: 'Bad Request: The request is invalid or malformed (missing/incorrect parameters).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1BadRequestResponse'
        '402':
          description: 'Payment Required: The client has exceeded credit limits.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1InternalServerError'
        '403':
          description: 'Forbidden: The authenticated user does not have permission to access this resource.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1PermissionDenied'
        '404':
          description: 'Not Found: The requested resource does not exist.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1NotFoundResponse'
        '409':
          description: 'Conflict: The request could not be completed due to a resource state conflict.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1ConflictResponse'
        '429':
          description: 'Too Many Requests: Rate limit exceeded. The client has sent too many requests in a given time period'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
        '500':
          description: 'Interval Server Error: An unexpected error occurred on the server.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1InternalServerError'
    delete:
      tags:
      - Segment Preference
      summary: Remove Default Segment
      description: Remove Default Segment for the user with the given Email under the given Dataset ID.
      operationId: deleteDefaultSegment
      parameters:
      - name: email
        in: query
        description: Email associated with the account. Default Segment for this user under the given dataset will be removed.
        required: true
        schema:
          type: string
      - name: datasetId
        in: query
        description: Dataset ID from which default segment is to be removed.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Default Segment removed successfully. No content returned.
        '400':
          description: 'Bad Request: The request is invalid or malformed (missing/incorrect parameters).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1BadRequestResponse'
        '402':
          description: 'Payment Required: The client has exceeded credit limits.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1InternalServerError'
        '403':
          description: 'Forbidden: The authenticated user does not have permission to access this resource.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1PermissionDenied'
        '404':
          description: 'Not Found: The requested resource does not exist.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1NotFoundResponse'
        '409':
          description: 'Conflict: The request could not be completed due to a resource state conflict.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1ConflictResponse'
        '429':
          description: 'Too Many Requests: Rate limit exceeded. The client has sent too many requests in a given time period'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
        '500':
          description: 'Interval Server Error: An unexpected error occurred on the server.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1InternalServerError'
components:
  schemas:
    V1PermissionDenied:
      type: object
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type
        title:
          type: string
          description: A short, human-readable summary of the problem type
        status:
          type: integer
          description: The HTTP status code
          format: int32
          example: 403
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence of the problem
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem
    V1InternalServerError:
      type: object
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type
        title:
          type: string
          description: A short, human-readable summary of the problem type
          example: Internal Server Error
        status:
          type: integer
          description: The HTTP status code
          format: int32
          example: 500
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence of the problem
          example: An unexpected error occurred. Please contact support.
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem
    RateLimitErrorResponse:
      type: object
      properties:
        timestamp:
          type: integer
          format: int64
          example: 1765611454230
        status:
          type: integer
          format: int32
          example: 429
        error:
          type: string
          example: Too Many Requests
        message:
          type: string
          example: Rate limit exceeded. Please try again later.
        retryAfter:
          type: integer
          format: int32
          example: 58
        limit:
          type: integer
          format: int32
          example: 2
        remaining:
          type: integer
          format: int32
          example: 0
      description: Rate limit exceeded error response
    SegmentPreferenceRequest:
      required:
      - datasetId
      - segmentId
      type: object
      properties:
        datasetId:
          type: string
          description: Dataset ID for which you need to assign segment as default.
        segmentId:
          type: integer
          description: Segment ID which you want to assign as default.
          format: int32
        users:
          type: array
          description: List of User IDs for whom you need to assign a segment as default.
          items:
            type: integer
            description: List of User IDs for whom you need to assign a segment as default.
            format: int64
    V1BadRequestResponse:
      type: object
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type
          example: https://developers.leadboxer.com/docs/validation-error
        title:
          type: string
          description: A short, human-readable summary of the problem type
          example: The request is malformed or contains invalid data
        status:
          type: integer
          description: The HTTP status code
          format: int32
          example: 400
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence of the problem
          example: email must be a well-formed email address
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem
          example: /v1/users/{userId}/name?email=johndoe.com
        errors:
          type: array
          description: Array of field-level validation errors
          items:
            $ref: '#/components/schemas/ValidationError'
    V1ConflictResponse:
      type: object
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type
        title:
          type: string
          description: A short, human-readable summary of the problem type
          example: Resource already exist
        status:
          type: integer
          description: The HTTP status code
          format: int32
          example: 409
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence of the problem
          example: 'User with email: john.doe@examplecompany.com already exist'
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem
          example: /v1/users/?email=john.doe@examplecompany.com
    V1NotFoundResponse:
      type: object
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type
        title:
          type: string
          description: A short, human-readable summary of the problem type
        status:
          type: integer
          description: The HTTP status code
          format: int32
          example: 404
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence of the problem
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem
    GetAllResponseLong:
      type: object
      properties:
        data:
          type: array
          items:
            type: integer
            format: int64
        metaData:
          type: object
    ValidationError:
      type: object
      properties:
        field:
          type: string
          description: The name of the field that failed validation
          example: email
        message:
          type: string
          description: Human-readable error message for this specific field
          example: must be a well-formed email address
      description: Array of field-level validation errors
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: Provide your LeadBoxer API Key
      name: x-api-key
      in: header
x-provenance:
  method: searched
  source: https://developers.leadboxer.com/reference
  harvested: '2026-10-30'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developers.leadboxer.com/reference/addcustomtrackingdomain.md
  - https://developers.leadboxer.com/reference/adddataset.md
  - https://developers.leadboxer.com/reference/adduser.md
  - https://developers.leadboxer.com/reference/adduserdataset.md
  - https://developers.leadboxer.com/reference/assignleads.md
  - https://developers.leadboxer.com/reference/authentication.md
  - https://developers.leadboxer.com/reference/createsegment.md
  - https://developers.leadboxer.com/reference/deletecustomtrackingdomain.md
  - https://developers.leadboxer.com/reference/deletedatasetexclusion.md
  - https://developers.leadboxer.com/reference/deletedefaultsegment.md
  - https://developers.leadboxer.com/reference/deletesegment.md
  - https://developers.leadboxer.com/reference/getavailablecreditgrants.md
  - https://developers.leadboxer.com/reference/getcustomtrackingdomains.md
  - https://developers.leadboxer.com/reference/getdatasetexclusions.md
  - https://developers.leadboxer.com/reference/getevents.md
  - https://developers.leadboxer.com/reference/getsegments.md
  - https://developers.leadboxer.com/reference/getsessions.md
  - https://developers.leadboxer.com/reference/getting-started.md
  - https://developers.leadboxer.com/reference/getuserdatasets.md
  - https://developers.leadboxer.com/reference/getuserdatasets_1.md
  - https://developers.leadboxer.com/reference/getusersbysegmentidanddatasetid.md
  - https://developers.leadboxer.com/reference/leaddetail.md
  - https://developers.leadboxer.com/reference/lookupdomain.md
  - https://developers.leadboxer.com/reference/lookupemail.md
  - https://developers.leadboxer.com/reference/lookupemailbyquery.md
  - https://developers.leadboxer.com/reference/lookupip.md
  - https://developers.leadboxer.com/reference/my-requests.md
  - https://developers.leadboxer.com/reference/removedataset.md
  - https://developers.leadboxer.com/reference/removeuser.md
  - https://developers.leadboxer.com/reference/removeuserdataset.md
  - https://developers.leadboxer.com/reference/resendinvite.md
  - https://developers.leadboxer.com/reference/savedatasetexclusion.md
  - https://developers.leadboxer.com/reference/savedefaultsegment.md
  - https://developers.leadboxer.com/reference/updatedatasetname.md
  - https://developers.leadboxer.com/reference/updatedcustomtrackingdomain.md
  - https://developers.leadboxer.com/reference/updateformtracking.md
  - https://developers.leadboxer.com/reference/updateleadtags.md
  - https://developers.leadboxer.com/reference/updatename.md
  - https://developers.leadboxer.com/reference/updatesegment.md
  - https://developers.leadboxer.com/reference/updatesegmentuser.md
  - https://developers.leadboxer.com/reference/users.md
  - https://developers.leadboxer.com/reference/userscsv.md
  - https://developers.leadboxer.com/reference/validatecustomtrackingdomain.md
  merge:
    pages: 43
    deduped: 355
    conflicts_kept_first: 0