TntConnect TM
Helping you build powerful connections for a lifetime of ministry...

How can I custom implement the web-based TntConnect DataSync protocol? from Bob!

Table of Contents

It is our pleasure to provide this software free of charge to help you in your ministry.  We're so thankful for our partners who make this possible!

About TntWare

Page Details

First published by:
Troy Wolbrink
on 29 Sep 2008
Last revision by:
Troy Wolbrink
on 16 Sep 2017
5 people found this article useful.

100% of people found this useful
How can I custom implement the web-based TntConnect DataSync protocol?

This document describes how you can make your organization's online donation system compatible with TntConnect.  The technical details are spelled out so that you can provide your own custom solution.  It requires a knowledge of computer programming.

If you're building an app to download donation information, then you're at the wrong place.
Instead, you should visit the Donor Hub API Developers Group
It has documentation on how to write an app that downloads donation information.

Make your life easier!  Instead of building it all yourself, take advantage of DonorHub Online DonorHub Online is very reasonably priced, and probably less total cost of ownership than your own custom solution.  TntWare makes this process seamless, both for the staff on the field and the accounting team back in the office.:
Ask us about DonorHub Online.  

Once you are TntConnect-compatible, your staff will be able to use TntConnect to connect to your system to:

  • Download contribution details
  • Download names and addresses of donors
  • Be notified of their staff account balance

What it takes...

  • Query INI file
  • Profiles Query
  • Account Balance Query
  • Donations Query
  • Addresses Query
  • Addresses By IDs Query

Query INI File

You need to provide a Query INI File.  This file will provide the web address and parameter template needed to download the results of the query.  Below is an example.  Notice it is based on a standard Windows INI file format.


Name=Your Organization Name
OrgHelpUrlDescription=Click here to report this issue!
OrgHelpOther=You may also reach the Call Center at 111-222-3333.







  Now let me explain the meaning of each value...

 /// Minimum and recommended versions of TntConnect

 /// Very first thing TntConnect checks, allows for permanent redirection of TntConnect to new query.ini url

 /// Specify the name of your organization here.
Name=Your Organization Name

 /// Specify a short abbreviation of your organization here.

 /// URL of where your logo can be downloaded (JPEG only).


 /// URL to help your staff get setup with an account.

 /// URL of your banner ad.

 /// Boundary of how back your online donation system provides data for. (DATE)

 /// Unique code to represent your ministry internally to TntConnect. (25 chars max!  User never sees this.)


 /// Set this to "1" if you want the queries to use basic HTTP authentication


 /// TntConnect internally removes leading zeros from numeric donor account ids. Specify the minimum number
 /// of digits a donor id should be, and TntConnect will add leading zeros when returning them back in the
 /// "Addresses By IDs Query" query.


 /// Where users can report errors with your download process.
OrgHelpUrlDescription=Click here to report this issue!
OrgHelpOther=You may also reach the Call Center at 111-222-3333.

 /// Specify the url where users can request new user profiles.

 /// Specify the url where users can view a staff portal.

 /// <new for TntConnect 2.1.68> indicates if TntConnect can attempt logging in while user types password.

 /// <new for TntConnect 3.1> Specify the assumed base currency code (ISO 4217 3-char) for gifts

 /// The rest of these sections describe Web Queries.  A Web Query has a Url and a Post
 /// The Url is where TntConnect requests data.
 /// The Post is a template of query encoded parameters that get POST-ed to the URL.
 /// More information is provided below to describe the details.


The benefit of keeping the instructions in this file is that if you later change the URL or POST template of your query, you can just edit the Query INI File and make a seamless transition.  The staff using the program will never know it changed.

The Queries

Each query has a URL and a POST.  The URL specifies your online donation server object (CGI object, for example).  The POST specifies the data to send with the HTTP POST transaction.  The POST is in a template form.  These placeholders are key words that will be substituted by the appropriate string based on the user's input in TntConnect:

