External Donation Ingestion

Last updated: March 3, 2026

Send donation data from any fundraising platform (Fundraise Up, GoodChange, NGP, etc.) directly to Switchboard using this API endpoint.

Endpoint

POST <https://webhooks.oneswitchboard.com/webhooks/donations/v1>

Authentication

For each provider you plan to ingest donations from, please send Switchboard:

the provider’s entity_id(s), and
the Switchboard organization(s) that each entity_id should be associated with.

Switchboard will configure each entity/organization mapping and will provide a separate set of credentials per provider.

e.g., “FundraiseUp: entity_id=campaign_123 mapped to Org A, Org B

This endpoint requires HTTP Basic Authentication.

Header	Required	Description
`Authorization`	Yes	Basic auth: `Basic base64(username:password)`
`Content-Type`	Yes	`application/json`

Request Body

Required Fields

Field	Type	Description
`entity_id`	string	The campaign or form ID provided by the provider during setup
`provider_donation_id`	string	Unique identifier for this donation from the provider.
`provider`	enum	The fundraising platform name. Options: `"fundraiseup"`, `"ngpvan"`, `"anedot"`, `"numero"`, `"goodchange"`, `"other"`. \|
`amount_in_cents`	integer	Donation amount in cents (e.g., `5000` for $50.00).
`paid_at`	string	ISO 8601 timestamp (e.g., `2025-01-15T14:30:00Z`).
`donor.email`	string	Donor's email address.

Optional Fields

Field	Type	Description
`test_mode`	boolean	When set to `true`, payload is validated but donation data is not stored.
`status`	nullable enum	The status of the donation. Only donations with status `approved` will be processed.
`form_name`	string	Name of the donation form or campaign.
`donor.phone`	string	Donor's phone number. E.164 format preferred (e.g.,`+15551234567`).
`donor.firstname`	string	Donor's first name.
`donor.lastname`	string	Donor's last name.
`donor.addr1`	string	Street address.
`donor.city`	string	City.
`donor.state`	string	State/province.
`donor.zip`	string	Postal code.
`donor.country`	string	Country code (default: `"US"`).
`donor.employer`	string	Employer name.
`donor.occupation`	string	Occupation.
`is_recurring`	boolean	Whether this is a recurring donation (`true` or `false`)
`recurring_period`	nullable enum	The recurring frequency. Options: `"monthly"`, `"weekly"`
`recurring_sequence`	integer	Payment number in the series (e.g., `3` for the third monthly payment)
`refcodes`	object	Key-value pairs for attribution tracking.
`refcodes.refcodeSB`	string	Switchboard refcode
`text_opt_in`	boolean	Whether the donor opted in to SMS.
`metadata`	object	Any additional data.

Example Requests

Full Payload

{
  "entity_id": "campaign_12345",
  "provider_donation_id": "ord_abc123",
  "provider": "goodchange",
  "amount_in_cents": 5000,
  "paid_at": "2025-01-07T10:00:00Z",
  "status": "approved",
  "form_name": "End of Year 2024",
  "donor": {
    "email": "jane@example.com",
    "phone": "+15551234567",
    "firstname": "Jane",
    "lastname": "Donor",
    "addr1": "123 Main St",
    "city": "Truckee",
    "state": "CA",
    "zip": "96161",
    "country": "US",
    "employer": "Acme Corp",
    "occupation": "Engineer"
  },
  "is_recurring": true,
  "recurring_period": "monthly",
  "recurring_sequence": 3,
  "refcodes": {
    "refcodeSB": "b-123-xYzAb",
    "utm_source": "email"
  },
  "text_opt_in": true,
  "metadata": {
    "payment_method": "card"
  }
}

Minimal Payload

{
  "entity_id": "campaign_12345",
  "provider_donation_id": "ord_xyz789",
  "provider": "fundraiseup",
  "amount_in_cents": 2500,
  "paid_at": "2025-01-07T10:00:00Z",
  "donor": { "email": "jane@example.com" }
}

Responses

Status	Description
`200 OK`	Accepted. Donation accepted and queued for processing.
`202 ACCEPTED`	Donation status is `refunded` or `declined`.
`400 Bad Request`	Invalid Payload. Missing or invalid request body, or missing required fields.
`401 Unauthorized`	Authentication failed. Invalid or missing credentials.
`500 Internal Server Error`	Server error.

Troubleshooting

Issue	Solution
`401 Unauthorized`	Verify your username and password. Contact support if credentials may be inactive.
`400 Bad Request`	Ensure all required fields are present, valid, and non-empty.
`500 Internal Server Error`	Retry or contact support.

Duplicate Protection

Switchboard uses provider + entity_id + provider_donation_id to construct an idempotency key for the donation. If the same provider_donation_id is sent more than once for the same provider and entity_id, the first request will be processed and subsequent requests will return a normal success response, but the duplicate donation will be ignored and not processed again.

Getting Setup

Before you can send donations, email support@oneswitchboard.com with:

Your provider name(s)
Each provider entity_id
Which Switchboard organization(s) each entity_id should map to

After we receive this, Switchboard will:

Configure your provider/entity-to-organization mappings
Issue your HTTP Basic Auth username/password (one set per provider)

Throughput Guidance

We recommend sending up to 300 requests per minute.

Backfill Guidance

You can start ingesting new donations as soon as credentials are issued.

For historical backfills, send us a CSV and we’ll estimate timing and handle the backfill for you.