TBD - Developer's Guide for Data Sharing API

TBD - Developer's Guide for Data Sharing API

Introduction

Using the Data Sharing API, you can generate your own custom solutions to meet special data management and other fundraising needs. Learn more about the data flow process.

While GiftTool offers you extensive flexibility in managing your online operations, your organization may need separate, custom-built services that integrate with the GiftTool solution. With open, secure access to your online transaction data, the GiftTool Data Sharing API provides you the freedom to innovate and develop services that leverage your online activities with your overall mission.

This guide is intended for programmers who want to access GiftTool transaction and other customer data via an API. It provides an introduction to using the Data Sharing API and reference material on the available parameters.

GiftTool uses XML to present and reuse the customer centric information securely captured from your online applications. This document will help to explain the XML tagging structure for technical integration. Character sets are converted and supplied in UFT-8 format.When any of the data changes, we send it all to you again.

GiftTool’s Use of ID Tags

ID’s alone are not unique across the different GiftTool services. In other words, Bob in the Shop and Mary in the Donations, could both have an ID of 417. What makes the ID unique, is it’s combination with a prefix, which indicates which GiftTool service is being used. So Bob would be S417 and Mary would be D417, thereby making the IDs different and unique. Below is a table to clarify the different Prefixes used within GiftTool.

Prefix	GiftTool Service	Customer Types
P	Pledge-a-thon	Participant, Sponsor, Pledger
M	Membership	Member
R	Event Registrar	Registrant
S	Shopping Cart	Shopper
R	Donations	Donor
E	Email Marketing	Subscriber

API Data

API Data contains a collection of objects and the information associated under APIVersion, APIShareAccount and API Customer. Both APIVersion and APIShareAccount are used for the passing of Data. Customer is used when passing customer information as well.

Formatting hints:

Dates are stored as YY-MM-DD
Phone numbers are not preformatted with any punctuation or brackets.

Example of java code for APIData:

import java.util.*;
public class ApiData
{ public Vector objects = new Vector();
}

API Version

API Version is used to determine if there is the need for an update on how <> receives our data. A change to any of the 3 numbers, will indicate a change in the data structure. For example, API Version number 2.0.1 (big.medium.small): If there is a change to the first number (2 in this example), there has been a large change, such as the removal or restructuring of tags or the data structure. If there is a change to the middle number (0 in this example), there has been a medium change, such as an item within questions that can be posed to customers. If the final number has changed (1 in this example) the most likely change is that to just a field.

	Subtype ID	V/ S/ I	Explanation
		String	The version number of our API in order of big.medium.small.

Example of java code for APIVersion:

import java.util.*;
public class ApiVersion
{ public String version = "1.0.0";
}

API ShareAccount

API ShareAccount(s) are created by GiftTool clients in order to push transaction data to your application. One or more can be created; depending upon the information required. Login credentials are used to authenticate the API ShareAccount against the custom application forged between GiftTool and your application. This custom application will return either a 'true' or 'false' response based upon the information associated within the login that was inputted.

**TBD - note: what app requires will determine what of 3 (username, password, token) gets sent for authentication??** A url will need to be provided by those clients wishing to share data with the custom application and get their data pushed out.

***TBD -- insert screen shot***

XML Tag	V/ S/ I	Explanation
	String	The security token provided by the client, needed for authentication with or in place of the username and password.
	String	User's email address.
	String	Password created by the user, minimum 8 characters.
	String	Either true or false. Used when testing if the connection to the username and password are correct.

Example of java code for APIShareAccount:

import java.util.*;
public class APIShareAccount
{       public String username;
         public String password;
         public String token;
         public String test;
}

API Customer

The API Customer is broken down by type and subtype. Prefixes define the GiftTool service being used.

The API Customer will contain one or more API Activity. This area contains the demographic fields, which were collected in order to process the transaction. The billing address is used and required for credit card processing; especially with some US based clients who may be enforcing Address Verification Software via their payment gateway.

If testing system, there will be no customer.

XML Tag	V/ S/ I	Explanation
	String	The Type of person (Member, Donor, Participant etc.).
	String	How the person registered, choices assigned by the client.
	String	Prefix + Customer ID.
	String	Indicates the archived state that the Activity is in. N = Not Archived (aka Active), Y = Yes Archived, and D = Draft Version.
	String	Email address as provided by the customer. Must contain an @ symbol and (dot) domain name.
	String	Created by customer. No requirements for use of strong password creation including digits and being certain number of characters.