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.
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
pendinguntil the person accepts. Then it’slinked, and carries thepairwise_idyou ask with.GET /subjects/{id}shows where it stands.
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_matchneeds a face on file: the person’s own first selfie, or one you enroll withPUT /subjects/{id}/reference-face. Without one, the call is refused withreference_face_missing. Ask forlivenessalone when there’s no face on file.
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 /eventslists them, andPOST /events/{id}/redeliversends 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-Versionwith the version you built against. Without it, your organization’s pinned version applies. - OpenAPI
SDK for Node: Soon.
Stuck? Contact us