Subjects

Search subjects by reference

POST https://api.xipid.org/subjects/search

One page of the brand's subjects under one of its references, oldest first: the one it refers now and those the person unlinked before. The reference travels in the body, where no log keeps it.

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

• 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.

Body

• reference string, at most 128 characters

• limit integer, 1 to 100, 20 by default, optional

  How many items the page holds.

• starting_after string, optional

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

• ending_before string, optional

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

{
  "reference": "acct_4417",
  "limit": 20
}

Answers

200 OK

A page of subjects.

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

• data array of Subject

  • id ULID

  • reference string

  • status string, one of the values below

    Where the referral stands for the brand; the last three are final.

    • pending: Waiting on the person to accept.
    • linked: The person accepted: the brand has their pairwise identifier and may challenge them.
    • declined: The person declined. Final.
    • expired: Unanswered for thirty days. Final.
    • unlinked: The person took the brand's access back. Final.

  • pairwise_id pairwise identifier, optional

  • linked_at instant, RFC 3339, optional

  • invite_url URL, at most 2,048 characters, optional

  • display_name string, optional

  • channel object

    • type string, one of the values below

      The channel the brand referred the person by.

      • phone: A phone number.
      • email: An email address.

    • to_masked string, optional

  • scopes array of object

    • attribute string, one of the values below

      What the scope lets the brand do with the person.

      • presence: Ask them to confirm it is really them, by a challenge.
      • name: See their name.
      • date_of_birth: See their date of birth.
      • email: See their email address.
      • phone: See their phone number.
      • address: See their address.
      • tier: See their verification tier.
      • ssn_match: Check that a Social Security number the brand holds is theirs.

    • purpose string

  • reference_face object, optional

    • enrolled_at instant, RFC 3339

  • created_at instant, RFC 3339

  • updated_at instant, RFC 3339

• has_more boolean

• next_cursor string or null

• previous_cursor string or null

{
  "data": [
    {
      "id": "01JD2R2B4D6F8H0J2K4M6N8P0Q",
      "reference": "acct_4417",
      "status": "linked",
      "pairwise_id": "Vb3kQ9xR2mTz7LpW4nYc8d",
      "linked_at": "2026-11-18T15:42:55.020Z",
      "display_name": "Sam Rivera",
      "channel": {
        "type": "phone",
        "to_masked": "+1 ••• ••• 0142"
      },
      "scopes": [
        {
          "attribute": "presence",
          "purpose": "wire_approval"
        }
      ],
      "reference_face": {
        "enrolled_at": "2026-11-18T16:01:13.668Z"
      },
      "created_at": "2026-11-18T15:20:07.311Z",
      "updated_at": "2026-11-18T16:01:13.668Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null
}

Errors

• json_invalid, 400: The request body is not valid JSON.
• parameter_missing, 400: The request lacks a required parameter.
• 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.