GiveCampus API - A Deep Dive on Parameters

If you've already read about the basic of the GiveCampus API, you may have a few additional questions about certain call parameters. Most can be answered on the API Documentation page, but for everything else, here are some FAQs

If you've already read about the basics of the GiveCampus API, you may have a few additional questions about certain call parameters. Most can be answered on the API Documentation page, but for everything else, we've added some FAQ's below.

API Documentation Site

The site includes:

• Request, result, and data models including field name, type, and description
• A testing tool (using your an API token from your school) to understand the request lifecycle and parameters
• Additional security information

Users must log in to access the information (they do not need to be GiveCampus school admins)

• Username: givecampus
• Password: apiuser

Available documentation pages:

Sandbox API access

When testing in a GiveCampus sandbox environment, use the sandbox hostname and a token created in that environment. Sandbox access is separate from production.

Sandbox payment processing and deposit validation

When testing payments in the GiveCampus sandbox, the checkout flows simulate real transactions but do not move actual funds. Use the following points for deposit and transaction validation:

• Sandbox Stripe accounts are not linked to real bank accounts.
• Test transactions use Stripe’s test account data, preventing real fund processing or deposits.
• As a result, deposits will not appear in production or bank dashboards.

What this means for validation:

• Validate sandbox transactions via the GiveCampus sandbox admin interface.
• Use the sandbox API (with the sandbox base URL and token) to retrieve gift records and check timestamps (such as confirmed_at, checkout_at, captured_at) and payment statuses that mirror the simulated lifecycle.

Validation checklist:

1. Use the sandbox base URL and a sandbox token (tokens are environment-specific).
2. Create test transactions using the sandbox checkout flow.
3. Confirm that the transaction appears in the GiveCampus sandbox admin interface.
4. Retrieve the gift record via the sandbox API to verify timestamps and payment status.
5. Note that bank or production Stripe dashboards will not display these test transactions.

• Sandbox API base URL: https://sandbox.givecampus.com/api/...
• Production API base URL: https://www.givecampus.com/api/...

API tokens are environment-specific:

• Tokens created in production won’t work in the sandbox and vice versa.
• Generate a unique API token in each environment.

Where to create API tokens:

• Sign in to the environment you intend to use and navigate to School Dashboard > Integrations > API Keys to generate the token.

Testing tips:

• In the API Documentation site’s testing tool, use the token that corresponds with the base URL (sandbox or production).
• When copying example curl commands or sample code from production documentation, update the base URL and replace the Authorization token with your sandbox token.
• Keep sandbox tokens secure, rotate them when needed, and consider creating distinct tokens for different test integrations or team members.

• Gifts API Documentation
• Events API Documentation
• Event Registrations API Documentation

More API FAQs

Here are some additional questions you may have as you begin working with the API.

How many records can I include in a single bulk write request?

• A bulk write request (POST or PUT) is limited to 5,000 records. If a request exceeds this limit, it will return a 400 Bad Request response.

• This cap applies to all bulk write requests in the GiveCampus API, including those for creating or updating constituents, designations, designation groups, imported gifts, and other resources.

• For the assignments endpoint, the 5,000-record limit counts every constituent reference in the entire request body—not per array item.

• To send more than 5,000 records, split the data into multiple sequential requests of 5,000 records or fewer. This sequential batching is recommended for large imports.

• Note that this limit is separate from GET request rate limits and pagination rules, which are documented on the API Documentation site.

Can you explain the timestamp options?

The following are plain English explanations of the various timestamps that can be used to query against the GiveCampus API:

confirmed_at (i.e., datetime_of_pledge) - DEFAULT
The confirmed_at timestamp represents when a donor completes the GiveCampus online checkout flow. That said, it doesn't represent when we actually took money out of the donor's bank account, or when a school received the funds. 

