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