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.
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)emails
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:
It’s not possible to have two emails with the same type. |
||||||||||||||||||||||||
addresses | A collection of:
It’s not possible to have two addresses with the same type. |
||||||||||||||||||||||||
phones | A collection of:
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.
|
||||||||||||||||||||||||
contactCodes |
A collection of:
|
||||||||||||||||||||||||
employer | String | ||||||||||||||||||||||||
occupation | String | ||||||||||||||||||||||||
facebookProfileUrl | String; the fully qualified URL for the contact’s Facebook profile. | ||||||||||||||||||||||||
disclosureFields |
A collection of:
|
||||||||||||||||||||||||
externalLinks |
A collection of:
|
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
).
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.
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.
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.
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 |
|
Optional Properties:
Key | Value | ||||||||
---|---|---|---|---|---|---|---|---|---|
batch |
batch is not optional if the Financial Batch Manager feature is enabled, but that is a minority of NGP clients.
|
||||||||
disclosureFields |
|
||||||||
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 |
|
||||||||
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 |
|
||||||||
attributedContactIds | An array of contact IDs to attribute to the contribution. | ||||||||
pledge |
|
||||||||
note | A 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
).
This endpoint request creates a contribution with the properties provided in the request body.
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.
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:
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 | ||||||||
---|---|---|---|---|---|---|---|---|---|
contactId | Required String; The contact ID of the disbursement. | ||||||||
amount | Required String; The amount of the disbursement. Value that has more than 2 digits after decimal point will not be accepted. | ||||||||
designation |
|
||||||||
bankAccount |
|
||||||||
batchName | String; a free-form description of the batch of disbursements. Not related to contribution batches. | ||||||||
checkNumber | String; the check number associated with this disbursement, if any. | ||||||||
date | String; 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 |
||||||||
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 |
||||||||
disclosureFields |
|
||||||||
note | A note detailing the disbursement. | ||||||||
sourceCode |
|
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
).
This endpoint request creates a disbursement with the properties provided in the request body.
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.
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.
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:
|
||||||
optionGroups |
Optional, supplied for single/multi select fields with option groups 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
}
]
This endpoint retrieves a list of designations and their codes.
/designations
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"
}
]
This endpoint retrieves a list of the disclosure fields required for a contact for the provided designation id.
/designations/{designationId}/contactDisclosureFields
This endpoint retrieves a list of the disclosure fields required for a contribution for the provided designation id.
/designations/{designationId}/contributionDisclosureFields
This endpoint retrieves a list of the disclosure fields required for a disbursement for the provided designation id.
/designations/{designationId}/disbursementDisclosureFields
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.
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
}
]
This endpoint retrieves a list of financial batches with optional querystrings.
Contact codes are hierarchical, up to 4 levels of hierarchy. They are used to categorize contact records for later searches and segments.
This endpoint retrieves a list of contact codes. The list is limited to the 1,000 most recently created contact codes.
/contactCodes
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"
}
]
This endpoint creates a new contact code based on data in the request body.
Key | Value |
---|---|
name | The contact code name. |
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
}
Successful contact code creation returns the ID of the newly created contact code. Example:
{
"contactCodeId": 23
}
Source codes are used to categorize contributions and disbursements. They, like contact codes are hierarchical, allowing up to 4 levels of hierarchy.
This endpoint gets a list of source codes.
/sourceCodes
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"
}
]
This endpoint creates a new source code based on data in the request body.
Parameters:
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. |
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"
}
Successful source code creation returns the ID of the newly created source code. Example:
{
"sourceCodeId": "23"
}
Pledges are used to track commitments by a contact record to donate or raise a certain amount of money.
This endpoint creates a pledge based on data in the request body.
Key | Value | ||||
---|---|---|---|---|---|
contactId | The contact ID of the pledger. | ||||
pledgeType | Can be one of two values: GIVE or RAISE. | ||||
pledgeDate | The Pledged On date. Must be in the form YYYY-MM-DD, per the ISO 8601 standard. | ||||
designation |
|
Key | Value | ||||
---|---|---|---|---|---|
amount | If not specified, it is considered an “unknown amount.” If specified, it cannot be less than $0.01 US. | ||||
commitment | The 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. | ||||
expectedFulfillmentDate | Expected 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 |
|
||||
attributedContactIds | An array of contact IDs to attribute to the pledge. | ||||
taskID | A 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
}
Successful pledge creation returns the ID of the newly created pledge. Example:
{
"pledgeId": "VN65J9H5SW3"
}
Forms are used to collect signups based on forms published in the system.
Retrieve the list of all Online Page Forms for the organization associated with this API key.
An example request:
/forms
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
}
This definition contains all of the information necessary to render this form, validate it, and submit its contents back to NGP.
This request does not require an API key. An example request:
/forms/3173630362412646400
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=}} {{StateProvince,DefaultTo=}} {{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=}} {{StateProvince,DefaultTo=}} {{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"
}
This endpoint processes a form submission based on data in the request body.
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"
}
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, DC 20005</span>"
},
"response": {
"fullName": "lefty donkey",
"contributionAmount": "0",
"contributionDateTimeStamp": "2015-05-15T02:42:28.0651036Z"
},
"errors": [],
"resultCode": "Success"
}
}
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.
Retrieves the list of all valid external sources for the organization associated with this API key.
An example request:
/externalSource
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",
}
Information about email lists which may be used in conjunction with NGP’s Communication Center.
Retrieves the list of all email lists for the organization associated with this API key.
An example request:
/emailLists
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"
}
Information about email messages and their variants which may be used in conjunction with NGP 7’s Communication Center.
This endpoint accepts standard pagination parameters and returns a standard pagination response of sent email messages.
By default, this endpoint returns 25 records per request. A maximum of 25 records per request is allowed via the $top
parameter.
An example request:
GET /broadcastEmails
This endpoint responds with a standard paged list of sent email messages.
Key | Value |
---|---|
emailMessageId | Unique identifier of email message |
name | Name of email message |
{
"items": {
[
{
"emailMessageId": "123",
"name": "2017 Call to Action"
}
]
},
"count": 1,
"nextPageLink": null
}
This endpoint returns details on an email message. Note that every email message has one or more variants. Each variant represents a different email message sent to a segment of the overall email audience, as in an A/B testing scenario.
The optional $expand=statistics
parameter provides additional statistics about the email message, summed over all variants.
Parameter | Location | Type | Description |
---|---|---|---|
emailMessageId |
route | integer | Required; Unique identifier of email message to be retrieved |
$expand |
query | string | Optional; expansion property: statistics |
An example request:
GET /broadcastEmails/123?$expand=statistics
This endpoint responds with details of a sent email message.
Key | Value | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
emailMessageId | Unique identifier of email message | ||||||||||||
name | Name of email message | ||||||||||||
variants |
A collection of:
|
||||||||||||
statistics |
Summary statistics about the email message, summed up over all the variants.
|
{
"emailMessageId": 123,
"name": "2017 Call to Action",
"variants": [
{
"emailMessageVariantId": 401,
"name": "2017 Call to Action - Variant 1",
"subject": "Come March With Us"
},
{
"emailMessageVariantId": 402,
"name": "2017 Call to Action - Variant 2",
"subject": "Won't you march with us?"
}
],
"statistics": {
"recipients": 1000,
"opens": 45,
"clicks": 20,
"unsubscribes": 65,
"bounces": 50
}
}
This endpoint returns details on an email message variant.
The optional $expand=statistics
parameter provides additional statistics about this email message variant.
Parameter | Location | Type | Description |
---|---|---|---|
emailMessageId |
route | integer | Required; Unique identifier of email message to be retrieved |
emailMessageVariantId |
route | integer | Required; Unique identifier of email message variant to be retrieved |
$expand |
query | string | Optional; expansion property: statistics |
An example request:
GET /broadcastEmails/123/variants/401?$expand=statistics
Key | Value | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
emailMessageId | Unique identifier of email message variant | ||||||||||||||||
emailMessageVariantId | Unique identifier of email message variant | ||||||||||||||||
name | Name of email message variant | ||||||||||||||||
subject | Subject of email message variant | ||||||||||||||||
statistics |
|
Example:
{
"emailMessageId": 123,
"emailMessageVariantId": 401,
"name": "2017 Call to Action - Variant 1",
"subject": "Come March With Us",
"statistics": {
"startSentOn": "2017-11-29T21:01:15.18Z",
"endSentOn": "2017-11-29T21:01:15.183Z",
"recipients": 100,
"opens": 10,
"clicks": 5,
"unsubscribes": 15,
"bounces": 12
}
}
This endpoint returns details on an email message variant.
The optional $expand=statistics
parameter provides additional statistics about this email message variant.
Parameter | Location | Type | Description |
---|---|---|---|
emailMailingId |
route | string | Required; Unique identifier of email message variant to be retrieved. The mailing id in the parameter is the same as the “Mailing ID” merge field value from NGP 7’s emails. |
$expand |
query | string | Optional; expansion property: statistics |
An example request:
GET /broadcastEmailVariants/mailingId:qwerty1234567890?$expand=statistics
Response is identical to GET /broadcastEmails/{emailMessageId}/variants/{emailMessageVariantId}.