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 Rewards 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: Rewards paths: /v2/rewards: get: description: Returns reward records for the client matching the specified query parameters. operationId: listRewards parameters: - description: Filter by reward state(s). Repeat for multiple values (e.g. `EARNED`, `FULFILLED`). in: query name: state schema: type: string - description: Filter by Extole reward supplier id(s). Repeat for multiple values. in: query name: reward_supplier_id schema: type: string - description: Filter by partner-assigned reward supplier id(s). Repeat for multiple values. in: query name: partner_reward_supplier_id schema: type: string - description: Filter by Extole person id(s). Repeat for multiple values. in: query name: person_id schema: type: string - description: Filter by Extole action id(s). Repeat for multiple values. in: query name: action_id schema: type: string - description: Filter by root event id(s). Repeat for multiple values. in: query name: root_event_id schema: type: string - description: Filter by partner-assigned reward id(s). Repeat for multiple values. in: query name: partner_reward_id schema: type: string - description: Filter by reward type(s). Repeat for multiple values. in: query name: reward_type schema: type: string - description: When true (default), include only rewards that were successfully fulfilled. in: query name: success_only schema: type: boolean - description: ISO 8601 time interval to restrict results to a date range (e.g. `P30D` for last 30 days). in: query name: time_interval schema: type: string - description: Maximum number of rewards to return. Defaults to 100. in: query name: limit schema: format: int32 type: integer - description: Number of rewards to skip for pagination. Defaults to 0. in: query name: offset schema: format: int32 type: integer responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/RewardResponse' 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_limit: $ref: '#/components/examples/invalid_limit' invalid_offset: $ref: '#/components/examples/invalid_offset' invalid_parameter: $ref: '#/components/examples/invalid_parameter' max_fetch_size_1000: $ref: '#/components/examples/max_fetch_size_1000' missing_request_body: $ref: '#/components/examples/missing_request_body' period_count_invalid: $ref: '#/components/examples/period_count_invalid' period_not_supported: $ref: '#/components/examples/period_not_supported' reward_state_invalid: $ref: '#/components/examples/reward_state_invalid' reward_type_not_supported: $ref: '#/components/examples/reward_type_not_supported' time_interval_invalid: $ref: '#/components/examples/time_interval_invalid' 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 rewards tags: - Rewards x-extole-bundle: integration-server-to-extole x-extole-visibility: visible /v2/rewards/state_summary: get: description: Returns aggregate state counts for rewards on this client (e.g. earned, fulfilled, cancelled). operationId: getRewardStateSummary parameters: - description: Time period for grouping (e.g. `DAY`, `WEEK`, `MONTH`). in: query name: period schema: enum: - DAY - MONTH - WEEK type: string - description: Number of periods to include in the summary. in: query name: period_count schema: type: string - description: End of the date range for the summary. in: query name: end_date schema: $ref: '#/components/schemas/ZonedDateTime' - description: When true, include only rewards that were successfully fulfilled. in: query name: success_only schema: type: boolean - description: Filter by one or more reward supplier ids (repeat the parameter for multiple values). in: query name: reward_supplier_id schema: type: string - description: Filter by one or more reward types (repeat the parameter for multiple values). in: query name: reward_type schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/RewardStateSummaryResponse' 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' period_count_invalid: $ref: '#/components/examples/period_count_invalid' period_not_supported: $ref: '#/components/examples/period_not_supported' reward_state_invalid: $ref: '#/components/examples/reward_state_invalid' reward_type_not_supported: $ref: '#/components/examples/reward_type_not_supported' time_interval_invalid: $ref: '#/components/examples/time_interval_invalid' 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: Get reward state summary tags: - Rewards x-extole-bundle: integration-server-to-extole x-extole-visibility: visible /v2/rewards/{reward_id}: get: description: Returns the reward record for the specified reward id, including its current state and history. operationId: getReward parameters: - description: Extole-assigned unique identifier for the reward. in: path name: reward_id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/RewardResponse' 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' period_count_invalid: $ref: '#/components/examples/period_count_invalid' period_not_supported: $ref: '#/components/examples/period_not_supported' retry_claimed_reward_not_allowed: $ref: '#/components/examples/retry_claimed_reward_not_allowed' reward_illegal_state_transition: $ref: '#/components/examples/reward_illegal_state_transition' reward_in_not_retryable_state: $ref: '#/components/examples/reward_in_not_retryable_state' reward_not_found: $ref: '#/components/examples/reward_not_found' reward_retry_not_supported: $ref: '#/components/examples/reward_retry_not_supported' reward_state_invalid: $ref: '#/components/examples/reward_state_invalid' reward_supplier_not_found: $ref: '#/components/examples/reward_supplier_not_found' reward_type_not_supported: $ref: '#/components/examples/reward_type_not_supported' sandbox_not_found: $ref: '#/components/examples/sandbox_not_found' time_interval_invalid: $ref: '#/components/examples/time_interval_invalid' 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: Get a reward tags: - Rewards x-extole-bundle: integration-server-to-extole x-extole-visibility: visible put: description: Updates attributes on the specified reward record. Returns the updated reward. operationId: updateReward parameters: - description: Extole-assigned unique identifier for the reward. in: path name: reward_id required: true schema: type: string requestBody: content: application/json: example: sandbox: sandbox schema: $ref: '#/components/schemas/RewardUpdateRequest' description: Reward update request. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/RewardResponse' 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' retry_claimed_reward_not_allowed: $ref: '#/components/examples/retry_claimed_reward_not_allowed' reward_illegal_state_transition: $ref: '#/components/examples/reward_illegal_state_transition' reward_in_not_retryable_state: $ref: '#/components/examples/reward_in_not_retryable_state' reward_not_found: $ref: '#/components/examples/reward_not_found' reward_retry_not_supported: $ref: '#/components/examples/reward_retry_not_supported' reward_supplier_not_found: $ref: '#/components/examples/reward_supplier_not_found' sandbox_not_found: $ref: '#/components/examples/sandbox_not_found' 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' person_not_found: $ref: '#/components/examples/person_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: Update a reward tags: - Rewards x-extole-bundle: integration-server-to-extole x-extole-visibility: visible /v2/rewards/{reward_id}/cancels: get: description: Returns the cancellation history for the specified reward. operationId: getRewardCancels parameters: - description: Extole-assigned unique identifier for the reward. in: path name: reward_id required: true schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/CanceledRewardStateResponse' 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' period_count_invalid: $ref: '#/components/examples/period_count_invalid' period_not_supported: $ref: '#/components/examples/period_not_supported' retry_claimed_reward_not_allowed: $ref: '#/components/examples/retry_claimed_reward_not_allowed' reward_illegal_state_transition: $ref: '#/components/examples/reward_illegal_state_transition' reward_in_not_retryable_state: $ref: '#/components/examples/reward_in_not_retryable_state' reward_not_found: $ref: '#/components/examples/reward_not_found' reward_retry_not_supported: $ref: '#/components/examples/reward_retry_not_supported' reward_state_invalid: $ref: '#/components/examples/reward_state_invalid' reward_supplier_not_found: $ref: '#/components/examples/reward_supplier_not_found' reward_type_not_supported: $ref: '#/components/examples/reward_type_not_supported' sandbox_not_found: $ref: '#/components/examples/sandbox_not_found' time_interval_invalid: $ref: '#/components/examples/time_interval_invalid' 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: Get reward cancels tags: - Rewards x-extole-bundle: integration-server-to-extole x-extole-visibility: visible /v2/rewards/{reward_id}/fails: get: description: Returns the fulfilment failure history for the specified reward. operationId: getRewardFails parameters: - description: Extole-assigned unique identifier for the reward. in: path name: reward_id required: true schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/FailedRewardStateResponse' 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' period_count_invalid: $ref: '#/components/examples/period_count_invalid' period_not_supported: $ref: '#/components/examples/period_not_supported' retry_claimed_reward_not_allowed: $ref: '#/components/examples/retry_claimed_reward_not_allowed' reward_illegal_state_transition: $ref: '#/components/examples/reward_illegal_state_transition' reward_in_not_retryable_state: $ref: '#/components/examples/reward_in_not_retryable_state' reward_not_found: $ref: '#/components/examples/reward_not_found' reward_retry_not_supported: $ref: '#/components/examples/reward_retry_not_supported' reward_state_invalid: $ref: '#/components/examples/reward_state_invalid' reward_supplier_not_found: $ref: '#/components/examples/reward_supplier_not_found' reward_type_not_supported: $ref: '#/components/examples/reward_type_not_supported' sandbox_not_found: $ref: '#/components/examples/sandbox_not_found' time_interval_invalid: $ref: '#/components/examples/time_interval_invalid' 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: Get reward fails tags: - Rewards x-extole-bundle: integration-server-to-extole x-extole-visibility: visible /v2/rewards/{reward_id}/fulfillments: get: description: Returns the fulfilment records for the specified reward. operationId: getRewardFulfillments parameters: - description: Extole-assigned unique identifier for the reward. in: path name: reward_id required: true schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/FulfilledRewardStateResponse' 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' period_count_invalid: $ref: '#/components/examples/period_count_invalid' period_not_supported: $ref: '#/components/examples/period_not_supported' retry_claimed_reward_not_allowed: $ref: '#/components/examples/retry_claimed_reward_not_allowed' reward_illegal_state_transition: $ref: '#/components/examples/reward_illegal_state_transition' reward_in_not_retryable_state: $ref: '#/components/examples/reward_in_not_retryable_state' reward_not_found: $ref: '#/components/examples/reward_not_found' reward_retry_not_supported: $ref: '#/components/examples/reward_retry_not_supported' reward_state_invalid: $ref: '#/components/examples/reward_state_invalid' reward_supplier_not_found: $ref: '#/components/examples/reward_supplier_not_found' reward_type_not_supported: $ref: '#/components/examples/reward_type_not_supported' sandbox_not_found: $ref: '#/components/examples/sandbox_not_found' time_interval_invalid: $ref: '#/components/examples/time_interval_invalid' 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: Get reward fulfillments tags: - Rewards x-extole-bundle: integration-server-to-extole x-extole-visibility: visible /v2/rewards/{reward_id}/history: get: description: Returns the full state-transition history for the specified reward. operationId: getRewardStateHistory parameters: - description: Extole-assigned unique identifier for the reward. in: path name: reward_id required: true schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/RewardStateResponse' 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' period_count_invalid: $ref: '#/components/examples/period_count_invalid' period_not_supported: $ref: '#/components/examples/period_not_supported' retry_claimed_reward_not_allowed: $ref: '#/components/examples/retry_claimed_reward_not_allowed' reward_illegal_state_transition: $ref: '#/components/examples/reward_illegal_state_transition' reward_in_not_retryable_state: $ref: '#/components/examples/reward_in_not_retryable_state' reward_not_found: $ref: '#/components/examples/reward_not_found' reward_retry_not_supported: $ref: '#/components/examples/reward_retry_not_supported' reward_state_invalid: $ref: '#/components/examples/reward_state_invalid' reward_supplier_not_found: $ref: '#/components/examples/reward_supplier_not_found' reward_type_not_supported: $ref: '#/components/examples/reward_type_not_supported' sandbox_not_found: $ref: '#/components/examples/sandbox_not_found' time_interval_invalid: $ref: '#/components/examples/time_interval_invalid' 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: Get reward state history tags: - Rewards x-extole-bundle: integration-server-to-extole x-extole-visibility: visible /v2/rewards/{reward_id}/redeems: get: description: Returns the redemption records for the specified reward. operationId: getRewardRedeems parameters: - description: Extole-assigned unique identifier for the reward. in: path name: reward_id required: true schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/RedeemedRewardStateResponse' 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' period_count_invalid: $ref: '#/components/examples/period_count_invalid' period_not_supported: $ref: '#/components/examples/period_not_supported' retry_claimed_reward_not_allowed: $ref: '#/components/examples/retry_claimed_reward_not_allowed' reward_illegal_state_transition: $ref: '#/components/examples/reward_illegal_state_transition' reward_in_not_retryable_state: $ref: '#/components/examples/reward_in_not_retryable_state' reward_not_found: $ref: '#/components/examples/reward_not_found' reward_retry_not_supported: $ref: '#/components/examples/reward_retry_not_supported' reward_state_invalid: $ref: '#/components/examples/reward_state_invalid' reward_supplier_not_found: $ref: '#/components/examples/reward_supplier_not_found' reward_type_not_supported: $ref: '#/components/examples/reward_type_not_supported' sandbox_not_found: $ref: '#/components/examples/sandbox_not_found' time_interval_invalid: $ref: '#/components/examples/time_interval_invalid' 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: Get reward redeems tags: - Rewards x-extole-bundle: integration-server-to-extole x-extole-visibility: visible /v2/rewards/{reward_id}/revokes: get: description: Returns the revocation records for the specified reward. operationId: getRewardRevokes parameters: - description: Extole-assigned unique identifier for the reward. in: path name: reward_id required: true schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/RevokedRewardStateResponse' 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' period_count_invalid: $ref: '#/components/examples/period_count_invalid' period_not_supported: $ref: '#/components/examples/period_not_supported' retry_claimed_reward_not_allowed: $ref: '#/components/examples/retry_claimed_reward_not_allowed' reward_illegal_state_transition: $ref: '#/components/examples/reward_illegal_state_transition' reward_in_not_retryable_state: $ref: '#/components/examples/reward_in_not_retryable_state' reward_not_found: $ref: '#/components/examples/reward_not_found' reward_retry_not_supported: $ref: '#/components/examples/reward_retry_not_supported' reward_state_invalid: $ref: '#/components/examples/reward_state_invalid' reward_supplier_not_found: $ref: '#/components/examples/reward_supplier_not_found' reward_type_not_supported: $ref: '#/components/examples/reward_type_not_supported' sandbox_not_found: $ref: '#/components/examples/sandbox_not_found' time_interval_invalid: $ref: '#/components/examples/time_interval_invalid' 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: Get reward revokes tags: - Rewards x-extole-bundle: integration-server-to-extole x-extole-visibility: visible /v2/rewards/{reward_id}/sends: get: description: Returns the send events for the specified reward. operationId: getRewardSends parameters: - description: Extole-assigned unique identifier for the reward. in: path name: reward_id required: true schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/SentRewardStateResponse' 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' period_count_invalid: $ref: '#/components/examples/period_count_invalid' period_not_supported: $ref: '#/components/examples/period_not_supported' retry_claimed_reward_not_allowed: $ref: '#/components/examples/retry_claimed_reward_not_allowed' reward_illegal_state_transition: $ref: '#/components/examples/reward_illegal_state_transition' reward_in_not_retryable_state: $ref: '#/components/examples/reward_in_not_retryable_state' reward_not_found: $ref: '#/components/examples/reward_not_found' reward_retry_not_supported: $ref: '#/components/examples/reward_retry_not_supported' reward_state_invalid: $ref: '#/components/examples/reward_state_invalid' reward_supplier_not_found: $ref: '#/components/examples/reward_supplier_not_found' reward_type_not_supported: $ref: '#/components/examples/reward_type_not_supported' sandbox_not_found: $ref: '#/components/examples/sandbox_not_found' time_interval_invalid: $ref: '#/components/examples/time_interval_invalid' 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: Get reward sends tags: - Rewards x-extole-bundle: integration-server-to-extole x-extole-visibility: visible /v2/rewards/{reward_id}/cancel: post: description: Cancels the specified reward, preventing fulfilment. Returns the updated reward record. operationId: cancelReward parameters: - description: Extole-assigned unique identifier for the reward. in: path name: reward_id required: true schema: type: string requestBody: content: application/json: example: message: message schema: $ref: '#/components/schemas/CancelRewardRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/RewardResponse' 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' period_count_invalid: $ref: '#/components/examples/period_count_invalid' period_not_supported: $ref: '#/components/examples/period_not_supported' retry_claimed_reward_not_allowed: $ref: '#/components/examples/retry_claimed_reward_not_allowed' reward_illegal_state_transition: $ref: '#/components/examples/reward_illegal_state_transition' reward_in_not_retryable_state: $ref: '#/components/examples/reward_in_not_retryable_state' reward_not_found: $ref: '#/components/examples/reward_not_found' reward_retry_not_supported: $ref: '#/components/examples/reward_retry_not_supported' reward_state_invalid: $ref: '#/components/examples/reward_state_invalid' reward_supplier_not_found: $ref: '#/components/examples/reward_supplier_not_found' reward_type_not_supported: $ref: '#/components/examples/reward_type_not_supported' sandbox_not_found: $ref: '#/components/examples/sandbox_not_found' time_interval_invalid: $ref: '#/components/examples/time_interval_invalid' 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: Cancel a reward tags: - Rewards x-extole-bundle: integration-server-to-extole x-extole-visibility: visible /v2/rewards/{reward_id}/retry: post: description: Retries fulfilment of a previously failed reward. Returns the updated reward. operationId: retryReward parameters: - description: Extole-assigned unique identifier for the reward. in: path name: reward_id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/RewardResponse' 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' period_count_invalid: $ref: '#/components/examples/period_count_invalid' period_not_supported: $ref: '#/components/examples/period_not_supported' retry_claimed_reward_not_allowed: $ref: '#/components/examples/retry_claimed_reward_not_allowed' reward_illegal_state_transition: $ref: '#/components/examples/reward_illegal_state_transition' reward_in_not_retryable_state: $ref: '#/components/examples/reward_in_not_retryable_state' reward_not_found: $ref: '#/components/examples/reward_not_found' reward_retry_not_supported: $ref: '#/components/examples/reward_retry_not_supported' reward_state_invalid: $ref: '#/components/examples/reward_state_invalid' reward_supplier_not_found: $ref: '#/components/examples/reward_supplier_not_found' reward_type_not_supported: $ref: '#/components/examples/reward_type_not_supported' sandbox_not_found: $ref: '#/components/examples/sandbox_not_found' time_interval_invalid: $ref: '#/components/examples/time_interval_invalid' 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: Retry a reward tags: - Rewards x-extole-bundle: integration-server-to-extole x-extole-visibility: visible /v2/rewards/{reward_id}/revoke: post: description: Revokes the specified reward, marking it as invalid. Returns the updated reward. operationId: revokeReward parameters: - description: Extole-assigned unique identifier for the reward. in: path name: reward_id required: true schema: type: string requestBody: content: application/json: example: message: message schema: $ref: '#/components/schemas/RevokeRewardRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/RewardResponse' 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' period_count_invalid: $ref: '#/components/examples/period_count_invalid' period_not_supported: $ref: '#/components/examples/period_not_supported' retry_claimed_reward_not_allowed: $ref: '#/components/examples/retry_claimed_reward_not_allowed' reward_illegal_state_transition: $ref: '#/components/examples/reward_illegal_state_transition' reward_in_not_retryable_state: $ref: '#/components/examples/reward_in_not_retryable_state' reward_not_found: $ref: '#/components/examples/reward_not_found' reward_retry_not_supported: $ref: '#/components/examples/reward_retry_not_supported' reward_state_invalid: $ref: '#/components/examples/reward_state_invalid' reward_supplier_not_found: $ref: '#/components/examples/reward_supplier_not_found' reward_type_not_supported: $ref: '#/components/examples/reward_type_not_supported' sandbox_not_found: $ref: '#/components/examples/sandbox_not_found' time_interval_invalid: $ref: '#/components/examples/time_interval_invalid' 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: Revoke a reward tags: - Rewards x-extole-bundle: integration-server-to-extole 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 period_count_invalid: summary: period_count_invalid value: code: period_count_invalid http_status_code: 400 message: Invalid period count parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 retry_claimed_reward_not_allowed: summary: retry_claimed_reward_not_allowed value: code: retry_claimed_reward_not_allowed http_status_code: 400 message: Retry for Claimed Reward is not allowed parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 reward_state_invalid: summary: reward_state_invalid value: code: reward_state_invalid http_status_code: 400 message: Specified reward state type is not supported 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 invalid_offset: summary: invalid_offset value: code: invalid_offset http_status_code: 400 message: Offset should be a non negative integer parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 reward_retry_not_supported: summary: reward_retry_not_supported value: code: reward_retry_not_supported http_status_code: 400 message: Reward retry not supported 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 reward_illegal_state_transition: summary: reward_illegal_state_transition value: code: reward_illegal_state_transition http_status_code: 400 message: Reward illegal state transition for current state parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 reward_in_not_retryable_state: summary: reward_in_not_retryable_state value: code: reward_in_not_retryable_state http_status_code: 400 message: Reward is in a not retryable state 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 reward_supplier_not_found: summary: reward_supplier_not_found value: code: reward_supplier_not_found http_status_code: 403 message: Reward supplier not found parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 time_interval_invalid: summary: time_interval_invalid value: code: time_interval_invalid http_status_code: 400 message: Time interval is invalid or not ISO-8601 explicit form 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 reward_not_found: summary: reward_not_found value: code: reward_not_found http_status_code: 400 message: Reward not found 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 person_not_found: summary: person_not_found value: code: person_not_found http_status_code: 403 message: Person not found parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 period_not_supported: summary: period_not_supported value: code: period_not_supported http_status_code: 400 message: Period not supported parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 reward_type_not_supported: summary: reward_type_not_supported value: code: reward_type_not_supported http_status_code: 400 message: Reward type not supported parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 invalid_limit: summary: invalid_limit value: code: invalid_limit http_status_code: 400 message: Limit should be a non negative integer parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 sandbox_not_found: summary: sandbox_not_found value: code: sandbox_not_found http_status_code: 400 message: Unable to find sandbox parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 max_fetch_size_1000: summary: max_fetch_size_1000 value: code: max_fetch_size_1000 http_status_code: 400 message: Maximum allowed difference between limit and offset should be 1000 parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 schemas: FailedRewardStateResponse: properties: created_at: $ref: '#/components/schemas/ZonedDateTime' message: description: Human-readable error message from the failed fulfillment attempt. type: string operator_user_id: description: Extole user id of the operator who triggered this failure, if applicable. type: string reward_id: description: Extole-assigned unique identifier for the reward. type: string required: - created_at - message - operator_user_id - reward_id type: object RevokedRewardStateResponse: properties: created_at: $ref: '#/components/schemas/ZonedDateTime' message: description: Human-readable reason provided for the revocation. type: string operator_user_id: description: Extole user id of the operator who triggered this revocation. type: string reward_id: description: Extole-assigned unique identifier for the reward. type: string required: - created_at - message - operator_user_id - reward_id type: object RewardStateResponse: properties: created_at: $ref: '#/components/schemas/ZonedDateTime' message: description: Human-readable message associated with this state transition. type: string operator_user_id: description: Extole user id of the operator who triggered this state transition, if applicable. type: string state_type: description: Lifecycle state type of this reward state transition. enum: - CANCELED - EARNED - FAILED - FULFILLED - REDEEMED - REVOKED - SENT type: string success: description: Whether this state transition was successful. type: boolean required: - created_at - message - operator_user_id - state_type - success type: object FulfilledRewardStateResponse: properties: amount: description: Monetary amount disbursed during fulfillment. Null if not applicable. nullable: true type: number cost_code: description: Cost accounting code used for this fulfillment. Null if not applicable. nullable: true type: string created_at: $ref: '#/components/schemas/ZonedDateTime' face_value: description: Face value of the reward at time of fulfillment. Deprecated. nullable: true type: number face_value_type: description: Face value type of the reward at time of fulfillment. Deprecated. enum: - AUD - BRL - CAD - CNY - EUR - GBP - HKD - INR - JPY - KRW - MONTH - MXN - NZD - PERCENT_OFF - POINTS - TRY - TWD - USD nullable: true type: string message: description: Human-readable message from the fulfillment attempt. type: string operator_user_id: description: Extole user id of the operator who triggered this fulfillment, if applicable. type: string partner_reward_id: description: Partner-assigned identifier for the reward. Null if not yet assigned. nullable: true type: string reward_id: description: Extole-assigned unique identifier for the reward. type: string success: description: Whether the fulfillment was successful. type: boolean required: - amount - cost_code - created_at - face_value - face_value_type - message - operator_user_id - partner_reward_id - reward_id - success type: object RewardStateSummaryResponse: properties: canceled: description: Number of rewards cancelled in this period. format: int32 type: integer date_from: $ref: '#/components/schemas/ZonedDateTime' date_to: $ref: '#/components/schemas/ZonedDateTime' earned: description: Number of rewards earned in this period. format: int32 type: integer failed: description: Number of rewards that failed fulfilment in this period. format: int32 type: integer fulfilled: description: Number of rewards fulfilled in this period. format: int32 type: integer redeemed: description: Number of rewards redeemed in this period. format: int32 type: integer revoked: description: Number of rewards revoked in this period. format: int32 type: integer sent: description: Number of rewards sent in this period. format: int32 type: integer required: - canceled - date_from - date_to - earned - failed - fulfilled - redeemed - revoked - sent type: object JourneyKey: properties: name: type: string value: type: string type: object RewardResponse: properties: action_id: description: Extole action id associated with this reward. type: string campaign_id: description: Extole campaign id associated with this reward. type: string cause_event_id: description: Id of the direct cause event that triggered this reward. type: string container: description: Campaign container the reward belongs to. type: string created_at: $ref: '#/components/schemas/ZonedDateTime' data: additionalProperties: description: Named data parameters attached to this reward. type: string description: Named data parameters attached to this reward. type: object email: description: Email address of the reward recipient. Null if not available. nullable: true type: string expires_at: $ref: '#/components/schemas/ZonedDateTime' face_value: description: Monetary or point face value of the reward. type: number face_value_type: description: Unit type of the face value (e.g. `CASH`, `POINTS`, `PERCENT`). enum: - AUD - BRL - CAD - CNY - EUR - GBP - HKD - INR - JPY - KRW - MONTH - MXN - NZD - PERCENT_OFF - POINTS - TRY - TWD - USD type: string journey_key: $ref: '#/components/schemas/JourneyKey' journey_name: description: Name of the journey associated with this reward. type: string partner_reward_id: description: Partner-assigned identifier for this reward. Null if not yet assigned. nullable: true type: string partner_reward_key_type: description: Type of key used to identify the reward at the partner's system. enum: - COUPON - ID - LINK type: string partner_reward_supplier_id: description: Partner-assigned identifier for the reward supplier. Null if not provided. nullable: true type: string partner_user_id: description: Partner's identifier for the person. Null if not provided. nullable: true type: string person_id: description: Extole person id of the reward recipient. type: string reward_id: description: Extole-assigned unique identifier for this reward. type: string reward_supplier_id: description: Extole reward supplier id that issued this reward. type: string root_event_id: description: Id of the root event that initiated the chain leading to this reward. type: string sandbox: description: Sandbox identifier for this reward. type: string state: description: Current lifecycle state of the reward. enum: - CANCELED - EARNED - FAILED - FULFILLED - REDEEMED - REVOKED - SENT type: string required: - action_id - campaign_id - cause_event_id - container - created_at - data - email - expires_at - face_value - face_value_type - journey_key - journey_name - partner_reward_id - partner_reward_key_type - partner_reward_supplier_id - partner_user_id - person_id - reward_id - reward_supplier_id - root_event_id - sandbox - state type: object CanceledRewardStateResponse: properties: created_at: $ref: '#/components/schemas/ZonedDateTime' message: description: Human-readable reason provided for the cancellation. type: string operator_user_id: description: Extole user id of the operator who triggered this cancellation. type: string reward_id: description: Extole-assigned unique identifier for the reward. type: string required: - created_at - message - operator_user_id - reward_id type: object RedeemedRewardStateResponse: properties: cause_event_id: description: Extole id of the event that caused this redemption. nullable: true type: string created_at: $ref: '#/components/schemas/ZonedDateTime' event_name: description: Name of the event that triggered this redemption. Null if not event-driven. nullable: true type: string message: description: Human-readable message associated with this redemption. Null if not provided. nullable: true type: string operator_user_id: description: Extole user id of the operator who triggered this redemption. Null if system-initiated. nullable: true type: string partner_event_id: description: Partner-provided identifier for the triggering event. Null if not provided. nullable: true type: string partner_reward_redeem_id: description: Partner-assigned identifier for this redemption event. type: string reward_id: description: Extole-assigned unique identifier for the reward. type: string required: - cause_event_id - created_at - event_name - message - operator_user_id - partner_event_id - partner_reward_redeem_id - reward_id type: object RevokeRewardRequest: properties: message: description: Optional human-readable reason for the revocation, stored for audit purposes. nullable: true type: string required: - message type: object RewardUpdateRequest: description: Body of a `PUT /v2/rewards/{reward_id}` request. properties: sandbox: description: Sandbox identifier for the reward. Omit to leave the current value unchanged. type: string 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 CancelRewardRequest: properties: message: description: Optional human-readable reason for the cancellation, stored for audit purposes. nullable: true type: string required: - message type: object SentRewardStateResponse: properties: created_at: $ref: '#/components/schemas/ZonedDateTime' email: description: Email address the reward notification was sent to. type: string message: description: Human-readable message from the send attempt. type: string operator_user_id: description: Extole user id of the operator who triggered this send, if applicable. type: string partner_reward_sent_id: description: Partner-assigned identifier for this send event. Null if not provided. nullable: true type: string reward_id: description: Extole-assigned unique identifier for the reward. type: string success: description: Whether the send was successful. type: boolean required: - created_at - email - message - operator_user_id - partner_reward_sent_id - reward_id - success 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