Inherits DdApiBaseController.

Public Member Functions
	getBaseUrl ()
	_getRequirements ()
	index ($strCommand=null)
Public Member Functions inherited from DdApiBaseController
	__construct ()
	test ()
	_createSmarty ()
	showTestPage (JSONTransactionRequirements $r)
	validateAPIKey ($strAccessLevel=null)
	getQueryMetaArrayFromJSONDocument ($JSONDocument)
	getRequestObject ($strSchemaUrl)

Additional Inherited Members
Static Public Member Functions inherited from DdApiBaseController
static	success ($mxdRowsOrMessage, $strMessage=null)
static	error ($iErrorCode, $strMessage=null)
static	respond ($response, $strContentType="application/json")
Data Fields inherited from DdApiBaseController
const	CACHE_GROUP = 'dd'
Protected Member Functions inherited from DdApiBaseController
	getSESessionId ()
	setSESessionId ($sessionid)
	getRowsFromQuery ($query)
Protected Attributes inherited from DdApiBaseController
	$m_strSESessionId = null

Detailed Description

The DDAPI (Donor Direct Application Interface) Library was created to provide a back-end API to the Studio Enterprise Studio Enterprise data system so that other FH systems could integrate with Studio Enterprise.

Current Projects Interfacing with Studio Enterprise through this API

There are no current projects interfacing with Studio Enterprise via this API.

Development/Production Environments

The production URL is https://ddapi.fh.org/dd/. Please do not use production for testing purposes. All code should be tested against the development sandbox API (below) before

Developer sandboxes are created by the developers themselves, and have unique names according to a naming convention. For example, a development environment for developer John Doe might be http://jdoe.ddapi.fh.org/.
All URLs provided in the Web Service API Reference below refer to the beta environment URL beta.ddapi.fh.org. However, if you are a developer testing changes you have made, please make sure your browser is pointing to your own developer instance of the API.

Access Policies:

All applications must be authorized to access DDAPI, and must have their own unique API key that is included in every transaction. This API key may or may not be combined with an authorized IP address of a server that is accessing the API via HTTP requests. To request an API key, email suppo.nosp@m.rt@f.nosp@m.h.org, or jwats.nosp@m.on@f.nosp@m.h.org.

Use of JSON and JSON Schema:

API transactions are conducted using JSON objects that can be validated against JSON Schemas. If you are not already familiar with how JSON Schema works, it is highly recommended that you familiarize yourself with it, and find a good implementation of a JSON Schema validator implemented in the language your client program will be using. As of this writing, you may find an implementation in your langauage here.

