The information below is meant to define how to connect to the GIVE_api and define the available methods/functions available within the GIVE_api. The GIVE_api is a FREE product as such, we provide technical support on a limited scale.

iOS, Android, JAVA, PHP and .NET/ASPX integration Libraries are now available for download. Click Here

GIVE_api Connection

Interested in using the GIVE_api? Here is all the information you'll need to connect your APP with our api.

Get Started

Available Methods

Search Charities

This method provides you with the ability to search active charities. (non-revoked status at CRA/IRS).

Learn More

Get Charity Details

This method provides numerous details on a specific charity. Examples are Mission Statement, Social Media links, Major Donors, Programs etc.

Learn More

Get Financial Details

This method provides financial details for a specific charity.

Learn More

Get Charity Files

This method provides charity files for a specific charity. Files may include information on General, Projects, Financial, Supplemental or NewProjects

Learn More

Get Charity Projects

This method provides details and information on specific projects for a charity.

Learn More

Get Charity Salaries

This method provides salary information for a charity.

Learn More

Donation Method

This method generates a unique URL to allow users the ability to make a one-time donation.

Learn More GAIN Response Info

Get Charity Types

This method provides a list of available charity types such as Education, Health, Religion, Welfare etc.

Learn More

Get Provinces and States

This method will provide a list of provinces and states that can be used to search charities.

Learn More

To view response codes and the corresponding messages Click Here

Search Charities

This method provides you with the ability to search charities active (non-revoked status at CRA/IRS) within Place2Give.

Action Name: searchCharities

Additional Request Parameters

Parameter Description Required
PageNumber The results page to display for the search. i.e. if the user is on page 5 – a 5 should be passed Yes
NumPerPage Number of results per page. Max value is 100 Yes
Keyword Keywords to aid in search *(conditional)
CharityType Charity Type ID – See Utility Methods section for details – This is the classification that is provided by the CRA and/or the IRS *(conditional)
CharitySize Charity Size – Available types are UNKNOWN, SMALL, MEDIUM, LARGE, and VERY LARGE – This is based on the previous year’s financials.
  • Unknown – Incomplete financial records available
  • Small – Under $500K
  • Medium – Under $500K-$3Million
  • Large $3MM-$5MM
  • Very Large - $5MM Plus
*(conditional)
Country Country of Search – Can be CA (Canada) or US (United States). Leaving blank returns results for both countries. NOTE – Mexico will be added by early 2015 No
ProvState Province or State to search. Must be valid 2-character state/province code. If this value is provided – Country will be ignored. See Utility Method section for details No

Conditional Fields

At least ONE of the fields marked as (*conditional) are required (Either Keyword, CharityType or CharitySize)

Response

<totalResults>/#</totalResults>
<totalPages>#</totalPages>
<onPage>#</onPage>
<charities>
<charity>
<…… refer to table below…..>
</charit>

Response Tags

Tag Description Data Returned
totalResults Total number of charities available as per search criteria passed #
totalPages Total number of pages of charity data available as per search criteria passed #
onPage Current Page number. Should be used by client to verify they are on the right page #
Charity Object – Head tag <charity>
regNum Registration Number of Charity – Either CRA or IRS Varchar
Name Name of Charity Varchar
Description Description of Charity Varchar
Type Type of Charity as per Charity type table – As described by either the CRA or the IRS Varchar
TypeID Type of Charity as per Charity type table in ID form #
ProvState 2-character Province/State code as per Province/State Table AA
City City charity resides in Varchar
Country Country where Charity is registered CA or US
CharitySize Size of charity UNKNOWN, SMALL, MEDIUM,LARGE,
VERY LARGE
LogoUrl Url to Logo for charity Varchar
OperatingCountry Country where Charity operates Varchar (Could be any country)
ContactInfo Contact Information of Charity
Includes name of staff (i.e. Executive Director) that we have on file. <ContactInfo> nested XML object
Contact Information – Head tag <ContactInfo>
NameOfStaff Main point of contact at the Charity (i.e Executive Director) that we have on file Varchar
Email Email of Charity Varchar
URL URL of Charity Varchar
Phone Phone number of Charity Varchar

