Groundswell: Giving & Charity API integration (Personal Giving Account · DAF OpenData)

Authorization & account binding

An OAuth-style consent flow that binds a Groundswell account to your back-end. We expose POST /auth/login, POST /auth/refresh and a session-revocation endpoint. Used by HRIS systems and benefits portals that surface a "View my Personal Giving Account" tile without forcing employees to leave the host app.

Contribution & balance API

Read the running balance of the Personal Giving Account, plus inbound contributions broken out by channel: payroll deduction, ACH (Plaid), stock gift, and Apple Pay / Google Pay. Used to reconcile employer match budgets and to power "your giving so far this year" charts.

Grant disbursement API

Outbound grants to 501(c)(3) charities, including grant ID, recipient EIN, amount, fee breakdown, status (queued, disbursed, returned) and the Chariot disbursement reference where applicable. Useful for finance teams and impact-reporting dashboards.

Match-on-donation & match-on-contribution

Programmatic access to corporate match programs: matchable amount remaining, applied multipliers, and per-employee caps. Lets engineering teams add a small "your match doubles this gift" callout inside an internal Slack bot or intranet widget.

Volunteering & events

Hours logged, events attended, and approval state for skills-based volunteering. Pairs with payroll or recognition systems so volunteer time-off (VTO) policies can be enforced without manual exports.

Tax-receipt automation

One consolidated annual receipt for all contributions to the donor-advised fund, plus per-grant acknowledgement metadata. Delivered as PDFs or structured JSON for direct import into TurboTax-style tax-prep tools or ERP charitable-giving ledgers.

1. HRIS-embedded giving tile

Business context: A 5,000-person employer wants employees to see their Personal Giving Account next to payslips inside their HRIS without rolling out a separate vendor login.

Data & APIs: account login, balance, year-to-date contributions, year-to-date matched amount, last three grants.

OpenData mapping: account-binding follows the same authorize / token / refresh pattern as OpenBanking AISP flows; only consented, read-only fields cross the boundary.

2. Finance & ERP grant reconciliation

Business context: Corporate finance needs to book outbound DAF grants and the matched corporate contribution as separate ledger entries.

Data & APIs: grant disbursement export (CSV / Excel), match-program records, settlement timestamps, fee breakdowns.

OpenData mapping: mirrors statement-API patterns from OpenBanking — paged, date-bounded, idempotent reads with stable transaction IDs for audit.

3. Tax-prep & donor reporting

Business context: A tax-prep app wants to ingest Groundswell year-end receipts so users do not re-enter charitable contributions.

Data & APIs: annual aggregated receipt, per-grant acknowledgement letters, capital-gains-eligible stock contribution metadata.

OpenData mapping: structured receipt JSON aligned with IRS substantiation rules under Revenue Ruling 2018-38 and DAF reporting under the Pension Protection Act of 2006.

4. Real-time match-on-donation widget

Business context: An internal Slack bot prompts employees with "Your company will match this gift up to $250 today."

Data & APIs: match-program eligibility check, remaining match cap, webhook for completed grants to auto-thank the donor.

OpenData mapping: consent-scoped read of match metadata; write actions remain inside Groundswell, so we ship an event-driven, read-only integration.

5. Impact reporting dashboard

Business context: A CSR team publishes a quarterly impact dashboard showing grants by cause area, geography and employee participation.

Data & APIs: grants joined to charity directory metadata (EIN, category, country) and to volunteer activity.

OpenData mapping: aggregated, anonymized output; raw donor identities never leave Groundswell unless the donor opts in to public recognition.

1. Authorization — bind a Personal Giving Account

// Step 1: redirect the user to the consent screen
GET /api/v1/groundswell/authorize?
    client_id=acme-hris
    &scope=account.read,contributions.read,grants.read,receipts.read
    &redirect_uri=https://acme.example/cb
    &state=xyz123

// Step 2: exchange the code for an access token
POST /api/v1/groundswell/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "ac_9F8a...",
  "redirect_uri": "https://acme.example/cb"
}

// Response
{
  "access_token": "gs_at_...",
  "refresh_token": "gs_rt_...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "account_id": "pga_01HZK..."
}

2. Statement query — donation history & grants

POST /api/v1/groundswell/statement
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "account_id": "pga_01HZK...",
  "from_date": "2026-01-01",
  "to_date":   "2026-04-29",
  "include":   ["contributions", "grants", "matches"],
  "page_size": 50
}

