Common Models

Some Contributions endpoints share a common data model for requests; these are described below.

Contribution

Example POST data (note that this is submitted with content-type application/json):

{
    "contactId": "VN97A11GJ53",
    "amount": 23.32,
    "designation": { "designationId": "2"},
    "method": "CHECK",
    "checkDate": "1925-04-07",
    "checkNumber": "123456",
    "depositDate": "1925-04-11",
    "depositNumber": "987654321",
    "bankAccount": { "bankAccountId": 432 },        
    "batch": {
        "batchId": "21",
        "batchName": "MyBatchName"
    },
    "disclosureFields": [
        {
            "disclosureFieldId": 1,
            "designationId": -1,
            "value": "23"
        },
        {
            "disclosureFieldId": 20,
            "designationId": 2,
            "value": "MyVAL"
        }
    ],
    "attributedContactIds": ["MERGE1ND1"],
    "date": "1925-04-10",
    "onlineRef": "CRZ",
    "marketSource": "DSP",
    "sourceCode": { sourceCodeId: 42 },
    "pledge": { "pledgeId": "V46898" },
    "note": "note goes here"
}

Batches require significant special handling, which differs depending on whether Financial Batch Manager is enabled. Note that it will not be enabled for most people, and when not enabled, batch is optional (and you probably won’t want to submit anything for it).

The following rules are applied to the specified batch for a tenant that has Financial Batch Manager turned off:

Batch specificationResult
A batch Id that references an existing batch is specifiedReferenced batch is used
A batch Id that does not reference an existing batch is specifiedError message is returned
Only a batch name that references an existing batch is specifiedReferenced batch is used
Only a batch name that does not reference an existing batch is specifiedA new batch with the specified name is created

The following rules are applied to the specified batch for a tenant that has Financial Batch Manager turned on:

Batch specificationResult
A batch Id that references an existing batch is specifiedReferenced batch is used
A batch Id that does not reference an existing batch is specifiedError message is returned
Only a batch name that references an existing batch is specifiedReferenced batch is used
Only a batch name that does not reference an existing batch is specifiedError message is returned
No batch is specifiedError message is returned

Required Properties:

KeyValue
contactIdString; The contact ID of the contributor.
amountString; The amount of the contribution. Value that has more than 2 digits after decimal point will not be accepted.
designationdesignationId | Integer; The designation to assign to the contribution.

Optional Properties:

KeyValue
batchbatchId | Integer; The batch ID to assign to this contribution.
batchName | String; The batch name to assign to this contribution.

Note: batch is not optional if the Financial Batch Manager feature is enabled, but that is a minority of NGP clients.
disclosureFieldsdisclosureFieldId | Integer; The ID of the disclosure field.
value | String; The value of the disclosure field.
designationId | Integer; the id of the designation to apply the disclosure field for. DesignationId is either the designation associated with the transaction or -1 (for disclosure fields that are not report-specific). Consult the designation-specific contribution disclosure fields service to determine the appropriate value.
methodThe method used for this contribution: CHECK, CREDITCARD, WIRETRANSFER, CASH, DEBITCARD, ELECTRONICPAYSYSTEM, MONEYORDER, OTHER, CASHIERSCHEK. Defaults to CREDITCARD.
checkDateString; A date string between 1901-01-01 and 2075-12-31.
checkNumberString; the check number associated with this contribution, if any.
depositDateString; A date string between 1901-01-01 and 2075-12-31.
depositNumberString; the deposit number associated with this contribution, if any.
bankAccountbankAccountId | Integer; The ID of the bank account to associate this contribution with. The bank account must be active and belong to the same designation as the contribution.
dateString; A date string between 1901-01-01 and 2075-12-31.
onlineRefString; A Direct Marketing Code to associate with this contribution.
marketSourceString; A Market Source to associate with this contribution.
sourceCodesourceCodeId | Integer; A source code id to attribute to the contribution.
attributedContactIdsAn array of contact IDs to attribute to the contribution.
pledgepledgeId | String; A pledge ID to associate with this contribution.
noteA note detailing the contribution.

Contribution Response

Successful contribution creation returns the ID of the newly created contribution. Example:

{
  "contributionId": "VN8429H8VZ2"
}

The status code of the response indicates whether a new contact was created (201) or if an existing one was updated (200).