Events

List events

GET https://api.xipid.org/events

One page of the brand's events of the last 30 days, oldest first: its outcomes as they were posted, of one type if it names one, created after, from, before or until the instants it names. A receiver that was down reads them from the created_at of the last event it processed.

Scope: any live key of the brand.

Limits: 1,000 requests a minute per key and 2,000 requests a minute per source address; every answer says what is left in X-RateLimit-Remaining, and a refusal when to come back in Retry-After.

Idempotency: a read, safe to repeat.

Changes: 2026-09-26: added.

Parameters

• limit in the query, optional, integer, 1 to 100, 20 by default

  How many items the page holds.

• starting_after in the query, optional, string

  The page after the item a page's next_cursor named.

• ending_before in the query, optional, string

  The page before the item a page's previous_cursor named; not with starting_after.

• type in the query, optional, string, one of the values below

  Events of this type alone.

  • challenge.verified: The person approved and every check passed.
  • challenge.check_failed: A check the policy asks for did not pass.
  • challenge.declined: The person declined.
  • challenge.expired: No decision came before the challenge expired.
  • challenge.canceled: The brand canceled the challenge, or its text could not be sent.

• created_at_gt in the query, optional, instant, RFC 3339, at most 35 characters

  Events created after it.

• created_at_gte in the query, optional, instant, RFC 3339, at most 35 characters

  Events created at it or after.

• created_at_lt in the query, optional, instant, RFC 3339, at most 35 characters

  Events created before it.

• created_at_lte in the query, optional, instant, RFC 3339, at most 35 characters

  Events created at it or before.

• Xip-Version a header, optional, string, one of the values below

  The version to answer in; when absent, the version the brand's org is pinned to.

  • 2026-09-26: The first version: challenges, subjects and events, and the signed outcome.

Answers

200 OK

A page of events.

Its headers: X-Request-Id, Xip-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

• data array of Event

  • id ULID

  • type string, one of the values below

    How the challenge closed.

    • challenge.verified: The person approved and every check passed.
    • challenge.check_failed: A check the policy asks for did not pass.
    • challenge.declined: The person declined.
    • challenge.expired: No decision came before the challenge expired.
    • challenge.canceled: The brand canceled the challenge, or its text could not be sent.

  • api_version string, one of the values below

    A released version of the API, named by the day its contract was fixed.

    • 2026-09-26: The first version: challenges, subjects and events, and the signed outcome.

  • created_at instant, RFC 3339

  • data Challenge

    • id ULID

    • brand_id ULID

    • status string, one of the values below

      Where the challenge is in its life; the last five are final.

      • created: Made; the text with its link is not sent yet.
      • sent: The text with the link went to the person's phone.
      • opened: The person opened the link and is reading the request.
      • approving: The person approved, and the checks the policy asks for are running.
      • verified: The person approved and every check passed. Final.
      • check_failed: A check the policy asks for did not pass. Final.
      • declined: The person declined. Final.
      • expired: No decision came before expires_at. Final.
      • canceled: The brand canceled it, or its text could not be sent. Final.

    • subject object

      • id ULID

      • pairwise_id pairwise identifier

      • reference string

      • tier number, one of the values below, optional

        How far the person's identity is verified.

        • 0: Their phone and email are verified.
        • 1: A selfie too, which keeps their reference face.
        • 2: A government document too.

    • request object

      • type string, one of the values below

        What the brand asks the person to approve.

        • wire: A wire transfer.
        • beneficiary_change: A change to whom a payment goes.
        • withdrawal: A withdrawal of funds.
        • password_reset: A reset of a password.
        • address_change: A change of address.
        • other: Anything else; the title says what.

      • title string, at most 120 characters

      • summary string, at most 280 characters, optional

      • money object, optional

        • amount_minor integer, at least 0

        • currency currency, ISO 4217

      • counterparty string, at most 200 characters, optional

      • reference string, at most 120 characters, optional

      • requested_at instant, RFC 3339

    • policy object

      • checks array of string, one of the values below

        • liveness: The selfie is of a live person at the phone, not a photo or a recording.
        • face_match: The selfie's face matches the person's reference face.

      • allow_decline boolean

      • allow_note boolean

      • expires_in_seconds integer, 60 to 3,600

    • callback object

      • url URL, at most 2,048 characters

    • metadata map, each value string, optional

    • agent object, optional

      • id ULID

      • key string

      • version integer

      • name string

      • org object

        • name string

      • credential_id ULID

    • checks array of one of the shapes below

      • One shape

        • check string, one of the values below

          A check the page runs before an approval counts.

          • liveness: The selfie is of a live person at the phone, not a photo or a recording.
          • face_match: The selfie's face matches the person's reference face.

        • passed always true

        • score number, 0 to 1, optional

        • mode string, one of the values below, optional

          The liveness mode the vendor says ran.

          • movement_and_light: Colored lights flashed on the screen during the selfie.
          • movement: No lights, for a device that asks for reduced motion; the vendor rates it the less accurate.

        • checked_at instant, RFC 3339

      • One shape

        • check string, one of the values below

          A check the page runs before an approval counts.

          • liveness: The selfie is of a live person at the phone, not a photo or a recording.
          • face_match: The selfie's face matches the person's reference face.

        • passed always false

        • score number, 0 to 1, optional

        • mode string, one of the values below, optional

          The liveness mode the vendor says ran.

          • movement_and_light: Colored lights flashed on the screen during the selfie.
          • movement: No lights, for a device that asks for reduced motion; the vendor rates it the less accurate.

        • reason string, one of the values below

          Why the check did not pass.

          • below_threshold: It scored under the threshold XipID holds it to.
          • no_face: The vendor found no face to score.
          • capture_failed: The selfie did not complete.
          • reference_missing: The brand deleted the reference face while the challenge was open.

        • checked_at instant, RFC 3339

    • consent object, optional

      • agreed_at instant, RFC 3339

      • notice_version string, one of the values below

        The notice the person agreed to before the selfie, by its version.

        • request-selfie-2026-11-02: A request's selfie notice of November 2, 2026, for a brand that keeps no frames.
        • person-selfie-2026-11-02: The notice of November 2, 2026, before the selfie that takes a person to Tier 1.
        • request-selfie-frames-2026-11-02: A request's selfie notice of November 2, 2026, for a brand that keeps frames, which says so and that the brand may get them only if the request is disputed.

    • note string, optional

    • text object, optional

      • provider_message_id string, optional

      • status string, one of the values below

        What became of the text, as the channel reports it; the last three are final.

        • accepted: The provider took the text.
        • queued: The provider holds the text before the carrier has it.
        • sending: The text is on its way to the carrier.
        • sent: The carrier has the text.
        • delivered: The phone received the text. Final.
        • undelivered: The carrier could not deliver the text. Final.
        • failed: The provider could not send the text. Final.

      • error_code string, optional

    • created_at instant, RFC 3339

    • sent_at instant, RFC 3339, optional

    • opened_at instant, RFC 3339, optional

    • decided_at instant, RFC 3339, optional

    • expires_at instant, RFC 3339

