NGP VAN

https://docs.ngpvan.com
Admin
NGP VAN provides all-in-one CRM systems and tools for political campaigns and nonprofits, enabling...
Tokens:405,038
Snippets:1,991
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Get Campaigns Example

Source: https://docs.ngpvan.com/reference/get-campaigns

This example demonstrates a successful response when retrieving a list of campaigns. It includes campaign details such as ID, name, type, and status. Use this to understand the structure of campaign data returned by the API.

```json
{
  "items": [
    {
      "campaignId": 7919,
      "name": "Increase the Minimum Wage",
      "campaignType": {
        "campaignTypeId": 1312,
        "name": "Advocacy"
      },
      "campaignDisplayName": "Advocacy: Increase the Minimum Wage",
      "status": "Active",
      "contents": null
    },
    {
      "campaignId": 7920,
      "name": "Adopt, Don't Shop!",
      "campaignType": {
        "campaignTypeId": 1312,
        "name": "Advocacy"
      },
      "campaignDisplayName": "Advocacy: Adopt, Don't Shop!",
      "status": "Active",
      "contents": null
    }    
  ],
  "nextPageLink": null,
  "count": 2
}
```

--------------------------------

### Get Folder Details (Success Example)

Source: https://docs.ngpvan.com/reference/foldersfolderid

This example shows a successful response when retrieving folder details. It returns the folder ID and its name.

```json
{
  "folderId":44
  "name":"API Generated Lists"
}
```

--------------------------------

### Get File Loading Job Stats (JSON Example)

Source: https://docs.ngpvan.com/reference/fileloadingjobsjobidstats

Example response for a successful request to retrieve file loading job statistics. This includes counts of added phones, matched rows, bad rows, and the action type.

```json
{
    "items": [
        {
            "countBadRows": 0,
            "percentMatched": 100,
            "countPhonesAdded": 1,
            "actionType": "PhonesFile",
            "countTotalRows": 1,
            "countMatchedRows": 1
        }
    ],
    "nextPageLink": null,
    "count": 1
}
```

--------------------------------

### Get Available Registration Forms

Source: https://docs.ngpvan.com/reference/voterregistrationbatchesregistrationforms

This example shows a successful response when retrieving a list of available registration forms. It includes the form ID and name, along with pagination information.

```json
{
  "items": [
    {
      "formId": 101,
      "name": "VR Form"
    }
  ],
  "nextPageLink": null,
  "count": 1
}
```

--------------------------------

### Get File Loading Job Status (200 OK)

Source: https://docs.ngpvan.com/reference/fileloadingjobsjobid

This example shows a successful response when retrieving the status and metadata for a File Loading Job. It includes details about the job's actions, file information, and source URL.

```json
{
    "jobId": 998877,
    "actions": [
      {
        "actionType": "score",
        "personIdColumn": "hatWearerId",
        "personIdType": "VANID",
        "scoreColumn": "hatWearingScore",
        "scoreId": 112233
      },
      {
        "actionType": "score",
        "personIdColumn": "hatWearerId",
        "personIdType": "VANID",
        "scoreColumn": "needsAnotherHatScore",
        "scoreId": 112234,
        "approvalCriteria": {
        "average": 75.2,
        "tolerance": 1.3
      }
    ],
    "description": "Load habberdasher score",
    "file": {
      "columnDelimiter": "Csv",
      "columns": [
        {"name": "hatWearerId"},
        {"name": "hatWearingScore"},
        {"name": "needsAnotherHatScore"}
      ],
      "fileName": "haberdashery.csv",
      "hasHeader": true,
      "sourceUrl": "sftp://keep:yourHatOn@ftp.headpieces.example.org/haberdasher.csv.zip"
    },
    "listeners": null,
    "interventionCallbackUrl": null,
    "invalidRowsFileUrl": null
}
```

--------------------------------

### Successful Response Example (204 No Content)

Source: https://docs.ngpvan.com/reference/peoplevanidcanvassresponses

This example represents a successful operation that does not return any content.

```json

```

--------------------------------

### Combine Callback Registration and Initialization

Source: https://docs.ngpvan.com/reference/callbacks

A consolidated example showing how to define a callback function, initialize the `nvtag_callbacks` object, and push the function into the `postRender` array.

