1. Data Workflows
Returning.AI
  • Getting Started
  • Users
    • User directory and provisioning
    • Get Users with Filters
      POST
    • Create New User
      POST
    • Get User Data
      POST
    • Manage User Account
      POST
    • Get User Milestones
      POST
    • Update User Data, Identifier, And Roles
      POST
    • Update User XP and Currency
      POST
  • Messaging
    • Agent messaging workflow
    • Get Messages
      GET
    • Send Message
      POST
    • Reply Message
      POST
    • React Message
      POST
    • Upload message images
      POST
    • Delete message
      DELETE
  • Gamification
    • Leaderboards
      • Leaderboards
      • List leaderboards with pagination
      • Create a new leaderboard
      • Update an existing leaderboard
      • Get a single leaderboard by ID
      • Delete a leaderboard
    • Streaks & Mini Games
      • Mini-game State and History
      • List user streak logs
      • List mini-game logs by user email
      • Get current mini-game and streak state
      • Update user spin-wheel information
    • Referral
      • Referral Program Integration
      • Get referral programs
      • Get user's referral summary
    • Rolling Data
    • Match Predictions
      • Create match prediction
      • List match predictions
      • Get match prediction
      • Patch match prediction
      • Publish match prediction
      • Settle match prediction
      • Get settlement results
      • Void match prediction
      • Bulk update match predictions
      • Get bulk job status
      • Get bulk job results
    • Loyalty Points
      • Create loyalty points export
      • Get loyalty points export status
      • Get loyalty points export download link
    • Get tier configuration
      GET
    • Get daily user XP and coin changes
      POST
    • Search user gamification logs
      POST
    • Get user activity stats
      POST
  • Rewards & Redemptions
    • Store catalog to redemptions
    • List redemption orders by custom-field identifier
    • Update redemption order status or refund
    • Create redemption order status
    • List redemption orders by user email
    • List redemption statuses
    • Get redemption status by ID
    • List redemption orders by community
    • Get redemption order status history
  • Chart Analysis
    • Create Analysis
    • Get Analysis
    • Update Analysis
    • Delete Analysis
    • List Analyses
    • Append Drawings
  • Bulk Operations
    • Bulk user updates
    • List bulk update jobs
    • Get bulk update job status
    • Get bulk update job details
    • Bulk update users from CSV
    • Bulk update premium currency from CSV
  • Channels
    • Iframe
    • List integration channels
  • Events
    • Outgoing webhooks
      • Encryption
      • User Joins Server
      • User Visits server
      • New Message Posted Anywhere
      • New Message Posted To channel
      • Purchased Store Item
    • Incoming webhooks
      • API Keys & Encryption
      • Send message into channels
      • Update Custom User Fields
      • Update In-game currency
  • Widgets
    • Authenticated Widgets
    • Public widgets
    • Channels
    • Leaderboard
    • Milestone
    • Socials
    • Store
  • Store
    • Store catalog
    • Purchase History
      • Archive or restore an order
      • Update redemption instructions or voucher details
    • Categories
      • List Store categories
      • Create Store category
      • Get Store category by ID
      • Update Store category
      • Delete Store category
    • Products
      • List products
      • Update products in bulk
      • Create products in bulk
      • Create product with vouchers
      • Read product
      • Update product and append vouchers
      • Delete product
    • Redemption-transaction
      • Get redemption transaction detail
    • Get Store configuration
    • Update Store configuration
  • Community Analytics
    • Get Loyalty Overview
    • Get Phone Verification Contacts
  • Community
    • Community directory and appearance
    • Appearance
      • Update community theme colors
      • Update community bot profile
      • Update community URL metadata
      • Update community name and URL
    • Community Users
      • Get community users
      • Get user
    • Create community
  • API Keys
    • API key lifecycle
    • Community API Keys
      • Create API key
      • Read API keys
      • Delete API key
      • Update API key
    • User API Keys
      • List user API keys
      • Create user API key
      • Update user API key
      • Delete user API key
      • Get current API key information
  • User Fields
    • User field definitions and history
    • User Field History
      • Get all user field histories in a community
      • Get user field histories for a specific field
      • Get user field histories for a specific user
      • Get user field histories of specific user field and user
      • Update A User Field Value
      • Deprecated Field-First History Write
      • Deprecated Field-First History Read
    • Get A User Field Definition
    • Update A User Field Definition
    • Create A User Field Definition
    • Delete A User Field Definition
    • List User Field Definitions
  • Legacy
    • Servers
      • Create server
      • List servers
      • Update server metadata
    • Bulk Operations
      • Bulk import users from CSV
    • Authentication
      • Secure Auth
      • Register user with password
      • Verify user email
      • Log in user with password
    • Badges
      • List badges
      • Create badge
      • Update badge
      • Delete badge
      • Remove badge from user
      • Award badge to user
    • Messaging
    • Roles & Permissions
      • List server roles
      • Create role
      • Update role
      • Delete role
      • List user roles
      • Add role to user
      • Remove role from user
    • Users
      • Get user
      • Upload user avatar
    • Channels
      • Create channel
      • Update channel
      • Delete channel
    • API Keys
      • List integration API keys
      • Create integration API key
      • Delete integration API key
      • Update integration API key
  • Data Workflows
    • Read event-ingest lifecycle status by trigger and batch ID.
      GET
    • Look up reward events
      POST
  • Community Logs
    • Retrieve and export community logs
  • Workflow Builder
    • Workflow Builder API overview
    • Connect an AI agent to the Workflow Builder tools
    • Bind step inputs to trigger and earlier-step outputs
    • Code steps through the API
    • Edit safely: revisions, conflicts, export, import and copying a workflow
    • Set up an event-ingest workflow and check batch status
    • Keep a member's tier or role in sync
    • Reversible rewards
    • Test without side effects, then confirm a live run
    • Build a trading-rewards workflow from event ingest
    • Reward members from your own system with a webhook workflow
    • List step types and trigger types
    • List workflows
    • Create a workflow
    • Get a workflow
    • Rename a workflow or set its failure webhook
    • Delete a workflow
    • Duplicate a workflow
    • Export a workflow definition
    • Validate a stored workflow
    • Create or replace the trigger
    • Add a step
    • Get a step
    • Update a step
    • Delete a step
    • Reorder a main-line step
    • Duplicate a step
    • Add a router branch
    • Update a router branch
    • Delete a router branch
    • Duplicate a router branch
    • Test one step
    • Test a whole workflow
    • Deploy a workflow
    • Undeploy a workflow
    • List the runs of a workflow
    • Get one run
    • Retry a failed run
    • Call the workflow tools over MCP
  • Schemas
    • Sample Schemas
    • Schemas
    • Outgoing webhooks
    • Analysis
    • Pet
    • Category
    • Tag
    • ValidationError
    • NotFoundError
    • InternalServerError
    • NotImplementedError
    • CreateUserFieldHistoryResponse
    • CreateUserFieldHistorySuccessResponse
    • UserFieldHistoryItem
    • GetUserFieldHistoriesResponse
    • UserFieldHistoriesValidationError
    • UserFieldHistoriesMetaWithValidation
    • UserFieldHistoriesMetaWithPagination
    • GetUserFieldHistoriesSuccessResponse
    • CreateUserFieldResponse
    • CreateUserFieldSuccessResponse
    • DeleteUserFieldResponse
    • DeleteUserFieldSuccessResponse
    • UserFieldCreator
    • GetUserFieldResponse
    • GetUserFieldSuccessResponse
    • ValidationErrorItem
    • GetUserFieldsMetaResponse
    • CreatorInfo
    • UserFieldResponse
    • GetUserFieldsSuccessResponse
    • UpdateUserFieldResponse
    • UpdateUserFieldPayload
    • UpdateUserFieldSuccessResponse
    • MetaResponse
    • GetUserResponse
    • GetUserSuccessResponse
    • Purchased store item
    • ErrorResponse
    • New message posted to channel
    • UpdateAnalysisRequest
    • User visits server
    • AppendDrawingsRequest
    • User join server
    • CreateAnalysisResponse
    • GetAnalysisResponse
    • UpdateAnalysisResponse
    • AppendDrawingsResponse
    • AnalysisMetadata
    • Expiry
    • Levels
    • LevelEntry
    • Drawing
    • HorizontalLineDrawing
    • LineDrawing
    • RectangleDrawing
    • ParallelDrawing
    • FibonacciRetracementDrawing
    • Coordinate
    • DrawingStyle
    • AnalysisDetail
    • AnalysisSummary
    • CreateAnalysisRequest
    • ListAnalysesResponse
    • StandardApiError
    • StandardSuccessEnvelope
    • PurchasedStoreItemEvent
    • ChannelMessagePostedEvent
    • UserVisitedCommunityEvent
    • UserJoinedCommunityEvent
  1. Data Workflows

