EveryAction 7 API

NGP

Overview

NGP is the application which powers EveryAction 7.

Welcome to the documentation for the public NGP API. The API is a JSON/REST API that follows most REST conventions. All URLs use a resource patch and an HTTP method to indicate the desired action on that resource. For example, a GET on /resource lists all resources in the current tenant. A GET on /resource/{id} gets the details of that particular object. A POST on /resource creates a new object. A POST on /resource/{id} updates the details of a specific object.

Authentication

Before using the API, you will need to know your API key, which will be provided by NGP VAN. The API key takes the form of a GUID formatted in the style 7c9e6679-7425-40de-944b-e07fc1f90ae7 (case-insensitive).

Your API key is tied to your specific tenant, and all API calls will only return data from within that tenant and will only modify data in that tenant.

You must attach your API key using BasicAuth when making all API calls. The username should be set to apiuser and the password should be the value of your API key. Here is a very simple example of how to implement that in NodeJS:

var request = require('request');
var username = 'apiuser';
var password = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
var options = {
  url: 'https://api.myngp.com/v2/resourcePath',
  auth: {
    user: username,
    password: password
  },
  ...
};
request(options, function (err, res, body) {
  if (err) {
    console.dir(err);
    return;
  }
  console.dir('headers', res.headers);
  console.dir('status code', res.statusCode);
  console.dir(body);
});

Alternatively, it can passed in your HTTP request headers, but with the identifier of apiKey instead of apiuser from our basic auth example above. For example:

POST /v2/contacts/findOrCreate HTTP/1.1
apiKey: 7c9e6679-7425-40de-944b-e07fc1f90ae7
Content-Type: application/json;

Errors

All API calls use a standardized format for returning errors. The simplest way to explain it is by example:

{
    "errors": [
        {
            "properties": [
                "firstName"
            ],
            "text": "First name may not contain numbers",
            "code": "INVALID_PARAMETER"
        }
    ]
}

The errors key will always contain an array of objects, even if there is only one error. Each error object always contains a code, which is a terse machine-readable code for what went wrong (think of it as an enum), a text value, which is a long-form description suitable for display to end users, and optionally a properties array which contains the keys that were invalid in the request. If there are multiple values in the properties array, then the error is caused by the combination of the two, e.g. a city name that doesn’t match a submitted postal code. In the above example, the API consumer attempted to POST an invalid value of firstName to the /contacts API.

If an API call does not return an errors array, then the call was successful, and the specific return data varies per call.

Contacts

Overview

A contact record is the basic element of data in NGP. Transactions such as contributions, disbursements or pledges are all attached to contact records. Use this endpoint to create or modify contacts.

Common Models

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

Required data: type is a required field. In addition, one of the following identification criteria must be satisfied:

  • firstName and lastName (required for INDIVIDUAL type)
  • commonName (required for ORGANIZATION type)
  • at least one emails
  • at least one phones

contactId should not be specified in the request body. If you do, the response will be a 301 redirect to the correct /contacts/{contactId} resource for making that call.

All other fields are optional. Note that deduping logic is always in effect, so if you make a POST with a set of data that closely matches a contact already in the system (e.g. same name and email address), then the data you are POSTing will be merged into the existing data.

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

{
    "type": "INDIVIDUAL",
    "firstName": "Lefty",
    "lastName": "McDonkey",
    "emails": [
        {
            "address": "leftyd@fake.ngpvan.com",
            "type": "MAIN",
            "doNotEmail": false,
            "appliedEmailLists": [{
                 "emailListId": 12,
            },
            {
                 "emailListId": 14
            }]
        }
    ],
    "addresses" : [
        {
            "line1": "1203 12th St",
            "line2": "Suite 525",
            "city": "Washington",
            "stateProvince": "DC",
            "postalCode": "20005",
            "type": "WORK"
        }
    ],
    "phones" : [
        {
            "number": "2025557979",
            "type": "MOBILE"
        },
        {
            "number": "3014884002",
            "type": "HOME"
        }
    ],
    "externalLinks" : [
        {
            "externalSourceTypeId": "13",
            "externalId": "12345"
        },
        {
            "externalSourceTypeId": "15",
            "externalId": "6789"
        }            
    ],
    "contactCodes": [
      {
          "contactCodeId": 37653
      }, 
      {
          "contactCodeId": 1022
      }, 
      {
          "contactCodeId": 27
      }
    ],
    "employer": "NGP VAN",
    "occupation": "Mascot",
    "facebookProfileUrl": "http://facebook.com/shia_labeouf",
    "disclosureFields": [
        {
            "disclosureFieldId": 1,
            "designationId": 8,
            "value": 702
        },
        {
            "disclosureFieldId": 2114,
            "designationId": 8,
            "value": 2013
        }
    ]
}
Key Value
type Either INDIVIDUAL or ORGANIZATION. Required.
prefix String (INDIVIDUAL type only, and must match one of your available prefixes Mr., Mrs., Miss, Ms. )
firstName String (INDIVIDUAL type only)
middleName String (INDIVIDUAL type only)
lastName String (INDIVIDUAL type only)
nickName String (INDIVIDUAL type only)
suffix String (INDIVIDUAL type only)
salutation String (INDIVIDUAL type only)
mailName String (INDIVIDUAL type only)
spouseName String (INDIVIDUAL type only)
commonName String (ORGANIZATION type only)
officialName String (ORGANIZATION type only)
primaryContactFirstName String (ORGANIZATION type only)
primaryContactLastName String (ORGANIZATION type only)
emails A collection of:
Key Value
address String; the email address
type One of: HOME, OTHER, OTHER_2, PERSONAL, WORK, ALTERNATIVE, BILLING, MAIN, ASSISTANT
doNotEmail Boolean
isPrimary Boolean
appliedEmailLists Integer. Must be a valid email list Id that already exists in the system. See the emailLists API call for retrieval of valid values.

It’s not possible to have two emails with the same type.

addresses A collection of:
Key Value
line1 String; address line 1
line2 String; address line 2; optional
city String
stateProvince String
postalCode String
isDisclosure Boolean; The address that is reported on a disclosure report. Only one address on a contact may be marked IsDisclosure=true.
isPrimary Boolean
type One of: ABROAD, HOME, MILITARY, SCHOOL, TEMPORARY, VACATION, WORK, ALTERNATIVE, BILLING, MAIN, ASSISTANT, OTHER, OTHER_2, VOTING

It’s not possible to have two addresses with the same type.

phones A collection of:
Key Value
number String; the phone number, digits only (no spaces, dashes, etc.)
isDisclosure Boolean; The phone that is reported on a disclosure report. Only one phone on a contact may be marked IsDisclosure=true.
isPrimary Boolean
type One of: HOME, HOME_FAX, OTHER_2, VACATION, WORK, WORK_FAX, BILLING, MAIN, MAIN_FAX, OTHER_FAX, ASSISTANT, MOBILE, OTHER, TTY_TDD

It’s not possible to have two phones with the same type.

communicationPreferences A single object containing the below properties(not all required). ndicates the best way to communicate with this contact. Setting values on this object does not override the properties of any phones, emails, or addresses.
Key Value
doNotContact Boolean; if doNotContact=true, will also override doNotCall, doNotTelemarket, doNotEmail, doNotMail to true
doNotCall Boolean; if doNotCall=true, will set prefersPhone to false
doNotTelemarket Boolean
doNotEmail Boolean; if doNotEmail=true, will set prefersEmail to false
doNotMail Boolean; if doNotMail=true, will set prefersMail to false
doNotExchangeInfo Boolean; if doNotExchangeInfo=true, this indicates the contact has requested not to have their information shared with others.
prefersEmail Boolean
prefersFax Boolean
prefersPhone Boolean
prefersMail Boolean
prefersSms Boolean
contactCodes A collection of:
Key Value
contactCodeId Integer. Must be a valid contact code Id that already exists in the system. See the contactCodes API call for retrieval of valid values.
employer String
occupation String
facebookProfileUrl String; the fully qualified URL for the contact’s Facebook profile.
disclosureFields A collection of:
Key Value
disclosureFieldId Integer; the id of a disclosure field (see the designations/{id}/contactDisclosureFields call for a list of valid values for this and also the designationId).
designationId Integer; the id of the designation to apply the disclosure field for (some disclosure fields may apply to multiple designations).
value The value of the disclosure field.
externalLinks A collection of:
Key Value
Key Value
externalSourceTypeId Integer. Must be a valid external source type Id that already exists in the system. See the externalSource API call for retrieval of valid values.
externalId String. The Id from the third-party database.

