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.

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;

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.

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.

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

Contact

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
        }
    ]
}

Contact Response

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

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

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:

The following rules are applied to the specified batch for a tenant that has Financial Batch Manager turned on:

Required Properties:

Optional Properties:

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

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.

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

Disbursement

{
    "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:

Disbursement Response

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

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.

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

Disclosure Fields Response

The response is a collection of:

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
  }
]

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.

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

Batches

Parameters:

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

Optional querystring filter parameters:

Batches Response

A collection of:

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
  }
]

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

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

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

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

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.

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