Look up reward events

POST
/v1/data-workflows/reward-events/lookup

What this endpoint does#

Check the XP and coins actually awarded for original reward events in a data workflow and see whether each award was reversed.

Authentication#

Send a community API key with Data Workflows (dataWorkflows) permission in Authorization: Bearer <API_KEY>. If you need to find the workflow ID with List workflows, that operation uses the separate workflowBuilder permission.

Request body#

Send only workflow_id and event_keys as JSON. The lookup is scoped to the API key's community and the supplied workflow ID. It reads receipts without awarding or reversing anything.

Response#

A missing receipt has only event_key and found: false. A well-formed workflow ID with no matching receipts also returns 200 with found: false for every key. A found receipt includes all the fields shown in the example. Unavailable values are null, and metadata defaults to {}.
Use actual_rewards on a completed original to reconcile what was awarded. A completed reversal records that the saved award was deducted. The original actual_rewards still shows the award and the lookup shows the cancellation under reversal. Look up the original key to see both. A cancellation key has no receipt of its own.

Retries#

A batch can already show processed while its reward updates are still queued. For found: false or status: processing with has_error: false, retry the lookup later. Apply the same rule to a reversal still processing without an error. Record a deduction only after its reversal is completed. Flag a receipt for manual reconciliation when it reports an error or stays unresolved past your reconciliation window.