Error Codes

On error the method will return 200 level error codes as shown in Appendix A. If no results are returned an error code of 101 should be used.

See Error Codes Click Here

Get Charity Details

This method provides details on a specific charity

Action Name: getCharityDetails

Additional Request Parameters

Parameter Description Required
regNum Registration Number of Charity – Provided by the CRA or IRS Yes

Conditional Fields

At least ONE of the fields marked as (*conditional) are required (Either Keyword, CharityType or CharitySize)

Response

The following response is returned for this method

<charityDetailss>
<… Refer to the table below … >
</charityDetails>

Response Tags

Tag Description Data Returned
CharityName Name of Charity – As registered with the government Varchar
CharityOppName Name of Charity as it goes by (i.e. Distress Centre (as opposed to the legal name)) Varchar
CharityType Type of Charity – As described by either the CRA or the IRS Varchar
CharitableStatus Status – Active or Revoked Varchar
DateOfStatus Date of last data update from CRA or IRS Date
MissionStatement Mission Statement Varchar
NumOfStaff Number Of Staff Involved Varchar
MajorDonors Major Donors Varchar
Competitors Competitors Varchar
UniqueBlurb Unique Blurb Varchar
TotalNumPeopleImpacted Total Number of People Impacted Varchar
ExistBlurb Exist Blurb Varchar
WhatIsNeeded What Is Needed Varchar
Notes Notes Varchar
CharitySubType Charity SubType Varchar
UpdateStatus Update Status #
DonorType RA Score – The ideal type of donor that aligns with this charity. The number value should translate to a letter: M (Maverick); S (Steady); I (Informed) #
OperatingBudget Operating Budget #.#
NumOfVolunteers Number Of Volunteers varchar
LogoFilename Logo Filename varchar
Description Description varchar
IndividualPrograms Individual Programs varchar
OperatingBudgetYear1 Operating Budget Year1 – Most current year on file varchar
OperatingBudgetYear2 Operating Budget Year2 – Previous year varchar
OperatingBudgetYear3 Operating Budget Year3 – Previous year to year 2 varchar
GovernancePolicies Governance Policies – Special motions/policies passed by the board and supporting documentation varchar
PeopleImpactedByOrganization People Impacted By Organization – High level clients varchar
PeopleImpactedByPrograms People Impacted By Programs – Project specific clients varchar
TrueCharityValue True Charity Value – The calculation of what the economic value that volunteers bring to the charity ADDED to the total operating costs #.#
RoleOfVolunteers Role Of Volunteers varchar
VolunteerTurnoverRate Volunteer Turnover Rate varchar
PublicPerception Public Perception – Any news articles, testimonials, donor feedback varchar
Keywords Keywords varchar
CostOfFundraising Cost Of Fundraising #.#
PressReleases Press Releases varchar
CharitySize Size of the Charity - Available types are UNKNOWN, SMALL, MEDIUM, LARGE, VERY LARGE – This is based on the previous year’s financials. Unknown – Incomplete financial records available, Small – Under $500K, Medium – Under $500K-$3Million, Large $3MM-$5MM, Very Large - $5MM Plus varchar
HasDonorBillOfRights Has Donor Bill of Rights TF
HasCodeOfEthicalFundraising Has Code of Ethical Fundraising TF
CharityIntelligenceURL Charity URL varchar
RealCharityValue Real Charity Value #.#
CharityAddress Charity Address varchar
CharityCity Charity City varchar
CharityProvState Charity Province AA
CharityPostalCode Charity Postal Code varchar
CharityCountry Charity Country varchar
CharityEmail Charity Email varchar
CharityUrl Charity Url varchar
CharityPhone1 Charity Phone1 varchar
CharityPhone2 Charity Phone2 varchar
CharityFax Charity Fax Varchar
ProgramDescription Program Description Varchar
CodeOfFundraising Has adopted a ethical Code Of Fundraising TF
KeyIssuesPercent Key Issues Percent – The number of ‘key issues’ items on the charity survey change, depending on the charity’s category. Charity selects which is important to them. Number is calculated based on total number of choices vs. selected items Decimal - varchar
KeyIssuesDescrip Key Issues Description Varchar
NeedEmerFund Need Emergency Funds TF
EmerFundDescrip Emergency Funds Description – What are the emergency funds required for Varchar
HaveProcess Have Process –Confirms a roll-out plan TF
ProcessDescrip Process Description – Description of the roll-out plan for use of funds Varchar
RelatedDoc Related Doc – Supporting documentation Varchar
HowOfferingsDiffered How Offerings Differed Varchar
OfferingsDifferedDescrip Offerings Differed Description – What makes this project/organization different from other things already happening in the community Varchar
HaveStrategicPlan Have Strategic Plan Guiding Growth TF
HaveBoardGovMan Has Updated Board Governance Manual & Terms TF
OverheadExpensesDescription Overhead Expenses Description Varchar
OverheadExpensesPercent Overhead Expenses Percent Decimal
FundraisingCost Fundraising Cost #.#
GrossFund Gross Fund #.#
InKindDonDescrip Value of in-kind donations for this fiscal year varchar
Comments Comments varchar
ExecutiveDirector Executive Director varchar

