Subjects

Read a subject

GET https://api.xipid.org/subjects/{id}

The subject as it stands, by XipID's id for it, with the pairwise identifier once the person linked. Its ETag may go back as If-Match with a change to its reference face. Each read is recorded as the brand's read, with the key that made 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

• id in the path, required, ULID

  XipID's id for the subject.

• 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

The subject.

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

• 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

{
  "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"
}

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.
• 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.
• resource_not_found, 404: No such resource.
• 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.
• service_unavailable, 503: The service is temporarily unavailable.