CharityCheck PDF Example
For this example, the GuideStar CharityCheck Web Services will be examined and compared to the GuideStar CharityCheck APIs.
GuideStar CharityCheck is the only product in the world that is 100% compliant with all IRS requirements for determining a nonprofit’s eligibility to receive tax-deductible contributions. The ability to download and render a PDF that delivers CharityCheck information is a popular use of GuideStar Web Services and is now available as a ReST API.
CharityCheck SOAP web services are at these URLs:
The services available at http://www.guidestar.org/WebService.asmx are:
- GetCCInfo – returns Charity Check data in an XML string which follows the spec at http://www.guidestar.org/xsl/web_services/cc_schema.xsd.
- GetCCPDF – returns Charity Check report as a PDF that can be displayed in a browser or in Adobe Acrobat.
We will use the GuideStar CharityCheck PDF web service, GetCCPDF, and compare its implementation and results to the GuideStar CharityCheck PDF API. Both the Web Service and the corresponding ReST API take as a parameter the EIN (Federal Employee Identification Number) for a specific organization.
Since CharityCheck is a paid product, the GetCCPDF Web Service requires a login for a valid web services customer. Therefore cookies must be enabled and authentication credentials must be maintained in the browser session and propagated from the login call to the CharityCheck GetCCPDF call.
The first call is to the Login method at https://www.guidestar.org/WebServiceLogin.asmx. This method takes two strings as parameters:
userName – the GuideStar Web Service account username (e.g. email@example.com)
password – the GuideStar password
The second call is to the methods at http://www.guidestar.org/WebService.asmx to download the API.
GetCCPDF – returns Charity Check report as a PDF
This method takes a single string parameter: EIN – the EIN of the organization you are querying. (e.g. 54-1774039)
As with all Microsoft .NET SOAP calls, you first set up a web reference to https://www.guidestar.org/WebServiceLogin.asmx and http://www.guidestar.org/WebService.asmx. in the project file. The web reference handles much of the overhead of the web service call.
Sample C# code to call the web service is below. Adobe Acrobat is invoked to display the PDF document.
Text of code samples is here: Text Code Samples - Web Service to API Conversion
For comparison, we will describe the equivalent implementation of the GuideStar CharityCheck PDFAPI that can be accessed with this URL:
This code creates a web request object, add the user ID and password in the HTTP header, executes the request and starts Adobe Acrobat to display the PDF document.
The results of either call displays a PDF document: