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.

Property

Type

Description

contributionId

int

Read-only; Unique identifier for a Contribution in this context

contact

object

The Person who contributed

designation

object

The financial entity which will receive this contribution.

dateReceived

datetime

The date and time of this contribution; must occur before the time of the API call.

amount

decimal

The amount of the contribution. Non-positive values, and values that have more than 2 digits after the decimal point, will not be accepted.

coverCostsAmount

decimal

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

status

string

The current status of the contribution: Declined, Pending, or Settled.

paymentType

string

A string representing the method of payment. See below for valid values of Payment Type.

financialBatchId

int

Optional; 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.

bankAccount

string

Optional; 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.

contributionBankAccount

object

Optional; the associated Bank Account object. Takes precedence over bankAccount if both are used.

depositDate

date

The date of the deposit.

depositNumber

string

The number of the deposit.

checkDate

date

The date of the check.

checkNumber

string

The number of the check.

contactAttributions

array

An array of Attribution objects associated with the contribution.

onlineReferenceNumber

string

An alphanumeric code used to identify additional information about a contribution, usually indicating a transaction ID from the contribution processor.

pledge

object

The associated Pledge object.

codes

array

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

generalLedgerFund

object

The associated GeneralLedgerFund object.

costCenter

object

The associated CostCenter object.

directMarketingCode

string

A direct marketing code.

dateThanked

date

The date the contributor was thanked.

notes

string

A note describing the contribution.

disclosureFieldValues

array

An array of Disclsure Field Value objects associated with the contribution.

extendedSourceCode

object

Optional; 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.

identifiers

array

An array of Identifier objects

linkedJointFundraisingContributionId

int

The 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”.

linkedPartnershipContributionId

int

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

processedAmount

decimal

Read-only; The amount of the contribution in the currency used by the contributor.

processedCurrency

string

Read-only; The ISO currency code of the currency used by the contributor.

acceptedOneTimeAmount

decimal

Read-only; The one-time contribution amount accepted by the donor in a split upsell scenario.

acceptedRecurringAmount

decimal

Read-only; The recurring contributiom amount accepted by the donor in an upsell scenario.

selectedOneTimeAmount

decimal

Read-only; The one-time contribution amount selected by the donor before being offered an upsell.

upsellType

string

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

isUpsellShown

bool

Read-only; Indicates whether a donor was offered an upsell when they contributed.

isUpsellAccepted

bool

Read-only; Indicates whether a donor accepted an upsell offer when they contributed.

Designation

Property

Type

Description

designationId

int

The id of the designation which receives this contribution.

Contribution Bank Account

Property

Type

Description

bankAccountId

int

Read-only; Unique identifier for a Bank Account in this context. Optional, if specified, the bank account must already exist.

name

string

The 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

Property

Type

Description

vanId

string

Unique identifier for the attributed contact. Represents contacts who acted as fundraisers, rather than contributors.

amountAttributed

string

Optional; 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.

attributionType

string

Optional; A string representing the attribution type. See below for valid values of Attribution Type. If no type is provided, default to “DefaultAttribution” type.

notes

string

Optional; A note describing the attribution. Max length of 100 characters.

dateThanked

date

Optional; 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

Property

Type

Description

pledgeId

int

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

Property

Type

Description

disclosureFieldId

int

Identifies the Disclosure Field. Together, the designation id and disclosure field id provide a unique identifier of a Disclosure Field.

disclosureFieldValue

string

The value of the Disclosure Field

designationId

int

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

Property

Type

Description

type

string

Required; a known external identifier that is available in the current context.

externalId

string

Required; case-insensitive

Payment Type

One of

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