Error Codes

On invalid charity registration number the method will return a 102 error code..

See Error Codes Click Here

Get Financial Details

This method provides financial details for a specific charity.

Action Name: getFinancialDetails

Additional Request Parameters

Parameter Description Required
regNum Registration Number of Charity Yes

Response

The following response is returned for this method. Financial data is sorted by Fiscal Year Descending.

<financialDetails>
<financialData>
<…. Refer to the table below …>
</financialData>
</financialDetails>

Response Tags

Tag Description Data Returned
FiscalYear Date that defines the fiscal year Date
PrimaryRevenue Gifts with Receipts – Donations that received a tax receipt #.#
GiftsNoReceipts Gifts without Receipts – Donations that didn’t get issued a tax receipt (may include corporate sponsorship) #.#
RevGovernment Government Contributions #.#
OtherRevenue Other Revenue – Fee for Service #.#
TotalRevenue Total Revenue #.#
ExpCharitablePrograms Expenses - Charitable Programs & Services #.#
ExpFundarising Expenses – Fundraising #.#
ExpMgmtAdmin Expenses - Management & Administrative #.#
ExpTotal Total Expenses #.#
ProfitLoss Profit / Loss #.#
Cash Cash – Access to liquidity. Cash on hand that may be in an investment account or bank account #.#
LTI Long Term Investments #.#
OtherAssets Other Assets #.#
TotalAssets Total Assets #.#
AcctsPayable Accounts Payable #.#
DefRevenue Deferred Revenue #.#
OtherLiabilities Other Liabilities #.#
TotalLiabilities Total Liabilities #.#

Error Codes

On invalid charity registration number the method will return a 102 error code. On no result the method will return a 101 error code.

See Error Codes Click Here

Get Charity Files

This method provides charity files for a specific charity.

Action Name: getCharityFiles

Additional Request Parameters

Parameter Description Required
regNum Registration Number of Charity Yes

Response

The following response is returned for this method. Charity files are sorted by Name.

<charityFiles>
<file>
<… Refer to the table below …>
</file>
</charityFiles>

Response Tags

Tag Description Data Returned
ID ID number for File #
Name URL to file Varchar
Description Description of File Varchar
FileDate Date file was added to system. Can be NULL Date
Type Type of File General, Project, Financial, Supplemental or NewProject

Error Codes

On invalid charity registration number the method will return a 102 error code. On no result the method will return a 101 error code.

See Error Codes Click Here

Get Charity Projects

This method provides project information for a charity.

Action Name: getCharityProjects

