Extole Promotion Links API
The Promotion Links API from Extole — 2 operation(s) for promotion links.
OpenAPI Specification
openapi: 3.0.1
info:
description: 'Consumer-to-Extole integration endpoints: consumer event submission, zone rendering, profile management, and SDK-backing operations for browser and native app environments.'
title: Integration API - Consumer to Extole Audiences Promotion Links API
version: '1.0'
servers:
- description: Production
url: https://{brand}.extole.io
variables:
brand:
default: yourcompany
description: Your Extole client subdomain (e.g. 'mycompany' for mycompany.extole.io)
security:
- HEADER: []
- QUERY: []
- COOKIE: []
tags:
- name: Promotion Links
paths:
/v2/promotion-links:
get:
description: Returns all promotion links for the client. Promotion links are the short URLs that participants share to drive referrals.
operationId: listPromotionLinks
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/PromotionLinkResponse'
type: array
description: Successful response
'400':
content:
application/json:
examples:
binding_error:
$ref: '#/components/examples/binding_error'
invalid_json:
$ref: '#/components/examples/invalid_json'
invalid_parameter:
$ref: '#/components/examples/invalid_parameter'
missing_request_body:
$ref: '#/components/examples/missing_request_body'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Bad Request
'401':
content:
application/json:
examples:
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unauthorized
'402':
content:
application/json:
examples:
payment_required:
$ref: '#/components/examples/payment_required'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Payment Required
'403':
content:
application/json:
examples:
access_denied:
$ref: '#/components/examples/access_denied'
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
missing_access_token:
$ref: '#/components/examples/missing_access_token'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Forbidden
'415':
content:
application/json:
examples:
unsupported_media_type:
$ref: '#/components/examples/unsupported_media_type'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unsupported Media Type
'429':
content:
application/json:
examples:
too_many_requests:
$ref: '#/components/examples/too_many_requests'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Too Many Requests
summary: List promotion links
tags:
- Promotion Links
x-extole-bundle: management
x-extole-visibility: visible
post:
description: Creates a new promotion link for a participant. Returns the created link with its server-assigned id.
operationId: createPromotionLink
requestBody:
content:
application/json:
example:
code: code
content:
content_id: content_id
description: description
image_url: image_url
title: title
url: url
data:
data_key: data_key
description: description
key: key
label: label
program_url: program_url
schema:
$ref: '#/components/schemas/PromotionLinkCreateRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PromotionLinkResponse'
description: Successful response
'400':
content:
application/json:
examples:
binding_error:
$ref: '#/components/examples/binding_error'
code_contains_reserved_word:
$ref: '#/components/examples/code_contains_reserved_word'
code_invalid:
$ref: '#/components/examples/code_invalid'
code_length_out_of_range:
$ref: '#/components/examples/code_length_out_of_range'
code_taken:
$ref: '#/components/examples/code_taken'
content_image_url_invalid:
$ref: '#/components/examples/content_image_url_invalid'
content_url_invalid:
$ref: '#/components/examples/content_url_invalid'
data_attribute_name_invalid:
$ref: '#/components/examples/data_attribute_name_invalid'
data_attribute_name_length_out_of_range:
$ref: '#/components/examples/data_attribute_name_length_out_of_range'
data_attribute_value_invalid:
$ref: '#/components/examples/data_attribute_value_invalid'
data_attribute_value_length_out_of_range:
$ref: '#/components/examples/data_attribute_value_length_out_of_range'
description_length_out_of_range:
$ref: '#/components/examples/description_length_out_of_range'
invalid_json:
$ref: '#/components/examples/invalid_json'
invalid_parameter:
$ref: '#/components/examples/invalid_parameter'
label_contains_illegal_character:
$ref: '#/components/examples/label_contains_illegal_character'
missing_request_body:
$ref: '#/components/examples/missing_request_body'
program_not_found:
$ref: '#/components/examples/program_not_found'
program_url_invalid:
$ref: '#/components/examples/program_url_invalid'
promotion_label_name_out_of_range:
$ref: '#/components/examples/promotion_label_name_out_of_range'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Bad Request
'401':
content:
application/json:
examples:
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unauthorized
'402':
content:
application/json:
examples:
payment_required:
$ref: '#/components/examples/payment_required'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Payment Required
'403':
content:
application/json:
examples:
access_denied:
$ref: '#/components/examples/access_denied'
code_missing:
$ref: '#/components/examples/code_missing'
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
missing_access_token:
$ref: '#/components/examples/missing_access_token'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Forbidden
'415':
content:
application/json:
examples:
unsupported_media_type:
$ref: '#/components/examples/unsupported_media_type'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unsupported Media Type
'429':
content:
application/json:
examples:
too_many_requests:
$ref: '#/components/examples/too_many_requests'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Too Many Requests
summary: Create a promotion link
tags:
- Promotion Links
x-extole-bundle: management
x-extole-visibility: visible
/v2/promotion-links/{code}:
get:
description: Returns the promotion link for the specified code.
operationId: getPromotionLink
parameters:
- in: path
name: code
required: true
schema:
pattern: .+
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PromotionLinkResponse'
description: Successful response
'400':
content:
application/json:
examples:
binding_error:
$ref: '#/components/examples/binding_error'
invalid_json:
$ref: '#/components/examples/invalid_json'
invalid_parameter:
$ref: '#/components/examples/invalid_parameter'
missing_request_body:
$ref: '#/components/examples/missing_request_body'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Bad Request
'401':
content:
application/json:
examples:
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unauthorized
'402':
content:
application/json:
examples:
payment_required:
$ref: '#/components/examples/payment_required'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Payment Required
'403':
content:
application/json:
examples:
access_denied:
$ref: '#/components/examples/access_denied'
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
missing_access_token:
$ref: '#/components/examples/missing_access_token'
promotion_link_not_found:
$ref: '#/components/examples/promotion_link_not_found'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Forbidden
'415':
content:
application/json:
examples:
unsupported_media_type:
$ref: '#/components/examples/unsupported_media_type'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unsupported Media Type
'429':
content:
application/json:
examples:
too_many_requests:
$ref: '#/components/examples/too_many_requests'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Too Many Requests
summary: Get a promotion link
tags:
- Promotion Links
x-extole-bundle: management
x-extole-visibility: visible
components:
examples:
invalid_json:
summary: invalid_json
value:
code: invalid_json
http_status_code: 400
message: JSON is invalid
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
description_length_out_of_range:
summary: description_length_out_of_range
value:
code: description_length_out_of_range
http_status_code: 400
message: Description is too long
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
code_missing:
summary: code_missing
value:
code: code_missing
http_status_code: 403
message: Missing code
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
program_not_found:
summary: program_not_found
value:
code: program_not_found
http_status_code: 400
message: Promotion link program not found
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
content_image_url_invalid:
summary: content_image_url_invalid
value:
code: content_image_url_invalid
http_status_code: 403
message: Invalid content image_url
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
data_attribute_value_length_out_of_range:
summary: data_attribute_value_length_out_of_range
value:
code: data_attribute_value_length_out_of_range
http_status_code: 403
message: Shareable data attribute value length is out of range. Max 2000 chars
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
payment_required:
summary: payment_required
value:
code: payment_required
http_status_code: 402
message: The access_token provided is associated with an unpaid account.
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
missing_access_token:
summary: missing_access_token
value:
code: missing_access_token
http_status_code: 403
message: No access_token was provided with this request.
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
code_taken:
summary: code_taken
value:
code: code_taken
http_status_code: 403
message: The code associated with this shareable has already been specified
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
unsupported_media_type:
summary: unsupported_media_type
value:
code: unsupported_media_type
http_status_code: 415
message: Request had an unsupported or no media type
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
label_contains_illegal_character:
summary: label_contains_illegal_character
value:
code: label_contains_illegal_character
http_status_code: 400
message: Label name can only contain alphanumeric, dash and underscore characters
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
method_unauthorized:
summary: method_unauthorized
value:
code: method_unauthorized
http_status_code: 401
message: Unauthorized access to this endpoint
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
promotion_link_not_found:
summary: promotion_link_not_found
value:
code: promotion_link_not_found
http_status_code: 403
message: Promotion link not found
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
promotion_label_name_out_of_range:
summary: promotion_label_name_out_of_range
value:
code: promotion_label_name_out_of_range
http_status_code: 400
message: Promotion label name is not of valid length
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
code_contains_reserved_word:
summary: code_contains_reserved_word
value:
code: code_contains_reserved_word
http_status_code: 403
message: Shareable code contains reserved word
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
missing_request_body:
summary: missing_request_body
value:
code: missing_request_body
http_status_code: 400
message: Missing request body
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
program_url_invalid:
summary: program_url_invalid
value:
code: program_url_invalid
http_status_code: 400
message: Promotion link program url is invalid
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
data_attribute_value_invalid:
summary: data_attribute_value_invalid
value:
code: data_attribute_value_invalid
http_status_code: 403
message: Shareable data value is invalid
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
access_denied:
summary: access_denied
value:
code: access_denied
http_status_code: 403
message: The access_token provided is not permitted to access the specified resource.
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
binding_error:
summary: binding_error
value:
code: binding_error
http_status_code: 400
message: Argument is not of the expected type
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
too_many_requests:
summary: too_many_requests
value:
code: too_many_requests
http_status_code: 429
message: The server is unable to process your request at the moment, please retry later.
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
invalid_parameter:
summary: invalid_parameter
value:
code: invalid_parameter
http_status_code: 400
message: Parameter is invalid.
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
data_attribute_name_invalid:
summary: data_attribute_name_invalid
value:
code: data_attribute_name_invalid
http_status_code: 403
message: Shareable data attribute name is invalid
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
content_url_invalid:
summary: content_url_invalid
value:
code: content_url_invalid
http_status_code: 400
message: Promotion link content url is invalid
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
data_attribute_name_length_out_of_range:
summary: data_attribute_name_length_out_of_range
value:
code: data_attribute_name_length_out_of_range
http_status_code: 403
message: Shareable data attribute name length is out of range. Max 200 chars
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
code_length_out_of_range:
summary: code_length_out_of_range
value:
code: code_length_out_of_range
http_status_code: 400
message: Promotion link code length must be between 4 and 50
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
code_invalid:
summary: code_invalid
value:
code: code_invalid
http_status_code: 400
message: Promotion link code can only contain alphanumeric characters, dashes and underscores
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
schemas:
PromotionLinkContentResponse:
properties:
content_id:
type: string
description:
type: string
image_url:
type: string
title:
type: string
url:
type: string
type: object
PromotionLinkResponse:
properties:
code:
type: string
content:
$ref: '#/components/schemas/PromotionLinkContentResponse'
data:
additionalProperties:
type: string
type: object
description:
type: string
key:
type: string
label:
type: string
program_url:
type: string
promotion_url:
type: string
required:
- code
- content
- data
- description
- key
- label
- program_url
- promotion_url
type: object
PromotionLinkCreateRequest:
description: Body of a `POST /v2/promotion-links` request.
properties:
code:
type: string
content:
$ref: '#/components/schemas/PromotionLinkContentRequest'
data:
additionalProperties:
type: string
type: object
description:
nullable: true
type: string
key:
nullable: true
type: string
label:
type: string
program_url:
nullable: true
type: string
required:
- code
- key
- program_url
type: object
PromotionLinkContentRequest:
properties:
content_id:
nullable: true
type: string
description:
nullable: true
type: string
image_url:
nullable: true
type: string
title:
nullable: true
type: string
url:
nullable: true
type: string
type: object
RestExceptionResponse:
description: Represents the API error response
properties:
code:
description: Specific error code for this error type, documented per endpoint
type: string
http_status_code:
description: HTTP status code that was returned with this error, useful if client get response code
format: int32
type: integer
message:
description: User readable English description of the error
type: string
parameters:
additionalProperties:
description: Attributes related to the error, varies be error code, documented per endpoint
type: object
description: Attributes related to the error, varies be error code, documented per endpoint
type: object
unique_id:
description: Unique id associated with this error, useful for discussions with Extole
type: string
required:
- code
- http_status_code
- message
- parameters
- unique_id
type: object
securitySchemes:
COOKIE:
in: cookie
name: extole_token
type: apiKey
HEADER:
in: header
name: Authorization
type: apiKey
x-bearer-format: bearer
QUERY:
in: query
name: access_token
type: apiKey
x-tagGroups:
- name: Integration API - Consumer to Extole
tags:
- Authentication
- Content
- Email
- Events
- Persons
- Profile Assets
- Profiles