Extole Components Types API
The Components Types API from Extole — 3 operation(s) for components types.
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 Components Types 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: Components Types
paths:
/v1/component-types:
get:
description: Returns component type definitions for the calling client, filtered by the supplied query parameters. Component types define the structure (settings, facets) of campaign components. Use `GET /v1/component-types/default` to retrieve the platform-default types.
operationId: listComponentTypes
parameters:
- in: query
name: parent
schema:
type: string
- in: query
name: include_archived
schema:
type: boolean
- in: query
name: limit
schema:
format: int32
type: integer
- in: query
name: offset
schema:
format: int32
type: integer
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ComponentTypeResponse'
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 component types
tags:
- Components Types
x-extole-bundle: management-expert
x-extole-visibility: expert
post:
description: Creates a new component type definition and returns the persisted record. Component types are typically managed by Extole staff; this endpoint is marked `expert`.
operationId: createComponentType
requestBody:
content:
application/json:
example:
display_name: display_name
name: name
parent: parent
schema: schema
schema:
$ref: '#/components/schemas/ComponentTypeCreateRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ComponentTypeResponse'
description: Successful response
'400':
content:
application/json:
examples:
binding_error:
$ref: '#/components/examples/binding_error'
component_type_display_name_contains_illegal_characters:
$ref: '#/components/examples/component_type_display_name_contains_illegal_characters'
component_type_name_already_used:
$ref: '#/components/examples/component_type_name_already_used'
component_type_name_contains_illegal_characters:
$ref: '#/components/examples/component_type_name_contains_illegal_characters'
invalid_component_type_display_name_length:
$ref: '#/components/examples/invalid_component_type_display_name_length'
invalid_component_type_name_length:
$ref: '#/components/examples/invalid_component_type_name_length'
invalid_component_type_parent:
$ref: '#/components/examples/invalid_component_type_parent'
invalid_component_type_schema:
$ref: '#/components/examples/invalid_component_type_schema'
invalid_json:
$ref: '#/components/examples/invalid_json'
invalid_parameter:
$ref: '#/components/examples/invalid_parameter'
missing_component_type_name:
$ref: '#/components/examples/missing_component_type_name'
missing_component_type_schema:
$ref: '#/components/examples/missing_component_type_schema'
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: Create a component type
tags:
- Components Types
x-extole-bundle: management-expert
x-extole-visibility: expert
/v1/component-types/default:
get:
description: Returns the platform-default component type definitions. Default types are provided by Extole and are available to all clients.
operationId: listDefaultComponentTypes
parameters:
- in: query
name: parent
schema:
type: string
- in: query
name: include_archived
schema:
type: boolean
- in: query
name: limit
schema:
format: int32
type: integer
- in: query
name: offset
schema:
format: int32
type: integer
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ComponentTypeResponse'
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 default component types
tags:
- Components Types
x-extole-bundle: management-expert
x-extole-visibility: expert
/v1/component-types/{name}:
get:
description: Returns the component type definition for the supplied name, including its settings schema, facets, and display configuration. Returns `400 component_type_not_found` if the name does not match any accessible type.
operationId: getComponentType
parameters:
- description: Name of the component type to retrieve.
in: path
name: name
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ComponentTypeResponse'
description: Component type definition that describes the settings schema, display metadata, and parent relationship for campaign components.
'400':
content:
application/json:
examples:
component_type_not_found:
$ref: '#/components/examples/component_type_not_found'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Component type was not found. The supplied name does not match any component type accessible to the calling client.
'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: Get a component type
tags:
- Components Types
x-extole-bundle: management-expert
x-extole-visibility: expert
put:
description: Applies a partial update to the supplied component type. Returns `400 component_type_not_found` if the name does not match any accessible type.
operationId: updateComponentType
parameters:
- description: Name of the component type to update.
in: path
name: name
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
display_name: display_name
schema:
$ref: '#/components/schemas/ComponentTypeUpdateRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ComponentTypeResponse'
description: Component type definition that describes the settings schema, display metadata, and parent relationship for campaign components.
'400':
content:
application/json:
examples:
component_type_not_found:
$ref: '#/components/examples/component_type_not_found'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Component type was not found. The supplied name does not match any component type accessible to the calling client.
'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: Update a component type
tags:
- Components Types
x-extole-bundle: management-expert
x-extole-visibility: expert
delete:
description: Archives the supplied component type. Archived types are hidden from the dashboard but their existing component instances remain. Returns `400 component_type_not_found` if the name does not match any accessible type.
operationId: archiveComponentType
parameters:
- description: Name of the component type to archive.
in: path
name: name
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ComponentTypeResponse'
description: Archived component type definition.
'400':
content:
application/json:
examples:
component_type_not_found:
$ref: '#/components/examples/component_type_not_found'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Component type was not found. The supplied name does not match any component type accessible to the calling client.
'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: Archive a component type
tags:
- Components Types
x-extole-bundle: management-expert
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
invalid_component_type_display_name_length:
summary: invalid_component_type_display_name_length
value:
code: invalid_component_type_display_name_length
http_status_code: 400
message: Component type display name length is invalid
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
missing_component_type_name:
summary: missing_component_type_name
value:
code: missing_component_type_name
http_status_code: 400
message: Component type name is not specified
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
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
component_type_name_already_used:
summary: component_type_name_already_used
value:
code: component_type_name_already_used
http_status_code: 400
message: Component type name is already used
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
component_type_not_found:
summary: component_type_not_found
value:
code: component_type_not_found
http_status_code: 400
message: Component type was not found
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
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
missing_component_type_schema:
summary: missing_component_type_schema
value:
code: missing_component_type_schema
http_status_code: 400
message: Component type schema is not specified
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
component_type_display_name_contains_illegal_characters:
summary: component_type_display_name_contains_illegal_characters
value:
code: component_type_display_name_contains_illegal_characters
http_status_code: 400
message: Component type display name should contain alphanumeric, dash, underscore, whitespace, asterisk, hash, dollar characters only
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
component_type_name_contains_illegal_characters:
summary: component_type_name_contains_illegal_characters
value:
code: component_type_name_contains_illegal_characters
http_status_code: 400
message: Component type name should contain alphanumeric, dot, underscore and dash characters only
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
invalid_component_type_schema:
summary: invalid_component_type_schema
value:
code: invalid_component_type_schema
http_status_code: 400
message: Invalid component type schema
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
invalid_component_type_parent:
summary: invalid_component_type_parent
value:
code: invalid_component_type_parent
http_status_code: 400
message: Invalid component type parent
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
invalid_component_type_name_length:
summary: invalid_component_type_name_length
value:
code: invalid_component_type_name_length
http_status_code: 400
message: Component type name length is invalid
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
schemas:
ComponentTypeUpdateRequest:
description: Body of a `PUT /v1/component-types/{name}` request.
properties:
display_name:
nullable: true
type: string
type: object
ComponentTypeCreateRequest:
description: Body of a `POST /v1/component-types` request.
properties:
display_name:
type: string
name:
type: string
parent:
type: string
schema:
type: string
required:
- name
- schema
type: object
ComponentTypeResponse:
description: Component type definition that describes the settings schema, display metadata, and parent relationship for campaign components.
properties:
created_date:
$ref: '#/components/schemas/ZonedDateTime'
display_name:
description: Optional human-readable display name for the component type.
type: string
name:
description: Unique component type name used when creating or filtering campaign components.
type: string
parent:
description: Optional parent component type name inherited by this component type.
type: string
schema:
description: JSON schema that defines the settings and facets available on components of this type.
type: string
updated_date:
$ref: '#/components/schemas/ZonedDateTime'
required:
- created_date
- display_name
- name
- parent
- schema
- updated_date
type: object
ZonedDateTime:
description: '[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) or [RFC 9557](https://datatracker.ietf.org/doc/html/rfc9557#section-4) date-time with a numeric [UTC offset](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and an optional [IANA time-zone](https://datatracker.ietf.org/doc/html/rfc9557#section-4) suffix in square brackets. Precision up to milliseconds.'
example: '2025-10-24T02:00:00-07:00'
pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?(Z|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])(\[[^\]]+\])?$
type: string
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