Additional Request Parameters

Parameter Description Required
regNum Registration Number of Charity Yes

Response

The following response is returned for this method. Projects are ordered by Name.

<charityProjects>
<project>
<… Refer to the table below …>
</project>
</charityProjects>

Response Tags

Tag Description Data Returned
DateModified Date of last update Date
ProjectName Project Name varchar
VolHours Volunteer Hours #
StaffSal Total Staff Salary for Project #.#
MaterialCost Material Cost #.#
Overhead Overhead #.#
OtherCosts Other costs #.#

Error Codes

On invalid charity registration number the method will return a 102 error code. On no result the method will return a 101 error code.

See Error Codes Click Here

Get Charity Salaries

This method provides salary information for a charity.

Action Name: getCharitySalaries

Additional Request Parameters

Parameter Description Required
regNum Registration Number of Charity Yes

Response

The following response is returned for this method. Projects are ordered by Name.

<charitySalaries>
<salaryData>
<… Refer to the table below …>
</salaryData>
</charitySalaries>

Response Tags

Tag Description Data Returned
NumTop10_1_39999 Number of Top 10 Salaries in (Range - [1:39999]) #
NumTop10_40K_79999 Number of Top 10 Salaries in (Range - [40K:79999]) #
NumTop10_80K_119999 Number of Top 10 Salaries in (Range - [80K:119999]) #
NumTop10_120K_159999 Number of Top 10 Salaries in (Range - [120K:159999]) #
NumTop10_160K_199999 Number of Top 10 Salaries in (Range - [160K:199999]) #
NumTop10_200K_249999 Number of Top 10 Salaries in (Range - [200K:249999]) #
NumTop10_250K_299999 Number of Top 10 Salaries in (Range - [250K:299999]) #
NumTop10_300K_349999 Number of Top 10 Salaries in (Range - [300K:349999]) #
NumTop10_350K_Plus Number of Top 10 Salaries in (Range - [350K +]) #
NumPartTimeEmployees Number of PartTime Employees #
TotalCompensationPartTimeEmployees Total Compensation - PartTime Employees #.#
TotalCompensationOrganization Total Compensation - Organization #.#

Error Codes

On invalid charity registration number the method will return a 102 error code. On no result the method will return a 101 error code.

See Error Codes Click Here

Donation Method

The GIVE_api provides a mechanism so that users of client systems can make donations to any charity within Place2Give’s charity database. The GIVE_api donation process is as follows:

Important Notes

There are some important notes you need to keep in mind when using the donation gateway within the GIVE_api. They are as follows

  1. The donation event happens on Place2Give servers. This means your user will leave your application to perform the donation much like how paypal works to process payments on websites
    • If you are interested in doing integration of payment within your platform – please contact Place2Give to discuss possible custom integration options.
  2. The Donation gateway allows you the opportunity to pre-populate donation fields on our end before processing of the donation. Please refer to the optional fields shown in the request parameters table below
  3. A unique URL for each donation URL request event will be generated each time
    • The URL will expire after 24 hours
  4. If you are planning on using the Donation Gateway – you may provide a GAIN URL
    • GAIN stands for GIVE_api Instant Notification
    • The URL is used as the call back for transactions so that your system is notified of a successful donation
    • GAIN events will occur instantly after a successful donation.
    • If your system is unable to get the notification – the GAIN scheduler will continue to send the transaction details once 30 minutes, for 24 hours, until your system acknowledges receipt of the transaction. ii. If your system does not acknowledge receipt after 24 hours – a representative from place2give technical support will follow-up with you.
  5. The Clientfee parameter is a string describing an additional fee charged by the GIVE_api client, that is over and above the standard Place2Give and payment gateway fees. This string has a specific format that should be followed. The format is {P}{X}{% OR $}. The first character is either ‘A’ or empty. The last character is either % or $. The number in between is a floating point.
    • The ‘A’ character means the fee will be ‘A’dded on top of the donation amount. The standard fees charged come out of the donation amount and the additional Clientfee is tacked on to the donation total.
    • The % character means X is a percentage of the amount
    • The $ means that X is a dollar amount.
    Examples:
    “12%”; Clientfee is 12% of donation amount; Clientfee is taken from donation amount
    “12.5$”. Clientfee is $12.50 of donation amount; Clientfee is taken from donation amount
    “a12%”. Clientfee is 12% of donation amount; Clientfee is added to the donation amount.

