Copy page

Account linking

Retroactive events

Retroactive events let an Advertiser report qualifying actions together with a Signed Token Callback connection. They are useful when a user completes an action during sign-up, before Onward knows which Platform and Advertiser identities belong to the same person.

For example, a user may create an account and make a first deposit before the Advertiser backend calls POST /v1/users/connect-account. Supplying that deposit as a retroactive event lets Onward evaluate the relevant task as soon as the account connection is established.

When to use them

Use retro_events only for Advertiser actions that:

• occurred before the account connection was confirmed;
• belong to the Advertiser user identified by advertiser_user_id;
• may satisfy a task in the user's active quest chains;
• have a trustworthy event timestamp and event type.

Events that happen after the connection should be sent through the normal Event API instead of being attached to another connection request.

Event fields

Field	Required	Description
event_type	Yes	Advertiser-defined event type, such as deposit.completed.
timestamp	Yes	Moment the event occurred, formatted as an ISO 8601 UTC timestamp.
amount	No	Non-negative measured value associated with the event.
currency	No	Currency or unit associated with amount.
reference	No	Stable Advertiser-side idempotency or audit reference.
metadata	No	Additional Advertiser-defined attributes.

One connection request can contain at most 100 retroactive events.

Example

Code
{
  "token": "<opaque-connection-token>",
  "advertiser_user_id": "advertiser-user-123",
  "retro_events": [
    {
      "event_type": "signup.completed",
      "timestamp": "2026-08-05T08:55:00.000Z",
      "reference": "signup-123"
    },
    {
      "event_type": "deposit.completed",
      "amount": 100,
      "currency": "USD",
      "reference": "deposit-987",
      "timestamp": "2026-08-05T09:00:00.000Z",
      "metadata": {
        "payment_method": "bank_transfer"
      }
    }
  ]
}

Onward links the accounts first and then evaluates the supplied events against the user's active tasks. The exact request and response schemas are documented under POST /v1/users/connect-account.

Integration guidance

• Preserve the original event timestamp; do not replace it with the connection time.
• Use the same event taxonomy and units as subsequent Event API calls.
• Supply a stable reference whenever the Advertiser has one.
• Include only events for the user being connected.
• Keep metadata small and limited to attributes needed for task evaluation or audit.
• Do not resend ordinary post-connection activity through retro_events.

Retroactive events are part of the connection request, so protect them and the connection token according to the account-linking security requirements.