The CausIO API

Getting started

An owner of your organization makes a key in CausIO on Settings > API, then sends a request with it. Every address below starts with:

https://api.causio.org/v1

curl https://api.causio.org/v1/auctions?status=live \
  -H "Authorization: Bearer cio_your_key"

{
  "data": [
    {
      "id": "6f1c…",
      "name": "Spring Gala 2027",
      "status": "live",
      "starts_at": "2027-04-12T23:00:00+00:00",
      "ends_at": "2027-04-19T03:00:00+00:00",
      "timezone": "America/Chicago",
      …
    }
  ],
  "has_more": false
}

Keys

• Send the key in the Authorization header as Bearer cio_…. A key only reaches its own organization's data.
• Read only keys can use every GET. Read and write keys can also use the POST and PATCH requests. No request charges a card, sends messages, or opens or closes an auction.
• A key is shown once, when it's made. Keep it on your server, never in a web page or app people can download. If one leaks, revoke it on Settings > API and make a new one.
• Every request is listed under Recent requests on Settings > API, so the organization can see what each key did.

Lists and paging

Lists answer { "data": [...], "has_more": true }, newest first (items by lot number). Use limit (1 to 100, 50 if left out) and offset to page, and created_after (an ISO date and time) to fetch only what's new since your last sync. One record answers { "data": {...} }.

Amounts are in dollars. Times are ISO 8601 in UTC; each auction has its own timezone. People are referred to by supporter_id.

Errors and limits

Errors answer { "error": "What went wrong", "code": "BAD_REQUEST" } with the matching status:

Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

Organization and auctions

• GET/v1/org

  The organization the key belongs to.

• GET/v1/auctions

  Auctions, newest first.

  Filters: status: draft, scheduled, live, paused, closed or archived

• GET/v1/auctions/{id}

  One auction with its totals: items, bids, current high bids, paid (everything paid, donations included) and donations, both after refunds.

Items and bids

• GET/v1/auctions/{id}/items

  An auction's items by lot number, with fair market value, reserve and high bidder.

• GET/v1/items/{id}

  One item.

• POST/v1/auctions/{id}/items

  Add an item (write keys). Same fields as Add item in CausIO: title, description, starting_bid, bid_increment, fair_market_value, reserve_price, buy_now_price, category, donor_name and item_number. Photos are added in CausIO.

• GET/v1/auctions/{id}/bids

  Bids, newest first.

  Filters: item_id

Supporters

Supporters are the people in your CausIO list: bidders, donors and ticket buyers.

• GET/v1/supporters

  Supporters, newest first.

  Filters: email (exact match, any capitals)

• GET/v1/supporters/{id}

  One supporter.

• POST/v1/supporters

  Add a supporter (write keys): first_name, last_name, and optional email, phone (US or Canada) and notes. If one already has that email, it's returned unchanged with "created": false. New supporters get a bidder number and start with texts off.

• PATCH/v1/supporters/{id}

  Change first_name, last_name or notes (write keys). Email and phone are changed in CausIO, which lets the supporter know.

curl -X POST https://api.causio.org/v1/supporters \
  -H "Authorization: Bearer cio_your_key" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Ana","last_name":"Lopez","email":"[email protected]"}'

Invoices, donations and tickets

• GET/v1/invoices

  Invoices, newest first.

  Filters: auction_id, status: pending, sent, paid, voided or refunded

• GET/v1/invoices/{id}

  One invoice with its lines (items won, Fund-a-Need gifts, tickets, donations), each with unit_price, quantity and amount.

• GET/v1/donations

  Donations, newest first.

  Filters: auction_id, status: pending, paid, refunded or canceled

• POST/v1/auctions/{id}/donations

  Record a gift you were handed (write keys): amount, method (cash, check, wire or other), and supporter_id or first_name and last_name (with optional email), plus an optional note. Nothing is charged, and the donor gets the usual receipt.

• GET/v1/tickets/orders

  Ticket and sponsorship orders with their lines, newest first.

  Filters: auction_id

Webhooks

Instead of asking the API for changes, your server can be told the moment they happen. An owner adds your https address on Settings > API > Webhooks and picks the events; CausIO then POSTs each one as JSON.

POST https://your-server.example.org/causio
CausIO-Event: invoice.paid
CausIO-Delivery: 4b0c…
CausIO-Signature: t=1793401234,v1=5f2a…

{
  "id": "e1d9…",
  "type": "invoice.paid",
  "created_at": "2027-04-19T03:12:44+00:00",
  "data": {
    "id": "9a7e…",
    "auction_id": "6f1c…",
    "supporter_id": "b2c4…",
    "total": 650.00,
    "payment_method": "card",
    "paid_at": "2027-04-19T03:12:44+00:00",
    "for": "auction"
  }
}

• Check the signature. The endpoint's signing secret (shown once when it's added, or after New secret) signs t + "." + body with HMAC-SHA256. Compare it with v1, and refuse a t more than 5 minutes old.
• Answer quickly with any 2xx status, within 10 seconds, and do the work afterwards. Anything else is tried again after 1 minute, 5 minutes, 30 minutes, 2, 6, 12 and 24 hours. An endpoint that fails for 3 days is turned off.
• Events can arrive twice or out of order. Use the event's id to skip ones you've seen, and read the latest state from the API when order matters. Data is kept small; fetch the full record by its id.
• Send test on Settings > API sends a ping event.

// Node.js
import crypto from 'node:crypto'

function fromCausIO(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')))
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false
  const want = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  return v1.length === want.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(want))
}