Donate Now Method

This method generates a unique URL to allow users the ability to make a one-time donation.

Action Name: getDonationURL

Additional Request Parameters

Parameter Description Required
regNum Registration Number of Charity or Project Yes
ProjectType Indicates if they want to donate to a charity or a project. Valid values are C or P Yes
BackURL URL provided by client in case the user decides to cancel the transaction Yes
RedirectURL URL provided by client for redirect after payment and donation is completed Yes
ClientUnique Unique identifier provided by client that is returned to client after successful payment. Used to aid client within internal references No
FirstName Donor’s first name *(conditional)
LastName Donor’s last name *(conditional)
Address Donor’s Address *(conditional)
City Donor’s City *(conditional)
ProvState Donor’s 2-character Province/State code as per Province/State Table *(conditional)
PostalZip Donor’s Zip or Postal Code *(conditional)
Country Donor’s Country. Acceptable values are CA (Canada) or US (United States) *(conditional)
Email Donor’s Email address *(conditional)
Amount Donation Amount(Users can select pre-determined amounts, 10,15,20,25,50,75,100 or any other amount) Yes
Clientfee Additional client fee; parameter string. See note 5 above for parameter string format No
Currency Currency of Donation – Acceptable values are USD or CAD Yes
IsAnonymous Whether or not the donation should be recorded as Anonymous – valid values are ‘true’ or ‘false’ No
Note Additional note to be included with donation. I.e. in tribute of message No
InMemorialOf If the donation is in memorial of someone No
InHonourOf If the donation is in honour of someone No

Conditional Fields

Fields marked as (*conditional) are required if parameter is IsAnonymous is not specified.
If parameter IsAnonymous is passed in as ‘true’, (*conditional) fields are optional

Request Notes

The intent behind the optional fields is to pre-populate the donation forms for the user. This is meant to make the donation process a little simpler and quicker. The user still has to confirm the information and provide payment details.


Response

The following response is returned for this method.

<donationURL>https://www.place2give.com/API-Donations/GIVE_api-Donate.aspx?UnID=[UUID]</donationURL>
<expires>[Expiry Date]</expires>

** Note: The Development GIVE_api will return a URL containing ‘server2.place2give.com’ to enable donation testing. See Donation Testing section below


Response Tags

Tag Description Data Returned
donationURL The URL the user must go to perform the URL Varchar
Expires The date and time the URL will expire Date

Error Codes

On invalid charity registration number the method will return a 102 error code. On invalid project code – the method will return a 103 error code. For all other error codes, refer to Appendix A.


Donation Testing (Development GIVE_api)

The Development GIVE_api (devapp.place2give.com) payment gateways will always remain in ‘test mode’. This requires you to use specific credit card numbers provided by the Stripe gateway. The full Stripe testing documentation can be found at: https://stripe.com/docs/testing

In test mode, you can use these test cards to simulate a successful transaction:

Number Card type
4242424242424242 Visa
4012888888881881 Visa
5555555555554444 MasterCard
5105105105105100 MasterCard
378282246310005 American Express
371449635398431 American Express
6011111111111117 Discover
6011000990139424 Discover
30569309025904 Diners Club
38520000023237 Diners Club
3530111333300000 JCB
3566002020360505 JCB

GAIN Response

The GAIN (GIVE_api Instant Notification) response is meant to provide your system with instant notification of any donations done by its users on Place2Give. The GAIN response returns data to a GAIN URL (that is already in the system and associated with your app token and account). The intent of this service is to provide your system with data they can log and/or report on for internal purposes.

