Attentive Segments API

openapi: 3.2.0
info:
  description: For any questions, reach out to your Attentive point of contact (if applicable) or api@attentivemobile.com.
  title: Attentive API V2 Segments API
  version: 2.0.0
servers:
- url: https://api.attentivemobile.com/
  description: Attentive API V2
security:
- bearerAuth: []
tags:
- name: Segments
  description: Endpoints for submitting bulk segment member additions and removals.
  x-beta: true
paths:
  /v2/bulk/segments/members:
    x-external: hidden
    x-requires-auth: false
    post:
      x-external: true
      x-emits-event: true
      security:
      - bearerAuth: []
      - OAuthFlow:
        - segments:write
      summary: Add Bulk Segment Members
      description: 'Add members to a segment in bulk. This endpoint accepts 1 to 10,000 members per request. Members are identified by email, phone number, and/or client user ID. The request is validated, queued for asynchronous processing, and a unique batch job ID is returned for tracking the status.


        **Request Limits:**

        - Minimum: 1 member per request

        - Maximum: 10,000 members per request

        - At least one identifier (email, phone, or clientUserId) required per member


        **Processing:**

        - Jobs are processed asynchronously

        - Use the batch job ID to check status via `GET /v2/bulk/job/{bulkJobId}`

        - Results available as downloadable `.jsonl` file when completed


        Scopes Required: [segments:all]


        Default Rate Limit: 100 requests per second'
      operationId: postBulkSegmentMembers
      parameters:
      - name: Authorization
        in: header
        description: Authorization for the request
        required: true
        schema:
          type: string
      tags:
      - Segments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentMembers'
            examples:
              addThreeMembers:
                summary: Add three members to loyalty segment
                description: Example showing adding members with different identifier combinations
                value:
                  externalId: loyalty_gold_2025
                  members:
                  - email: customer1@example.com
                    phone: '+14155551234'
                  - email: customer2@example.com
                    clientUserId: user-abc-123
                  - phone: '+14155555678'
                    clientUserId: user-xyz-789
              addByEmailOnly:
                summary: Add members by email only
                description: Example showing members identified by email address
                value:
                  externalId: newsletter_subscribers
                  members:
                  - email: subscriber1@example.com
                  - email: subscriber2@example.com
                  - email: subscriber3@example.com
      responses:
        '202':
          description: 'The bulk job request was successfully received and accepted for asynchronous processing. The response includes a batchJobId to track the status of the job, along with a confirmation message. Processing has not yet completed, please use the job status endpoint to monitor progress and retrieve results once available.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSuccessResponse'
              examples:
                successResponse:
                  summary: Successful job submission
                  description: The job was accepted and queued for processing
                  value:
                    message: Bulk segment member add job successfully submitted
                    batchJobId: 550e8400-e29b-41d4-a716-446655440000
        '400':
          $ref: '#/components/responses/InvalidParameter'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccessDenied'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      x-external: true
      x-emits-event: true
      security:
      - bearerAuth: []
      - OAuthFlow:
        - segments:write
      summary: Remove Bulk Segment Members
      description: 'Remove members from a segment in bulk. This endpoint accepts 1 to 10,000 members per request. Members are identified by email, phone number, and/or client user ID. The request is validated, queued for asynchronous processing, and a unique batch job ID is returned for tracking the status.


        **Request Limits:**

        - Minimum: 1 member per request

        - Maximum: 10,000 members per request

        - At least one identifier (email, phone, or clientUserId) required per member


        **Processing:**

        - Jobs are processed asynchronously

        - Use the batch job ID to check status via `GET /v2/bulk/job/{bulkJobId}`

        - Results available as downloadable `.jsonl` file when completed


        Scopes Required: [segments:all]


        Default Rate Limit: 100 requests per second'
      operationId: deleteBulkSegmentMembers
      parameters:
      - name: Authorization
        in: header
        description: Authorization for the request
        required: true
        schema:
          type: string
      tags:
      - Segments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentMembers'
            examples:
              removeThreeMembers:
                summary: Remove three members from loyalty segment
                description: Example showing removing members with different identifier combinations
                value:
                  externalId: loyalty_gold_2025
                  members:
                  - email: former.customer1@example.com
                    phone: '+14155551234'
                  - email: former.customer2@example.com
                    clientUserId: user-def-456
                  - phone: '+14155559999'
                    clientUserId: user-ghi-789
              removeByPhoneOnly:
                summary: Remove members by phone only
                description: Example showing members identified by phone number
                value:
                  externalId: unsubscribed_users
                  members:
                  - phone: '+14155551111'
                  - phone: '+14155552222'
                  - phone: '+14155553333'
      responses:
        '202':
          description: 'The bulk job request was successfully received and accepted for asynchronous processing. The response includes a batchJobId to track the status of the job, along with a confirmation message. Processing has not yet completed, please use the job status endpoint to monitor progress and retrieve results once available.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSuccessResponse'
              examples:
                successResponse:
                  summary: Successful job submission
                  description: The job was accepted and queued for processing
                  value:
                    message: Bulk segment member removal job successfully submitted
                    batchJobId: 660f9511-f3ac-52e5-b827-557766551111
        '400':
          $ref: '#/components/responses/InvalidParameter'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/AccessDenied'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /v2/segments:
    x-external: hidden
    x-requires-auth: true
    post:
      x-external: true
      x-emits-event: true
      security:
      - bearerAuth: []
      - OAuthFlow:
        - segments:write
      summary: Create new segment
      description: 'Creates a new empty segment with the specified name and optional description.


        Scopes Required: [segments:Write]


        Default Rate Limit: 100 requests per second'
      operationId: createSegment
      tags:
      - Segments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSegmentRequest'
      responses:
        '201':
          description: Segment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSegmentResponse'
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized - invalid or missing token
        '403':
          description: Access denied - insufficient permissions
        '429':
          description: Too many requests - rate limit exceeded
        '500':
          description: Internal server error
    get:
      x-external: true
      x-requires-auth: true
      security:
      - bearerAuth: []
      - OAuthFlow:
        - segments:read
      summary: List segments
      description: 'Lists segments with optional filtering by name, external ID, or update timestamp.


        Scopes Required: [segments:Read OR segments:Write]


        Default Rate Limit: 100 requests per second'
      operationId: listSegments
      tags:
      - Segments
      parameters:
      - name: name
        in: query
        description: Filter by segment name (partial match). Cannot be empty or whitespace only.
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 240
      - name: externalId
        in: query
        description: Filter by external ID. Cannot be empty or whitespace only.
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 255
      - name: updatedSince
        in: query
        description: Filter by segments updated since this timestamp (ISO 8601 format)
        required: false
        schema:
          type: string
          format: date-time
      - name: cursor
        in: query
        description: Pagination cursor from previous response. Cannot be empty or whitespace only.
        required: false
        schema:
          type: string
          minLength: 1
      - name: limit
        in: query
        description: Maximum number of results to return (default 20, max 1000)
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 20
      responses:
        '200':
          description: List of segments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSegmentsResponse'
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized - invalid or missing token
        '403':
          description: Access denied - insufficient permissions
        '429':
          description: Too many requests - rate limit exceeded
        '500':
          description: Internal server error
  /v2/segments/external/{externalId}:
    x-external: hidden
    x-requires-auth: true
    get:
      x-external: true
      x-requires-auth: true
      security:
      - bearerAuth: []
      - OAuthFlow:
        - segments:read
      summary: Get segment by external ID
      description: 'Retrieves segment details by external ID.


        Scopes Required: [segments:Read OR segments:Write]


        Default Rate Limit: 100 requests per second'
      operationId: getSegmentByExternalId
      tags:
      - Segments
      parameters:
      - name: externalId
        in: path
        description: External ID of the segment
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 255
      responses:
        '200':
          description: Segment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentResponse'
        '401':
          description: Unauthorized - invalid or missing token
        '403':
          description: Access denied - insufficient permissions
        '404':
          description: Segment not found
        '429':
          description: Too many requests - rate limit exceeded
        '500':
          description: Internal server error
    patch:
      x-external: true
      x-requires-auth: true
      x-emits-event: true
      security:
      - bearerAuth: []
      - OAuthFlow:
        - segments:write
      summary: Partial update segment by external ID
      description: 'Partially updates an existing segment. Only provided fields will be updated.


        Scopes Required: [segments:Write]


        Default Rate Limit: 100 requests per second'
      operationId: patchSegmentByExternalId
      tags:
      - Segments
      parameters:
      - name: externalId
        in: path
        description: External ID of the segment
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchSegmentRequest'
      responses:
        '200':
          description: Segment updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentResponse'
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized - invalid or missing token
        '403':
          description: Access denied - insufficient permissions
        '404':
          description: Segment not found
        '429':
          description: Too many requests - rate limit exceeded
        '500':
          description: Internal server error
    delete:
      x-external: true
      x-requires-auth: true
      x-emits-event: true
      security:
      - bearerAuth: []
      - OAuthFlow:
        - segments:write
      summary: Archive segment by external ID
      description: 'Archives (soft deletes) a segment by external ID. The segment will no longer be visible in list operations but can be restored if needed.


        Scopes Required: [segments:Write]


        Default Rate Limit: 100 requests per second'
      operationId: deleteSegmentByExternalId
      tags:
      - Segments
      parameters:
      - name: externalId
        in: path
        description: External ID of the segment to archive
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 255
      responses:
        '204':
          description: Segment archived successfully
        '401':
          description: Unauthorized - invalid or missing token
        '403':
          description: Access denied - insufficient permissions
        '404':
          description: Segment not found
        '429':
          description: Too many requests - rate limit exceeded
        '500':
          description: Internal server error
