Common models

The following is an example of a contribution.

{
    "contributionId": 23453,
    "contact": {
        "vanId": 10005165
    },
    "designation": {
        "designationId": 18754,
    },
    "dateReceived": "2013-12-25T12:23:00Z",
    "amount": "12.34",
    "coverCostsAmount": "2.34",
    "status": "Settled",
    "paymentType": "Check",
    "bankAccount": "PNC Bank Account 1",
    "contributionBankAccount": {
        "bankAccountId": 9876,
        "name": "PNC Bank Account 1"
    },
    "depositDate": "2013-12-28",
    "depositNumber": 3,
    "checkDate": "2013-12-25",
    "checkNumber": "1222 123",
    "contactAttributions": [
        {
          "vanId": 303,
          "amountAttributed": "100.50",
          "attributionType": "DefaultAttribution",
          "notes": "some notes go here",
          "dateThanked": "2013-12-30"
        },
        {
          "vanId": 701,
          "amountAttributed": "202.10",
          "attributionType": "CorporateMatch",
          "notes": "some notes go here",
          "dateThanked": "2013-12-30"
        },
    ],
    "onlineReferenceNumber": "1230230423",
    "pledge": {
        "pledgeId": 1035
    },
    "codes": [
        { "codeId": 12345, "codeName": "Signup Form Source Code" }
    ],
    "generalLedgerFund": {
      "generalLedgerFundId": 89,
      "name": "GL3",
      "description": "gl3",
      "isActive": true
    },
    "costCenter": {
      "costCenterId": 71,
      "name": "CC3",
      "description": "cc3",
      "isActive": true
    },
    "directMarketingCode": "Excelsior Consulting",
    "dateThanked": "2013-12-30",
    "notes": "Processed as part of the Christmas Fundraiser",
    "disclosureFieldValues": [
        {
          "disclosureFieldId": 190,
          "disclosureFieldValue": "41",
          "designationId": 1121
        },
        {
          "disclosureFieldId": 40,
          "disclosureFieldValue": "5",
          "designationId": 1121
        },
        {
          "disclosureFieldId": 1001,
          "disclosureFieldValue": "John",
          "designationId": 1121
        }
    ],
    "extendedSourceCode" : {
      "extendedSourceCodeId": 12
    },
    "identifiers": [
        {
          "type": "ActBlue ID",
          "externalId": "123456"
        }
    ],
    "financialBatchId": 825,
    "processedAmount": 3,
    "processedCurrency": "USD",
    "acceptedOneTimeAmount": "12.34",
    "acceptedRecurringAmount": "5.67",
    "selectedOneTimeAmount": "20.00",
    "upsellType": "Split",
    "isUpsellShown": true,
    "isUpsellAccepted": true
}

The following is an overview of the Contribution object and its related objects. In some cases, the related object has a dedicated endpoint. In these cases, a link to those endpoints is provided.

Contribution

The required properties are contact, designation, dateReceived, amount, status, and paymentType.

