Common API Use Cases and Examples

This article walks through a handful of the most common tasks integration developers use the WeGive API for, with worked request examples. All examples assume you already have an API key — see the API Overview & Authentication article if you don’t yet have one. Every request below uses the production base URL, https://api.wegive.com, and requires the standard bearer-token Authorization header. Swap in your sandbox base URL while developing.

Listing and finding donors

List donors for your organization:

curl https://api.wegive.com/api/dashboard/donors \
  -H "Authorization: Bearer ***" \
  -H "Accept: application/json"

Look up a single donor:

curl https://api.wegive.com/api/dashboard/donors/{donor} \
  -H "Authorization: Bearer ***"

Find an existing donor or create one if no match exists — useful for sync integrations that don’t want to maintain their own donor-existence check:

curl -X POST https://api.wegive.com/api/dashboard/donors/find-or-create \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "first_name": "Jane", "last_name": "Doe"}'

Create a donor directly, or update an existing one:

curl -X POST https://api.wegive.com/api/dashboard/donors \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "first_name": "Jane", "last_name": "Doe"}'

curl -X PUT https://api.wegive.com/api/dashboard/donors/{donor} \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Jane"}'

Managing communication lists

List your organization’s communication lists:

curl https://api.wegive.com/api/dashboard/communication-lists \
  -H "Authorization: Bearer ***"

Subscribe or unsubscribe a donor from a specific list:

curl -X POST https://api.wegive.com/api/dashboard/communication-lists/{communicationList}/subscribe \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"donor_id": 123}'

curl -X POST https://api.wegive.com/api/dashboard/communication-lists/{communicationList}/unsubscribe \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"donor_id": 123}'

Creating and managing pledges

Create a pledge:

curl -X POST https://api.wegive.com/api/dashboard/pledges \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"donor_id": 123, "amount": 5000, "fund_id": 456}'

Look up or update a pledge:

curl https://api.wegive.com/api/dashboard/pledges/{pledge} \
  -H "Authorization: Bearer ***"

curl -X PUT https://api.wegive.com/api/dashboard/pledges/{pledge} \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"amount": 6000}'

Reading and writing custom fields

Most resource types (campaigns, pledges, and others) expose their own custom-fields sub-endpoints for reading and updating custom field values on a specific record, e.g.:

curl https://api.wegive.com/api/dashboard/campaigns/{campaign}/custom-fields \
  -H "Authorization: Bearer ***"

curl -X POST https://api.wegive.com/api/dashboard/campaigns/{campaign}/custom-fields \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"my_custom_field": "value"}'

A note on stability

None of these endpoints are guaranteed against future change — see the API Versioning and Stability article for the current state of WeGive’s versioning practice before building a production integration that depends on an exact request/response shape.

Sources

wegive-api/routes/api.php: donor routes (GET/POST /dashboard/donors, POST /dashboard/donors/find-or-create, GET/PUT /dashboard/donors/{donor}), communication-list routes (GET/POST /dashboard/communication-lists, POST /dashboard/communication-lists/{communicationList}/subscribe|unsubscribe), pledge routes (GET/POST /dashboard/pledges, GET/PUT /dashboard/pledges/{pledge}), and the per-resource custom-fields sub-routes (e.g. GET/POST /dashboard/campaigns/{campaign}/custom-fields).
hermes-kb/external/support/settings/api-overview-authentication.md: base URLs and authentication header format reused here.

​Common API Use Cases and Examples

​Listing and finding donors

​Managing communication lists

​Creating and managing pledges

​Reading and writing custom fields

​A note on stability

​Sources