Every API request must have a bearer token attached in the Authorization header.
These tokens are generated within the GiveCampus UI and only school administrators with super-user permissions can generate and manage them. You will choose this initial set of “full” administrators during the GiveCampus onboarding process.
All API responses will be delivered over a secure HTTPS connection, and a TLS version of 1.2 or 1.3 is required.
GiveCampus maintains detailed logs of API access and can provide them to your team upon request.
The API delivers data asynchronously using a request-and-poll pattern:
request_id and a status of in_progress./results/{request_id} every 2–5 seconds until status changes to completed (or error).download_url containing a JSON array of objects matching the model defined below.Most requests complete within a few seconds.
You can use the tools below to see responses from the API to understand how to build your own implementation.
You will see the URLs and paths necessary to make your own API calls.
Bearer API_TOKENrequest_id. Copy that ID and then use that in the results section to see the progress of your request and to see the download URL once the request is completed.In the routes section below, there is a "Try it out" button. After authenticating, you can select from the available parameters, and you will see the curl request performed, the results of your request, and any errors if applicable.
GiveCampus Proprietary and Confidential
basePath: "/api/v2" securityDefinitions: Bearer: type: apiKey name: Authorization in: header description: Enter the token with the `Bearer ` prefix, e.g. "Bearer XXXXXXXXXXXXX" paths: "/constituents/search": post: tags: - Search for constituents summary: Search for constituents description: 'Retrieve a list of constituents based on various search criteria.
gc_constituent_ids (optional) - Array of GiveCampus’s internal identifier
ids (optional) - Array of your external CRM’s identifier
last_updated_at (optional) - UTC Unix Timestamp of when constituent was last modified; if provided, the API will return all records updated on or after this timestamp
emails (optional) - Array of emails that will search based on any of the known email addresses
first_names, last_names, middle_names (optional) - Arrays of names
phones (optional) - Array of phone numbers; matched
against the cell, home, work, and preferred numbers, comparing digits only
so formatting is ignored. A US number matches whether or not the country code
is included, and extensions are ignored, so +1 (555) 987-6543,
5559876543 and 555-987-6543 x12 are all treated
as the same number
address_cities, address_states, address_zipcodes, address_countries, address_line_1s (optional) - Arrays of address values; when more than one address filter is provided, a single address on the constituent must satisfy all of them
How filters are matched:
text values are matched exactly, ignoring case and surrounding whitespace,
against the values returned in the constituent payload. Partial and nickname
matching are not supported, so first_names: ["Dan"] will not
return "Daniel".
Any value within a single filter may match; when multiple filters are provided, all of them must match. A single value may be sent on its own in place of a one-element array.
' operationId: searchConstituents produces: - application/json parameters: - in: body required: true schema: type: object "$ref": "#/definitions/SearchConstituents" security: - Bearer: [] responses: '200': description: Successfully retrieved constituents schema: "$ref": "#/definitions/ApiRequest" '400': description: Invalid request schema: "$ref": "./types/bad_request_error.yaml" '401': description: Unauthorized schema: "$ref": "./types/unauthorized_error.yaml" '500': description: Internal Server Error schema: "$ref": "./types/internal_server_error.yaml" "/constituents": post: tags: - Create constituents summary: Create constituents description: Batch create one or more constituents. Limited to 5000 records per request. Please make sure to include the `id` field for each constituent. Without the `id`, the constituent will not be created and will return an error. When adding email addresses, you can provide as many as you'd like. If you provide an email address whose `primary` field is set to `true`, it will be set as the **preferred email** for the constituent. If you provide an email address with an `email_type` of `business`, it will be set as the **business email** for the constituent. If you provide an email address with an `email_type` of `other`, it will be set as the **other email** for the constituent. These email types are case-insensitive. If you provide multiple email addresses with `email_type` `business` or `other`, the first one will be used. operationId: createConstituents produces: - application/json parameters: - in: body required: true schema: type: array items: "$ref": "#/definitions/CreateConstituent" security: - Bearer: [] responses: '200': description: Successfully created constituents schema: "$ref": "#/definitions/ApiRequest" '400': description: Invalid request schema: "$ref": "./types/bad_request_error.yaml" '401': description: Unauthorized schema: "$ref": "./types/unauthorized_error.yaml" '500': description: Internal Server Error schema: "$ref": "./types/internal_server_error.yaml" put: tags: - Update constituents summary: Update constituents description: Batch update one or more constituents. Limited to 5000 records per request. Please make sure to include the `gc_constituent_id` field for each constituent. This field is the unique identifier for the constituent in GiveCampus. If you do not include this field, the constituent will not be updated and will return an error. Empty arrays for associated data will delete all records of that type. Only included data will be retained - omitted data will be deleted. When adding email addresses, you can provide as many as you'd like. If you provide an email address whose `primary` field is set to `true`, it will be set as the **preferred email** for the constituent. If you provide an email address with an `email_type` of `business`, it will be set as the **business email** for the constituent. If you provide an email address with an `email_type` of `other`, it will be set as the **other email** for the constituent. These email types are case-insensitive. If you provide multiple email addresses with `email_type` `business` or `other`, the first one will be used. operationId: updateConstituents produces: - application/json parameters: - in: body required: true schema: type: array items: "$ref": "#/definitions/UpdateConstituent" security: - Bearer: [] responses: '200': description: Successfully updated constituents schema: "$ref": "#/definitions/ApiRequest" '400': description: Invalid request schema: "$ref": "./types/bad_request_error.yaml" '401': description: Unauthorized schema: "$ref": "./types/unauthorized_error.yaml" '500': description: Internal Server Error schema: "$ref": "./types/internal_server_error.yaml" "/results/{request_id}": get: tags: - Results summary: Get your results description: Returns the results of your request, like constituents operationId: findResults produces: - application/json parameters: - in: path name: request_id schema: type: string required: true description: Request ID security: - Bearer: [] responses: '200': description: returns a status and download url for your request schema: "$ref": "#/definitions/ApiResults" '202': description: returns a status for your request schema: "$ref": "../shared/types/in_progress_api_results.yaml" '401': description: Unauthorized schema: "$ref": "./types/unauthorized_error.yaml" '404': description: Not Found schema: "$ref": "./types/not_found_error.yaml" '500': description: Internal Server Error schema: "$ref": "./types/internal_server_error.yaml" definitions: SearchConstituents: type: object properties: gc_constituent_ids: type: array items: type: string format: uuid description: Array of GiveCampus's internal identifiers required: false ids: type: array items: type: string example: '39596819' description: Array of your external CRM's identifiers required: false last_updated_at: type: integer example: 1713805903 description: UTC Unix Timestamp of when a constituent was last modified; if provided, the API will return all records updated on or after this timestamp required: false emails: type: array items: type: string format: email description: Array of emails that will search based on any of the known email addresses required: false first_names: type: array items: type: string example: Daniel description: Array of first names; matched exactly, ignoring case and surrounding whitespace required: false last_names: type: array items: type: string example: Smith description: Array of last names; matched exactly, ignoring case and surrounding whitespace required: false middle_names: type: array items: type: string example: Marie description: Array of middle names; matched exactly, ignoring case and surrounding whitespace required: false phones: type: array items: type: string example: 555-555-1234 description: Array of phone numbers; matched against the cell, home, work, and preferred numbers, comparing digits only so formatting is ignored. A US number matches with or without the country code, and extensions are ignored required: false address_cities: type: array items: type: string example: Los Angeles description: Array of cities; matched exactly, ignoring case and surrounding whitespace required: false address_states: type: array items: type: string example: California description: Array of states; matched exactly against the value stored on the address, ignoring case and surrounding whitespace required: false address_zipcodes: type: array items: type: string example: '90001' description: Array of zip codes; matched exactly against the value stored on the address, ignoring case and surrounding whitespace required: false address_countries: type: array items: type: string example: US description: Array of countries; matched exactly against the value stored on the address, ignoring case and surrounding whitespace required: false address_line_1s: type: array items: type: string example: 555 Cherry Cir description: Array of street addresses; matched exactly, ignoring case and surrounding whitespace required: false CreateConstituent: allOf: - "$ref": "./types/constituent_base.yaml" - type: object required: - id UpdateConstituent: allOf: - type: object properties: gc_constituent_id: type: string format: uuid required: - gc_constituent_id - "$ref": "./types/constituent_base.yaml" Constituent: allOf: - "$ref": "./types/constituent_base.yaml" - type: object properties: gc_constituent_id: type: string format: uuid ApiRequest: "$ref": "../shared/types/api_request.yaml" ApiResults: "$ref": "../shared/types/api_results.yaml"