Push Post API
=============

These calls allow you to add records to a TouchPoint database using the API.

Authentication to the API requires a user with both the ``Developer``, ``APIOnly`` and ``APIWrite`` roles
  (``APIOnly`` and ``APIWrite`` might not exist and will need to be created).

.. important::

    The examples below show using curl, a command line tool for transferring data using various URL protocols.
    This tool comes on a Mac and can be downloaded for Windows.

.. note::

    The examples below explicitly set the authorization header, but you can also set it like so::

        curl --user "atester:MyApiPasswordToRuleThemAll" \
            "https://sandbox.tpsdb.com/api/People?\$top=5"

.. py:function:: AddContribution

    :return: information including the PeopleId and the ContributionId
    :rtype: json object
    :param string First: first name (required)
    :param string Last: last name (required)
    :param string Email: email address (required)
    :param string Phone: phone number (required)
    :param decimal Amount: amount of the gift (required)
    :param string Address: street address (optional)
    :param string Zip:  zip code (optional)
    :param datetime Date: date and time of the contribution (optional)
    :param string Notes: notes about this contribution (optional)
    :param string Source: service name like txt2give
    :param int FundId: id of the fund (optional)
    :param int PeopleId: attach this contribution to specific record by Id (optional)
    :param bool IgnoreUnknownPerson: When true, if no people match is found, do not record this contribution (optional)
    :param int BundleTypeId: id of the bundle header type (optional)
    :param int ContributionTypeId: e.g. 1=Regular, 9=NonTaxDed (optional)

    This call allows you to add a contribution to the database.

    Curl Example::

        curl -X POST -H "Authorization: Basic YXRlc3RlcjpNeUFwaVBhc3N3b3JkVG9SdWxlVGhlbUFsbA==" \
            -H "Content-Type: application/json" -d '{
            "First": "John",
            "Last": "Appleseed",
            "Email": "david@tpsdb.com",
            "Phone": "901-489-0611",
            "Amount": "10"
        }' "https://sandbox.tpsdb.com/Api/AddContribution"

    returns::

        {
            "PeopleId":152,
            "ContributionId":1,
            "NewPerson":true,
            "MultipleMatches":false,
            "Source":null
        }


    In the return object, NewPerson indicates whether a new person record was created or not.
    MultipleMatches is true if it matched multiple existing records, (it chose the first one).


.. py:function:: ReverseContribution

    :return: information including the PeopleId and the ContributionId
    :rtype: json object
    :param int id: id of the contribution to be reversed
    :param string source: identifies the party / company making the reversal

    This call allows you to reverse a contribution in the database.

    The arguments are passed in the URL as /Api/ReverseContribution/**1234**/**company** 
    where `1234` is the contributionid of the contribution to be reversed 
    and `company` is an indicator of the party doing the reversal.
    The body of the POST is empty.

    Curl Example::

        curl -X POST -H "Authorization: Basic YXRlc3RlcjpNeUFwaVBhc3N3b3JkVG9SdWxlVGhlbUFsbA==" \
            "https://sandbox.tpsdb.com/Api/ReverseContribution/1234/text2give"

    returns::

       {
            "operation": "Reversal",
            "peopleId": 4444,
            "contributionId": 1234,
            "source": "API Reverse (source=txt2give)"
       }


   The operation will notify Finance personnel at the church.