Response Method

It is expected that Donation your system will have the ability to receive a HTTP or HTTPS post to their server from the GIVE_api.

Posted Parameters

The following parameters and data will be posted to your GAIN URL in JSON format.

Parameter Description Data Type
regNum Registration Number of Charity or Project Varchar
Type Indicates if the donation was to a charity or a project. Valid values are C or P A
ClientUnique Unique identifier provided by client during URL creation. Varchar
FirstName Donor’s first name Varchar
LastName Donor’s last name Varchar
TransNum Transaction Number for the donation Varchar
RefNum Reference Number for the payment Varchar
TransDate Date of Transaction Date
Amount Donation Amount(Users can select pre-determined amounts, 10,15,20,25,50,75,100 or any other amount) #.#
Currency Currency of Donation – Acceptable values are USD or CAD AAA
PaymentMethod Method of payment used. Acceptable values are VISA, MC, AMEX or Paypal Varchar
ReceiptURL URL to obtain copy of Receipt. Null if unavailable (i.e. US charity donations) Varchar

Acknowledgement

Your system is expected to acknowledge the GAIN response by returning a simple text string of: THANKYOU

If your system does not respond as expected – or if the response times out then the GIVE_api will continue to send the GAIN response once every 30 minutes for 24 hours until acknowledgement occurs. If acknowledgment doesn’t occur after 24 hours – PlaceToGive staff will contact you.

Add Recurring Donation (Note: Only available for Stripe payments)

This method creates a recurring donation plan for a customer given the defined donor / payment info, and the donation interval (day/month/year). Interval count (number of intervals to pass before another donation can be made) and a delayed start date option add extra flexibility.

Action Name: addRecurring

Notes:

  • Upon successful addRecurring, an Email from support@place2give.ca is sent to welcome the new user.
  • Upon successful charge from Stripe, an email is sent to the donor with a PDF receipt attached.
  • The Interval may only contain: day, month or year
  • The intervalCount is an integer that specifies the frequency. IE) Interval = day, intervalCount = 3 ; once every three days a donation will occur
  • Startchargingafterdays is for setting the offset in days for the donation to start. This is useful when you need to specify an alternate start date for the donations to begin.
  • AmountinCents is the dollar amount converted to cents (Integer).
  • Currency can be USD or CAD only

Additional Request Parameters

Parameter Description Required
regNum Registration Number of Charity or Project Yes
Email Donor’s Email address Yes
Interval Interval at which charges will re-occur. Valid values: year, month or day Yes
FirstName Donor’s first name Yes
LastName Donor’s last name Yes
Address Donor’s full address as appears at credit card agent Yes
Address2 Donor secondary address line as appears at credit card agent No
City Donor City No
ProvState Donor’s 2-character Province/State code as per Province/State Table No
PostalZip Donor’s Zip or Postal Code No
PhoneNumber Donor’s 10 digit phone number No
Country Donor’s country as appears at credit agent Yes
residenceCountry Donor’s country of residence No
AmountinCents Donation Amount - ** must be in cents (pences also allowed via Stripe) Yes
intervalCount Number of ‘intervals’ to occur between payments - Integer No
Startchargingafterdays Number of days to delay the first payment by - Integer No
programID Program ID (integer) of specific program in charity to donate to No
Cardname Name that appears on the donor’s credit card Yes
Cardnumber Credit card number Yes
CardCVC Credit card security code Yes
CardExpMonth Expiry month of card Yes
CardExpYear Expiry year of card Yes
Currency CAD or USD Yes
Annotation A Text field for storing a note about the recurring donation. IE) ‘In Honour of’ and/or ‘In Memorial Of’ information No

Unsubscribe Recurring Donation (Note: Only available for Stripe payments)

This method sets a current recurring donation plan for a customer to ‘Inactive’ status, and removes the subscription from the payment gateway service.

Action Name: unsubscribeRecurring