PropertyTypeDescription
contributionIdintRead-only; Unique identifier for a Contribution in this context
contactobjectThe Person who contributed
designationobjectThe financial entity which will receive this contribution.
dateReceiveddatetimeThe date and time of this contribution; must occur before the time of the API call.
amountdecimalThe amount of the contribution. Non-positive values, and values that have more than 2 digits after the decimal point, will not be accepted.
coverCostsAmountdecimalRead-only; The amount by which the donor increased their total contribution amount in order to cover costs associated with the online transaction (payment processing fees, shipping fees, administrative costs, etc.).
statusstringThe current status of the contribution: Declined, Pending, or Settled.
paymentTypestringA string representing the method of payment. See below for valid values of Payment Type.
financialBatchIdintOptional; the associated Financial Batch. If specified, the Designation of the Financial Batch must match the Designation of this contribution. Financial Batch Manager must be enabled in this context to assign a financialBatchId.
bankAccountstringOptional; the associated Bank Account. If no Bank Account with this name is found, a new Bank Account is created. Additional permissions required to create a new Bank Account. Property contributionBankAccount takes precedence if both are used.
contributionBankAccountobjectOptional; the associated Bank Account object. Takes precedence over bankAccount if both are used.
depositDatedateThe date of the deposit.
depositNumberstringThe number of the deposit.
checkDatedateThe date of the check.
checkNumberstringThe number of the check.
contactAttributionsarrayAn array of Attribution objects associated with the contribution.
onlineReferenceNumberstringAn alphanumeric code used to identify additional information about a contribution, usually indicating a transaction ID from the contribution processor.
pledgeobjectThe associated Pledge object.
codesarrayAn array of zero or one Code to apply to the contribution. Contributions may not have more than one Code applied, and if a Code is applied, it must be a Source Code.
generalLedgerFundobjectThe associated GeneralLedgerFund object.
costCenterobjectThe associated CostCenter object.
directMarketingCodestringA direct marketing code.
dateThankeddateThe date the contributor was thanked.
notesstringA note describing the contribution.
disclosureFieldValuesarrayAn array of Disclsure Field Value objects associated with the contribution.
extendedSourceCodeobjectOptional; the Extended Source Code to apply to the contribution. This is only supported in POST and only the extendedSoureCodeId property is required. If this is provided, we’ll look for and apply a matching Source Code to the contribution from a Direct Response Plan segment that the contact is in with a contact history record that has the extended source code. If no matching source code is found, then the POST will fail.
identifiersarrayAn array of Identifier objects
linkedJointFundraisingContributionIdintThe ID of the total Joint Fundraising Transfer record, if any. When adding an itemized Joint Fundraising Allocation, use linkedJointFundraisingContributionId to link the allocations to the parent transaction. The Designation for the current Contribution and the Designation for the parent Contribution, indicated by linkedJointFundraisingContributionId, must be identical. Also, the Disclosure Field named “Contribution Type” must have an Option ID corresponding to “Joint Fundraising Allocation”.
linkedPartnershipContributionIdintThe ID of the total Partnership Contribution record, if any. When adding an itemized partner Contribution, use linkedPartnershipContributionId to link the itemizations to the parent transaction. The Designation for the current Contribution and the Designation for the parent Contribution, indicated by linkedPartnershipContributionId, must be identical. Also, the Disclosure Field named “Partnership” must have a value of true for this Contribution.
processedAmountdecimalRead-only; The amount of the contribution in the currency used by the contributor.
processedCurrencystringRead-only; The ISO currency code of the currency used by the contributor.
acceptedOneTimeAmountdecimalRead-only; The one-time contribution amount accepted by the donor in a split upsell scenario.
acceptedRecurringAmountdecimalRead-only; The recurring contributiom amount accepted by the donor in an upsell scenario.
selectedOneTimeAmountdecimalRead-only; The one-time contribution amount selected by the donor before being offered an upsell.
upsellTypestringRead-only; The type of upsell associated with a given contribution. Split or Switch if there is an associated upsell. null indicates there is no associated upsell.
isUpsellShownboolRead-only; Indicates whether a donor was offered an upsell when they contributed.
isUpsellAcceptedboolRead-only; Indicates whether a donor accepted an upsell offer when they contributed.

Designation

PropertyTypeDescription
designationIdintThe id of the designation which receives this contribution.

Contribution Bank Account

PropertyTypeDescription
bankAccountIdintRead-only; Unique identifier for a Bank Account in this context. Optional, if specified, the bank account must already exist.
namestringThe name of this Bank Account, no longer than 100 characters, optional if bankAccountId is specified. If a bankAccountId is not specified, an attempt is made to look up a Bank Account by this name. If a bankAccountId is not specified and no Bank Account with this name is found, a new Bank Account is created. Additional permissions required to create a new Bank Account.

Attributions

PropertyTypeDescription
vanIdstringUnique identifier for the attributed contact. Represents contacts who acted as fundraisers, rather than contributors.
amountAttributedstringOptional; The amount of the attribution. Values that have more than 2 digits after the decimal point will not be accepted. If no amount is provided, default to contribution amount.
attributionTypestringOptional; A string representing the attribution type. See below for valid values of Attribution Type. If no type is provided, default to “DefaultAttribution” type.
notesstringOptional; A note describing the attribution. Max length of 100 characters.
dateThankeddateOptional; The date on which the attributed contact was thanked for the contribution.

Attribution Type

One of

  • BoardMemberGiving
  • CorporateMatch
  • DefaultAttribution
  • DonorAdvisedFund
  • DonorMatch
  • FamilyPrivateFoundation
  • FinanceCommittee
  • GiftMembership
  • RaisedContribution
  • TributeGift
  • TallyMember
  • WorkplaceGiving

Pledge

PropertyTypeDescription
pledgeIdintThe pledge id of the associated pledge.

Disclosure Field Values

Disclosure Fields exist on a range of objects (e.g. People, Contributions) and are used for Disclosure Reports for FEC and state filing purposes.

PropertyTypeDescription
disclosureFieldIdintIdentifies the Disclosure Field. Together, the designation id and disclosure field id provide a unique identifier of a Disclosure Field.
disclosureFieldValuestringThe value of the Disclosure Field
designationIdintThe unique identifier of the Designation of the Disclosure Field

Identifier

Used for known external identifiers (e.g., ActBlue ID). External IDs are case-insensitive. Abcd1234 will always match ABCD1234.

PropertyTypeDescription
typestringRequired; a known external identifier that is available in the current context.
externalIdstringRequired; case-insensitive

Payment Type

One of

  • Check
  • MoneyOrder
  • Cash
  • CreditCard
  • InKind
  • Unknown
  • ElectronicFundsTransfer
  • ElectronicPaySystem
  • PayPal
  • Stock
  • ApplePay