Fundraise Up

说明文档

# FundraiseUp API Skill

## Overview
This skill enables Claude to interact with the FundraiseUp REST API for processing donations, managing recurring plans, retrieving supporter data, and accessing fundraising analytics. FundraiseUp is a digital fundraising platform that allows nonprofits to process donations from various channels.

## Configuration
Required environment variables:


```FUNDRAISEUP_API_KEY ```- API Key (e.g., ```ABEDDDD_XSSSHwzZc98KR53CWQeWeclA```)

## Base URL
```
https://api.fundraiseup.com/v1
```

## Authentication

### API Key Generation
1. Go to Dashboard > Settings > API keys
2. Click "Create API key"
3. Enter a descriptive name
4. Select data mode:
   - **Live data**: For production use
   - **Test data**: For testing (keys have `test_` prefix)
5. Select permissions:
   - Retrieve donation data
   - Create new donations
   - Generate Donor Portal access links
6. Save the API key securely (shown only once)

### Authentication Header
All API requests must include the `Authorization` header with Bearer token:

```bash
Authorization: Bearer YOUR_API_KEY
```

### Important Notes
- API keys are scoped to specific accounts/subaccounts
- Parent account API keys cannot create donations for subaccounts
- Only Organization Administrators can create API keys
- Never expose API keys publicly

## Rate Limits
- **8 requests per second**
- **128 requests per minute**
- Implement retry logic with exponential backoff for rate limit handling

## Required Headers
```bash
Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_API_KEY
```

---

## API Endpoints

### 1. Donations

#### List Donations
**Endpoint:** `GET /donations`

**Description:** Retrieve all donations with cursor-based pagination.

**Query Parameters:**
- `limit` (optional): Number of records per page (1-100, default: 10)
- `starting_after` (optional): Cursor for pagination (donation ID)
- `ending_before` (optional): Cursor for backward pagination (donation ID)
- Note: `starting_after` and `ending_before` are mutually exclusive

**Example Request:**
```bash
curl --request GET \
  --url 'https://api.fundraiseup.com/v1/donations?limit=50' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'
```

**Response Fields:**
- `id`: Donation identifier
- `created_at`: ISO 8601 timestamp
- `livemode`: Boolean (true for live, false for test)
- `amount`: Donation amount in selected currency
- `amount_in_default_currency`: Amount in organization's default currency
- `currency`: Three-letter ISO code (lowercase)
- `status`: Donation status (e.g., succeeded, pending, failed)
- `campaign`: Campaign details (id, code, name)
- `supporter`: Supporter information
- `recurring_plan`: Recurring plan details (if applicable)
- `designation`: Fund/program designation
- `tribute`: Tribute information (if provided)
- `custom_fields`: Array of custom field values
- `processing_fee`: Processing fee details
- `platform_fee`: Platform fee details
- `fees_covered`: Amount of fees covered by donor

---

#### Get Single Donation
**Endpoint:** `GET /donations/{id}`

**Description:** Retrieve details of a specific donation.

**Path Parameters:**
- `id` (required): Donation ID

**Example Request:**
```bash
curl --request GET \
  --url 'https://api.fundraiseup.com/v1/donations/DFQLCFEP' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'
```

---

#### Create Donation
**Endpoint:** `POST /donations`

**Description:** Create a one-time or recurring donation. API-created donations will have "API" as the donation source.

**Prerequisites:**
- Stripe account connected to FundraiseUp and activated
- Active campaign with money-based payment method
- API key with "create new donations" permission
- Stripe Payment Method ID (created via Stripe API)
- PCI compliance requirements met

**Request Body:**
```json
{
  "campaign_id": "FUNCPJTZZQR",
  "amount": "25.00",
  "currency": "usd",
  "payment_method_id": "pm_1234567890abcdef",
  "supporter": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "mailing_address": {
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "New York",
      "region": "NY",
      "postal_code": "10001",
      "country": "us"
    }
  },
  "recurring_plan": {
    "frequency": "monthly"
  },
  "designation": [
    {
      "id": "EHHJ9R36"
    }
  ],
  "tribute": {
    "type": "in_honor_of",
    "honoree": "Jane Smith"
  },
  "comment": "Monthly donation for general fund",
  "anonymous": false,
  "custom_fields": [
    {
      "name": "referral_source",
      "value": "Email Campaign"
    }
  ]
}
```

**Required Fields:**
- `campaign_id`: Must belong to the account and be active
- `amount`: Decimal string (e.g., "9.99" for USD, "200" for JPY), minimum $1 or equivalent
- `currency`: Three-letter ISO code (lowercase)
- `payment_method_id`: Stripe Payment Method ID
- `supporter.first_name`: Up to 256 characters
- `supporter.last_name`: Up to 256 characters
- `supporter.email`: Valid email address (not verified by API)
- `supporter.phone`: Up to 20 characters (required if campaign requires it)
- `supporter.mailing_address`: Required if campaign requires it

**Optional Fields:**
- `recurring_plan.frequency`: Creates recurring plan ("monthly", "weekly", "quarterly", "yearly", "daily")
- `designation`: Array of designation IDs
- `tribute.type`: "in_honor_of" or "in_memory_of"
- `tribute.honoree`: Name of person being honored
- `comment`: Donation comment
- `anonymous`: Boolean (default: false)
- `custom_fields`: Array of custom field objects

