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 specification

Result

A batch Id that references an existing batch is specified

Referenced batch is used

A batch Id that does not reference an existing batch is specified

Error message is returned

Only a batch name that references an existing batch is specified

Referenced batch is used

Only a batch name that does not reference an existing batch is specified

A 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 specification

Result

A batch Id that references an existing batch is specified

Referenced batch is used

A batch Id that does not reference an existing batch is specified

Error message is returned

Only a batch name that references an existing batch is specified

Referenced batch is used

Only a batch name that does not reference an existing batch is specified

Error message is returned

No batch is specified

Error message is returned

Required Properties:

Key

Value

contactId

String; The contact ID of the contributor.

amount

String; The amount of the contribution. Value that has more than 2 digits after decimal point will not be accepted.

designation

designationId | Integer; The designation to assign to the contribution.

Optional Properties:

Key

Value

batch

batchId | 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.

disclosureFields

disclosureFieldId | 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.

method

The method used for this contribution: CHECK, CREDITCARD, WIRETRANSFER, CASH, DEBITCARD, ELECTRONICPAYSYSTEM, MONEYORDER, OTHER, CASHIERSCHEK. Defaults to CREDITCARD.

checkDate

String; A date string between 1901-01-01 and 2075-12-31.

checkNumber

String; the check number associated with this contribution, if any.

depositDate

String; A date string between 1901-01-01 and 2075-12-31.

depositNumber

String; the deposit number associated with this contribution, if any.

bankAccount

bankAccountId | 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.

date

String; A date string between 1901-01-01 and 2075-12-31.

onlineRef

String; A Direct Marketing Code to associate with this contribution.

marketSource

String; A Market Source to associate with this contribution.

sourceCode

sourceCodeId | Integer; A source code id to attribute to the contribution.

attributedContactIds

An array of contact IDs to attribute to the contribution.

pledge

pledgeId | String; A pledge ID to associate with this contribution.

note

A 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).