The Eligibility API from Bluecore — 2 operation(s) for eligibility.
openapi: 3.0.3
info:
title: Bluecore Authn Eligibility API
version: 0.0.1
description: The Bluecore API supports the REST architecture style and uses JSON requests and responses. It exposes Bluecore's Customer (Shopper) profiles, Eligibility (subscription/consent) management, and Communicate (Direct Send + Transactional messaging) surfaces, plus OAuth 2.0 client-credentials authentication. Harvested by API Evangelist from the per-operation OpenAPI definitions published at developers.bluecore.com.
contact:
name: Bluecore Support
email: support@bluecore.com
url: https://developers.bluecore.com/
servers:
- url: https://a.bluecore.com/api
description: Bluecore API server
tags:
- name: Eligibility
paths:
/namespaces/{namespace}/eligibility:
get:
tags:
- Eligibility
summary: Retrieve Eligibility Status
operationId: Eligibility_Get
parameters:
- name: namespace
in: path
description: The Bluecore environment, which is a unique identifier that contains integrations, data feeds, and campaigns.
required: true
schema:
type: string
example: bluestore
- name: email
in: query
description: The primary identifier that represents the customer’s email address. See [Email address](https://developers.bluecore.com/docs/email-address#/) for information on how they are normalized and validated.
schema:
type: string
- name: phone_number
in: query
description: The secondary identifier that represents the customer’s phone number. E.164 format.
schema:
type: string
responses:
'200':
description: OK
headers:
x-ratelimit-limit:
description: The number of allowed requests in the current period
schema:
example: 700;w=60;burst=75;w=1
type: string
format: quota-policy
x-ratelimit-remaining:
description: The number of remaining requests in the current time window
schema:
type: integer
x-ratelimit-reset:
description: The number of seconds until reset of the current time window
schema:
type: integer
x-bluecore-id:
description: Request id to trace the logs for this particular request.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/eligibility.public.GetResponse'
examples:
get_email_eligibility:
summary: Get Email Eligibility
value:
data:
namespace: bluestore
subscription:
id:
email: alice@gmail.com
states:
- consented_at: '2025-08-24T15:22:09.650080419Z'
message_type: MARKETING
source: public-api
status: SUBSCRIBED
get_sms_eligibility:
summary: Get SMS Eligibility
value:
data:
namespace: bluestore
subscription:
id:
phone_number: '+15556667777'
states:
- consented_at: '2025-08-24T15:22:09.650080419Z'
message_type: MARKETING
source: public-api
status: SUBSCRIBED
'429':
description: ''
headers:
x-ratelimit-limit:
description: The number of allowed requests in the current period
schema:
example: 700;w=60;burst=75;w=1
type: string
format: quota-policy
x-ratelimit-remaining:
description: The number of remaining requests in the current time window
schema:
type: integer
x-ratelimit-reset:
description: The number of seconds until reset of the current time window
schema:
type: integer
x-bluecore-id:
description: Request id to trace the logs for this particular request.
schema:
type: string
content:
application/json: {}
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/google.rpc.Status'
security:
- GlooAuth:
- eligibility.read
/namespaces/{namespace}/eligibility_events:
post:
tags:
- Eligibility
summary: Update Eligibility Status
operationId: Eligibility_Update
parameters:
- name: namespace
in: path
description: The Bluecore environment, which is a unique identifier that contains integrations, data feeds, and campaigns.
required: true
schema:
type: string
example: bluestore
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Eligibility_Update_eligibility.public.UpdateRequest'
examples:
update_email_eligibility:
summary: Update Email Eligibility
value:
id:
email: alice@gmail.com
state:
consented_at: '2025-08-22T12:29:20.650080419Z'
event: OPTIN
message_type: MARKETING
update_sms_eligibility:
summary: Update SMS Eligibility
value:
id:
phone_number: '+15556667777'
state:
channel_identifier: '+15556667777'
consented_at: '2025-08-22T12:29:20.650080419Z'
event: OPTIN
message_type: MARKETING
required: true
responses:
'200':
description: OK
headers:
x-ratelimit-limit:
description: The number of allowed requests in the current period
schema:
example: 700;w=60;burst=75;w=1
type: string
format: quota-policy
x-ratelimit-remaining:
description: The number of remaining requests in the current time window
schema:
type: integer
x-ratelimit-reset:
description: The number of seconds until reset of the current time window
schema:
type: integer
x-bluecore-id:
description: Request id to trace the logs for this particular request.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/eligibility.public.UpdateResponse'
examples:
update_email_eligibility:
summary: Update Email Eligibility
value:
data:
namespace: bluestore
subscription:
id:
email: alice@gmail.com
states:
- consented_at: '2025-08-24T15:22:09.650080419Z'
message_type: MARKETING
source: public-api
status: SUBSCRIBED
update_sms_eligibility:
summary: Update SMS Eligibility
value:
data:
namespace: bluestore
subscription:
id:
phone_number: '+15556667777'
states:
- channel_identifier: '+15556667777'
consented_at: '2025-08-24T15:22:09.650080419Z'
message_type: MARKETING
source: public-api
status: SUBSCRIBED
'429':
description: ''
headers:
x-ratelimit-limit:
description: The number of allowed requests in the current period
schema:
example: 700;w=60;burst=75;w=1
type: string
format: quota-policy
x-ratelimit-remaining:
description: The number of remaining requests in the current time window
schema:
type: integer
x-ratelimit-reset:
description: The number of seconds until reset of the current time window
schema:
type: integer
x-bluecore-id:
description: Request id to trace the logs for this particular request.
schema:
type: string
content:
application/json: {}
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/google.rpc.Status'
security:
- GlooAuth:
- eligibility.write
components:
schemas:
eligibility.public.SubscriptionEvent:
type: object
allOf:
- type: object
properties:
event:
type: string
description: "The eligibility update. The available options are: \n\n - `OPTIN` opts the customer in to receive email campaigns if the `email` parameter was sent or SMS/MMS campaigns if the `phone_number` was sent. This can only be used for single opt-in SMS/MMS workflows.\n - `UNSUBSCRIBE` unsubscribes the customer from email campaigns if the `email` parameter` was sent or SMS/MMS campaigns if the `phone_number` was sent.\n - `SIGNUP` is used in the double opt-in flow for SMS/MMS campaigns. This sets the status to `pending_confirmation` and sends the customer the double opt-in message."
consented_at:
type: string
description: The timestamp that this update was known to be accurate. The semantic time the update took place. For example, if the data is from last week's activity, set the value to that time. When unset, it defaults to when the backend receives the request.
format: date-time
message_type:
type: string
description: The campaign type for which eligibility is updated.
channel_identifier:
type: string
description: The send code used to deliver a double opt-in message to the customer. If left blank, the system selects the first short code in the Namespace. If no short code is available, the first toll free number is used. For more information, see [Understand SMS short codes.](https://help.bluecore.com/en/articles/5624524-understanding-sms-sending-codes)
eligibility.public.SubscriptionDetails:
type: object
allOf:
- type: object
properties:
source:
type: string
description: "How the eligibility was updated. The available options are: \n\n - `integration` is an update from the Events API or Bluecore Website Integration.\n - `public-api` is an update from the Eligibility API.\n - `upload` is an update from a file import."
consented_at:
type: string
description: The timestamp that this update was known to be accurate. The semantic time the update took place. For example, if the data is from last week's activity, set the value to that time. When unset, it defaults to when the backend receives the request.
format: date-time
message_type:
enum:
- MARKETING
- TRANSACTIONAL
type: string
description: The campaign type for which eligibility is updated.
format: enum
channel_identifier:
type: string
description: The send code used to deliver a double opt-in message to the customer. If left blank, the system selects the first short code in the Namespace. If no short code is available, the first toll free number is used. For more information, see [Understand SMS short codes.](https://help.bluecore.com/en/articles/5624524-understanding-sms-sending-codes)
status:
enum:
- PENDING_CONFIRMATION
- SUBSCRIBED
- UNSUBSCRIBED
type: string
description: "The customer's eligibility subscription status \n\n - `SUBSCRIBED` means the customer has opted in to receive marketing communication.\n - `UNSUBSCRIBED` means the customer has unsubscribed from receiving marketing communication.\n - `NOT_KNOWN` means that the customer has neither subscribed to nor unsubscribed from receiving marketing communication.\n\n\n\n\nFor more information on eligibility statuses, see [Understand email eligibility](https://help.bluecore.com/help/understand-email-eligibility) and [Understand SMS/MMS eligibility](http://help.bluecore.com/en/articles/6252691-understand-sms-mms-eligibility)."
format: enum
Eligibility_Update_eligibility.public.UpdateRequest:
required:
- id
type: object
properties:
id:
allOf:
- $ref: '#/components/schemas/eligibility.public.Identifier'
description: Identifier the subscription statuses are for
state:
allOf:
- $ref: '#/components/schemas/eligibility.public.SubscriptionEvent'
description: List of eligibility update actions
google.rpc.Status:
type: object
properties:
code:
type: integer
description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
format: int32
message:
type: string
description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
details:
type: array
items:
$ref: '#/components/schemas/google.protobuf.Any'
description: A list of messages that carry the error details. There is a common set of message types for APIs to use.
description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).'
eligibility.public.GetResponse:
type: object
properties:
data:
$ref: '#/components/schemas/eligibility.public.Subscriptions'
eligibility.public.Subscription:
type: object
properties:
id:
allOf:
- $ref: '#/components/schemas/customers.Identifier'
description: Who the subscription statuses are for
states:
type: array
items:
$ref: '#/components/schemas/eligibility.public.SubscriptionDetails'
description: Subscription details for marketing type
eligibility.public.Subscriptions:
type: object
properties:
namespace:
type: string
description: The Bluecore environment, which is a unique identifier that contains integrations, data feeds, and campaigns.
subscription:
allOf:
- $ref: '#/components/schemas/eligibility.public.Subscription'
description: Each entry reflects the channel's current subscription state for a message type
customers.Identifier:
type: object
allOf:
- oneOf:
- title: email
type: object
properties:
email:
type: string
description: 'The email address for the customer. It must be "valid" according to Bluecore''s current policy (Python: bluecore.email.validate_email), and lower-cased (Python: bluecore.email.clean_email).'
- title: phone_number
type: object
properties:
phone_number:
type: string
description: An phone number
description: A customer identifier used for lookups
eligibility.public.UpdateResponse:
type: object
properties:
data:
$ref: '#/components/schemas/eligibility.public.Subscriptions'
eligibility.public.Identifier:
type: object
allOf:
- oneOf:
- title: email
type: object
properties:
email:
example: alice@gmail.com
maxLength: 254
type: string
description: The primary identifier that represents the customer’s email address. See [Email address](https://developers.bluecore.com/docs/email-address#/) for information on how they are normalized and validated.
format: email
- title: phone_number
type: object
properties:
phone_number:
example: '+15556667777'
pattern: ^\+?[1-9]\d{0,14}$
type: string
description: The secondary identifier that represents the customer’s phone number. E.164 format.
format: e.164
google.protobuf.Any:
type: object
properties:
'@type':
type: string
description: The type of the serialized message.
additionalProperties: true
description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
securitySchemes:
GlooAuth:
type: apiKey
in: header
name: authorization
description: Value for the authorization header will be Bearer followed by the token generated with the [Get access token](https://developers.bluecore.com/reference/authn_getaccesstoken#/) call.
x-default: Bearer token