// Response
{
  "balance": { "currency": "USD", "amount": 412.55 },
  "contributions": [
    { "id": "ctr_01...", "channel": "payroll",  "amount": 50.00, "ts": "2026-04-15T13:02Z" },
    { "id": "ctr_02...", "channel": "ach_plaid", "amount": 100.00, "ts": "2026-03-30T18:11Z" }
  ],
  "grants": [
    { "id": "grt_91...", "ein": "13-1644147", "charity": "American Red Cross",
      "amount": 75.00, "status": "disbursed", "settled_at": "2026-04-02T09:15Z" }
  ],
  "next_cursor": "eyJwYWdlIjoyfQ=="
}

3. Webhook — new grant disbursed

POST https://acme.example/hooks/groundswell
X-Groundswell-Signature: t=1714435200,v1=9f8e...
Content-Type: application/json

{
  "event": "grant.disbursed",
  "account_id": "pga_01HZK...",
  "grant": {
    "id": "grt_91...",
    "ein": "13-1644147",
    "amount": 75.00,
    "match_amount": 75.00,
    "settled_at": "2026-04-02T09:15Z",
    "disbursement_ref": "chariot_xc_4421"
  }
}

// Verify HMAC-SHA256 signature with your webhook secret,
// then upsert into your CSR ledger and trigger the
// "thank you" notification flow.

4. Tax-receipt fetch (annual)

GET /api/v1/groundswell/receipts/annual?year=2025
Authorization: Bearer <ACCESS_TOKEN>

// Response (truncated)
{
  "year": 2025,
  "donor": { "name_on_record": "J. Doe", "country": "US" },
  "sponsoring_org": {
    "name": "Groundswell Charitable Foundation",
    "ein":  "XX-XXXXXXX",
    "type": "501(c)(3) public charity"
  },
  "total_contributions_usd": 1820.00,
  "stock_gift_fmv_usd":      400.00,
  "receipt_pdf_url": "https://.../receipts/2025-jdoe.pdf"
}

Charitable-giving regulation

Groundswell’s Personal Giving Accounts are donor-advised funds sponsored by a 501(c)(3) public charity, so the integration must respect IRS DAF rules under the Pension Protection Act of 2006: no more-than-incidental benefit to the donor, no quid-pro-quo grants, and proper substantiation per Revenue Ruling 2018-38. Every API surface we ship logs the consent record and the originating user agent for audit.

Data privacy

For U.S. donors we align with state privacy laws including the CCPA / CPRA, and for international employees of multinational customers we follow GDPR principles — lawful basis, purpose limitation, retention windows, and data-subject access. Bank credentials never touch our servers; account linking goes through Plaid as Groundswell already does in production.

Authorized access only

We do not bypass authentication, scrape PII, or extract data without consent. All flows are authorized by the end user via an explicit consent screen, scoped to read-only fields, and revocable at any time. Where Groundswell publishes an official partner API or sandbox, we prefer that path; reverse-engineering is reserved for documented, lawful use cases under written customer authorization.

Deliverables checklist

• OpenAPI / Swagger specification for every exposed endpoint
• Protocol and authorization-flow report (consent, token refresh, revocation, signature verification)
• Runnable source for login, statement, grant and receipt APIs (Python or Node.js)
• Webhook receiver template with HMAC verification
• Automated test suite plus Postman / Insomnia collection
• Compliance brief covering DAF rules, IRS substantiation, GDPR / CCPA

Engagement workflow

1. Scope confirmation: which screens / fields you need (account, contributions, grants, match, receipts).
2. Authorized protocol analysis and API design (2–5 business days).
3. Build and internal validation against a test Personal Giving Account (3–8 business days).
4. Documentation, sample apps, and acceptance tests (1–2 business days).
5. First delivery typically 5–15 business days; multi-employer or webhook-heavy stacks may take longer.

FAQ

What do you need from me?

How do you handle compliance?

Source code or hosted API?

About our studio

We are an independent technical-service studio specialising in App interface integration and authorized API integration. Our engineers come from fintech, payments and CSR / philanthropy infrastructure backgrounds, and have shipped donor-advised fund, payroll-giving and impact-reporting integrations on both Android and iOS.

• Protocol analysis & reverse engineering for authorized data extraction
• OpenData / OpenFinance / OpenBanking pattern alignment
• Custom Python, Node.js and Go SDKs with test harnesses
• Two engagement models: source-code delivery from $300 (pay after delivery upon satisfaction) or pay-per-call hosted APIs with no upfront cost

Contact

For a quote, sandbox access discussion, or to share your Groundswell integration requirements, open our contact page:

Contact page

Typical response within one business day. NDAs available on request.