XipID

Challenges

Create a challenge

POST https://api.xipid.org/challenges

Asks a person the brand linked, named by the pairwise identifier their referral answered, to approve a request. XipID texts them a link before it answers, and posts the outcome to the callback URL when the challenge closes. The callback URL is https and resolves to public addresses alone, or the challenge is refused before anything is made; XipID checks it again at each delivery and never follows a redirect. A retry under the same Idempotency-Key is answered the same challenge, its link null: the link is shown once. An agent of the brand's org creates one for a person who delegated their presence to it, naming them by the pairwise identifier one of its org's brands holds for them: the challenge goes out under that brand, by the brand's text, and its outcome, signed with the brand's secrets, names the agent. Without a live delegation it is refused, consent_missing, before anything is sent.

Scope: any live key of the brand, or any live credential of an agent.

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. Each challenge is a text: at most 5 an hour and 20 a day reach one number whoever asks, and one org's brands ask for at most 600 an hour and 10,000 a day; past either, the create is refused 429 and makes nothing.

Idempotency: takes an Idempotency-Key, which it requires: a retry under the same key is answered what the first request was, for 24 hours, and the key sent with another request is refused.

Changes: 2026-09-26: added.

Parameters

Body

{
  "subject": {
    "pairwise_id": "Vb3kQ9xR2mTz7LpW4nYc8d"
  },
  "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-19T13:04:00-05:00"
  },
  "policy": {
    "checks": [
      "liveness",
      "face_match"
    ],
    "expires_in_seconds": 600
  },
  "callback": {
    "url": "https://acme-bank.example/xipid/outcomes"
  },
  "metadata": {
    "branch": "downtown"
  }
}

Answers

201 Created

The challenge, with the link the person was texted, which no other answer shows. Location names it.

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

{
  "id": "01JD2R5W8Y3K6M9P2S5V8X1Z4B",
  "brand_id": "01JD2R1A3C5E7G9J1K3M5N7P9Q",
  "status": "sent",
  "subject": {
    "id": "01JD2R2B4D6F8H0J2K4M6N8P0Q",
    "pairwise_id": "Vb3kQ9xR2mTz7LpW4nYc8d",
    "reference": "acct_4417"
  },
  "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": [],
  "text": {
    "status": "sent"
  },
  "created_at": "2026-11-19T18:04:00.512Z",
  "sent_at": "2026-11-19T18:04:01.204Z",
  "expires_at": "2026-11-19T18:14:00.512Z",
  "link": "https://app.xipid.org/c/Ab3dEf6hJk9mNp2qRs5tUv"
}

Errors