```javascript
var sampleCallback = function() {
  alert("The form has been rendered!");
}
var nvtag_callbacks = nvtag_callbacks || {};
vtag_callbacks.postRender = nvtag_callbacks.postRender || [];
vtag_callbacks.postRender.push(sampleCallback);
```

--------------------------------

### Add Shift to Event Request Example

Source: https://docs.ngpvan.com/reference/eventseventidshifts

This is an example of the JSON payload to create a new shift for an event. It includes the shift's name, start time, and end time.

```json
{
  "name": "Late Shift",
  "startTime": "2015-11-13T20:00:00-05:00",
  "endTime": "2015-11-13T22:00:00-05:00"
}
```

--------------------------------

### Person Signup Example

Source: https://docs.ngpvan.com/reference/signups-common-models

An example of a Person's signup for an event, including details like event ID, person information, event details, shift, role, status, and location.

```json
{
  "eventSignupId": 2452,
  "person": {
    "vanId": 100476252,
    "firstName": "James",
    "middleName": "Worthington",
    "lastName": "Gordon"
  },
  "event": {
    "eventId": 1370,
    "name": "Neighbors Calling Neighbors",
    "shortName": "NeighborCall"
  },
  "shift": {
    "eventShiftId": 2162,
    "name": null
  },
  "role": {
    "roleId": 111687,
    "name": "Host"
  },
  "status": {
    "statusId": 4,
    "name": "Invited"
  },
  "location": {
    "locationId": 272,
    "name": "Campaign HQ",
    "displayName": "Campaign HQ, 48 Grove St Somerville, MA 02144-2500"
  },
  "startTimeOverride": "2015-06-01T15:00:00-04:00",
  "endTimeOverride": "2015-06-01T16:00:00-04:00"
}
```

--------------------------------

### Create a SourceCode with Metadata

Source: https://docs.ngpvan.com/reference/post-codes

Example of creating a 'SourceCode' with various metadata fields such as campaign, contact type, and financial information.

```json
{
    "name": "SourceCode 22-06-02",
    "description": "Description of a source code",
    "codeType": "SourceCode",
    "campaign": {
        "campaignId": 2541
    },
    "contactType": {
        "contactTypeId": 82
    },
    "generalLedgerFund": {
        "generalLedgerFundId": 69
    },
    "costCenter": {
        "costCenterId": 47
    },
    "revenueStream": {
        "revenueStreamId": 179
    },
    "mailMergeTemplate": {
        "mailMergeTemplateId": 337
    },
    "isSourceCodeApplicable": true
}
```

--------------------------------

### Original Resource Example

Source: https://docs.ngpvan.com/reference/json-patch

This is the initial state of a resource before applying JSON Patch operations.

```json
{
    "customer": {
        "name": "Jim Gordon",
        "email": "jim@gotham.ci.us"
    },
    "orders": [
        {
            "orderNumber": 121,
            "amount": 123
        },
        {
            "orderNumber": 122,
            "amount": 37
        }
    ]
}
```

--------------------------------

### Get Person Canvass Responses by External ID

Source: https://docs.ngpvan.com/reference/peoplepersonidcanvassresponsesreferenceid