For example, let's pretend I set up a matching gift on an athletics challenge (e.g., "I will give $5 for every donor who gives to Baseball, up to $1000"). I won't be charged immediately, because my total gift amount is conditionally based on how many other donors give to the campaign. If 30 donors make a gift to Baseball, my matching gift will ultimately get charged $150 at the end of the campaign. My confirmed_at field might be set to February 27th, 4:00pm ET (when I set up my match), whereas the captured_at + deposited_at fields described below might be a few days into the future (when the school's payment processor actually charged my credit card).

checkout_at
The checkout_at timestamp represents the moment a school's payment processor initiated a charge against the donor's credit card or bank account. This is when the money leaves the donor's account, but doesn't necessarily represent when it shows up within the payment processor's dashboard, or the school's bank account.

captured_at
The captured_at timestamp represents when the donor's money makes its way into the school's payment processor. It hasn't necessarily been deposited into the school's bank account yet.

deposited_at
The deposited_at timestamp represents when a donor's funds are deposited into the school's bank account. Schools can choose to accept daily, weekly, or monthly deposits for Stripe and daily deposits for PayPal.

Can you give an example of how timestamps might differ by payment type?

Example: Credit Cards
For regular one-time credit card transactions, the confirmed_at, checkout_at, and captured_at fields will almost always be within a few minutes of each other. This is by far the most popular type of gift made on GiveCampus. Let's pretend you make a gift to a school using Stripe. As soon as you complete our online checkout flow, Stripe will try to charge your card, and it will quickly appear within the school's Stripe account. That said, the checkout_at + captured_at fields can still be delayed for a few hours/days with credit card gifts, if the donor chose to make a matching gift in a Social Fundraising campaign (like in the first timestamp example for the confirmed_at field).

Example: Bank Gifts (Instant Verification)
Before you can initiate a bank transfer on GiveCampus, you have to prove you're the rightful owner of the bank account in question. If a donor uses Plaid to instantly verify ownership of their bank account (by logging into their online bank during the GiveCampus checkout process), the confirmed_at and checkout_at fields should be within a few minutes of each other. Stripe is able to immediately initiate the bank transfer, but the captured_at field will still be a few days into the future (to account for the extra time it takes for bank transfers to complete).

Example: Bank Gifts (Micro-deposit Verification)
If a donor does not want to login to their bank via Plaid to instantly verify ownership of the account, they can opt to manually verify ownership. They will receive a few pennies in their bank account, and be asked to verify the amounts deposited to prove they have access to the account. confirmed_at will represent the moment they completed the GiveCampus checkout flow, checkout_at will be a few days after that to represent when they verified the micro-deposit amounts, and captured_at will be a few more days after that once the funds land in the school's Stripe account. 

For gifts, what are the different payment states?

• Stripe payment states explained
• PayPal payment states explained (Coming soon)

For events, what are the different states?

draft - The event has been created but is not live and able to accept registrations

active - The event is live and able to accept registrations

complete - The event has concluded and is no longer accepting registrations

For events, what are the different payment states?

complete - The registration is complete and payment (if any) confirmed

incomplete - The registration has begun but final checkout and payment (if any) are not complete

payment_processing - The registration is in the process of completing payment

payment_failed - The registration payment failed

Preventing duplicate gifts when pulling gifts from the Gifts API

Duplicate gifts in your CRM often result from filtering requests incorrectly. Use the following guidelines and examples to make your integration idempotent and avoid importing the same gift more than once.

Quick checklist

• The default Gifts query filters by the confirmed_at timestamp. (The GiftApiRequestQuery uses start and end against confirmed_at unless you change the time_field.)
• You can set time_field to captured_at, checkout_at, created_at, deposited_at, refunded_at, or updated_at depending on your needs.
• Always include both start and end (as Unix timestamps) in your time-range queries.
• Use incremental, contiguous, non-overlapping ranges.
• For absolute control, use the ids parameter to request specific gift IDs and avoid duplicates.
• Remember that API tokens are environment-specific—production tokens won’t work in the sandbox and vice versa.

Recommended incremental pattern (safe, idempotent)

1. Store the most recent timestamp you successfully processed (for example, the maximum confirmed_at imported) as last_processed_at (Unix timestamp).
2. When polling the API, request a new batch with start = last_processed_at + 1 and end = now.
3. Sort the results by your chosen time_field in ascending order and process each gift, recording its unique API id to your deduplication index or CRM record.
4. Update last_processed_at to the largest time_field value from the successfully processed gifts.

This strategy prevents overlapping time windows and avoids retrieving duplicate gifts.

Why overlapping ranges cause duplicates

Requesting overlapping ranges (for example, using a lower start value than the previous request) can return the same gifts twice, as the API does not deduplicate results across calls. Deduplicate by gift id or ensure your time ranges do not overlap.

When to use a time_field other than the default

• Use confirmed_at for workflows that track when a donor completes checkout.
• Use captured_at or checkout_at to determine when a charge is initiated.
• Use deposited_at for deposit timing in reconciliation.
• Use updated_at to capture edits, refunds, or status changes.

Choose the time_field that best fits the event you want to record, as it directly affects which gifts fall within your specified time range.

Using the ids parameter

If you have a list of specific gift IDs (for reconciliation or re-import), pass the ids parameter to retrieve only those gifts. This avoids reliance on timestamps and prevents duplicates from overlapping time ranges.

Practical deduplication tips

• Persist the GiveCampus gift id when importing; use it as your primary deduplication key.
• If relying on timestamps, combine filtering with deduplication by id during import.
• If your polling strategy involves slight overlap (for network retries or safety), ensure your importer ignores gifts whose id is already in your system.

Handling updates and refunds

If you need to capture updates such as refunds or donor edits, use time_field=updated_at with appropriate start/end values. Match records by GiveCampus id and update existing entries rather than creating new ones.

Common pitfalls

• Not including both start and end: The API requires a bounded Unix timestamp range for predictable results.
• Using an incorrect time_field: For example, using deposited_at when immediate donation visibility is needed may delay record retrieval.
• Reusing tokens across environments: Production tokens are not valid in sandbox and vice versa.
• Relying on client-side time zones: Always use UTC in Unix timestamp format to avoid daylight saving and timezone issues.

Addressing existing duplicate gifts

• Export duplicate records from your CRM and match them with the corresponding GiveCampus id values, which are the canonical keys for deduplication.
• Remove or merge duplicate records, ensuring that only one record per GiveCampus id remains.
• For future prevention, adopt the incremental pattern and record each imported gift’s id into a deduplication table before creating CRM entries.