Successful contact creation or merging returns the ‘contactId’ of the newly created contact. Example:

{
    "contactId": "VN93A9H7CW7"
}

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

POST/contacts/findOrCreate

Create or updates a contact
Description

Creates a new contact with the given details, or updates details on an existing contact if one already exists that matches deduping criteria with the submitted data.

Request

Contact

POST/contacts/{contactId}

Updates specified contact
Description

Updates the specified contact with the properties provided in the request body. The request body and expected response are of the same form as the ‘POST /contacts/findOrCreate` endpoint.

Request

Contact

Contributions

Overview

Contribution records are attached to a contact record in order to record a contribution by that person or organization.

Common Models

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

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
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.
designation
Key Value
designationId Integer; The designation to assign to the contribution.

Optional Properties:



Key Value
batch
Key Value
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
Key Value
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.
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.
bankAccount
Key Value
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.
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.
sourceCode
Key Value
sourceCodeId Integer; A source code id to attribute to the contribution.
attributedContactIdsAn array of contact IDs to attribute to the contribution.
pledge
Key Value
pledgeId String; A pledge ID to associate with this contribution.
noteA note detailing the contribution.

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

POST/contributions

Creates a contribution
Description

This endpoint request creates a contribution with the properties provided in the request body.

Request

Contribution

POST/contributions/{contributionId}

Updates a specified contribution
Description

This endpoint updates the specified contribution with the properties provided in the request body. The request body and expected response are of the same form as the ‘POST /contributions’ endpoint.

Request

Contribution

Disbursements

Overview

A disbursement is an expense paid by an organization. It is necessary to properly record disbursements in order to file accurate compliance reports. In particular, disbursements must accurately report the Contact who incurred the expense as well as the Designation which paid it. Depending on the nature of the designation, certain disclosure fields may also be required. Disbursements may be linked to one another in certain circumstances:

  • If numerous items were paid via a single credit card transaction, then the credit card transaction would be a single disbursement, and each individual item purchased would be another disbursement linked to the credit card transaction.
  • If an individual purchases items on behalf of the organization with personal funds, and the organization later reimburses that individual, then the original purchase must be reported as a single disbursement, and the reimbursement for that purchase must be reported as another disbursement linked to the original purchase.

Common Models

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

{
    "contactId": "VN94T9H7815",
    "amount": 23.32,
    "designation": { "designationId": 501 },
    "batchName": "MyBatchName",
    "bankAccount": { "bankAccountId": 26 },
    "checkNumber": "12345",
    "date": "1925-04-10",
    "disclosureFields": [
    {
        "disclosureFieldId": 30007,
        "designationId": 501,
        "value": "30028"
    },
    {
        "disclosureFieldId": 30008,
        "designationId": -1,
         "value": "2016"
    }
    ],
    "note": "note goes here",
    "sourceCode": { sourceCodeId: 42 },
    "disbursementCreditCardLinkId": null,
    "disbursementReimbursementLinkId": "VN8429H8VZ2"
}

Properties:

Key Value
contactIdRequired String; The contact ID of the disbursement.
amountRequired String; The amount of the disbursement. Value that has more than 2 digits after decimal point will not be accepted.
designation
Key Value
designationId Required Integer; The designation to assign to the disbursement.
bankAccount
Key Value
bankAccountId Integer; The numeric ID of the bank account to associate this disbursement with. The bank account must be active and belong to the same designation as the disbursement. May be retrieved in the UI.
batchNameString; a free-form description of the batch of disbursements. Not related to contribution batches.
checkNumberString; the check number associated with this disbursement, if any.
dateString; A date string between 1901-01-01 and 2075-12-31.
disbursementCreditCardLinkId

String; A disbursement to link with this disbursement, if any. When disclosing a payment made to a credit card, use disbursementCreditCardLinkId to link disbursements itemizing each purchase made to the parent disbursement with which the bill was paid.

Must be in the same designation as the disbursement in question, and must also associate the correct ExpenseSubtype disclosure field of Credit Card/Paycheck Item with this disbursement.

disbursementReimbursementLinkId

String; A disbursement to link with this disbursement, if any. When reimbursing an individual or organization for purchases made on your behalf, use disbursementReimbursementLinkId to link disbursements itemizing each purchase to the parent disbursement in which they are reimbursed.

Must be in the same designation as the disbursement in question, and must also associate the correct ExpenseSubtype disclosure field of Reimbursement Item with this disbursement.

disclosureFields
Key Value
disclosureFieldId Integer; The ID of the disclosure field, from among the designation-specific disbursement disclosure fields for this disbursement. .
value String; The value of the disclosure field.
designationId Integer; the id of the designation to apply the disclosure field for. Must be the designation associated with the disbursement, or -1 for disclosure fields that are not report-specific.
noteA note detailing the disbursement.
sourceCode
Key Value
sourceCodeId Integer; A source code id to attribute to the disbursement.

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

{
  "disbursementId": "VN8429H8VZ2"
}

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

POST/disbursements

Creates a disbursement
Description

This endpoint request creates a disbursement with the properties provided in the request body.

Request

Disbursement

POST/disbursements/{disbursementId}

Updates a specified disbursement
Description

This endpoint updates the specified disbursement with the properties provided in the request body. The request body and expected response are of the same form as the ‘POST /disbursements’ endpoint.

Request

Disbursement

Designations

Overview

A designation is the representation of different compliance reports inside one NGP tenant. Calls to the designation endpoint retrieve a list of designations and the specific settings for that designation.

Common Models

Some Designations endpoints share a common data model; these are described below.

The response is a collection of:

Key Value
dataType String, Boolean, Number, Date, SingleSelect, MultiSelect, Unsupported
designationId The designation Id.
disclosureFieldId Field id (key)
name String identifier
displayLabel Label used when rendering this field
isRequired Required for reporting, not necessarily for form submission
dataType String identifying the expected data type to be provided for this field
defaultValue Optional, supplied for fields with options if non-null
numericRangeMin Optional, supplied if non-null. Only present for some numeric fields.
numericRangeMax Optional, supplied if non-null. Only present for some numeric fields.
textLengthMin Optional, supplied if non-null. Only present for some text fields.
textLengthMax Optional, supplied if non-null. Only present for some text fields.
options Optional, supplied for all single/multi select fields a collection of:
KeyValue
optionId The option’s value
displayLabel Human-readable value
optionGroups Optional, supplied for single/multi select fields with option groups a collection of:
Key Value
displayLabel Label/heading rendered for the group
options The options for this group, as explained above

Example GET data (note that this is submitted with content-type application/json) with successful get returns a list of disclosure fields. Example:

[
  {
    "disclosureFieldId": 40,
    "name": "Contribution.Memo",
    "displayLabel": "",
    "isRequired": true,
    "designationId": 1,
    "dataType": "SingleSelect",
    "defaultValue": "5",
    "options": [
      {
        "optionId": 5,
        "displayLabel": "Non-Memoed"
      },
      {
        "optionId": 4,
        "displayLabel": "Memoed"
      }
    ]
  },
  {
    "disclosureFieldId": 50,
    "name": "Contribution.Note",
    "displayLabel": "Note",
    "isRequired": false,
    "designationId": 1,
    "dataType": "String",
    "textLengthMin": 1,
    "textLengthMax": 36
  }
]

GET/designations

Retrieves a list of designations
Description

This endpoint retrieves a list of designations and their codes.

Request
/designations
Response

The response is a collection of:

Key Value
designationId The designation Id.
name String identifier

Example GET data (note that this is submitted with content-type application/json) with successful get returns a list of disclosure fields. Example:

[
  {
    "designationId": 1,
    "name": "Fred for Congress"
  },
  {
    "designationId": 2,
    "name": "Freds PAC"
  }
]

GET/designations/{designationId}/contactDisclosureFields

Retrieves a list of disclosure fields required for a contact
Description

This endpoint retrieves a list of the disclosure fields required for a contact for the provided designation id.

Request
/designations/{designationId}/contactDisclosureFields

GET/designations/{designationId}/contributionDisclosureFields

Retrieves a list of disclosure fields required for a contribution
Description

This endpoint retrieves a list of the disclosure fields required for a contribution for the provided designation id.

Request
/designations/{designationId}/contributionDisclosureFields

GET/designations/{designationId}/disbursementDisclosureFields

Retrieves a list of disclosure fields required for a disbursement
Description

This endpoint retrieves a list of the disclosure fields required for a disbursement for the provided designation id.

Request
/designations/{designationId}/disbursementDisclosureFields

Batches

Overview

Batches are used to signify batches of deposits into a bank account. If the Financial Batch Manager feature is enabled for the tenant, this parameter will be required for creating a new contribution.

Common Models

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

Parameters:

Note that all dates are in ISO-8601 format, i.e. they should be specified as “YYYY-MM-DD”.

Optional querystring filter parameters:

Key Value
excludeClosedBatches Boolean for excluding batches that have been closed.
openedAfter Displays only batches opened after the specified date.
openedBefore Displays only batches opened before the specified date.
closedAfter Displays only batches closed after the specified date.
closedBefore Displays only batches closed before the specified date.

A collection of:

Key Value
batchId The batch ID to assign to this contribution.
batchName The batch name to assign to this contribution.
designationId The designation Id.
dateOpened The date the batch was opened.
currentCount Total number of contributions in the batch.
currentAmount Total amount
currentMemoedCount Count of memoed contributions.
currentMemoedAmount Total amount of memoed contributions.
currentNonmemoedCount Count of non-memoed contributions.
currentNonmemoedAmount Total amount of non-memoed contributions.
isOpen Is the batch open.

Example GET data (note that this is submitted with content-type application/json) with a successful get returns a list of contact codes. Example:

[
  {
    "batchId": 1594,
    "batchName": "test",
    "designationId": 1,
    "dateOpened": "2014-03-11T04:00:00Z",
    "currentCount": 1,
    "currentAmount": 23.32,
    "currentMemoedCount": 0,
    "currentMemoedAmount": 0,
    "currentNonmemoedCount": 1,
    "currentNonmemoedAmount": 23.32,
    "isOpen": true
  },
  {
    "batchId": 1595,
    "batchName": "test2",
    "designationId": 1,
    "dateOpened": "2014-03-11T04:00:00Z",
    "currentCount": 4,
    "currentAmount": 93.28,
    "currentMemoedCount": 0,
    "currentMemoedAmount": 0,
    "currentNonmemoedCount": 4,
    "currentNonmemoedAmount": 93.28,
    "isOpen": true
  }
]

GET/batches

Retrieves a list of batches
Description

This endpoint retrieves a list of financial batches with optional querystrings.

Request

Batches

Contact Codes

Overview

Contact codes are hierarchical, up to 4 levels of hierarchy. They are used to categorize contact records for later searches and segments.

GET/contactCodes

Retrieves a list of contact codes
Description

This endpoint retrieves a list of contact codes. The list is limited to the 1,000 most recently created contact codes.

Request
/contactCodes
Response

The response is a collection of:

Key Value
contactCodeId Contact code id
description Comment
name String identifier

Example GET data (note that this is submitted with content-type application/json) with a successful get returns a list of contact codes. Example:

[
  {
    "contactCodeId": 2,
    "name": "union",
    "description": "Union members"
  },
  {
    "contactCodeId": 3,
    "name": "volunteers",
    "description": "Volunteers"
  }
]

POST/contactCodes

Creates a new contact code
Description

This endpoint creates a new contact code based on data in the request body.

Request
Required POST Data
Key Value
name The contact code name.
Optional Data:
Key Value
description The contact code description.
parentId The parent contact code ID.

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

{
  "name": "Test",
  "description": "this is a test",
  "parentId": 1
}
Response

Successful contact code creation returns the ID of the newly created contact code. Example:

{
  "contactCodeId": 23
}

Source Codes

Overview

Source codes are used to categorize contributions and disbursements. They, like contact codes are hierarchical, allowing up to 4 levels of hierarchy.

GET/sourceCodes

Gets a list of source codes
Description

This endpoint gets a list of source codes.

Request
/sourceCodes
Response

A collection of:

Key Value
sourceCodeId Source code id
description Comment
name String identifier

A successful example GET returns a list of source codes (note that this is submitted with content-type application/json):

[
  {
    "sourceCodeId": 1,
    "name": "Basketball",
    "description": "Basketball"
  },
  {
    "sourceCodeId": 4,
    "name": "Picnic99",
    "description": "Picnic99"
  }
]

POST/sourceCodes

Creates a new source code
Description

This endpoint creates a new source code based on data in the request body.

Request

Parameters:

Required POST Data
Key Value
name The source code name. Must be no more than 20 characters, and contain only letters, numbers, underscores, hyphens, and spaces. Source code names must be unique.
Optional Data:
Key Value
description The source code description.
parentId The parent source code ID.

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

{
  "name": "Test",
  "description": "this is a test",
  "parentId": "1"
}
Response

Successful source code creation returns the ID of the newly created source code. Example:

{
 "sourceCodeId": "23"
}

Pledges

Overview

Pledges are used to track commitments by a contact record to donate or raise a certain amount of money.

POST/pledges

Creates a pledge
Description

This endpoint creates a pledge based on data in the request body.

Request
Required POST Data
Key Value
contactIdThe contact ID of the pledger.
pledgeTypeCan be one of two values: GIVE or RAISE.
pledgeDateThe Pledged On date. Must be in the form YYYY-MM-DD, per the ISO 8601 standard.
designation
Key Value
designationId The designation to assign to the contribution.
Optional Data:
Key Value
amountIf not specified, it is considered an “unknown amount.” If specified, it cannot be less than $0.01 US.
commitmentThe commitment level. If not specified in the request, it is automatically set to “Not Specified.” If specified, must be one of two values: STRONG or WEAK.
expectedFulfillmentDateExpected pledge fulfillment date. Must be in the form YYYY-MM-DD, per the ISO 8601 standard. If specified, it must be greater than or equal to pledgeDate.
sourceCode
Key Value
sourceCodeId A source code id to attribute to the pledge.
attributedContactIdsAn array of contact IDs to attribute to the pledge.
taskIDA Social Organizing task ID to link to the pledge.

An example request:

{
  "contactId": "VN289395603",
  "pledgeType": "GIVE",
  "pledgeDate": "2013-10-06",
  "designation": { "designationId": 202 },
  "amount": 123.01,
  "commitment": "STRONG",
  "expectedFulfillmentDate": "2013-10-07",
  "sourceCode": { "sourceCodeId": 1 },
  "attributedContactIds": ["TESTC0NTACT2"],
  "taskId": 123
}
Response

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

{
  "pledgeId": "VN65J9H5SW3"
}

Forms

Overview

Forms are used to collect signups based on forms published in the system.

GET/forms

Gets a list of forms from the tenant
Description

Retrieve the list of all Online Page Forms for the organization associated with this API key.

Request

An example request:

/forms
Response

The response is a JSON array containing form name, form ID, form URL, form type, form status, layout, and if it forces recurring contributions. Example:

{
    "name": "asdf fasdfasdf",
    "obfuscatedId": "-2319072333119094784",
    "url": "/Forms/-2319072333119094784",
    "type": "ContributionForm",
    "version": "00-00-00-03-ED-9B-98-72",
    "status": "Published",
    "layoutStyle": "MultiStep",
    "isRecurring": false
}, {
    "name": "sample sign up",
    "obfuscatedId": "3173630362412646400",
    "url": "/Forms/3173630362412646400",
    "type": "SignupForm",
    "version": "00-00-00-03-ED-9B-5B-EC",
    "status": "Published",
    "layoutStyle": "SinglePage",
    "isRecurring": false
}

GET/forms/{formId}

Retrieve the JSON definition of an Online Form.
Description

This definition contains all of the information necessary to render this form, validate it, and submit its contents back to NGP.

Request

This request does not require an API key. An example request:

/forms/3173630362412646400
Response

The form definition will come back as a JSON array of the fields that make up the form, as well as metadata about it and the post-submission information. Example:

{
"autoFastAction": false,
"confirmation": {
    "action": "DisplayContent",
    "email_from_address": "",
    "email_from_name": "",
    "email_html_content": "<p>Dear {{FirstName,DefaultTo=Friend}},</p><br /><p>Thank you for joining our campaign.</p><span style=\"font-weight:bold\">Contact Information:<br/>{{FullName,DefaultTo=}}<br/>{{AddressLine1,DefaultTo=}}<br/>{{AddressLine2,DefaultTo=}}<br/>{{City,DefaultTo=}}&nbsp; {{StateProvince,DefaultTo=}}&nbsp;{{PostalCode,DefaultTo=}}</span>",
    "page_content": "<p>Dear {{FirstName,DefaultTo=Friend}},</p><br /><p>Thank you for joining our campaign.</p><span style=\"font-weight:bold\">Contact Information:<br/>{{FullName,DefaultTo=}}<br/>{{AddressLine1,DefaultTo=}}<br/>{{AddressLine2,DefaultTo=}}<br/>{{City,DefaultTo=}}&nbsp; {{StateProvince,DefaultTo=}}&nbsp;{{PostalCode,DefaultTo=}}</span>",
    "page_title": "bjorn sign up",
    "email_is_enabled": false,
    "email_plaintext_content": "<ul><li>I am not a foreign national who lacks permanent residence in the United States.</li><li>This contribution is made from my own funds, and not those of another.</li><li>This contribution is not made from the funds of a corporation or labor organization.</li><li>This contribution is made on a personal credit card or debit card for which I have the legal obligation to pay, and is not made either on a corporate or business entity card or on the card of another person.</li><li>I am at least eighteen years old.</li></ul>",
    "email_reply_to_address": "",
    "email_send_installment": false,
    "email_subject": ""
},
"created": "2012-08-02 16:56:40Z",
"fastAction": false,
"form_elements": [{
    "name": "HeaderHtml",
    "type": "markup",
    "markup": "<h1>\r\n\tPlease join us, so we can get our message out and win the campaign.</h1>\r\n"
}, {
    "name": "ContactInformation",
    "title": "Contact Information",
    "type": "fieldset",
    "children": [{
        "name": "FirstName",
        "title": "First Name",
        "type": "textfield",
        "required": true,
        "maxlength": 50,
        "queryString": "fn"
    }, {
        "name": "LastName",
        "title": "Last Name",
        "type": "textfield",
        "required": true,
        "maxlength": 50,
        "queryString": "ln"
    }, {
        "name": "AddressLine1",
        "title": "Address Line 1",
        "type": "textfield",
        "required": true,
        "maxlength": 100,
        "queryString": "add1"
    }, {
        "name": "AddressLine2",
        "title": "Address Line 2",
        "type": "textfield",
        "maxlength": 100,
        "queryString": "add2"
    }, {
        "name": "City",
        "title": "City",
        "type": "textfield",
        "required": true,
        "maxlength": 50,
        "queryString": "ci"
    }, {
        "name": "StateProvince",
        "title": "State or Province",
        "type": "select",
        "required": true,
        "queryString": "st",
        "options": "states"
    }, {
        "name": "PostalCode",
        "title": "Zip/Postal Code",
        "type": "textfield",
        "required": true,
        "maxlength": 15,
        "queryString": "pc",
        "validation": "postalCode"
    }, {
        "name": "HomePhone",
        "title": "Home Phone",
        "type": "textfield",
        "maxlength": 25,
        "queryString": "hp",
        "validation": "phone"
    }, {
        "name": "EmailAddress",
        "title": "Email",
        "type": "textfield",
        "required": true,
        "maxlength": 100,
        "queryString": "em",
        "validation": "email"
    }, {
        "name": "YesSignMeUpForUpdatesForBinder",
        "value": true,
        "type": "hidden",
        "queryString": "ae"
    }]
}, {
      "name": "MarketSource",
      "value": "",
      "type": "hidden",
      "queryString": "ms"
}, {
      "name": "MailingId",
      "value": "",
      "type": "hidden",
      "queryString": "midqs"
}, {
      "name": "TrackingPixel",
      "type": "markup",
      "markup": "<img alt=\" \" src='https://act.myngp.com/fo/3173630362412646400' />"
}, {
      "name": "submitForm",
      "type": "submit",
      "value": "Submit"
}],
  "formId": 2860,
  "googleAnalytics": "",
  "metadata": {
      "hideCompletedFormSections": false,
      "layoutStyle": "standard",
      "displayConfirmationMessage": false,
      "deactivationHtmlContent": "Sorry, the page you are trying to access is not accepting submissions at this time.",
      "columns": 1
  },
  "metatags": [{
      "property": "og:title",
      "content": "bjorn sign up"
  }, {
      "property": "fb:app_id",
      "content": "178968525494985"
  }, {
      "property": "og:url",
      "content": "http://act.myngp.com/Forms/3173630362412646400"
  }, {
      "property": "og:type",
      "content": "article"
  }, {
      "property": "og:site_name",
      "content": "act.myngp.com"
  }],
  "returnToWebsiteName": "",
  "returnToWebsiteUrl": "",
  "status": "Published",
  "title": "bjorn sign up",
  "type": "SignupForm",
  "updated": "2014-03-17 04:26:35Z",
  "url": {
      "full": "http://act.myngp.com/Forms/3173630362412646400",
      "base": "https://act.myngp.com/",
      "prefix": "",
      "slug": ""
  },
  "version": "00-00-00-03-ED-9B-5B-EC",
  "errors": [],
  "resultCode": "Success"
}

POST/forms/{formId}

Submits a form with its data
Description

This endpoint creates a pledge based on data in the request body.

Request

In addition to all of the required fields from the form definition JSON, the type must also be included. It is in the form definition, but it can be one of ContributionForm, EventForm, PetitionForm, SignupForm, VolunteerForm, or AdvocacyForm. This must come with a Content-Type=application/x-www-form-urlencoded; charset=UTF-8; with key/value pairs, the key of each field being the name attribute from the form definition. A sample POST to a contribution form (note that this is expressed in the form of a JSON object for consumption by the interactive documentation; for the real API, send POST data):

{
  "AddressLine1": "1101+15th+St+NW",
  "AddressLine2": "Ste+500",
  "City": "Washington",
  "EmailAddress": "info%40ngpvan.com",
  "FirstName": "lefty",
  "LastName": "donkey",
  "PostalCode": "20005",
  "StateProvince": "DC",
  "YesSignMeUpForUpdatesForBinder": "true",
  "type": "SignupForm"
}
Response

A successful form post returns the resultCode of Success as well as the page response and a timestamp of the submission. Example:

{
  {
  "page": {
      "confirmationActionType": "DisplayContent",
      "confirmationPageContent": "<p>Dear lefty,</p><br /><p>Thank you for joining our campaign.</p><span style=\"font-weight:bold\">Contact Information:<br/>lefty donkey<br/>1101 15th St NW<br/>Ste 500<br/>Washington,&nbsp; DC&nbsp;20005</span>"
  },
  "response": {
      "fullName": "lefty donkey",
      "contributionAmount": "0",
      "contributionDateTimeStamp": "2015-05-15T02:42:28.0651036Z"
  },
  "errors": [],
  "resultCode": "Success"
  }
}

External Sources

Overview

An external source is a third-party database of contacts that is outside of NGP. In NGP, it’s possible to connect a contact to an ID in an external source. This service indicates the list of third-party databases whose IDs may be connected to NGP contacts. Each contact can contain multiple links to external sources. An examples of an external source could be an HR database containing a list of employees, or a database of members from a third-party membership system.

GET/externalSource

Retrieves a list of valid External Sources
Description

Retrieves the list of all valid external sources for the organization associated with this API key.

Request

An example request:

/externalSource
Response

The response is a JSON array containing the external source ID and name for all valid external sources. Example:

{
    "externalSourceTypeId": "7",
    "name": "EmployeeId",
}, {
    "externalSourceTypeId": "15",
    "name": "MemberId",
}

Email Lists

Overview

Information about email lists which may be used in conjunction with NGP’s Communication Center.

GET/emailLists

Retrieves a list of email lists.
Description

Retrieves the list of all email lists for the organization associated with this API key.

Request

An example request:

/emailLists
Response

The response is a JSON array containing the creation date, description, list ID, binding, internal name, and public name. Example:

{
    "dateCreated": "2015-05-08T15:10:46.997Z",
    "description": "The default list for your account.",
    "id": 19,
    "emailBinding": "default",
    "name": "General",
    "publicLabel": "General"
},
{
    "dateCreated": "2015-08-11T15:52:16.48Z",
    "description": "This email list is for organization members",
    "id": 20,
    "emailBinding": "default",
    "name": "Members",
    "publicLabel": "An email list for organization members"
}