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/account/connect. 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 user's actions at Advertiser's side that occurred before the account connection was confirmed;

Consider retroactive events as regular events (which are delivered through the normal Event API) which affect task completion but occured before the account connection.

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.

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 tasks. The exact request and response schemas are documented under POST /v1/account/connect.

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.
• Keep metadata small and limited to attributes needed for task evaluation or audit.

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