Quick start

Ask a person to approve a request, and get a signed answer back. It takes two calls and a callback.

Before you start

  • Your organization on XipID. We set it up with you. Book a demo
  • An API key. An admin makes it in your console, under Brands. A key is shown once, so keep it safe.
  • Your callback secret, from the same page.
  • A callback URL on https that XipID can reach.

Every request goes to https://api.xipid.org, with your key as a bearer token. Send an Idempotency-Key with every POST, so a retry never makes a second request.

1

Link the person

Invite the person by your own reference for them, and say what you’ll ask them to confirm. They accept once, in their own XipID.

curl -X POST https://api.xipid.org/subjects \
  -H "Authorization: Bearer $XIPID_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "acct_4417",
    "display_name": "Sam Rivera",
    "channel": { "type": "phone", "to": "+16195550142" },
    "scopes": [{ "attribute": "presence", "purpose": "wire_approval" }]
  }'
  • With a phone number, XipID doesn’t text the invitation. The answer carries an invite_url, and you send it to the person yourself, on your own channel.
  • With an email address ("type": "email"), XipID emails the invitation.
  • The subject stays pending until the person accepts. Then it’s linked, and carries the pairwise_id you ask with. GET /subjects/{id} shows where it stands.
2

Ask

When a request needs the person’s yes, create a challenge with the request in full and the checks you want.

curl -X POST https://api.xipid.org/challenges \
  -H "Authorization: Bearer $XIPID_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "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" }
  }'
  • XipID texts the person your name and one link, then answers with the challenge. The answer shows the link this once, and never again.
  • face_match needs a face on file: the person’s own first selfie, or one you enroll with PUT /subjects/{id}/reference-face. Without one, the call is refused with reference_face_missing. Ask for liveness alone when there’s no face on file.
3

Get the answer

When the person decides, or the challenge ends, XipID posts the outcome to your callback. It’s signed with your callback secret, by the Standard Webhooks spec. Check the signature with any Standard Webhooks library before you act on it.

challenge.verified
They approved, and every check passed.
challenge.check_failed
A check didn’t pass.
challenge.declined
They declined, with their note if they left one.
challenge.expired
No decision came before the challenge expired.
challenge.canceled
You canceled it, or its text couldn’t be sent.
  • GET /challenges/{id} has the result at any time. Each read is recorded, and the person sees it in their XipID.
  • Missed a callback? GET /events lists them, and POST /events/{id}/redeliver sends one again.

Next

  • API reference

    Every operation, with its parameters and its answers.

  • Errors

    Every code a call can be refused with. Each refusal links to its own page.

  • Changelog

    Send Xip-Version with the version you built against. Without it, your organization’s pinned version applies.

  • OpenAPI

SDK for Node: Soon.

Stuck? Contact us