Notes:

  • Upon successful unsubscribeRrecurring, an email is sent to donor as confirmation.

Additional Request Parameters

Parameter Description Required
regNum Registration Number of Charity or Project Yes
Email Donor’s Email address Yes
FirstName Donor’s first name Yes
LastName Donor’s last name Yes
programID Program ID (integer) of specific program in charity to donate to No

See Error Codes Click Here

Utility Methods

The methods shown here are available to all licenses as utility methods for setting type fields.

Get Charity Types

This method provides a list of available charity types.

Action Name: getCharityTypes

Additional Request Parameters

None

Response

The following response is returned for this method. Projects are ordered by Name.

<charityType id=”#”>[Description]</charityType>

** Currently, there are only a few Charity Types in use. Please use the following list to provide Charity Types to other methods

CharityType
Benefits to Community
Education
Health
Other
Religion
Welfare

See Error Codes Click Here

Get Provinces and States

This method will provide a list of provinces and states that can be used for charity search.

Action Name: getProvState

Additional Request Parameters

Parameter Description Required
Country CA (Canada) or US (USA) are the two valid values. When the country is provided – the appropriate list is returned. If no country is provided – all provinces/states are returned. No

Response

<provState id=”AA”>[Description]</provState>

** Please use the standardized two-character code for provinces and states. A comprehensive list can be found here.


See Error Codes Click Here

GIVE_api Connection Set-up

When ready – you can connect to the free GIVE_api via our public web-service through a HTTPS connection. The URLs for the web-service are:

Authentication Method

https://app.place2give.com/Service.svc/give-api-auth?params…

Request Method

https://app.place2give.com/Service.svc/give-api?params…

** Note: If you have only been given access to the Development GIVE_api, replace ‘app.place2give.com‘ in all URL requests with ‘devapp.place2give.com’

To request an authentication token Click Here

Requests against the GIVE_api are done via URL parameters. All URL parameters should be encoded before sending to the GIVE_api in a percent-encoded format (URL Encoding). Certain parameters are required for every method call – while additional parameters are required as per the method being called at the time.

Response Method

The GIVE_api response is by default in XML. For JSON output include a format=JSON parameter in every method call

Default Response Envelope

On all responses – the GIVE_api will provide a response with the following envelope. Unless otherwise documented, all responses are encoded in UTF-8 format.

<?xml version="1.0" encoding="utf-8"?>
<give-api>
<status-code>###</status-code>
<status-code-description>{String}</status-code-description>
<data p2:type="{method}" xmlns:p2="http://www.w3.org/2001/XMLSchema-instance">
<{data return}>Data returned from method</{data return}>
</data> </give-api>

Response Notes

  • Whenever # is used in a response – it is assumed a integer is returned
  • Whenever #.# is used in a response – it is assumed a double/decimal is returned
  • Whenever AA is used in a response – it is assumed a Alphanumeric character is returned of the defined size is returned. I.e. AA = 2 alphanumeric characters
  • Whenever VARCHAR is used in a response – it is assumed a alphanumeric character of variable size is returned
  • Whenever TF is used in a response – it is assumed a Boolean value is returned (I.e. True or False)
  • Whenever DATE is used in a response – it is assumed a Date value is returned.

Authentication Method

Before you can start using the GIVE_api web-service – you first must authenticate your application to get an access token. When your account is created within the GIVE_api licensing system – an APPID and APPSECRET will be generated and provided to you.

If you do not have your APPID or APPSECRET Click Here

To authenticate the following must be done:

Request: https://app.place2give.com/Service.svc/give-api-auth?app_id={APPID}&app_secret={APPSECRET}&format={FORMAT}

Parameter Description Required
app_id APPID provided by Place2Give support Yes
app_secret APPSECRET provided by Place2Give support Yes
format ‘Json’ or ‘xml’. If no format is provided, default is XML No

On successful connection – the GIVE_api will record your server’s IP address and will return an APP Token. The token will be a generated UUID and is required for all future transactions. The token does not expire; however, if your IP Address changes, your token will become invalid.