For each request and response in this API, a JSON Schema has been prepared that describes each type of object. All JSON objects received and sent from this API are validated against a JSON Schema as described in IETF.org at (http://tools.ietf.org/html/draft-zyp-json-schema-03). The JSON Schema recommendation was proposed by Kris Zyp.

You can view the JSON Schema for any object in this API by accessing https://beta.ddapi.fh.org/dd/schema/requests/(objectname). For example, the json object required to be sent in an saveaccountdetail operation would be an object of type "account", described by the JSON Schema found at https://beta.ddapi.fh.org/dd/schema/requests/account

You can view all available schemas in this API by pointing your browser to: https://beta.ddapi.fh.org/dd/schema

Success and Error Schema

While accessing the API, if any error occurs, the standard error object will be returned as described in this JSON Schema. The schema for the standard error object can be found at https://beta.ddapi.fh.org/dd/schema/responses/error.

For operations that are not returning data, like an account save operation, the standard success object will be returned. The schema for the standard success object can be found at https://beta.ddapi.fh.org/dd/schema/responses/success.

Rider Data

Sometimes it can be useful for the server to return a unique identifer, or a set of data from the client as a pass through. This is useful for handling multiple asynchronous operations that may be acting on a single DOM element. This might help in avoiding race conditions or identifying the asynchronous response to the client.

The DD API supports this with the "clientdata" JSON property. When submitting the request, simply add an additional GET or POST parameter called "clientdata" and it will be appended to the JSON response object.

Example JSON Error with "clientdata" attached.

{ "success": false, "errorcode": 5000, "message": "Reason for login error will be provided here.", "clientdata": (arbitrary data from request) }

Example JSON Successful GET with "clientdata" attached.

{ "success": true, "message": "Records retrieved successfully.", "data": [...(record objects would be here)...], "clientdata": (arbitrary data from request) }

Web Service Reference:

https://beta.ddapi.fh.org/dd (these docs)
https://beta.ddapi.fh.org/dd/docs (also these docs)
https://beta.ddapi.fh.org/dd/getaccountdetail
https://beta.ddapi.fh.org/dd/getaccountpaymenthistory
https://beta.ddapi.fh.org/dd/getaccountcolumnreference
https://beta.ddapi.fh.org/dd/findaccount
https://beta.ddapi.fh.org/dd/saveaccountdetail
https://beta.ddapi.fh.org/dd/getpledgecolumnreference/
https://beta.ddapi.fh.org/dd/findpledge
https://beta.ddapi.fh.org/dd/processdonation
https://beta.ddapi.fh.org/dd/processimportbatch
https://beta.ddapi.fh.org/dd/gettestcards
https://beta.ddapi.fh.org/dd/getprojectcolumnreference
https://beta.ddapi.fh.org/dd/findproject
https://beta.ddapi.fh.org/dd/cache
https://beta.ddapi.fh.org/dd/schema

Documentation

Service URL: https://beta.ddapi.fh.org/dd/

Alternate URL: https://beta.ddapi.fh.org/dd/docs

Displays this documentation.

Required Form Post Parameters:
NONE

Returns:
HTML Document.
Example Request:
https://beta.ddapi.fh.org/dd/

Get Account Details (Getaccountdetail)

Service URL: https://beta.ddapi.fh.org/dd/getaccountdetail/

Test URL: https://beta.ddapi.fh.org/dd/getaccountdetail/test

Returns account details for the account you're looking for.

Required Form Post Parameters:
apikey: (string) The application's unique API Key that has been authorized to access DDAPI.
requestobject: JSON login object as defined in https://beta.ddapi.fh.org/dd/schema/requests/accountnumber.

Optional Form Post Parameters:
clientdata: (string) JSON data structure or scalar value that you would like the transaction to return to you with your request.

Returns:
(string) JSON object conforming to https://beta.ddapi.fh.org/dd/schema/responses/success.

NOTE: Unlike the 'find' family of transactions, the getaccountdetail transaction returns a complex JSON data object in the data.rows array rather than a flat set of columns as object properties. The data structure returned in this transaction is defined in https://beta.ddapi.fh.org/dd/schema/requests/account. All information associated with the account can therefore be found by crawling this object.
Example Request:

https://beta.ddapi.fh.org/dd/getaccountdetail/ POST apikey=q4nyAw3giEAbJp&requestobject={"accountnumber":"40286399"}

Get Account Details (Getaccountpaymenthistory)

Service URL: https://beta.ddapi.fh.org/dd/getaccountpaymenthistory/

Test URL: https://beta.ddapi.fh.org/dd/getaccountpaymenthistory/test

Returns account payment history for the account you're looking for.

Required Form Post Parameters:
apikey: (string) The application's unique API Key that has been authorized to access DDAPI.
requestobject: JSON login object as defined in https://beta.ddapi.fh.org/dd/schema/requests/accountnumber.

Optional Form Post Parameters:
clientdata: (string) JSON data structure or scalar value that you would like the transaction to return to you with your request.

Returns:
(string) JSON object conforming to https://beta.ddapi.fh.org/dd/schema/responses/success.

Example Request:

https://beta.ddapi.fh.org/dd/getaccountpaymenthistory/ POST apikey=q4nyAw3giEAbJp&requestobject={"accountnumber":"40286399"}

Get Account Column Reference (Getaccountcolumnreference)

Service URL: https://beta.ddapi.fh.org/dd/getaccountcolumnreference

Test URL: https://beta.ddapi.fh.org/dd/getaccountcolumnreference/test

Returns a resultset describing all the possible note-table fields associated with an account along with a discription of each one. These fields can be included in your account.ddnotefields request object array when filtering for accounts when calling findaccount.

Required Form Post Parameters:
apikey: (string) The application's unique API Key that has been authorized to access DDAPI.

Optional Form Post Parameters:
clientdata: (string) JSON data structure or scalar value that you would like the transaction to return to you with your request.

Returns:
(string) JSON object conforming to https://beta.ddapi.fh.org/dd/schema/responses/success.

Example Request:

https://beta.ddapi.fh.org/dd/getaccountcolumnreference/ POST apikey=q4nyAw3giEAbJp
Alternate View:
https://beta.ddapi.fh.org/dd/getaccountcolumnreference/html
(Displays the reference table in HTML view so you don't have to parse it into a table to look at it.)

Find Account (Findaccount)

Service URL: https://beta.ddapi.fh.org/dd/findaccount

Test URL: https://beta.ddapi.fh.org/dd/findaccount/test

Finds accounts by criteria provided in the requestobject. Any fields filled in on the account object you send in are used as filters to search for accounts in the database.

Required Form Post Parameters:
apikey: (string) The application's unique API Key that has been authorized to access DDAPI.
requestobject: JSON account object as defined in https://beta.ddapi.fh.org/dd/schema/requests/account

Optional Form Post Parameters:
clientdata: (string) JSON data structure or scalar value that you would like the transaction to return to you with your request.

Returns:
(string) JSON object conforming to https://beta.ddapi.fh.org/dd/schema/responses/success.

Example Request:

https://beta.ddapi.fh.org/dd/findaccount POST apikey=q4nyAw3giEAbJp&requestobject={...account object goes here...}

Account Save (Saveaccountdetail)

Service URL: https://beta.ddapi.fh.org/dd/saveaccountdetail/

Test URL: https://beta.ddapi.fh.org/dd/saveaccountdetail/test

Updates an existing account with new information.

Required Form Post Parameters:
apikey: (string) The application's unique API Key that has been authorized to access DDAPI.
requestobject: JSON account object as defined in https://beta.ddapi.fh.org/dd/schema/requests/account

Request Object Notes:

phones - This represents a phone record.
- Creating Phone Numbers To create a new phone number, simply don't include a recordid when saving the phone number. This will create a new phone record.
- Modifying Phone Numbers Phone numbers can be modified by including the recordid of the phone record you want to modify along with any new information you want to change. Fields that are not included in the JSON Request object will not be changed. If you would like to replace a certain value with an empty string, create a property on your JSON Request object with the appropriate name and assign an empty string as its value.
- Deleting Phone Numbers To delete a phone number, simply set the delete flag to true, as in phones[n].delete = true.
emails - This represents a email address record.
- Creating Email Addresses To create a new email address, simply don't include a recordid when saving the email address. This will create a new email address.
- Modifying Email Addresses Email addresses can be modified by including the recordid of the email address you want to modify along with any new information you want to change. Fields that are not included in the JSON Request object will not be changed. If you would like to replace a certain value with an empty string, create a property on your JSON Request object with the appropriate name and assign an empty string as its value.
- Deleting Email Addresses To delete a email address, simply set the delete flag to true, as in emails[n].delete = true.
creditcards - TBD: This is not done yet.
addresses[n].address - This represents an address record in the A03_AddressMaster table. The Account Save API does not allow you to modify an address. In order to do that, you must access the Address Save API. The reason this is restricted is because several accounts may be attached to the same address. Since Studio Enterprise supports grouping of accounts by a family ID, many accounts may be associated with the same address record in A03_AddressMaster. So in order to avoid changing the family's address when, say, a college student moves, the Account Save API allows you to detach the existing address using the delete flag, as in addresses[n].delete = true. Then you would save the account with a new address.
- Creating Addresses To create a new address, simply don't include an addressid when saving the address. This will create a new address record and associate it with the current account.
- Modifying Address Meta Data Address meta data, such as addresses[n].active (boolean), addresses[n].useasprimary (boolean), etc., are modifiable through this API. Simply provide the addressid in addresses[n].addressid along with your meta data, and the meta data attached to the account address will be updated.
- Detatching an Address from an Account Because addresses can't be deleted using the Account Save API, the only way to remove an address from an account is to detatch it. Detatch the address by setting the delete flag to true, as in addresses[n].delete = true.
notefields - This represents a pre-defined custom field associated with an account.
- Creating Note Fields Determine with your team ahead of time what a certain notetypecode should be for a given value if it doesn't already exist in the list generated by the /dd/getaccountcolumnreference/html endpoint. Once you have determined what the notetypecode will be, you really should add it to X02_DataTypeMaster along with a description of what the field means. The X02_DataTypeMaster table also defines any other constraints that might pertain to that field. For example, whether the system should allow multiple values to the same account for that typecode. After that is done, you simply need to save it as a notefield in the account. Note fields are arbitrary in the data model.
  
  There are no constraints between the actual note tables and X02_DataTypeMaster. So the list generated by /dd/getaccountcolumnreference is simply a compilation of all note fields that are being used now in some account somewhere. There are no foreign key constraints because the X02_DataTypeMaster table represents polymorphic links to various note tables.
  
  Note fields with an unrecognized typecode will be treated as a new notetypecode. In this case you will need to specify the storagetype on the notefield object. See the JSON Schema document for /dd/schema/requests/accountnotefield
- Modifying Note Fields Note fields can be modified by simply including the recordid of the note record in the notefields[n].accountnotefield object with your updated notevalue. Take special care to spell the notetypecode correctly, since misspelling it may result in adding a new notetypecode to the list of possible notetypescodes as mentioned above.
- Deleting Note Fields To delete a note field, simply set the delete flag to true, as in notfields[n].delete = true.

Optional Form Post Parameters:
clientdata: (string) JSON data structure or scalar value that you would like the transaction to return to you with your request.

Returns:
(string) JSON object conforming to https://beta.ddapi.fh.org/dd/schema/responses/success.

Note: The data.rows collection of the success object will contain a copy of the modified account object, populated with any new identifiers that you might need for a future request. This precludes the need to send another request to /dd/findaccount to get that info if you needed it for future queries.

Example Request:

https://beta.ddapi.fh.org/dd/saveaccountdetail/ POST apikey=q4nyAw3giEAbJp&sessionkey=qr2f3dahr7e4f5r&requestobject={...account object goes here...}

Find Pledge (Findpledge)

Service URL: https://beta.ddapi.fh.org/dd/findpledge

Test URL: https://beta.ddapi.fh.org/dd/findpledge/test

Finds pledges by criteria provided in the requestobject. Any fields filled in on the Pledge object you send in are used as filters to search for pledges in the database.

Required Form Post Parameters:
apikey: (string) The application's unique API Key that has been authorized to access DDAPI.
requestobject: JSON pledge object as defined in https://beta.ddapi.fh.org/dd/schema/requests/pledge

Optional Form Post Parameters:
clientdata: (string) JSON data structure or scalar value that you would like the transaction to return to you with your request.

Returns:
(string) JSON object conforming to https://beta.ddapi.fh.org/dd/schema/responses/success.

Example Request:

https://beta.ddapi.fh.org/dd/findpledge/ POST apikey=q4nyAw3giEAbJp&requestobject={...pledge object goes here...}

Process Donation (Processdonation)

Service URL: https://beta.ddapi.fh.org/dd/processdonation

Test URL: https://beta.ddapi.fh.org/dd/processdonation/test

Enters a donation into the Queue tables in Studio Enterprise for processing.

Required Form Post Parameters:
apikey: (string) The application's unique API Key that has been authorized to access DDAPI.
requestobject: JSON pledge object as defined in https://beta.ddapi.fh.org/dd/schema/requests/importbatch

Request Object Notes:

donations[n].accountnumber - An account number is always required for this transaction. Since Studio Enterprise does not actually support making anonymous donations, if the donation is anonymous, then the "Anonymous Donation" account number should be provided. Please contact Donor Direct for help creating an anonymous account if you don't already have one.
donations[n].transactions[n].payments[n].processpayment - This is a boolean flag that tells the system to send the payment to the card processing gateway. At the time of this writing, this system supports sending payments to BlueFin (BlueFin)
Important Concepts & Definitions:
- Transaction: A transaction represents any payment that was sent to the payment processing gateway or is supposed to be sent right now. Recurring transactions are not included in this array. However, if a customer would like the first installment of a recurring transaction charged to their card now, and recurring payments charged on a regular basis, then there should be a single transaction/payment along with a recurringdonation record. Recurring donation records represent ONLY future recurring transactions that have not yet been billed to the customer's card yet, and will not be billed until the specified date (recurringdonations[n].useonday)
- Payment: A payment represents a single card payment or "checkout" which would include any items that were in the donor's "cart" at the time of the checkout. If the item was a recurring donation, then it should only be included in the "payments" array if the first installment should be billed to the client now.
- RecurringDonation: A recurringdonation represents a recurring future card payment which would include any recurring items that were in the donor's "cart" at the time of the checkout. If the first installment should be billed immediately, then it should also be included in the "payments" array.

Optional Form Post Parameters:
apikey: (string) The application's unique API Key that has been authorized to access DDAPI.
sessionkey: (string) A unique session key returned by the getaccountdetail success object and associated with this user.
clientdata: (string) JSON data structure or scalar value that you would like the transaction to return to you with your request.

Returns:
(string) JSON object conforming to https://beta.ddapi.fh.org/dd/schema/responses/success.

Example Request:

https://beta.ddapi.fh.org/dd/processdonation/ POST apikey=q4nyAw3giEAbJp&requestobject={...donation object goes here...}

Get Pledge Column Reference (Getpledgecolumnreference)

Service URL: https://beta.ddapi.fh.org/dd/getpledgecolumnreference

Test URL: https://beta.ddapi.fh.org/dd/getpledgecolumnreference/test

Returns a resultset describing all the possible note-table fields associated with a pledge along with a discription of each one. These fields can be included in your pledge/ddnotefields/ request object array when filtering for pledges.

Required Form Post Parameters:
apikey: (string) The application's unique API Key that has been authorized to access DDAPI.

Optional Form Post Parameters:
clientdata: (string) JSON data structure or scalar value that you would like the transaction to return to you with your request.

Returns:
(string) JSON object conforming to https://beta.ddapi.fh.org/dd/schema/responses/success.

Example Request:

https://beta.ddapi.fh.org/dd/getpledgecolumnreference/ POST apikey=q4nyAw3giEAbJp
Alternate View:
https://beta.ddapi.fh.org/dd/getpledgecolumnreference/html
(Displays the reference table in HTML view so you don't have to parse it into a table to look at it.)

Get Test Credit Card Numbers (Gettestcards)

Service URL: https://beta.ddapi.fh.org/dd/gettestcards/

Returns a resultset describing all the possible credit card numbers you can use to test donation processing in this API. All of these card numbers are fake, but fit the standard checksum algorythm used to validate credit cards for their particular type. When using these cards, simply use any future expiration date, and any number with the appropriate number of digits in the CVC field for that card type.

Required Form Post Parameters:
apikey: (string) The application's unique API Key that has been authorized to access DDAPI.

Optional Form Post Parameters:
clientdata: (string) JSON data structure or scalar value that you would like the transaction to return to you with your request.

Returns:
(string) JSON object conforming to https://beta.ddapi.fh.org/dd/schema/responses/success.

Example Request:

https://beta.ddapi.fh.org/dd/getpledgecolumnreference/ POST apikey=q4nyAw3giEAbJp
Alternate View:
https://beta.ddapi.fh.org/dd/gettestcards/html
(Displays the reference table in HTML view so you don't have to parse it into a table to look at it.)

Get Project Column Reference (Getprojectcolumnreference)

Service URL: https://beta.ddapi.fh.org/dd/getprojectcolumnreference

Test URL: https://beta.ddapi.fh.org/dd/getprojectcolumnreference/test

Returns a resultset describing all the possible note-table fields associated with a project along with a discription of each one. These fields can be included in your project.ddnotefields request object array when filtering for projects when calling findproject.

Required Form Post Parameters:
apikey: (string) The application's unique API Key that has been authorized to access DDAPI.

Optional Form Post Parameters:
clientdata: (string) JSON data structure or scalar value that you would like the transaction to return to you with your request.

Returns:
(string) JSON object conforming to https://beta.ddapi.fh.org/dd/schema/responses/success.

Example Request:

https://beta.ddapi.fh.org/dd/getprojectcolumnreference/ POST apikey=q4nyAw3giEAbJp
Alternate View:
https://beta.ddapi.fh.org/dd/getprojectcolumnreference/html
(Displays the reference table in HTML view so you don't have to parse it into a table to look at it.)

Find Project (Findproject)

Service URL: https://beta.ddapi.fh.org/dd/findproject

Test URL: https://beta.ddapi.fh.org/dd/findproject/test

Finds projects by criteria provided in the requestobject. Any fields filled in on the project object you send in are used as filters to search for projects in the database.

Required Form Post Parameters:
apikey: (string) The application's unique API Key that has been authorized to access DDAPI.
requestobject: JSON project object as defined in https://beta.ddapi.fh.org/dd/schema/requests/project

Optional Form Post Parameters:
clientdata: (string) JSON data structure or scalar value that you would like the transaction to return to you with your request.

Returns:
(string) JSON object conforming to https://beta.ddapi.fh.org/dd/schema/responses/success.

Example Request:

https://beta.ddapi.fh.org/dd/findproject POST apikey=q4nyAw3giEAbJp&requestobject={...project object goes here...}

Cache Utility (Cache)

Service URL: https://beta.ddapi.fh.org/dd/cache/clear

Clears the server cache so information will be re-cached on the next request.

Various parts of the application cache information. At the time of this writing, the information stored in the cache is limited to expensive SQL queries that are not expected to change often. A good example of such a query would be the Pledge Column Reference, which takes about 6 to 10 seconds to compile the complete list of available note fields attached to a pledge.

This utility allows you to clear the cache so you can get up-to-date information about queries that have been cached. This is helpful when information stored in those queries has changed on the database server, and the new information must be reloaded into the cache.

Required Form Post Parameters:
apikey: (string) The application's unique API Key that has been authorized to access DDAPI.

NOTE: A special API key is required to clear the cache. This is to prevent any arbitrary application from clearing the API cache. Only authorized staff should use this API.

Required Form Post Parameters:
NONE

Returns:
(string) JSON object conforming to https://beta.ddapi.fh.org/dd/schema/responses/success.
Example Request:
https://beta.ddapi.fh.org/dd/cache/clear

JSON Schema Reference (Schema)

Service URL: https://beta.ddapi.fh.org/dd/schema

Test URL: https://beta.ddapi.fh.org/dd/schema/test

Shows a list of all available JSON schemas so you can browse and download the shema you're looking for.

Required Form Post Parameters:
apikey: (string) The application's unique API Key that has been authorized to access DDAPI.

Required Form Post Parameters:
NONE

Returns:
HTML Page listing available schemas that you can then click on to download. Example Request:
https://beta.ddapi.fh.org/dd/schema

Member Function Documentation

_getRequirements ( )

Should construct and return a JSONTransactionRequirements object defining the HTTP REQUEST requirements for this transaction.

Returns: JSONTransactionRequirements object

Reimplemented from DdApiBaseController.

getBaseUrl ( )

Returns the base URI for this API endpoint.

Returns: string URI for this API endpoint.