Errors#

Read meta.code for structured errors and meta.errors for invalid fields. Malformed JSON can return 400 before body validation. If your community opts into API rate limiting, a request over the limit returns 429 with meta.code: RATE_LIMITED and a Retry-After header in seconds.
HTTPCodeWhat to do
400VALIDATION_ERRORCheck meta.errors and fix the request body before retrying.
401AUTHENTICATION_REQUIREDSend a valid community API key in the Authorization header.
403API_KEY_PERMISSION_DENIEDGrant the community key Data Workflows permission.
403COMMUNITY_ACCESS_DENIEDUse a community API key for the workflow's community.
404COMMUNITY_NOT_FOUNDCheck that the API key belongs to an existing community.
429RATE_LIMITEDWait for the time in the Retry-After header before calling again.
500AUTHENTICATION_FAILEDRetry the read with backoff.
500INTERNAL_ERRORRetry the read with backoff.

Request

Authorization
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
Body Params application/jsonRequired

Examples

Responses

🟢200Reward events fetched successfully
application/json
Bodyapplication/json

🟠400VALIDATION_ERROR
🟠401AUTHENTICATION_REQUIRED
🟠403API_KEY_PERMISSION_DENIED / COMMUNITY_ACCESS_DENIED
🟠404COMMUNITY_NOT_FOUND
🟠429RATE_LIMITED
🔴500AUTHENTICATION_FAILED / INTERNAL_ERROR
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.returning.ai/v1/data-workflows/reward-events/lookup' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "workflow_id": "66f000000000000000000001",
  "event_keys": [
    "trade-1001",
    "trade-1002"
  ]
}'
Response Response Example
200 - Completed receipt and missing receipt
{
  "status": "success",
  "message": "Reward events fetched successfully",
  "data": {
    "workflow_id": "66f000000000000000000001",
    "results": [
      {
        "event_key": "trade-1001",
        "found": true,
        "status": "completed",
        "account_id": "account-88",
        "trade_id": "1001",
        "occurred_at": "2026-11-20T08:00:00.000Z",
        "requested_rewards": {
          "xp": 100,
          "coins": 100
        },
        "actual_rewards": {
          "xp": 100,
          "coins": 80,
          "premium_coins": 0,
          "premium_currency_id": null
        },
        "metadata": {
          "instrument": "EURUSD"
        },
        "has_error": false,
        "completed_at": "2026-11-20T08:05:00.000Z",
        "reversal": {
          "event_key": "cancel-trade-1001",
          "status": "completed",
          "occurred_at": "2026-11-20T09:00:00.000Z",
          "claimed_at": "2026-11-20T09:04:00.000Z",
          "completed_at": "2026-11-20T09:05:00.000Z",
          "has_error": false
        }
      },
      {
        "event_key": "trade-1002",
        "found": false
      }
    ]
  }
}
Modified at 2026-11-21 00:23:50
Previous
Read event-ingest lifecycle status by trigger and batch ID.
Next
Retrieve and export community logs
Built with