REST API Data Feeds
GiveGab Enterprise supports at-will downloading of existing transaction and form response data, with no configuration needed. Use this feed to populate your customer relationship management database and update your client information after each campaign or event.
Query Structures
There are three REST API endpoints. You can build URL's using either response, transaction, or record endpoints and include specific parameters to pull different data samples. Please see below for a break down on the different endpoints and for the available parameters for each endpoint.
response.xml endpoint returns the master feed. This feed includes all of the response data from all forms and campaigns for an organization. The data feed generated by the response.xml endpoint can include all of the signup data as well as the transactional information from all forms, based on the parameters chosen, making it the most complete feed. This feed can be customized to provide data for specific campaigns to narrow down the data download.
transaction.xml endpoint returns all of the transactions for the organization grouped by for each successful credit card trans-action (charge or refund) that is processed by the GiveGab Enterprise system. It is used in conjunction with the response.xml feed to provide updates if you are have recurring or ongoing transactions. It does not provide any of the signup data. This feed can also be customized to return data only for specific campaigns.
record.xml endpoint returns a single form response record. It includes the original record or response information, all transactions to date, and all signup information relating to the form response. If you have a transaction record that does not correlate to an existing response record in your CRM, use this feed to create the response record.
Queries:
Schemas:
Query parameters for the Response Endpoint:
This query returns the master feed and will return data for all campaigns and forms in the GiveGab Enterprise history of your organization. Use following query parameters to target campaigns or dates for the feed.
*We recommend using a max record count of 500-1000 records to ensure there is not delay in processing. If you include commitments or answers, keep the record count lower to ensure the feed is responsive to the request. The more data you request at a time, the longer the response time.
Example query:
*Input your own user key, organization key, and channel for <string>
Glossary of Parameters for Response endpoint
*Note these parameters are caseSensitive.
user - Identifies the Show Anywhere Private Key for authentication. You can access this via the Your Profile tab under the Organization tab. Click the Show Anywhere Private Key icon to obtain your user key.
*Note each user key is tied to a particular admins email. If you remove that admin, any API query that utilizes its user key can break. We recommend creating a dedicated admin login for API testing purposes.
organization - Identifies the organization API key for authentication. You can obtain this by visiting the Organization Details tab under the Organization icon. Click the Show Organization API Key icon to obtain the Organization key:
feedVersion - V2 includes reporting codes for campaigns, forms and individual question answers.
startDate - Enter a value in yyyymmdd format. The feed will start with the first response after the date entered. By default, the response feed starts at the beginning of time unless you use this parameter. It will continue to present time unless you set a maxRecordCount.
Example URL:
https://api.kimbia.com/datafeed/rest/v01/response.xml?includeAnswers=true&feedVersion=V2&maxRecordCount=100&user=4G9RJRRC527Q9LRIRUXIB29G&organization=WZOS34P6&channel=abilap2ptestteam&startDate=20180716
firstTrackingCode - The feed will start with the response indicated by tracking code. By default, their response feed starts at the beginning of time unless you use this parameter. IT will continue to the present time unless you set a maxRecordCount.
Example URL:
firstConfirmationCode - The feed will start with the response indicated by confirmation code. By default, the response feed starts at the beginning of time unless you use this parameter. It will continue to the present time unless you set a maxRecordCount.
The confirmation code can be found on the Donation or Registration details page as the Registration or Donation code. It can also be found in the response or record feed as signup.id
lastTrackingCode - Starts the feed with the entry after the one specified as the lastTrackingCode. For example, if the last record included in the previous feed had a response id of 123456, use lastTrackingCode=123456 to start the next feed with record 123457. Within the context of the response datafeed, the tracking code is the response id . The response id is listed on the Donation or Registration Details page in the Kimbia platform as tracking code.
Example URL:
channel - Restricts your feed to responses from the forms for a specific campaign. The channel id is the channel prefix on the Campaign Details page.
maxRecordCount - Indicates to return up to X number of responses in this feed. This can be modified to any number. GiveGab recommends always including this parameter along with lastTrackingCode to reduce the amount of data being passed. We recommend adding a maxRecordCount=100, especially if you include answers and commitments.
includeAnswers - Set to true to include full responses with detailed answer information, such as mailing address city and state. The default is false. This parameter must be set to true if you want to use the includeCommitments parameter.
Example URL:
includeCommitments - Set to true to include records on signups that are Peer-to-peer Fundraiser Commitments. The default is false. You must also set includeAnswers=true for this parameter to work properly.
includeMetadata - Set includeMetadata=true to include all form response metaday in key value pairs, such as webBrowser, ipAddres, callerId, and messagingProfile as well as other user-defined metadata. The default is to exclude.
excludeDeclines - excludeDeclines=false will include all transaction result types including declines and errors. The default is to only include successful transactions.
Query Parameters for the Transaction Endpoint:
The below example query returns the master feed and will return data for all campaigns and forms in the Kimbia history of your organization. Use query parameters to target campaigns or dates for the feed.
We recommend using a max record count of 500-1000 records to ensure there is no delay in processing. If you include commitments or answers, keep the record count lower to ensure the feed is responsive to the request. The more data you request at a time, the longer the response time.
Example query:
*Input your own user key, organization key, and channel for <string>
Glossary of Parameters for the Transaction Endpoint
user - Identifies the Show Anywhere Private Key for Authentication
organization - Identifies the organization API key for authentication
feedVersion - V1 or V2. V1 is a subset of the metadata from V2. The Abila Fundraising50 and Abila Millennium format only supports this version. V2 includes reporting codes for campaigns, forms, and individual question answers.
startDate - Enter a value in yyyymmdd format. The feed will start with the first response after the date entered. By default, the response feed starts at the beginning of time unless you use this parameter. It will continue to present time unless you set a maxRecordCount.
Example URL:
firstTrackingCode - This feed will start with the response indicated by the Transaction code. By default, the response feed starts at the beginning of time unless you use this parameter. It will continue to the present time unless you set a maxRecordCount. The Transaction Code is listed on the Donation or Registration Details page in the Kimbia platform as tracking code:
firstConfirmationCode - The feed will start with the response indicated by confirmation code. By default, the response feed starts at the beginning of time unless you use this parameter. It will continue to the present time unless you set a maxRecordCount.
The confirmation code can be found on the Donation or Registration details page as the Registration or Donation code.
lastTrackingCode - Starts the feed with the entry after the one specified as the lastTrackingCode. For example, if the last record included in the previous feed had a response id of 123456, use lastTrackingCode=123456 to start the next feed with record 123457. The response id is listed on the Donation or Registration Details page in the Kimbia platform as transaction code. For the transaction endpoint, you need to pull the Transaction Code as shown here:
lastConfirmationCode - Starts the feed with the transaction after the confirmation code entered. For example, if you enter lastConfirmationCode=123456, then the feed will begin with the confirmation code 1234567.
maxRecordCount - Indicates to return up to X number of responses in this feed. This can be modified to any number. GiveGabe recommends always including this parameter along with lastTrackingCode to ensure the feed is responsive.
excludeDeclines - excludeDeclines=false will include all transaction result types. The default is to only include successful transactions.
includeCCDetails - This parameter allows you to return gateway detail metadata provided by the gateway at the time of the form submission.
includeCCDetails=ALL will return all of the available metadata that the gateway provides. The gateway metadata is also available via the form response record within the Enterprise platform:
Instead of returning ALL of the metadata available, a comma-separated list of keys returns a list of the details of the keys listed. For example, you can construct the parameter &includeCCDetails=Description,currency,amount
To find out which available keys are available for your particular gateway, you can navigate to the Gateway Information from the transaction details of the form response record.
Simply search a confirmation code, donor name, or email address within the platform and pull up the form response record. From there, you will need to click on the Transaction Code that is listed under the Associated Transactions section:
From there, click into the hyperlinked Gateway Information icon to expand the keys that will be available under the Details section as shown here:
*Note the keys that are available are unique to your gateway provider.
Example Query of ALL of the ccDetails:
Example Query of specific keys separated by commas:
eventTypes - This parameter allows you to filter the results of the feed based of the event type.
eventTypes=REFUND will filter the feed to only include refunds.
This parameter works well with the startDate parameter too. For example, if you wanted to generate results for all refunds that have occurred after a specific date, you'd add
&eventTypes=REFUND&startDate=YYYYMMDDto your query.
paymentSchedules - This parameter acts a filter to include or exclude transactions that are apart of a payment schedule (installment plan or ongoing plan).
=true means only txns with a Payment Schedule ID are included
=false means only txns without a Payment Schedule ID are included
if the parameter is not included no filtering happens
Example Queries:
Query Parameters for the Record Endpoint:
Single records can be requested based on the tracking code, the confirmation code, or the transaction code. It will return the entire form response record, including answers and commitments (if specified).
Example Query:
*Input your own user key, organization key, and desired tracking code for <string>
Glossary of Parameters for the Record Endpoint:
user - Identifies the Show Anywhere Private Key for Authentication
organization - Identifies the organization API key for authentication
feedVersion - V1 or V2. V1 is a subset of the metadata from V2. The Abila Fundraising50 and Abila Millennium format only supports this version. V2 includes reporting codes for campaigns, forms, and individual question answers.
trackingCode - Tracking code of the requested record.
confirmationCode - Confirmation code of the requested record.
transactionCode - Transaction code of the requested record.
includeAnswers - Set to true to include full responses with detailed answer information, such as mailing address, city, and state.
includeCommitments - Set to true to include records on signups that are Peer to peer Fundraising Commitments. You must set includeAnswers=true for this parameter to work.
includeMetadata - Set includeMetadata=true to include all form response metadata in key value pairs, such as webBrowser, ipAddress, calledId, and messagingProfiles as well as other user-defined metadata. The default is to exclude.