$ACCOUNT$ The user name of the staff logging in to the system.
$PASSWORD$ The password of the staff logging in to the system.
$PROFILE$ The profile code of the staff logging in to the system.
This comes from the Profiles query.
$DATEFROM$ The specified beginning date.  (M/D/YYYY) (I'll explain later where and how this is used.)
$DATETO$ The specified ending date.  (M/D/YYYY) (I'll explain later where and how this is used.)
$PERSONIDS$ A comma separated list of donor IDs.  (I'll explain later where and how this is used.)

So for example, if I defined my Post value by:


And if my user name was "JohnDoe", and my password was "abc123" then the following data would be send with the HTTP POST transaction:


--Standard Response--
Each query should return its results as CSV text.  I will describe the
field names expected for each query.

--Error Response--
Each query should handle invalid conditions (such as an invalid username) by
returning two lines of text.  The first line of text should be "ERROR". 
The second line of text is the error description.  Here are a couple of
examples to give you the general idea.

Invalid password.


Invalid user name.


Server is down for maintenance.


Invalid date range.

Note for anyone consuming this api, some existing legacy servers may return errors using a different format, such as BAD_PASSWORD instead of ERROR, with a multi-line error description.

Profiles Query

The purpose of this query is to return a list of profiles associated with the user.  A user might have different "modes" for downloading information, without having to setup different username/passwords for each mode.  This works especially well in a Single Sign On (SSO) environment.

Example result:

Staff Account (Default)
MIN1 Operating Account #1
MIN2 Operating Account #2

Field Descriptions:

FieldName Description
PROFILE_CODE (A18) A code to identify this profile.  A blank profile code would be the default profile associated with the account.  Note: The Field Name "ROLE_CODE" was supported at one time, but is now deprecated for new work.
PROFILE_DESCRIPTION (A50) A description of the profile.  This is what the user sees.  Note: The Field Name "ROLE_DESCRIPTION" was supported at one time, but is now deprecated for new work.

Account Balance Query

The purpose of this query is to simply return the staff account balance of the staff member submitting the request.  It only uses the $ACCOUNT$, $PASSWORD$ and $PROFILE$ placeholders.

Example result:

12345678 Doe, John & Jane 1225.30

Result in it's raw form just in case you are not familiar with the CSV format:

12345678,"Doe, John & Jane",1225.30

Field Descriptions:

FieldName Description
EMPLID Comma separated list of designation ids (A18) associated with this user/profile.
ACCT_NAME List of designation account names (A50) associated with this user.  Each name is delimited by carriage returns and line feeds (vbCrLf or #13#10), and correlates to designation ids found in EMPLID.
BALANCE (Text) Custom text that describes the user's account balance.


Donations Query

The purpose of this query is to return all donation detail data for the staff member within a certain date range.  In addition to the usual $ACCOUNT$, $PASSWORD$ and $PROFILE$ placeholders, it also uses $DATEFROM$ and $DATETO$.  Keep in mind that these placeholders come in the (M/D/YYYY) format.  The $DATEFROM$ and $DATETO$ placeholders describe the beginning and ending dates of the query.  You should include donation data for all dates between and including these dates.  The beginning date will be limited by the "MinimumWebGiftDate" value in the Query INI file.

Here's an example result:

"921875429","Smith, Dave J & Julie J","08/23/2002","60","J5INQ","0455770","Z01000"
"332812300","Pine Hills Christian Church","08/22/2002","50","J5E2S","0455770","Z01000"
"220389751","Fryerson, Sue","08/22/2002","40","J5EGE","0455770","Z01000"

Field Descriptions:

FieldName Type TntConnect Version Description
PEOPLE_ID A18   Donor Code/ID
ACCT_NAME A50   Donor full name
DISPLAY_DATE DATE   Date of contribution
AMOUNT FLOAT   Amount of contribution
DONATION_ID A18   Donation Code/ID
DESIGNATION A18   What account this donation is designated for (normally same as employee id)
MOTIVATION A18   (Optional)  If you track this in your donation system you may include this code here.
PAYMENT_METHOD A18 3.0 (Optional)  Payment method of this donation.
MEMO MEMO 3.0 (Optional)  Any comments associated with this gift.
TENDERED_AMOUNT FLOAT 3.1 (Optional)  Amount of donation as tendered by donor. 
You may leave this blank if it is tendered in the same as currency code defined in the query.ini file.
TENDERED_CURRENCY A3 3.1 (Optional)  Currency code (ISO 4217 3-char) of donation as tendered by donor.  You may leave this blank if it is the same as the default currency code from the query.ini file.


Addresses Query

The purpose of this query is to return detailed name, address and phone data for the staff member's donors.  In addition to the usual $ACCOUNT$, $PASSWORD$ and $PROFILE$ placeholders, it also uses $DATEFROM$.  Keep in mind that this parameter comes in the (M/D/YYYY) format.  The $DATEFROM$ placeholder limits the address list to only those that have changed since the given date.  If the given date is blank, the user is requesting ALL addresses. 

Note: You may simply ignore the $DATEFROM$ parameter and return all addresses every time if you wish.  But keep in mind that this will generally increase the download time for the user.

All fields are optional (column header must exist, but data can be blank) except PEOPLE_ID and ACCT_NAME.

Here's an example result:

"921875429","Smith, Dave J & Julie J","630 Pine St",,,,"Hickleman","SD","18372-2637",... 
"332812300","Pine Hills Christian Church","1212 Elm Cir",,,,"Orlando","FL","32828-1868",... 
"220389751","Fryerson, Sue","900 S Sarmon Dr",,,,"Mitchell","SD","57302-9244", ... 

Field Descriptions:

FieldName Type TntConnect Version Description
PEOPLE_ID A18   Donor Code/ID
ACCT_NAME A50   Donor full name
INFO_URL MEMO 3.0 URL to view/edit donor information.
RELATED_IDS MEMO 3.0 A comma seperated list of related donor codes/ids.
DECEASED BOOL 3.0 Blank implies "FALSE".  Is the donor deceased?
PERSON_TYPE A1   "O" or "P" (Organization or Person)
LAST_NAME_ORG A50   Last Name or Organization Name
Contact person for this organization.
TITLE A25   [PERSON_TYPE="P"]  Title (Mr., Mrs.)
SUFFIX A25   [PERSON_TYPE="P"]  Suffix (Jr., Sr.)
SP_TITLE A25   [PERSON_TYPE="P"]  for spouse
SP_FIRST_NAME A25   [PERSON_TYPE="P"]  for spouse
SP_MIDDLE_NAME A25   [PERSON_TYPE="P"]  for spouse
SP_LAST_NAME A25   [PERSON_TYPE="P"]  for spouse
SP_SUFFIX A25   [PERSON_TYPE="P"]  for spouse
    Note: If provided, it is concatenated with a space to SP_LAST_NAME.
ADDR1 MEMO   Street Address (Line 1)
ADDR2 MEMO   Street Address (Line 2)
ADDR3 MEMO   Street Address (Line 3)
ADDR4 MEMO   Street Address (Line 4)
CITY A50   City
STATE A50   State
ZIP A25   Postal Code
COUNTRY A3   (A3) ISO 3166 Alpha 3 country code 
<new in TntConnect 2.0>
ISO 3166 Alpha 2 country codes are supported in TntConnect 2.0.
CNTRY_DESCR A50   Name of country.
ADDR_CHANGED DATE   When the address was last changed.
PHONE A50   Phone number.
PHONE_CHANGED DATE   When the phone was last changed.
MOBILE_PHONE A50 3.0 Mobile phone number.
MOBILE_PHONE_CHANGED DATE 3.0 When the mobile phone was last changed.
SP_MOBILE_PHONE A50 3.0 Spouse mobile phone number.
SP_MOBILE_PHONE_CHANGED DATE 3.0 When the spouse mobile phone was last changed.
EMAIL MEMO 3.0 Email address.
EMAIL_CHANGED DATE 3.0 When the email address was last changed.
SP_EMAIL MEMO 3.0 Spouse email address.
SP_EMAIL_CHANGED DATE 3.0 When the spouse email address was last changed.
MEMO MEMO 3.0 A note regarding the donor.


Addresses By IDs Query

This Query only differs from the Addresses Query in that it uses the $PERSONIDS$ parameter instead of the $DATEFROM$ parameter.  The $PERSONID$ parameter is substituted by a comma separated list of donor IDs.  These donor IDs are obtained from donations in the Donations Query.  TntConnect will never submit a request with more than 200 donor IDs.

Note: You may simply ignore the $PERSONIDS$ parameter and return all addresses every time if you wish.  But keep in mind that this will generally increase the download time for the user.

Data Types Explained
  • A25, a text column with a maximum of 25 characters

  • MEMO, a text column with no predefined length limits

  • DATE, a date formatted as M/D/YYYY (or  <new in TntConnect 3.1> the YYYY-MM-DD format).

  • BOOL, a boolean as "TRUE" or "FALSE"

  • FLOAT, a floating point number.  Currency symbols or thousands separators are not allowed.  The decimal separator must be a period.

(Note: for all types, leading and trailing spaces are removed from the value.  So "  ABC  " is always trimmed down to just "ABC".)

Case Insensitivity

TntConnect will store designation ids, donor ids and donation ids exactly as it is received.  (Leading zeros will be removed from numeric donor ids.)  But internally when TntConnect is syncing incoming data, it will match up these ids in a case insensitive way.  So a donation id of "ABC" and "abc" are the same from TntConnect's perspective.  Sending your staff two donations with an id of "ABC" and "abc" respectively will either result in a "duplicate id error" in TntConnect or it will overwrite the one donation with the other.

Testing your compatibility with TntConnect

To test your online donation system's compatibility with TntConnect, pull up the "Gift Input from Web" screen.  Where it has you choose your Organization, hold the "Shift" key down while you drop down the list and then choose "Custom".  Then you can simply type in the URL of your Query INI File.  That is all there is to it!

Making it easy for your staff to connect...

If you want to include your organization in the drop down list where you choose the Organization, just send me an email. (  Be sure to include your organization's name, and the URL of your Query INI File.  I can update the list on my website, and your organization will automatically appear in the list.

Then when your staff member tries to do "Gift Input from Web" for the first time, they can just select your organization's name in the list.  It couldn't be much easier!

Recent Comments

By: fly4theking Posted on 23 Jan 2017 9:40 PM

Is this a secure way to transfer username/password over the Internet? What is the best way to implement this securely?

By: Troy Wolbrink Posted on 20 Apr 2017 11:17 PM

You must use TLS/SSL, with an SSL certificate on your web server.

© 2019 TntWare, Inc. | Privacy | Terms of Use