Extole Content API
The Content API from Extole — 6 operation(s) for content.
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 Content 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: Content
paths:
/api/v6/zones:
post:
description: API-friendly zone rendering at `POST /api/v6/zones`. Intended for backend rendering where the caller supplies a bearer access token directly. Renders the zone identified by `event_name` in the JSON request body and returns the structured zone content as JSON. Returns an error when no content backs the zone. For browser or in-app rendering use `POST /zones` instead.
operationId: renderZone
requestBody:
content:
application/json:
example:
data:
data_key: {}
event_name: event_name
id_token: id_token
jwt: jwt
schema:
$ref: '#/components/schemas/RenderZoneRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/RenderZoneRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ZoneResponse'
description: Zone content.
'400':
content:
application/json:
examples:
invalid_creative_result:
$ref: '#/components/examples/invalid_creative_result'
invalid_zone_name:
$ref: '#/components/examples/invalid_zone_name'
missing_zone_name:
$ref: '#/components/examples/missing_zone_name'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: 'Zone rendering failed: `missing_zone_name` if no zone name was supplied in the request body, `invalid_zone_name` if the name is not recognised by the client''s campaign configuration, or `invalid_creative_result` if the configured creative did not return valid JSON.'
'401':
content:
application/json:
examples:
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unauthorized
'403':
content:
application/json:
examples:
access_denied:
$ref: '#/components/examples/access_denied'
expired_access_token:
$ref: '#/components/examples/expired_access_token'
invalid_access_token:
$ref: '#/components/examples/invalid_access_token'
jwt_authentication_error:
$ref: '#/components/examples/jwt_authentication_error'
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: Render a zone
tags:
- Content
x-extole-bundle: integration-consumer-to-extole
x-extole-visibility: visible
/api/v6/zones/{event_name}:
post:
description: API-friendly zone rendering at `POST /api/v6/zones/{event_name}`. Intended for backend rendering where the caller supplies a bearer access token directly. Renders the zone identified by the `event_name` path parameter and returns the structured zone content as JSON. Pass zone input data in the request body. Returns an error when no content backs the zone. For browser or in-app rendering use `POST /zones/{zone_name}` instead.
operationId: renderZoneByEventName
parameters:
- in: path
name: event_name
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
value: {}
schema:
additionalProperties:
type: object
type: object
application/x-www-form-urlencoded:
schema:
additionalProperties:
type: object
type: object
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ZoneResponse'
description: Zone content.
'400':
content:
application/json:
examples:
invalid_creative_result:
$ref: '#/components/examples/invalid_creative_result'
invalid_zone_name:
$ref: '#/components/examples/invalid_zone_name'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: 'Zone rendering failed: `invalid_zone_name` if the zone name from the URL path is not recognised by the client''s campaign configuration, or `invalid_creative_result` if the configured creative did not return valid JSON.'
'401':
content:
application/json:
examples:
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unauthorized
'403':
content:
application/json:
examples:
access_denied:
$ref: '#/components/examples/access_denied'
expired_access_token:
$ref: '#/components/examples/expired_access_token'
invalid_access_token:
$ref: '#/components/examples/invalid_access_token'
jwt_authentication_error:
$ref: '#/components/examples/jwt_authentication_error'
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: Render a named zone
tags:
- Content
x-extole-bundle: integration-consumer-to-extole
x-extole-visibility: visible
/zones:
post:
description: 'Web-friendly zone rendering at `POST /zones`. Intended for direct use from a browser page or web SDK embed — accepts form-encoded, plain-text, and multipart bodies in addition to JSON, and handles cookie-based identity automatically. Renders the zone identified by `event_name` in the request body, applies any other body fields as targeting data passed to the creative, and returns the rendered creative content (HTML, JavaScript, JSON, or plain text). If `event_name` is omitted, returns an empty 200 with `Extole-Log: target zone=unknown`; the access token is still allocated and written as a cookie. For backend zone rendering use `POST /api/v6/zones` instead.'
operationId: renderZoneWeb
requestBody:
content:
application/json:
example:
data:
data_key: {}
event_name: event_name
id_token: id_token
jwt: jwt
schema:
$ref: '#/components/schemas/RenderZoneRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/RenderZoneRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/RenderZoneRequest'
text/plain:
schema:
$ref: '#/components/schemas/RenderZoneRequest'
responses:
'200':
content:
'*/*':
schema:
type: string
description: 'Rendered zone content. The response body shape varies by the zone''s creative configuration: HTML, JavaScript, JSON, or plain text.'
'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
'403':
content:
application/json:
examples:
access_denied:
$ref: '#/components/examples/access_denied'
expired_access_token:
$ref: '#/components/examples/expired_access_token'
invalid_access_token:
$ref: '#/components/examples/invalid_access_token'
jwt_authentication_error:
$ref: '#/components/examples/jwt_authentication_error'
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: Render a zone with the name in the body
tags:
- Content
x-extole-bundle: integration-consumer-to-extole
x-extole-visibility: visible
/zones/{zone_name}:
post:
description: Web-friendly zone rendering at `POST /zones/{zone_name}`. Intended for direct use from a browser page or web SDK embed — accepts form-encoded and multipart bodies in addition to JSON, and handles cookie-based identity automatically. Renders the zone identified by `zone_name` and returns its content (HTML, JavaScript, JSON, or plain text). For backend zone rendering use `POST /api/v6/zones/{event_name}` instead.
operationId: renderZoneByNameWeb
parameters:
- in: path
name: zone_name
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
value: {}
schema:
additionalProperties:
type: object
type: object
application/x-www-form-urlencoded:
schema:
additionalProperties:
type: object
type: object
multipart/form-data:
schema:
additionalProperties:
type: object
type: object
text/plain:
schema:
additionalProperties:
type: object
type: object
responses:
'200':
content:
'*/*':
schema:
type: string
description: 'Rendered zone content. The response body shape varies by the zone''s creative configuration: HTML, JavaScript, JSON, or plain text.'
'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
'403':
content:
application/json:
examples:
access_denied:
$ref: '#/components/examples/access_denied'
expired_access_token:
$ref: '#/components/examples/expired_access_token'
invalid_access_token:
$ref: '#/components/examples/invalid_access_token'
jwt_authentication_error:
$ref: '#/components/examples/jwt_authentication_error'
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: Render a named zone for web-page embedding
tags:
- Content
x-extole-bundle: integration-consumer-to-extole
x-extole-visibility: visible
/web/me/assets/download:
get:
operationId: downloadAssetByName_2
parameters:
- in: query
name: name
schema:
type: string
- in: query
name: default_url
schema:
type: string
responses:
'200':
content:
'*/*': {}
description: Successful response
'400':
content:
application/json:
examples:
asset_content_not_downloadable:
$ref: '#/components/examples/asset_content_not_downloadable'
asset_not_found:
$ref: '#/components/examples/asset_not_found'
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
'403':
content:
application/json:
examples:
access_denied:
$ref: '#/components/examples/access_denied'
expired_access_token:
$ref: '#/components/examples/expired_access_token'
invalid_access_token:
$ref: '#/components/examples/invalid_access_token'
jwt_authentication_error:
$ref: '#/components/examples/jwt_authentication_error'
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
tags:
- Content
x-extole-bundle: integration-consumer-to-extole
x-extole-visibility: expert
/web/me/assets/{assetId}/download:
get:
operationId: downloadAssetById_2
parameters:
- in: path
name: assetId
required: true
schema:
type: string
- in: query
name: default_url
schema:
type: string
responses:
'200':
content:
'*/*': {}
description: Successful response
'400':
content:
application/json:
examples:
asset_content_not_downloadable:
$ref: '#/components/examples/asset_content_not_downloadable'
asset_not_found:
$ref: '#/components/examples/asset_not_found'
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
'403':
content:
application/json:
examples:
access_denied:
$ref: '#/components/examples/access_denied'
expired_access_token:
$ref: '#/components/examples/expired_access_token'
invalid_access_token:
$ref: '#/components/examples/invalid_access_token'
jwt_authentication_error:
$ref: '#/components/examples/jwt_authentication_error'
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
tags:
- Content
x-extole-bundle: integration-consumer-to-extole
x-extole-visibility: expert
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
expired_access_token:
summary: expired_access_token
value:
code: expired_access_token
http_status_code: 403
message: The access_token provided with this request has expired.
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
invalid_zone_name:
summary: invalid_zone_name
value:
code: invalid_zone_name
http_status_code: 403
message: Invalid zone name (not an EMAIL zone)
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
asset_not_found:
summary: asset_not_found
value:
code: asset_not_found
http_status_code: 400
message: Asset not found
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
invalid_creative_result:
summary: invalid_creative_result
value:
code: invalid_creative_result
http_status_code: 400
message: Configured creative did not return json.
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
jwt_authentication_error:
summary: jwt_authentication_error
value:
code: jwt_authentication_error
http_status_code: 403
message: The jwt authentication failed.
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
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
missing_zone_name:
summary: missing_zone_name
value:
code: missing_zone_name
http_status_code: 400
message: Zone name must be present
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
invalid_access_token:
summary: invalid_access_token
value:
code: invalid_access_token
http_status_code: 403
message: The access_token provided with this request is invalid.
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
asset_content_not_downloadable:
summary: asset_content_not_downloadable
value:
code: asset_content_not_downloadable
http_status_code: 400
message: Asset content could not be downloaded
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
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
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
schemas:
ZoneResponse:
properties:
campaign_id:
description: Extole campaign id that served this zone. Absent if not determinable.
type: string
data:
additionalProperties:
description: Creative output for this zone. Structure varies by campaign configuration.
type: object
description: Creative output for this zone. Structure varies by campaign configuration.
type: object
event_id:
description: Extole event id generated for this zone render request.
type: string
required:
- campaign_id
- data
- event_id
type: object
RenderZoneRequest:
properties:
data:
additionalProperties:
type: object
nullable: true
type: object
event_name:
type: string
id_token:
nullable: true
type: string
jwt:
nullable: true
type: string
required:
- data
- event_name
- id_token
- jwt
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