> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wegive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Common API Use Cases and Examples

> Worked request examples for common WeGive API tasks: listing/creating donors, managing communication lists, creating and updating pledges.

# 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": "donor@example.com", "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": "donor@example.com", "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.