Build with VeriGiving

API basics and authentication

The base address is https://verigiving.com/api/v1. Requests and responses are JSON. Amounts are Canadian dollars as numbers (8500 or 8500.50). Times are ISO 8601 in UTC. Identifiers are UUIDs.

Create a key in your dashboard under API and send it as a bearer token. A key acts as your business, so keep it on your server. It is shown once, stored only as a hash, and can be revoked at any time.

curl https://verigiving.com/api/v1/business \
  -H "Authorization: Bearer vg_sk_your_key"

There are two kinds of key. A test key (vg_test_...) makes pages marked "test": true: nobody is emailed and no money can be taken, so it is the safe way to build and rehearse an integration. A live key (vg_sk_...) makes real pages. The requests and responses are identical.

A machine readable description is at /developers/openapi.json (OpenAPI 3.1), which Postman and most code generators can import.

When you create a page, send an Idempotency-Key header with a value that is unique to that file in your system. If the same request is retried, you get the page that was made the first time instead of a second page and a second email to the family.

The page object

A page is one family, one invoice, one link. Every endpoint that returns a page returns this shape.

{
  "id": "5b0c2a9e-3f1d-4c57-9a55-0d0a3b1f6c21",
  "object": "page",
  "slug": "in-memory-of-arun-sharma",
  "title": "In memory of Arun Sharma",
  "family_name": "The Sharma family",
  "family_email": "priya@example.com",
  "client_reference": "CRM-48213",
  "story": null,
  "status": "collecting",
  "visibility": "link_only",
  "created_via": "api",
  "invoice": {
    "id": "0f6d7c1e-8a52-4b0c-b1d2-7e9c4a3f2b10",
    "total": 8500,
    "currency": "CAD",
    "reference": "File 2026-0412",
    "document_url": null,
    "confirmed_at": "2026-10-01T15:04:11.000Z"
  },
  "contributed_total": 1250,
  "remaining": 7250,
  "contributor_count": 9,
  "url": "https://verigiving.com/c/in-memory-of-arun-sharma",
  "own_domain_url": "https://giving.yourbusiness.ca/c/in-memory-of-arun-sharma",
  "qr_url": "https://verigiving.com/api/qr?u=...",
  "test": true,
  "created_at": "2026-10-01T15:04:11.000Z",
  "updated_at": "2026-10-01T15:04:11.000Z"
}

POST/pages

Start a page for a family. Because you supply the invoice amount, the invoice is confirmed on creation and contributions open immediately. If you include the family's email, they receive the link.

curl https://verigiving.com/api/v1/pages \
  -H "Authorization: Bearer vg_sk_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: file-2026-0412" \
  -d '{
    "title": "In memory of Arun Sharma",
    "family_name": "The Sharma family",
    "family_email": "priya@example.com",
    "amount": 8500,
    "reference": "File 2026-0412",
    "client_reference": "CRM-48213"
  }'

Returns 201 with the page, or 200 with the original page when the idempotency key was seen before.

GET/pages

Your pages, newest first. Filter with status, client_reference (every page for one client in your CRM), or reference (your invoice number). Page with limit (1 to 100, default 25) and starting_after (the id of the last page you received).

curl "https://verigiving.com/api/v1/pages?status=collecting&limit=50" \
  -H "Authorization: Bearer vg_sk_your_key"

# Everything for one client in your CRM
curl "https://verigiving.com/api/v1/pages?client_reference=CRM-48213" \
  -H "Authorization: Bearer vg_sk_your_key"

{ "object": "list", "data": [ { "id": "...", "object": "page", ... } ], "has_more": false }

GET/pages/:id

One page with live totals. Use webhooks to be told when it changes, or poll; once a minute is plenty.

curl https://verigiving.com/api/v1/pages/5b0c2a9e-3f1d-4c57-9a55-0d0a3b1f6c21 \
  -H "Authorization: Bearer vg_sk_your_key"

PATCH/pages/:id

Send only what changes.

curl -X PATCH https://verigiving.com/api/v1/pages/5b0c2a9e-3f1d-4c57-9a55-0d0a3b1f6c21 \
  -H "Authorization: Bearer vg_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "invoice_total": 9100, "note": "Added reception catering" }'

GET/pages/:id/contributions

Contributions to a page, newest first: amount, the name the contributor gave, their note, and the time. Email addresses are not included. Use limit up to 100.

{ "object": "list",
  "data": [ { "id": "...", "object": "contribution", "amount": 100, "currency": "CAD",
              "contributor_name": "Meera K.", "note": "With love", "status": "succeeded",
              "created_at": "2026-10-02T13:20:05.000Z" } ],
  "has_more": false }

GET/business

The business the key belongs to: whether payments are enabled, your fee, and the links you hand to families (profile, start page, family package, QR code). The quickest way to check a key works.

Webhooks

Register up to three HTTPS addresses in your dashboard under API and VeriGiving will POST a signed JSON event to each one as things happen. Answer with any 2xx status within six seconds. Failed deliveries are retried daily, six times in all, and the dashboard shows the result of each.

Every event about a page carries your own client_reference and invoice reference, so your CRM can update the right client record without another request.

POST https://yoursystem.ca/verigiving-events
VeriGiving-Signature: t=1790900000,v1=5f2b...e91a

{ "id": "evt_9c1f...", "type": "page.settled", "created_at": "2026-10-04T18:22:10.000Z",
  "data": { "page_id": "5b0c2a9e-...", "client_reference": "CRM-48213", "reference": "File 2026-0412",
            "contributed_total": 8500, "contributor_count": 31, "test": false } }

Verify every event. The signature is an HMAC SHA256 of the timestamp, a dot, and the raw request body, using the signing secret shown once when you added the endpoint. Reject anything older than five minutes.

const crypto = require("crypto");

function verify(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 expected = crypto.createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Errors and rate limits

Errors use the HTTP status and one JSON shape. param names the field at fault when there is one.

{ "error": { "type": "invalid_request", "message": "The invoice amount must be between $100 and $500,000.", "param": "amount" } }

Rules the API will not bend

• Every page pays your own connected payment account. There is no field for another recipient, and there never will be.
• Collection stops at the invoice total. The last contribution can only be as large as what remains.
• Contributions of $1,000 or more include an identity check required by Canadian law, done on the page before payment. Nothing changes for you.
• Contributors are never charged a fee and are never asked for a tip.
• Keys are for your server. A key found in a public web page or repository will be revoked.

Questions and requests: support@verigiving.com.