ID.me requires two bits of information to create a User Verification Event Stream:

• Receiver URL: The public URL to which ID.me should stream events.
  Example: https://example.com/api/v1/events
• Authentication Method: If protected by authentication, the details of the auth pattern. We support:

If your Receiver URL uses another form of authentication, please reach out to us at partnersupport@id.me.

Architecture

Setup your audience

Process

Event schema

Each event is delivered as a JSON payload. A data envelope carries routing metadata about where the event came from, and the nested event object carries the event itself.

{
  "data": {
    "source": "...",
    "sourcetype": "...",
    "event": {
      "event": "...",
      "object": { ... }
    }
  }
}

Every event carries the same set of common fields. Events that relate to a specific ID.me resource also carry that resource, in full, on the object field.

The event object

The object field

The object field carries the full resource an event relates to, so you do not need a follow-up API call to act on the event. Its shape varies by event type, and event is the discriminator: read event first, then parse object according to that event’s resource.

Every resource carries a type field naming itself, so a receiver can also branch on the resource directly without maintaining an event-to-resource lookup table.

Events with no resource

Events that describe an action rather than a resource deliver "object": null.

{
  "data": {
    "source": "idme:dev",
    "sourcetype": "idme:auth",
    "event": {
      "event_id": "4c7e2a19-6b58-42d3-8e91-05f7c3a1b6d2",
      "event": "session.signin",
      "uuid": "c3850702f02f4f948cede41610c2a715",
      "user_email": "xbzi.gqcv@gmail.com",
      "application_name": "Auth Portal",
      "ipaddress": "55.55.55.55",
      "device_fingerprint": "lu2pFqAQyLIr0MqVpDEV",
      "useragent": "Mozilla/5.0 (iPhone; CPU iPhone OS 12_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Mobile/15E148 Safari/604.1",
      "created_at": "2026-07-04T13:12:26.877091Z",
      "eid": null,
      "app_id": null,
      "state": null,
      "object": null
    }
  }
}

Handling events

Because object is polymorphic, branch on event before reading it.

const { event, object } = payload.data.event;
switch (event) {
  case "2fa.complete":
    // object.type === "authenticator"
    recordFactor(object.method);
    break;
  case "session.verification_status":
    // object.type === "verification_status"
    if (object.is_preverified_for_policy) skipOnboarding();
    break;
  default:
    // object may be null
    break;
}

Event types