Attentive Bulk Segment Operations API
The Bulk Segment Operations API from Attentive — 1 operation(s) for bulk segment operations.
OpenAPI Specification
openapi: 3.0.3
info:
description: For any questions, reach out to your Attentive point of contact (if applicable) or [api@attentivemobile.com](mailto:api@attentivemobile.com).
title: Attentive Access Token Bulk Segment Operations API
version: ''
servers:
- url: https://api.attentivemobile.com/v1
description: Attentive API
security:
- bearerAuth: []
tags:
- name: Bulk Segment Operations
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:
- Bulk Segment Operations
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:
- Bulk Segment Operations
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'
components:
responses:
InternalError:
description: Internal Server Error
InvalidParameter:
description: Invalid parameter in request query or body
Unauthorized:
description: Unauthorized
NotFound:
description: The specified resource was not found
TooManyRequests:
description: The user has sent too many requests in a given amount of time
AccessDenied:
description: Access Denied
schemas:
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.
'
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
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