• has_more boolean

• next_cursor string or null

• previous_cursor string or null

{
  "data": [
    {
      "id": "01JD2RB7C9E1G3J5K7M9N1P3R5",
      "type": "challenge.verified",
      "api_version": "2026-09-26",
      "created_at": "2026-11-19T18:06:41.090Z",
      "data": {
        "id": "01JD2R5W8Y3K6M9P2S5V8X1Z4B",
        "brand_id": "01JD2R1A3C5E7G9J1K3M5N7P9Q",
        "status": "verified",
        "subject": {
          "id": "01JD2R2B4D6F8H0J2K4M6N8P0Q",
          "pairwise_id": "Vb3kQ9xR2mTz7LpW4nYc8d",
          "reference": "acct_4417",
          "tier": 1
        },
        "request": {
          "type": "wire",
          "title": "Wire to Ridgeline Fabrication",
          "summary": "The first payment on invoice 2291.",
          "money": {
            "amount_minor": 4500000,
            "currency": "USD"
          },
          "counterparty": "Ridgeline Fabrication",
          "reference": "INV-2291",
          "requested_at": "2026-11-19T18:04:00.000Z"
        },
        "policy": {
          "checks": [
            "liveness",
            "face_match"
          ],
          "allow_decline": true,
          "allow_note": true,
          "expires_in_seconds": 600
        },
        "callback": {
          "url": "https://acme-bank.example/xipid/outcomes"
        },
        "metadata": {
          "branch": "downtown"
        },
        "checks": [
          {
            "check": "liveness",
            "passed": true,
            "score": 0.98,
            "mode": "movement_and_light",
            "checked_at": "2026-11-19T18:06:41.090Z"
          },
          {
            "check": "face_match",
            "passed": true,
            "score": 0.99,
            "checked_at": "2026-11-19T18:06:41.090Z"
          }
        ],
        "text": {
          "status": "delivered"
        },
        "created_at": "2026-11-19T18:04:00.512Z",
        "sent_at": "2026-11-19T18:04:01.204Z",
        "expires_at": "2026-11-19T18:14:00.512Z",
        "consent": {
          "agreed_at": "2026-11-19T18:06:12.377Z",
          "notice_version": "request-selfie-2026-11-02"
        },
        "opened_at": "2026-11-19T18:05:30.861Z",
        "decided_at": "2026-11-19T18:06:41.090Z"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null
}

Errors

• json_invalid, 400: The request body is not valid JSON.
• parameter_invalid, 400: The request contains invalid parameters.
• parameter_unknown, 400: The request contains a parameter this route does not take.
• version_invalid, 400: Xip-Version names no released version of this API.
• cursor_invalid, 400: The cursor is malformed or belongs to another list.
• authentication_required, 401: Authentication is required.
• authentication_failed, 401: The credential is invalid, expired or revoked.
• insufficient_scope, 403: The credential does not allow this operation.
• content_too_large, 413: The request body is larger than this route accepts.
• media_type_unsupported, 415: This route does not accept that Content-Type.
• rate_limit_exceeded, 429: Too many requests; try again later.
• internal_error, 500: Something went wrong on our side.
• upstream_error, 502: A service XipID depends on failed.
• service_unavailable, 503: The service is temporarily unavailable.
• upstream_timeout, 504: A service XipID depends on did not answer in time.