**Example Request:**
```bash
curl --request POST \
  --url 'https://api.fundraiseup.com/v1/donations' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaign_id": "FUNCPJTZZQR",
    "amount": "50.00",
    "currency": "usd",
    "payment_method_id": "pm_1234567890",
    "supporter": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  }'
```

**Important Notes:**
- All string parameters are trimmed; empty strings converted to null
- Addresses and emails are not formatted or verified
- Only credit card payments are currently supported
- Fees may show as 0 initially until Stripe finalizes (use Events endpoint for finalized fees)

---

#### Update Donation
**Endpoint:** `PATCH /donations/{id}`

**Description:** Update a donation. Updates only allowed within 24 hours of creation and only for API-created donations.

**Path Parameters:**
- `id` (required): Donation ID

**Limitations:**
- Only API-created donations can be updated
- Updates must occur within 24 hours of creation
- No bulk updates supported

---

### 2. Recurring Plans

#### List Recurring Plans
**Endpoint:** `GET /recurring_plans`

**Description:** Retrieve all recurring donation plans.

**Query Parameters:**
- `limit` (optional): Number of records per page (1-100)
- `starting_after` (optional): Cursor for pagination
- `ending_before` (optional): Cursor for backward pagination

**Example Request:**
```bash
curl --request GET \
  --url 'https://api.fundraiseup.com/v1/recurring_plans?limit=50' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'
```

**Response Fields:**
- `id`: Recurring plan identifier
- `created_at`: ISO 8601 timestamp
- `frequency`: "monthly", "weekly", "quarterly", "yearly", or "daily"
- `amount`: Recurring donation amount
- `currency`: Three-letter ISO code
- `status`: Plan status (active, paused, canceled)
- `next_installment_at`: Next scheduled donation date
- `ended_at`: End date (if set)
- `campaign`: Associated campaign details
- `supporter`: Supporter information

---

#### Get Single Recurring Plan
**Endpoint:** `GET /recurring_plans/{id}`

**Description:** Retrieve details of a specific recurring plan.

**Path Parameters:**
- `id` (required): Recurring plan ID

**Example Request:**
```bash
curl --request GET \
  --url 'https://api.fundraiseup.com/v1/recurring_plans/RVSHJNPJ' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'
```

---

#### Update Recurring Plan
**Endpoint:** `PATCH /recurring_plans/{id}`

**Description:** Update a recurring plan. Updates only allowed within 24 hours of creation and only for API-created plans.

---

### 3. Supporters

#### List Supporters
**Endpoint:** `GET /supporters`

**Description:** Retrieve all supporters/donors.

**Query Parameters:**
- `limit` (optional): Number of records per page (1-100)
- `starting_after` (optional): Cursor for pagination
- `ending_before` (optional): Cursor for backward pagination

**Example Request:**
```bash
curl --request GET \
  --url 'https://api.fundraiseup.com/v1/supporters?limit=50' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'
```

**Response Fields:**
- `id`: Supporter identifier
- `created_at`: ISO 8601 timestamp
- `email`: Email address
- `first_name`: First name
- `last_name`: Last name
- `phone`: Phone number
- `mailing_address`: Address details
- `mailing_list_subscribed`: Boolean
- `anonymous`: Boolean
- `employer`: Employer name (if provided)

---

#### Get Single Supporter
**Endpoint:** `GET /supporters/{id}`

**Description:** Retrieve details of a specific supporter.

**Path Parameters:**
- `id` (required): Supporter ID

**Example Request:**
```bash
curl --request GET \
  --url 'https://api.fundraiseup.com/v1/supporters/SXXXXXXX' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'
```

---

### 4. Events

#### List Events
**Endpoint:** `GET /events`

**Description:** Retrieve audit log events for donations, recurring plans, and supporters.

**Query Parameters:**
- `limit` (optional): Number of records per page (1-100)
- `starting_after` (optional): Cursor for pagination
- `ending_before` (optional): Cursor for backward pagination

**Example Request:**
```bash
curl --request GET \
  --url 'https://api.fundraiseup.com/v1/events?limit=50' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'
```

**Use Cases:**
- Track when fees are finalized (look for `donation.success` event)
- Monitor status changes
- Audit trail for compliance
- Integration debugging

---

### 5. Campaigns

#### List Campaigns
**Endpoint:** `GET /campaigns`

**Description:** Retrieve all campaigns.

**Query Parameters:**
- `limit` (optional): Number of records per page (1-100)
- `starting_after` (optional): Cursor for pagination
- `ending_before` (optional): Cursor for backward pagination

**Example Request:**
```bash
curl --request GET \
  --url 'https://api.fundraiseup.com/v1/campaigns' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'
```

**Response Fields:**
- `id`: Campaign identifier
- `code`: Campaign code
- `name`: Campaign name
- `status`: Campaign status

---

#### Get Single Campaign
**Endpoint:** `GET /campaigns/{id}`

**Path Parameters:**
- `id` (required): Campaign ID

---

### 6. Designations

#### List Designations
**Endpoint:** `GET /designations`

**Description:** Retrieve all fund/program designations.

**Example Request:**
```bash
curl --request GET \
  --url 'https://api.fundraiseup.com/v1/designations' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{FUNDRAISEUP_API_KEY}}'
```

---

### 7. Donor Portal Access

#### Generate Supporter Portal Link
**Endpoint:** `POST /donor_portal/access_links/supporters/{id}`

**Description:** Generate a secure link for a supporter to access their Donor Portal without logging in.

**Path Parameters:**
- `id` (required): Supporter ID

**Prerequisites:**
- API key with "Generate Donor Portal access links" permission ...