GivingData’s Web Publishing APIs allow foundations to pull information from GivingData into their website via their own integration, with control over what fields and data from the available endpoints will be published.
Website APIs are not intended to be queried in real-time from the public-facing site. The best practice is for clients using these APIs to schedule a process that pulls all of the currently published data from GivingData and stores it within the database of the public-facing site.
These APIs allow for the retrieval of Published Grants data and pairs with our Published Grants feature. The Published Grants feature allows you to decide which Organizations, Grants and Payments should be published, create separate grant Titles and Descriptions for external audiences, and manage a 990 Description for each grant.
Available endpoints include:
Grants - Request records that have been published.
Grantees - Organization records associated with your published grant records
Payments - You can optionally allow Payments records belonging to your published grant records to be retrieved.
Code Types - You can publish individual Code Types and their associated Codes from within GivingData. This will allow your website to mirror the coding structure you have defined in GivingData.
Getting Access to GivingData’s Web Publishing Endpoints
After your CSM has turned on the API Web Publishing Functionality within your site, it is time to decide what endpoints from the organizations and requests you would like to be available for publication.
Most fields on Organization, Requests and Payments records are available for potential publication. The most important thing to think about here is how and what you are hoping to show on your website.
For example, are you hoping to see your grants split by their Geographic Area Code? By Fiscal Year, By Program Area? Do you want the Descriptions of Grants, Recommended or Requested Amount?
For a full list of available fields, please see the list at the bottom of this article. Here are some common fields that we see Foundations configuring for publication to their website:
Requests:
OrganizationId
WebsiteTitle (entered in the Publishing tab)
WebsiteDescriptions (entered in the Publishing tab)
GrantAmount
ApprovalDate
ProgramArea (code assignment)
PrimaryStaffMember
Organizations:
Name
LegalName
Website
PrimaryAddress
Payments:
RequestId
OrganizationId
Amount
PaymentDate
ProgramArea (code assignment)
Once you have decided which fields to publish, please contact your Client Success Manager with the final options. The GivingData Development team will then prepare those fields for publication.
Connecting to Your Integration
At this point, the member of your team who will be building the integration (most likely a member of your IT team or your foundation’s website developer) will need to have an account created in GivingData and be in a role that will give them the necessary permissions. After a user account for the member has been created, the following two steps will need to be taken in whatever order works best for you:
An API key for that user will need to be generated: In order to use APIs within the system, users need a key. This key can be generated by going into “Manage My Profile” in the top right hand corner of your GivingData site.
Once in your Profile, navigate down to Integrations, and press “Create API Key”. You can optionally assign an expiration date for your API Key if you want it to only be operable for a certain amount of time.
Alternatively, you can generate and manage API Keys for other GivingData users in the “Settings > Users” area. The same options to generate, delete, and set an expiration date are available here.
If the user already has an API Key generated, you can use this same key for the Web Publishing API.
Web Publishing Permissions must be given to the user for the appropriate edits.
There are two sets of permissions associated with the Web Publishing API:
One group provides permissions for selecting the requests to be published via the integration. These permissions are discussed in the “Publishing Grants Data to your Website” section below.
The other group provides a role the ability to use the APIs within the system and pull the information into the foundation's website. These permissions are primarily for this IT/Technical User who is responsible for the integration.
To provide API permissions to a role, go to “Manage Roles and Permissions” in Settings Management and select the appropriate Role. Within that role you can give them permissions to “View Data in Open APIs” and then the associated permission within the “Published Grants” tab.
Then press “Update.”
Publishing Grants Data from within GivingData
After the Foundation’s website developers or IT team have completed building your custom integration, grants can be published to your website individually or in batch using Super Search.
User Permissions
Determine which roles within GivingData should be able to publish grants to your website.
To access the associated permissions, go to Settings→ Roles and Permissions and click into the role you want to edit.
Scroll down to the Publishing Tab in the Request Permissions section and select the “Manage Website Export Fields” permission. Then, specify which dispositions you would like the user to have these permissions.
Requests within the Exploring Disposition cannot be published on the website due to their early stage in a grant's life cycle.
Publishing to the Website on an Individual Record:
Navigate to the request record you would like to publish to your website and click on the Publishing tab.
Fill out the appropriate fields within the tab.
There are three fields available for use when website publishing:
Website Title (Optional): If you include the Request Title as one of the data points used in your website grants list, you have the option to use this field as a way of creating a “public facing” grant title. Your web integration can be set up to use this field if it’s populated, and, if blank, to use the standard Request Title field.
Often clients will use this field when funding sensitive issues in order to provide a vaguer title for external audiences while maintaining more detail within the internal GivingData site.Website Description (Optional): Like the Web Title/Request Title, if the Request Description field (on the Overview tab) is a field you include in your website grants list, it can be used to create a “public-facing” grant description where necessary.
Ready For Web (Required): This field defaults as Null. You have the option to change it to No or Yes. Null means the grant hasn’t been reviewed yet to determine if it should be published to the website or not. No means a determination that the grant should not be published to the website. Yes means the grant should, and is, published to the website.
Change the status to Yes to trigger the grant's push to the website. Only change it to Yes once you are ready for the grant to appear on the web.
Your grant is published and ready to be pulled by your custom integration into your website!
Publishing to the Website in Batch
Put together a Request Super Search with records that you would like added to the website.
For clients that publish all their approved grants on the website after their review meetings, that might look something like this:
Change your results list to Batch Edit mode and scroll down to “Update Publishing Properties” and Press the “Go” Button.
Note: Any requests with the checkbox next to them will be batch updated using this function. For more information about batch edits, please see this associated article.
In the Publishing Properties dropdown, select “Ready for Web” and “Yes.” Then, press “Update.”
Once you press “Update,” you will receive a notification letting you know that the batch process is taking place. You will then receive another notification about which records were successfully published.
If there are any requests that could not be successfully published, you will find further information within your notifications section of the site.
Full list of fields available are below:
Requests:Id
ApplicationReceiptDate
ApprovalDate
AssessmentPeriodLabels
AssessmentPeriods
AssessmentPeriodsComplete
Balance
CalculateEndDate
ChangeDate
CreateDate
Currency
DeclinationDate
DeclinationNotes
DeclinationReason
DeclinedAmountExchangeRate
DeclinedAmountOtherCurrency
DeclinedAmountRateDate
Description
DispositionDate
DocketNumber
ExpenditureBalance
FiscalSponsor (see Organization fields)
GrantAmount
GrantAmountExchangeRate
GrantAmountOtherCurrency
GrantAmountRateDate
GrantFiscalYear
HasAlert
HasAssessmentGroups
HasAssessments
HasFiscalSponsor
InternalApprovalAllowed
InternalApprovalDecisionRequired
MatchAmount
MatchBenefitsReceived
MatchDate
MatchDonorId
MatchDonorType
MatchDonorUserId
MatchHonoreeName
MatchMultiplier
MatchNotes
MatchTaxDeductibleAmount
MatchTotalContributionAmount
MeetingDate
MeetingMinutes
NineNinetyDescription
Notes
NumberOfPayments
NumberOfRequirements
Organization (see Organization fields)
OriginalGrantAmount
Paid
PaymentsRemaining
PendingAmount
PendingDate
PrimaryContact
PrimaryStaffMember (see User/Contact fields)
ProjectBudget
ProjectBudgetExchangeRate
ProjectBudgetOtherCurrency
ProjectBudgetRateDate
ProjectEndDate
ProjectStartDate
ProjectTitle
PublishedToBoardPortal
PublishingNotes
ReadyForWeb
RecommendedAmount
RecommendedAmountExchangeRate
RecommendedAmountOtherCurrency
RecommendedAmountRateDate
ReferenceNumber
RegrantingAmount
RegrantingBalance
RegrantingEnabled
RegrantingTotal
Renewable
Renewal
RenewalNotificationDate
RequestAmount
RequestAmountExchangeRate
RequestAmountOtherCurrency
RequestAmountRateDate
RequestDate
SalesforceId
SecondaryStaffMember (see User/Contact fields)
SourceId
SourceTypeId
Status (Id, Name, Type/Disposition)
StatusDate
Subdivision
TermMonths
TermYears
TotalExpended
TotalUnverifiedExpenses
TrackExpenditureResponsibility
UnscheduledAmount
WebsiteDescription (entered in the Publishing tab)
WebsiteTitle (entered in the Publishing tab)
Code Assignments
Custom Fields
Organizations:Id
Aka
ApprovedTotal
AvgGrantSize
Background
BoardMembers
ChangeDate
ChangeUser
ComplianceNotes
CreateDate
CreateUser
DeclinedCount
DeclinedTotal
ExploringCount
ExploringTotal
FaxExtension
FaxNumber
FirstGrantApprovedAmount
FirstGrantApprovedDate
FullTimeStaff
GrantAmountPerMonth
HasAlert
HasRegrants
IntacctVendorId
LastGrantApprovedAmount
LastGrantApprovedDate
LastPaymentDate
LegalName
Mission
Name
Notes
OfficePhoneExtension
OfficePhoneNumber
PartTimeStaff
PendingCount
PendingTotal
PlanningCount
PlanningTotal
PublishedToBoardPortal
SalesforceId
SortAs
SourceId
SourceTypeId
TaxId
TaxStatusExpiresDate
TaxStatusLastVerifiedDate
TotalPaid
Type
VendorId
Vision
Volunteers
Website
YearFoundedCode Assignments
Custom Fields
Payments
Id
RequestId
OrganizationId
Amount
ScheduleDate
PaymentDate
Status
Code Assignments
Custom Fields
User/Contact Fields (for above entities)Id
FullName
Email
FirstName
MiddleName
LastName
Title
