Skip to main content

Giveforms Connector (Technical Documentation)

Written by Philippe Trussart

Overview

The Give Forms connector provides read-only access to donation data from the Give Forms API.

It currently retrieves a single dataset:

  • donations

Each donation uses:

id

as its unique key. The connector does not create, update, refund, or otherwise modify Give Forms data.

Authentication

The connector requires:

username password

Requests use Basic Authentication against:

https://app.giveforms.com/api/v1

The connection test requests the first page of donations beginning from 0001-01-01 and succeeds when the API returns a valid array response.

API Requests

The connector uses GET requests only. There are no POST, PUT, PATCH, or DELETE requests.

Donation requests use:

GET /donations?date_from={YYYY-MM-DD}&page={page}

Example:

GET https://app.giveforms.com/api/v1/donations?date_from=2026-08-01&page=1

Pagination starts at page 1 and continues until Give Forms returns an empty page.

Sync Behavior

The connector performs an incremental date-based sync.

For each run, it reads the previous:

last_started

bookmark and converts it to a date:

YYYY-MM-DD

That date is then passed to Give Forms as date_from.

After the sync completes, the bookmark is advanced to the timestamp captured at the beginning of the current run.

Same-day overlap

Although the bookmark contains a full timestamp, only the date portion is used in the next API request.

For example:

Stored bookmark: 2026-08-10T15:30:00+00:00  Next API request: date_from=2026-08-10

This means donations from the bookmark day may be returned again on the next run. Consumers should expect some overlap and use id to identify the same donation across repeated syncs.

Data Shape & Raw Data

The connector maps commonly used donation attributes into dedicated fields, including donor information, donation amounts, payment details, campaign/source information, recurring information, refunds, UTM values, and other donation metadata.

It also includes:

raw

which contains the complete original donation response as JSON. This is useful when Give Forms returns fields that do not have dedicated mapped columns.

Nested values such as:

items questions url_parameters donation_honor

are also preserved as JSON.

Donation items

The connector exposes several dedicated fields for the first donation item:

items_0_name items_0_type items_0_quantity items_0_amount items_0_formatted_amount

If a donation contains multiple items, only item 0 is broken out into these dedicated columns. The complete items array remains available in the JSON field.

Refund Information

Refund information is partially flattened into dedicated fields, including the refunded amount, converted amount, new donation amount, and new net amount.

The original donation response is also retained in raw, so additional refund details returned by Give Forms remain available even if they are not separately mapped.

Deletes

The donation id is declared as both the unique key and delete key.

However, the connector does not actually retrieve or generate explicit deletion events. It does not:

  • Query a deleted-donations endpoint

  • Compare the current source dataset with the previous sync

  • Issue DELETE requests

Therefore, consumers should not assume that a donation removed from Give Forms will automatically be removed downstream.

Known Limitations & Notable Behavior

  • Only donations are supported. The connector does not currently retrieve other Give Forms resources.

  • Incremental filtering is date-only. The saved bookmark contains a timestamp, but requests use only YYYY-MM-DD. This intentionally results in same-day records potentially being re-read.

  • There is no upper date bound on a sync. Give Forms is queried using only date_from, so a run retrieves everything the API considers newer than that date.

  • Deletes are not explicitly propagated. Although id is identified as a delete key, there is no deleted-record feed or reconciliation process in the connector.

  • No retry or rate-limit handling is implemented. A failed API request causes the sync to fail rather than being automatically retried.

  • Pagination ends when an empty page is returned. There is no separate total-record or total-page value used to confirm completeness.

  • Only the first donation item is flattened. Donations containing multiple items require consumers to inspect the full items JSON field to access items beyond the first.

  • Schemas are predefined. New fields added by Give Forms will not automatically receive dedicated columns, but they remain available through the raw JSON record.

  • Missing nested values become NULL. If an expected nested path does not exist, the corresponding mapped field is returned as null rather than causing the donation to fail.

Did this answer your question?