Events API

Submit advertiser events for quest-chain task matching.

Send a user event

POST

https://api.onwardinc.net

/v1/events

X-API-Key (header)

+X-API-Secret (header)

Publisher Advertiser

Records a Platform or Advertiser event for a user identified in the caller's own system and matches it against quest-chain tasks. Reusing the same user ID, event type, and event timestamp returns the existing event with status: duplicate.

Send a user event › Request Body

A Platform or Advertiser event to record and match against the user's quest-chain tasks.

user_id

string · minLength: 1 · maxLength: 255 · required

Identifier of the user in the caller's own system: a Platform user ID for Platform credentials or an Advertiser user ID for Advertiser credentials.

Example: platform-user-456

event_type

string · minLength: 1 · maxLength: 100 · required

Caller-defined event type. Common examples include registration, kyc, link_account, and transaction.

Example: transaction

timestamp

string · date-time · pattern: ^(?:(?:\d\d[2468][04… · required

Required ISO 8601 UTC timestamp indicating when the event occurred.

Example: 2025-10-21T18:45:00Z

amount

number · min: 0

Optional non-negative value associated with the event, such as a deposit or purchase amount.

Example: 100

currency

string · maxLength: 10

Optional currency or unit associated with amount, for example an ISO 4217 code.

Example: USD

reference

string · maxLength: 255

Optional caller-defined business or audit reference associated with the event.

Example: tx_9h2j3k4l

object

Additional caller-defined context used for task evaluation, audit, or analytics.

Example: {"transaction_type":"deposit","transaction_id":"tx_9h2j3k4l"}

Send a user event › Responses

Response for status 200

success

boolean · enum · required

Indicates that the request was successful.

Enum values:

object · required

Result of recording or deduplicating a Platform or Advertiser event.

Example: {"event_id":"9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d","user_id":"platform-user-456","event_type":"transaction","received_at":"2025-10-21T18:45:01Z","status":"received"}

POST/v1/events

curl https://api.onwardinc.net/v1/events \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-API-Secret: <api-key>' \
  --data '{
  "user_id": "platform-user-456",
  "event_type": "transaction",
  "amount": 100,
  "currency": "USD",
  "reference": "tx_9h2j3k4l",
  "timestamp": "2025-10-21T18:45:00Z",
  "metadata": {
    "transaction_type": "deposit",
    "payment_method": "stripe",
    "transaction_id": "tx_9h2j3k4l",
    "campaign": "black_friday"
  }
}'

Example Request Body

{
  "user_id": "platform-user-456",
  "event_type": "transaction",
  "amount": 100,
  "currency": "USD",
  "reference": "tx_9h2j3k4l",
  "timestamp": "2025-10-21T18:45:00Z",
  "metadata": {
    "transaction_type": "deposit",
    "payment_method": "stripe",
    "transaction_id": "tx_9h2j3k4l",
    "campaign": "black_friday"
  }
}

json

Example Responses

{
  "success": true,
  "data": {
    "event_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "user_id": "platform-user-456",
    "event_type": "transaction",
    "received_at": "2025-10-21T18:45:01Z",
    "status": "received"
  }
}