components:
  responses:
    TooManyRequests:
      description: The user has sent too many requests in a given amount of time
    AccessDenied:
      description: Access Denied
    InternalError:
      description: Internal Server Error
    NotFound:
      description: The specified resource was not found
    InvalidParameter:
      description: Invalid parameter in request query or body
    Unauthorized:
      description: Unauthorized
  schemas:
    ListSegmentsResponse:
      type: object
      properties:
        segments:
          type: array
          items:
            $ref: '#/components/schemas/SegmentResponse'
        cursor:
          type:
          - string
          - 'null'
          description: Cursor for pagination (null if no more results)
          example: eyJpZCI6MTIzNDU2fQ==
        hasMore:
          type: boolean
          description: Whether there are more results available
          example: false
    SegmentMember:
      type: object
      description: 'A segment member identified by one or more of: email, phone, or clientUserId. At least one identifier must be provided. Multiple identifiers can be provided to increase matching accuracy.

        '
      properties:
        email:
          type: string
          format: email
          description: 'The member''s email address. Use this to identify users by their email. At least one of email, phone, or clientUserId must be provided.

            '
          example: user1@example.com
        phone:
          type: string
          description: 'The member''s phone number in E.164 format (e.g., +14155551234). At least one of email, phone, or clientUserId must be provided.


            **E.164 Format Requirements:**

            - Must start with ''+''

            - Include country code

            - No spaces, dashes, or parentheses

            '
          example: '+14155551234'
        clientUserId:
          type: string
          description: 'Your system''s unique identifier for this user. Use this when you want to identify users by your own internal ID system. At least one of email, phone, or clientUserId must be provided. Maximum 100 characters.

            '
          maxLength: 100
          example: client-user-123
      example:
        email: loyalty.member@example.com
        phone: '+14155551234'
        clientUserId: cust-789-xyz
    SegmentResponse:
      type: object
      properties:
        externalId:
          type: string
          description: The external segment ID (client-facing identifier)
          example: loyalty_gold_2025
        name:
          type: string
          description: The name of the segment
          example: Loyalty Gold Members
        description:
          type: string
          description: The description of the segment
          example: Customers with gold loyalty status
        created:
          type: string
          format: date-time
          description: When the segment was created (ISO 8601 format)
          example: '2025-01-30T12:00:00Z'
        updated:
          type: string
          format: date-time
          description: When the segment was last updated (ISO 8601 format)
          example: '2025-01-30T12:00:00Z'
    SegmentMembers:
      type: object
      required:
      - externalId
      - members
      properties:
        externalId:
          type: string
          description: 'The external ID of the segment. This is the client-provided unique identifier for the segment, as defined when creating the segment via the Segment API.

            '
          example: loyalty_gold_2025
        members:
          type: array
          description: 'Array of segment members to add or remove. Each member must have at least one identifier (email, phone, or clientUserId). Minimum 1 member, maximum 10,000 members per request.

            '
          minItems: 1
          maxItems: 10000
          items:
            $ref: '#/components/schemas/SegmentMember'
      example:
        externalId: loyalty_gold_2025
        members:
        - email: customer1@example.com
          phone: '+14155551234'
        - email: customer2@example.com
          clientUserId: user-abc-123
        - phone: '+14155555678'
          clientUserId: user-xyz-789
    BulkSuccessResponse:
      type: object
      properties:
        message:
          type: string
          description: 'A human-readable message confirming that the bulk job was successfully submitted.

            '
        batchJobId:
          type: string
          description: 'A unique identifier representing the submitted batch job. Use this ID to query the job''s status, retrieve results, or diagnose any errors related to the job. This ID is returned upon successful job submission and required for all follow-up actions related to the batch.

            '
    CreateSegmentRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: The name of the segment. Cannot be empty or whitespace only. Leading and trailing whitespace will be trimmed.
          example: Loyalty Gold Members
          minLength: 1
          maxLength: 240
        description:
          type: string
          description: Optional description of the segment. If not provided, defaults to "Manual Segment Upload Public API V2". When provided, cannot be empty or whitespace only and must be at least 2 characters. Leading and trailing whitespace will be trimmed.
          example: Customers with gold loyalty status
          minLength: 2
          maxLength: 500
        externalId:
          type: string
          description: Auto generated if not supplied. Optional externalId set on the segment. Cannot be empty or whitespace only. Leading and trailing whitespace will be trimmed.
          example: SEG_abc123def456
          minLength: 1
          maxLength: 255
    PatchSegmentRequest:
      type: object
      properties:
        name:
          type: string
          description: The name of the segment. If provided, cannot be empty or whitespace only and must be at most 240 characters. Leading and trailing whitespace will be trimmed. At least one field (name or description) must be provided for PATCH.
          example: Loyalty Gold Members Updated
          minLength: 1
          maxLength: 240
        description:
          type: string
          description: The description of the segment. If provided, cannot be empty or whitespace only, must be at least 2 characters, and at most 500 characters. Leading and trailing whitespace will be trimmed. At least one field (name or description) must be provided for PATCH.
          example: Updated description
          minLength: 2
          maxLength: 500
    CreateSegmentResponse:
      type: object
      properties:
        externalId:
          type: string
          description: The external segment ID (client-facing identifier)
          example: loyalty_gold_2025
        name:
          type: string
          description: The name of the segment
          example: Loyalty Gold Members
        description:
          type: string
          description: The description of the segment
          example: Customers with gold loyalty status
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    OAuthFlow:
      type: oauth2
      description: This API uses OAuth 2 with the authorization code grant flow. [More info](https://docs.attentivemobile.com/pages/authentication/)
      flows:
        authorizationCode:
          authorizationUrl: https://ui-devel.attentivemobile.com/integrations/oauth-install?client_id={clientId}&redirect_uri={redirectUri}&scope={scope}
          tokenUrl: https://api.attentivemobile.com/v1/authorization-codes/tokens
          scopes:
            attributes:write: read and write custom attributes
            subscriptions:write: read and write subscriptions
            events:write: read and write custom events
            ecommerce:write: read and write ecommerce events
            segments:write: read and write segments
            segments:read: read segments
x-readme:
  explorer-enabled: false