Example Response:

<?xml version="1.0" encoding="utf-8"?> <give-api> <status-code>100 <status-code-description>Success</status-code-description>
<data p2:type="Token" xmlns:p2="http://www.w3.org/2001/XMLSchema-instance">
<token>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</token>
</data>
</give-api>

On error – the GIVE_api will respond as per 900 error codes noted in the response code appendix as well as their description

Additional Notes

Only 1 token can be generated per IP. On any future requests – the IP will be validated alongside the token. If you are planning on connecting from more than one IP – then an additional license will need to be created per server.

Token Expiry

At the moment tokens are not meant to expire – however in the future that may come into play. As such it will be important to keep that in mind when connecting to the GIVE_api


Common Parameters for every method request

Once you are authenticated – 2 parameters are required with every request. They are the ‘action’ and ‘token’. Beyond this, a ‘format’ parameter can be specified too, in which you may choose your response format in json or xml. If no ‘format’ parameter is provided, the default is xml.

Beyond this, additional parameters specific to each action method will be required depending on the action.

Example Request Calls:

Request: XML (default):

https://app.place2give.com/Service.svc/give-api?action=ACTION&token=TOKEN[&{Parameter}={VALUE}]

Request: JSON:

https://app.place2give.com/Service.svc/give-api?action=ACTION&token=TOKEN&format=json[&{Parameter}={VALUE}]
Parameter Description Required
action This is the GIVE_api method being called Yes
token This is the token that was provided by the GIVE_apiI during authentication Yes
format ‘json’ or ‘xml’. If no format is provided, default is XML No
<additional parameters> Additional parameters with values as specified by the method (ACTION) definition (Required parameters for each action)

Error Codes

If there are any problems with the action or token provided – a 900 level error code as found in the Appendix will be returned.

Error Codes

Response Code Description
100 This is the standard all is good response code. This means everything is working as it should
101 No results returned
102 Invalid Charity Registration Number
103 Invalid Project Registration Number
200 Invalid page number provided for search criteria passed
201 Number of results requested exceeds maximum number allowed
202 Invalid Charity Type passed. Please refer to the getCharityType Method for details
203 Invalid Charity Size passed. Only UNKNOWN, SMALL, MEDIUM, LARGE and VERY LARGE allowed
204 Invalid Country passed – only Canada or USA allowed
205 Invalid Province/State passed. Please refer to the getProvState Method for details
206 Invalid Email Format
300 Project or Charity can no longer accept donations
301 Invalid Type passed. Acceptable values are C or P
302 Type does not match registration number passed. Please confirm data
303 BackURL is missing
304 RedirectURL is missing
305 Invalid Currency provided. Only USD or CAD allowed
306 Amount is not a number
307 Missing donor first name
308 Missing donor last name
309 Missing donor address
310 Missing donor city
311 Missing donor province or state
312 Missing donor postal or zip
313 Missing donor country
314 Missing donor email
315 Invalid Fee format
319 Missing credit card expiry month
320 Missing credit card expiry year
321 Missing Name as it appears on Credit Card
322 Missing Interval
323 Invalid Interval
324 Invalid Interval Count
325 Missing Amount value
326 Invalid value for Startchargingafterdays
327 Payment gateway Error ; Invalid payment information
328 Missing Credit Card Number
329 Missing Credit Card CVC security identifier
331 Missing Credit Card type
332 Missing Currency
333 Missing Charity regnum
409 Payment method is invalid – acceptable values are VISA, MC, AMEX and Paypal
410 Receipt cannot be generated for this charity
411 Transaction Date is not a valid date
900 APP ID and/or APP secret is invalid
901 Token is invalid
902 Invalid Action
903 Token does not match IP address on file
904 Action provided is not available for the token provided. Please contact your site administrator.
905 Expired License. Please contact your site administrator
906 One or more parameters passed is invalid for this action
907 Internal Error within Place2Give system