Use this GET request to retrieve canvass responses for a person using their external ID type and ID. Ensure the referenceId is a valid GUID obtained from a previous POST request.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "van-crm",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.securevan.com/v4"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/people/{personIdType}:{personId}/canvassResponses/{referenceId}": {
      "get": {
        "summary": "/people/{personIdType}:{personId}/canvassResponses/{referenceId}",
        "description": "This endpoint is the same as [GET /people/{vanId}/canvassResponses/{referenceId}](https://docs.ngpvan.com/reference/people#peoplevanidcanvassresponsesreferenceid) but uses external IDs rather than VANIDs.",
        "operationId": "peoplepersonidcanvassresponsesreferenceid",
        "parameters": [
          {
            "name": "personIdType",
            "in": "path",
            "description": "Required; a known person identifier type available in the current context",
            "schema": {
              "type": "string",
              "default": "GWID"
            },
            "required": true
          },
          {
            "name": "personId",
            "in": "path',
            "description": "Required; an external identifier, URL encoded",
            "schema": {
              "type": "string",
              "default": "3"
            },
            "required": true
          },
          {
            "name": "referenceId",
            "in": "path",
            "description": "Required; Unique GUID found in the response body of [POST /people/{vanId}/canvassResponses](https://docs.ngpvan.com/reference/peoplevanidcanvassresponses) when includeReferenceIdInResponse is set to true.",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"vanId\": \"6297278\",\n    \"canvassResponses\": [\n        {\n            \"canvassResponseId\": 1530651,\n            \"canvassContext\": {\n                \"contactTypeId\": 37,\n                \"inputTypeId\": 11,\n                \"dateCanvassed\": \"2023-06-01T11:06:00-04:00\",\n                \"phone\": {\n                    \"phoneId\": 6886215,\n                    \"phoneNumber\": \"4567890100\",\n                    \"dialingPrefix\": \"1\",\n                    \"countryCode\": \"US\",\n                    \"ext\": null,\n                    \"dateCreated\": \"2023-06-16T13:09:00Z\",\n                    \"phoneType\": \"Home\",\n                    \"isPreferred\": false,\n                    \"smsOptInStatus\": null,\n                    \"phoneOptInStatus\": null,\n                    \"isCellStatus\": {\n                        \"statusId\": 3,\n                        \"statusName\": \"Likely Not a Cell\"\n                    }\n                },\n                \"campaignId\": null,\n                \"contentId\": null,\n                \"skipMatching\": false,\n                \"teamId\": null,\n                \"divisionId\": null,\n                \"omitActivistCodeContactHistory\": null\n            },\n            \"resultCodeId\": 14,\n            \"responses\": [],\n            \"note\": null,\n            \"emails\": null,\n            \"phones\": null,\n            \"externalReferenceId\": \"58F366C1-B215-46E8-AF45-7FD255DAE3B0\",\n            \"selfReportedDemographicFields\": null\n        }\n    ]\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "vanId": {
                      "type": "string",
                      "example": "6297278"
                    },
                    "canvassResponses": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "canvassResponseId": {
                            "type": "integer",
                            "example": 1530651,
                            "default": 0
                          },
                          "canvassContext": {
                            "type": "object",
                            "properties": {
                              "contactTypeId": {
                                "type": "integer",
                                "example": 37,
                                "default": 0
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Bulk Import with Organizing Turfs

Source: https://docs.ngpvan.com/reference/bulkimportjobs

Example demonstrating how to apply organizing turfs to contacts during a bulk import.

```APIDOC
## POST /bulkImportJobs (Organizing Turfs)

### Description
Creates a bulk import job to apply organizing turf levels to Contacts.

### Method
POST

### Endpoint
/bulkImportJobs

### Request Body
- **description** (string) - Required - A description for the import job.
- **file** (object) - Required - Information about the file to be imported.
  - **fileName** (string) - Required - The name of the file.
  - **hasHeader** (boolean) - Required - Indicates if the file has a header row.
  - **hasQuotes** (boolean) - Required - Indicates if the file uses quotes.
  - **sourceUrl** (string) - Required - The URL of the file.
  - **columns** (array) - Required - A list of column definitions.
    - **name** (string) - Required - The name of the column.
  - **columnDelimiter** (string) - Required - The delimiter used in the file (e.g., 'Csv').
- **actions** (array) - Required - A list of actions to perform on the imported data.
  - **resultFileSizeKbLimit** (integer) - Required - The maximum size of the result file in kilobytes.
  - **resourceType** (string) - Required - The type of resource to import (e.g., 'Contacts').
  - **actionType** (string) - Required - The type of action to perform (e.g., 'loadMappedFile').
  - **mappingTypes** (array) - Required - Defines how organizing turfs should be mapped.
    - **name** (string) - Required - Must be 'ApplyOrganzingTurfs'.
    - **fieldValueMappings** (array) - Required - Mappings for organizing turf levels.
      - **fieldName** (string) - Required - The name of the turf level field (e.g., 'CF123', 'CF124', 'CF125').
      - **columnName** (string) - Required - The name of the column in the source file to use for mapping.

### Request Example
```json
{
  "description": "A bulk import with organizing turfs",
  "file": {
    "fileName": "my_bulk_upload.csv",
    "hasHeader": true,
    "hasQuotes": false,
    "sourceUrl": "https://a-place-for-files.com/my_bulk_upload.zip",
    "columns": [
      { "name": "VANID" },
      { "name": "Region" },
      { "name": "Organizer" },
      { "name": "Team" }
    ],
    "columnDelimiter": "Csv"
  },
  "actions": [
    {
      "resultFileSizeKbLimit": 5000,
      "resourceType": "Contacts",
      "actionType": "loadMappedFile",
      "mappingTypes": [
        {
          "name": "ApplyOrganzingTurfs",
          "fieldValueMappings": [
            {
              "fieldName": "CF123",
              "columnName": "Region"
            },
            {
              "fieldName": "CF124",
              "columnName": "Organizer"
            },
            {
              "fieldName": "CF125",
              "columnName": "Team"
            }
          ]
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Get Saved List Metadata (200 OK)

Source: https://docs.ngpvan.com/reference/savedlistssavedlistid

Example of a successful response when retrieving metadata for a saved list. This JSON object contains details about the saved list.

```json
{
    "savedListId": 123,
    "name": "GOTV list",
    "description": "People we want to talk to for GOTV",
    "listCount": 2000,
    "doorCount": 987
}
```

--------------------------------

### Retrieve Pronouns

Source: https://docs.ngpvan.com/reference/pronouns

Use this GET request to retrieve a list of available pronouns. You can control the number of results and the starting point using $top and $skip query parameters.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "van-crm",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.securevan.com/v4"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/pronouns": {
      "get": {
        "summary": "/pronouns",
        "description": "Retrieve available Pronouns",
        "operationId": "pronouns",
        "parameters": [
          {
            "name": "$top",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 3
            }
          },
          {
            "name": "$skip",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"items\": [\n    {\n      \"pronounId": 6,\n      \"pronounName\": \"E/Em/Eirs\"\n    },\n    {\n      \"pronounId": 7,\n      \"pronounName\": \"Ey/Em/Eirs\"\n    },\n    {\n      \"pronounId": 2,\n      \"pronounName\": \"He/Him/His\"\n    }\n  ],\n  \"nextPageLink\": \"https://api.securevan.com/v4/pronouns?$top=3&$skip=4\",\n  \"count\": 14\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "pronounId": {
                            "type": "integer",
                            "example": 6,
                            "default": 0
                          },
                          "pronounName": {
                            "type": "string",
                            "example": "E/Em/Eirs"
                          }
                        }
                      }
                    },
                    "nextPageLink": {
                      "type": "string",
                      "example": "https://api.securevan.com/v4/pronouns?$top=3&$skip=4"
                    },
                    "count": {
                      "type": "integer",
                      "example": 14,
                      "default": 0
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"errors\": [\n        {\n            \"code\": \"Error code\",\n            \"text\": \"Error description\"\n        }\n    ]\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string",
                            "example": "Error code"
                          },
                          "text": {
                            "type": "string",
                            "example": "Error description"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```

--------------------------------

### Example Successful Response (200)

Source: https://docs.ngpvan.com/reference/folders-1

An example of a successful response from the /folders endpoint, showing a list of folders with their IDs and names.

```json
{
  "items":[
    {
      "folderId":44
      "name":"API Generated Lists"
    }
    {
      "folderId":40
      "name":"Test Folder 6"
    }
  ]
  "nextPageLink":NULL
  "count":2
}
```

--------------------------------

### OpenAPI Definition for Attribution Types

Source: https://docs.ngpvan.com/reference/contributionsattributiontypes

This is the OpenAPI 3.1.0 definition for the /contributions/attributionTypes endpoint. It outlines the GET request, its parameters, and the structure of the successful 200 response, including example data.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "van-crm",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.securevan.com/v4"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/contributions/attributionTypes": {
      "get": {
        "summary": "/contributions/attributionTypes",
        "description": "Retreive a list of [Attribution Types](https://docs.ngpvan.com/reference/contributions#attributions) which are enabled on a [Designation](https://docs.ngpvan.com/reference/contributions#designation) in the current committee.",
        "operationId": "contributionsattributiontypes",
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "[
        {
          "vanId": 303,
          "amountAttributed": "100.50",
          "attributionType": "DefaultAttribution",
          "notes": "some notes go here",
          "dateThanked": "2013-12-30"
        },
        {
          "vanId": 701,
          "amountAttributed": "202.10",
          "attributionType": "CorporateMatch",
          "notes": "some notes go here",
          "dateThanked": "2013-12-30"
        }
]"
                  }
                },
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "vanId": {
                        "type": "integer",
                        "example": 303,
                        "default": 0
                      },
                      "amountAttributed": {
                        "type": "string",
                        "example": "100.50"
                      },
                      "attributionType": {
                        "type": "string",
                        "example": "DefaultAttribution"
                      },
                      "notes": {
                        "type": "string",
                        "example": "some notes go here"
                      },
                      "dateThanked": {
                        "type": "string",
                        "example": "2013-12-30"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```

--------------------------------

### Apply Names and Salutations to Contacts

Source: https://docs.ngpvan.com/reference/bulkimportjobs

This example demonstrates how to load contact names and salutations by mapping columns from a source file. It specifies the file details and defines field-value mappings for contact attributes like 'LastName', 'FirstName', and 'Salutation'.

```json
POST /bulkImportJobs
{
  "description": "Load Contact Names",
  "listeners": [{"type": "email", "value": "test@example.com" }],
  "file": {
    "fileName": "NamesImport.txt",
    "hasHeader": true,
    "hasQuotes": false,
    "sourceUrl": "https://a-place-for-files.com/NamesImport.zip",
    "columns": [
      { "name": "VANID" },
      { "name": "Last" },
      { "name": "First" },
      { "name": "Middle" },
      { "name": "Suffix" },
      { "name": "Salutation" },
      { "name": "EnvelopeName" }
    ],
    "columnDelimiter": "Tab"
  },
  "actions": [
    {
      "resultFileSizeKbLimit": 5000,
      "resourceType": "Contacts",
      "actionType": "loadMappedFile",
      "mappingTypes": [
        {
          "name": "Salutations",
          "fieldValueMappings": [
            {
              "fieldName": "LastName",
              "columnName": "Last"
            },
            {
              "fieldName": "FirstName",
              "columnName": "First"
            },
            {
              "fieldName": "MiddleName",
              "columnName": "Middle"
            },
            {
              "fieldName": "Suffix",
              "columnName": "Suffix"
            },
            {
              "fieldName": "Salutation",
              "columnName": "Salutation"
            },
            {
              "fieldName": "FormalSalutation",
              "columnName": "Salutation"
            },
            {
              "fieldName": "AdditionalSalutation",
              "columnName": "Salutation"
            },
            {
              "fieldName": "EnvelopeName",
              "columnName": "EnvelopeName"
            },
            {
              "fieldName": "FormalEnvelopeName",
              "columnName": "EnvelopeName"
            },
            {
              "fieldName": "AdditionalEnvelopeName",
              "columnName": "EnvelopeName"
            }
          ]
        }
      ]
    }
  ]
}
```

--------------------------------

### Get Available Code Types

Source: https://docs.ngpvan.com/reference/codetypes

This example shows the expected JSON response when successfully retrieving the available code types for your API key. It lists 'Tag' and 'SourceCode' as the available types.

```json
[
  "Tag",
  "SourceCode"
]
```

--------------------------------

### Retrieve Employers (OpenAPI)

Source: https://docs.ngpvan.com/reference/employers-1

This OpenAPI definition outlines the GET request for the /employers endpoint. It specifies parameters like `isMyOrganization` and `$expand`, and defines successful (200) and error (400) responses with example payloads.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "van-crm",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.securevan.com/v4"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/employers": {
      "get": {
        "summary": "/employers",
        "description": "Use this endpoint to retrieve all Employers available in the current context.\n\nBy default, this endpoint returns 250 records per request. A maximum of 500 records per request is allowed via the `$top` parameter.",
        "operationId": "employers-1",
        "parameters": [
          {
            "name": "isMyOrganization",
            "in": "query",
            "description": "Optional; filters results by whether an Employer is designated `isMyOrganization`",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "$expand",
            "in": "query",
            "description": "Optional; comma delimited list of expansion properties: `parent`, `phones`",
            "schema": {
              "type": "string",
              "default": "parent"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\"items\":[
  {
  \"employerId\": 671,
  \"name\": \"Eastside Regional Medical Center\",
  \"shortName\": \"Eastside Regional\",
  \"parentOrganization\": {
      \"organizationId\": 65,
      \"organizationType\": null,
      \"name\": \"United Healthcare Systems\",
      \"shortName\": \"United Healthcare\",
      \"website\": null,
      \"parentOrganization\": null
  },
  \"website\": \"https://eastsideregionalmc.com\",
  \"isMyOrganization\": true,
  \"phones\": [],
  \"departments\": [],
  \"jobClasses\": [],
  \"worksites\": [],
  \"shifts\": []
	}
]
\"nextPageLink\":NULL
\"count\":0
}"
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"errors\": [
        {
            \"code\": \"Error code\",
            \"text\": \"Error description\"
        }
    ]
}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string",
                            "example": "Error code"
                          },
                          "text": {
                            "type": "string",
                            "example": "Error description"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}

```

--------------------------------

### Retrieve Supporter Groups (Success Example)

Source: https://docs.ngpvan.com/reference/supportergroups

This example demonstrates a successful response when retrieving supporter groups. It includes a list of groups with their IDs, names, and descriptions, along with pagination information.

```json
{
  "items": [
    {
      "id": 15,
      "name": "North End Volunteers",
      "description": "Volunteers from the North End that help out frequently"
		}
  ],
  "nextPageLink": null,
  "count": 1
}
```

--------------------------------

### Get People

Source: https://docs.ngpvan.com/reference/get-people

Fetches a list of people matching the provided query parameters. At least one string parameter must be specified. Search criteria are case-insensitive and match strings that start with the provided value.

```APIDOC
## GET /people

### Description
Returns a paginated list of contacts who meet all of the specified criteria.

Unless noted otherwise, search criteria can be partial inputs; they will match any string that starts with the value provided (case-insensitive).

At least one string parameter must be specified.

### Method
GET

### Endpoint
/people

### Parameters
#### Query Parameters
- **firstName** (string) - Optional - First name to search for.
- **middleName** (string) - Optional - Middle name to search for.
- **lastName** (string) - Optional - Last name to search for.
- **streetAddress** (string) - Optional - Street address to search for.
- **city** (string) - Optional - City to search for.
- **stateOrProvince** (string) - Optional - Must be a valid state or province code (two or three characters).
- **zipOrPostalCode** (string) - Optional - Must be a valid ZIP5 zip code or postal code. For UK clients, this parameter accepts valid partial postcodes (e.g., postcode sector).
- **phoneNumber** (string) - Optional - Must be a valid phone number.
- **email** (string) - Optional - Matches records with emails starting with this value.
- **commonName** (string) - Optional - If Organizations-as-Contacts is enabled, matches organizations whose Common Name begins with this value.
- **officialName** (string) - Optional - If Organizations-as-Contacts is enabled, matches organizations whose Official Name begins with this value.
- **contactMode** (string) - Optional - If Organizations-as-Contacts is enabled, filters to records of this type. Enum: "Person", "Organization".
- **$top** (integer) - Optional - Number of records to return.
- **$skip** (integer) - Optional - Number of records to skip.
- **$expand** (string) - Optional - Valid `$expand` sections are `Addresses`, `Districts`, `Emails`, and `Phones`.
- **$orderby** (string) - Optional - `Name asc` and `Name desc` are the only valid `$orderby` arguments.

### Response
#### Success Response (200)
- **field1** (type) - Description

#### Response Example
{
  "example": "response body"
}
```

--------------------------------

### Create Employer Response Example

Source: https://docs.ngpvan.com/reference/employers-2

This example shows the structure of a successful response when creating a new employer. It includes the employer's ID, name, parent organization details, website, and associated worksites.

```json
{
  "employerId": 671,
  "name": "Eastside Regional Medical Center",
  "shortName": "Eastside Regional",
  "parentOrganization": {
      "organizationId": 65,
      "organizationType": null,
      "name": "United Healthcare Systems",
      "shortName": "United Healthcare",
      "website": null,
      "parentOrganization": null
  },
  "website": "https://eastsideregionalmc.com",
  "isMyOrganization": true,
  "phones": [],
  "departments": [],
  "jobClasses": [],
  "worksites": [],
  "shifts": []
}
```

--------------------------------

### Get Bulk Import Job Metadata (Success)

Source: https://docs.ngpvan.com/reference/bulkimportjobsjobid

Example of a successful response when retrieving metadata for a completed bulk import job. It includes the job ID, status, resource type, and details about result files.

```json
{
  "id": 75,
  "status": "Completed",
  "resourceType": "Contacts",
  "resultFileSizeLimitKb": 5000,
  "errors": [],
  "resultFiles": [
    {
      "url": "https://somedomain.com/filename.csv",
      "dateExpired": "2019-05-15T08:45:50.2062048-04:00"
    }
  ]
}
```

--------------------------------

### Initiate a Bulk Import Job

Source: https://docs.ngpvan.com/reference/bulkimportjobs

Use this endpoint to start a bulk import job. Provide a URL to a zipped, delimited file. The file can contain update and/or creation records for a single resource type and may include a header row.

```json
POST /bulkImportJobs
{
  "description": "Unsuppress Phones Data",
  "file": {
     "fileName": "my_bulk_upload.zip",
     "hasHeader": true,
     "hasQuotes": false,
     "sourceUrl": "https://a-place-for-files.com/my_bulk_upload.zip",
     "columns": [
       {
         "name": "VanID"
       },
       {
         "name": "PhoneNumber"
       }
    ],
    "columnDelimiter": "csv"
  },
  "actions": [
    {
      "resultFileSizeKbLimit": 5000,
      "resourceType": "Contacts",
      "actionType": "loadMappedFile",
      "mappingTypes": [
        {
          "name": "UnsuppressPhones",
          "fieldValueMappings": [
            {
              "fieldName": "Phone",
              "columnName": "PhoneNumber"
            }
          ]
        }
      ]
    }
  ]
}
```

--------------------------------

### Get District Field Details (200 OK)

Source: https://docs.ngpvan.com/reference/districtfieldsdistrictfieldid

Example of a successful response when retrieving district field details. Includes field ID, name, parent ID, custom status, and a list of district field values.

```json
{
"districtFieldId":1
"name":"County"
"parentFieldId":6
"isCustomDistrict":false
"districtFieldValues":
[
    {
    "id":"000"
    "name":""
    "parentId":"AA"
    },
    {
    "id":"000"
    "name":""
    "parentId":"AE"
    },
    {
    "id":"000"
    "name":""
    "parentId":"AP"
    }
]
}
```

--------------------------------

### Example Next Page Link

Source: https://docs.ngpvan.com/reference/events-1

This example demonstrates the format of a nextPageLink, used for paginating through event results.

```json
{
  "type": "string",
  "example": "https://api.securevan.com:443/v4/events?startingAfter=2015-05-31&$expand=shifts&$top=2&$skip=2"
}
```

--------------------------------

### Create or Update Canvass Response

Source: https://docs.ngpvan.com/reference/peoplepersonidcanvassresponsescanvassresponseid

Creates a new canvass response for a person or updates an existing one. It allows specifying phone numbers, SMS opt-in status, campaign details, and content details. The `includeReferenceIdInResponse` parameter can be used to get a GUID for future reference.

```APIDOC
## POST /people/{vanId}/canvassResponses/{canvassResponseId}

### Description
Creates or updates a canvass response for a specific person.

### Method
POST

### Endpoint
/people/{vanId}/canvassResponses/{canvassResponseId}

### Parameters
#### Path Parameters
- **vanId** (integer) - Required - The Van ID of the person.
- **canvassResponseId** (string) - Required - The ID of the canvass response to create or update.

#### Query Parameters
- **includeReferenceIdInResponse** (boolean) - Optional - When set to true, the response body will include a GUID corresponding to the newly created canvass response. This GUID can be used later at GET /people/{vanId}/canvassResponses to retrieve the associated canvassResponseId, which is necessary for patching canvass responses at PATCH /people/{vanId}/canvassResponses/{canvassResponseId}. By default, this parameter is false.

#### Request Body
- **phoneNumber** (string) - Required when inputTypeId is 1 (Phone) or 37 (SMS); the phone number you are attempting - without calling code/dialing prefix.
- **smsOptInStatus** (string) - Optional; Must be one of three values: `I` (Opt-In), `O` (Opt-Out), `U` (Unknown).
- **campaignId** (integer) - Optional; a valid Campaign ID. Required if `contentId` is also specified.
- **contentId** (integer) - Optional; a valid Content ID. If specified, the Content's corresponding Campaign must be specified as `campaignId`.

### Request Example
```json
{
  "phoneNumber": "555-555-1234",
  "smsOptInStatus": "I",
  "campaignId": 12345,
  "contentId": 67890
}
```

### Response
#### Success Response (204)
- **(empty object)**

#### Response Example
```json
{}
```
```

--------------------------------

### Error with Resource URL

Source: https://docs.ngpvan.com/reference/errors

This example includes a URL pointing to resources that describe supported protocols for an error.

```json
{
  "errors": [
    {
      "properties": [
        "sourceFile.fileUrl"
      ],
      "text": "The URL provided does not represent a supported protocol",
      "resourceUrl": "https://api.ngpvan.com/support/supportedProtocols",
      "code": "UNSUPPORTED_PROTOCOL"
    }
  ]
}
```

--------------------------------

### OpenAPI Definition Example

Source: https://docs.ngpvan.com/reference/peoplepersonidtypepersonidcodes

This is an example of an OpenAPI definition structure.

```json
{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "NGPVAN API",
    "description": "API for accessing NGP VAN data."
  },
  "servers": [
    {
      "url": "https://api.ngpvan.com/v2"
    }
  ],
  "paths": {
    "/people": {
      "get": {
        "summary": "Get a list of people",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of people."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Person": {
        "type": "object",
        "properties": {
          "personId": {
            "type": "integer",
            "description": "Unique identifier for the person."
          },
          "firstName": {
            "type": "string"
          },
          "lastName": {
            "type": "string"
          }
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```

--------------------------------

### Load Relationships

Source: https://docs.ngpvan.com/reference/bulkimportjobs

This example demonstrates how to load relationships by mapping columns from a file to specific fields. It includes details about the file source, column delimiters, and mapping types for applying relationships.

```APIDOC
## POST /bulkImportJobs

### Description
Loads relationships from a file, mapping specified columns to relationship fields.

### Method
POST

### Endpoint
/bulkImportJobs

### Request Body
- **description** (string) - Optional - A description for the import job.
- **listeners** (array) - Optional - A list of listeners for import job notifications.
- **file** (object) - Required - Details about the file to be imported.
  - **fileName** (string) - Required - The name of the file.
  - **hasHeader** (boolean) - Required - Indicates if the file has a header row.
  - **hasQuotes** (boolean) - Required - Indicates if fields are enclosed in quotes.
  - **sourceUrl** (string) - Required - The URL where the file is located.
  - **columns** (array) - Required - An array of column definitions.
    - **name** (string) - Required - The name of the column.
  - **columnDelimiter** (string) - Required - The delimiter used in the file (e.g., 'csv').
- **actions** (array) - Required - A list of actions to perform on the imported data.
  - **resultFileSizeKbLimit** (integer) - Optional - The size limit for result files in kilobytes.
  - **resourceType** (string) - Required - The type of resource to import (e.g., 'Contacts').
  - **actionType** (string) - Required - The type of action to perform (e.g., 'loadMappedFile').
  - **mappingTypes** (array) - Required - An array of mapping configurations.
    - **name** (string) - Required - The name of the mapping type (e.g., 'ApplyRelationships').
    - **fieldValueMappings** (array) - Required - Mappings between file columns and resource fields.
      - **fieldName** (string) - Required - The name of the field in the resource.
      - **columnName** (string) - Optional - The name of the column in the file to map from.
      - **values** (array) - Optional - A list of source-to-target value mappings.
        - **sourceValue** (string) - Required - The value in the source file.
        - **targetValue** (string) - Required - The value to map to.
      - **staticValue** (any) - Optional - A static value to assign to the field.
      - **overwrite** (boolean) - Optional - Indicates if existing values should be overwritten.

### Request Example
```json
{
  "description": "Load Relationships",
  "listeners": [{"type": "email", "value": "test@example.com" }],
  "file": {
    "fileName": "RelationshipsImport.txt",
    "hasHeader": true,
    "hasQuotes": false,
    "sourceUrl": "https://a-place-for-files.com/RelationshipsImport.zip",
    "columns": [
      { "name": "VANID" },
      { "name": "Secondary" },
      { "name": "Relationship" },
      { "name": "Overwrite" }
    ],
    "columnDelimiter": "csv"
  },
  "actions": [
    {
      "resultFileSizeKbLimit": 5000,
      "resourceType": "Contacts",
      "actionType": "loadMappedFile",
      "mappingTypes": [
        {
          "name": "ApplyRelationships",
          "fieldValueMappings": [
            {
              "fieldName": "SecondaryVANID",
              "columnName": "Secondary"
            },
            {
              "fieldName": "Relationship",
              "values" : [
                                {
                                    "sourceValue" : "Assistant",
                                    "targetValue" : "Assistant"
                                }
                            ]
            },
            {
              "fieldName": "OverwriteExistingRelationship",
              "columnName": "Overwrite"
            }
          ]
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Employer Model Example

Source: https://docs.ngpvan.com/reference/common-models-10

An example of an Employer object, showing its properties.

```json
{
  "employerId": 123,
  "name": "ABC Employer"
}
```
Tokens:
Raw