Match Candidates

In order to ensure we are accurately matching to the one true person you are looking for in My Voters or My Campaign (or My Members or My Workers, where applicable), there are a few minimum combinations in order to trigger a match attempt. These include:

first name, last name, and email address
first name, last name, and phone
first name, last name, zip5, and date of birth
first name, last name, street number, street name, and zip5
email address

Note that these are minimums - the more information you can provide about a contact, the better. If you fail to provide the minimum amount of required information, you will not get a match when attempting to find contacts, and will always create a new record when adding contacts.

Also note that clients can enable stricter match rules within specific contexts. These stricter rules do not change how a developer interacts with these endpoints but may reduce the match rate relative to other contexts (e.g., in sandbox accounts). Your VAN Administrator should be able to determine which rules are enabled in their production context. An example of a matching rule is “Disable Partial Matching” which requires a match on full first name and last name in order to match to an existing record (as opposed to using possible nicknames and other permutations of the name).

Matching is accent insensitive in all databases. Pérez will match Perez and vice versa. Matching is also case insensitive. PEREZ will match Perez.

All requests to “find” endpoints expect data to be structured like the following.

{
  "vanId": 1234,
  "firstName": "James",
  "middleName": "Worthington",
  "lastName": "Gordon",
  "suffix": "M.D.",
  "title": "Dr.",
  "salutation": "Dr. Gordon",
  "envelopeName": "Dr. Jim Gordon",
  "pronouns": {
    "pronounId": 3
  },
  "contactMethodPreferenceCode": "S",
  "nickname": "Jim",
  "website": "www.jimgordon.com",
  "party": "D",
  "employer": "Acme Medical Group",
  "occupation": "Physician",
  "jobTitle": "Doctor of Internal Medicine",
  "sex": "M",
  "dateOfBirth": "1976-07-04",
  "yearOfBirth": 1976,
  "collectionLocationId": 123,
  "electionType": "G",
  "cycle": "2020",
  "selfReportedRaces": [
    {
      "reportedRaceId": 4
    }
  ],
  "selfReportedEthnicities": [
    {
      "reportedEthnicityId": 5
    }
  ],
  "selfReportedLanguagePreference": {
    "reportedLanguagePreferenceId": 6
  },
  "selfReportedSexualOrientations": [
    {
      "reportedSexualOrientationId": 1
    }
  ],
  "selfReportedGenders": [
    {
      "reportedGenderId": 1
    }
  ],
  "emails": [
    {
      "email": "jim@gotham.city.us",
      "type": "P",
      "isPreferred": true,
      "isSubscribed": null,
      "subscriptionStatus": "N"
    },
    {
      "email": "jim@fake.ngpvan.com",
      "type": "W",
      "isPreferred": false,
      "isSubscribed": true,
      "subscriptionStatus": "S"
    }
  ],
  "phones": [
    {
      "phoneId": 867,
      "phoneNumber": "1-555-888-9999",
      "phoneType": "H",
      "isPreferred": true,
      "phoneOptInStatus": "I",
      "isCellStatus": {
        "statusId": 2,
        "statusName": "Likely Cell"
      }
    },
    {
      "phoneId": 5309,
      "phoneNumber": "1-555-555-1234",
      "phoneType": "W",
      "ext": 999,
      "isPreferred": false,
      "isCellStatus": null
    }
  ],
  "addresses": [
    {
      "addressId": 1234,
      "addressLine1": "123 Main St",
      "addressLine2": "Apt 3",
      "addressLine3": "c/o Jane Smith",
      "city": "Gotham City",
      "stateOrProvince": "IL",
      "zipOrPostalCode": "01234",
      "countryCode": "US",
      "type": "Voting",
      "isPreferred": true,
    },
    {
      "addressId": 6789,
      "addressLine1": "555 Elm St",
      "addressLine2": "Suite 101",
      "addressLine3": "Marketing Department",
      "city": "Springfield",
      "stateOrProvince": "IL",
      "zipOrPostalCode": "01234",
      "countryCode": "US",
      "type": "Mailing",
      "isPreferred": false
    }
  ],
  "identifiers": [
    {
      "type": "bsdid",
      "externalId": "746313"
    }
  ],
  "customFieldValues": [
    {
      "customFieldId": 500,
      "customFieldGroupId": 100,
      "assignedValue": "someValue"
    }
  ],
  "contactMode": "Person"
}

Match Candidate

Property	Type	Max length	Description
`vanId`	string	n/a	Optional; unique identifier of the My Campaign or My Voters record if known in advancewn in advance.
`firstName`	string	75	Optional; a person’s first name
`middleName`	string	75	Optional; a person’s middle name
`lastName`	string	150	Optional; a person’s last name
`suffix`	string	50	Optional; part of name following last name, e.g. "Jr."
`title`	string	10	Optional; an honorific
`salutation`	string	100	Optional; preferred greeting for correspondence
`envelopeName`	string	350	Optional; preferred name to use for mailings
`pronouns`	object	n/a	Optional; a person's pronouns
`nickname`	string	50	Optional; a person's preferred informal name
`website`	string	50	Optional; a person's personal website
`party`	string	1	Optional; a one-character string indicating party affiliation, e.g. "D"
`contactMethodPreferenceCode`	string	1	Optional; a person's preferred method of contact; must be one of: `P` → phone, `E` → email, `M` → mail, `F` → fax, or `S` → SMS
`employer`	string	50	Optional; name of the organization where the person works, e.g. "Kennedy High School"; may not be available in every context
`occupation`	string	50	Optional; nature of the person’s work, e.g. "teacher"; may not be available in every context
`jobTitle`	string	150	Optional; name of the position the person holds at an organization; maybe not be available in every context
`sex`	string	1	Optional; a one-character string indicating sex; must be `M` or `F`
`dateOfBirth`	datetime	n/a	Optional; a person’s date of birth; must be ISO 8601 formatted and in the 20th or 21st century
`collectedLocationId`	int	n/a	Optional; location where a person's voter registration application was collected
`electionType`	string	2	Optional; type of election registered for; must be one of `G` → General, `P` → Primary, `R` → Run-off, `PP` → Presidential Primary, `SP` → Special Primary, `SG` → Special General, `MP` → Municipal Primary, `MG` → Municipal General, `C` → Caucus, or `O` → Other
`cycle`	string	4	Optional; a numeric string indicating the election year a person registered to vote
`selfReportedRaces`	array	n/a	Optional; the person’s race(s); `reportedRaceId` must match one of the reported races available in the current context
`selfReportedEthnicities`	array	n/a	Optional; a person’s ethnicity or ethnicities; `reportedEthnicityId` must match one of the reported ethnicities available in the current context
`selfReportedGenders`	array	n/a	Optional; a person’s gender(s); `reportedGenderId` must match one of the reported genders available in the current context
`selfReportedSexualOrientations`	array	n/a	Optional; indicates the person’s sexual orientation(s). The `reportedSexualOrientationId` must match one of the reported sexual orientation available in the current context
`selfReportedLanguagePreference`	object	n/a	Optional; a person’s language preference: `reportedLanguagePreferenceId` must match one of the reported language preferences available in the current context
`emails`	array	n/a	Optional; an array of email objects
`phones`	array	n/a	Optional; an array of phone objects
`addresses`	array	n/a	Optional; an array of address objects
`identifiers`	array	n/a	Optional; an array of identifier objects
`customFieldValues`	array	n/a	Optional; an array of customFieldValue objects
`organizationContactCommonName`	string	150	Optional; an organization's common name; applicable only in My Campaign databases where organizations as contacts is enabled
`organizationContactOfficialName`	string	150	Optional; an organization's official name; applicable only in My Campaign databases where organizations as contacts is enabled
`contactMode`	string	n/a	Optional; the type of contact; must be `Person` or `Organization`; applicable only in My Campaign databases where organizations as contacts is enabled

🚧
Note:
Many of the properties listed above are expressed as arrays (e.g., addresses, phones, emails, etc.). If objects (rather than an array of a single object) are passed, they will be ignored.

Email

Property	Type	Description
`email`	string	Required; a valid email address
`type`	string	Optional; one of: `P` → personal, `W` → work, `O` → other. Default, if not supplied, is `P`.
`isPreferred`	bool	Optional; an indicator of whether the email address is the person’s preferred address; defaults to false
`isSubscribed`	bool	Deprecated if Targeted Email is available. Optional; indicates whether the email address may be used in a broadcast email. Default value is `true`. If it’s explicitly set to `false`, it is treated as an opt-out and you will not be able to resubscribe the email address.
`subscriptionStatus`	string	Optional; indicates the email address subscription status for Targeted Email. One of `U` → unsubscribed, `N` → neutral, `S`→ subscribed. If unspecified, assumed value is `S`. Only email addresses with status `S` will receive messages from Targeted Email. Once an email address has been unsubscribed, it may not be subscribed or set to neutral. This property is only available if Targeted Email is available; it is not valid to set this property and `isSubscribed` at the same time.

Phone

Property	Type	Description
`phoneId`	int	Read-only; unique identifier of the phone.
`phoneNumber`	string	Required; after removing all non-numeric characters, the number is evaluated using country specific validation, defaulting to the target context’s country if no other is provided.
`phoneType`	string	Optional; one of: `H` → home, `W` → work, `C` → cell (alias for mobile), `M` → main, `F` → fax
`deviceType`⚠️	string	(Available May 9, 2024) Optional; one of: `C` → cell, `L` → landline, `U` → unknown, `F` → fax, `V` → VoIP
`ext`	string	Optional; no more than six numeric characters
`isPreferred`	bool	Optional; an indicator of whether the phone number is the person’s preferred phone number; defaults to false
`phoneOptInStatus`	string	Optional; one of: `I` → opt in, `U` → unknown, `O` → opt out. Default, if not supplied, is `U`
`isCellStatus`	object	Optional; indicates the level of confidence for whether the phone number is a cell phone. See GET /phones/isCellStatuses for more information. Specifying just a valid value for either the `statusId` property or the `statusName`, instead of both, would still work. If no value is provided, any existing explicitly applied `isCellStatus` for this number will remain unchanged.
`dialingPrefix`	string	Optional; 1 to 3 numeric characters that indicate the country associated with the phone number. If this and `countryCode` are both specified, they must refer to the same country.
`countryCode`	string	Optional; the ISO alpha-2 code for the country associated with the phone number. If this and `dialingPrefix` are both specified, they must refer to the same country.

Address

Property	Type	Description
`addressId`	long	Read-only; unique identifier of the address on this person
`addressLine1`	string	Optional; indicates first line of a street address when used in the POST /people/findOrCreate. In the GET method, indicates the result of concatenating all three address lines and standardizing the resulting street address.
`addressLine2`	string	Optional; second line of a street address
`addressLine3`	string	Optional; third line of a street address
`city`	string	Optional; city or town
`stateOrProvince`	string	Optional; two or three character State or Province code (e.g., MN, ON, NSW, etc.)
`zipOrPostalCode`	string	Optional; ZIP, ZIP+4, Postal Code, Post code, etc.
`countryCode`	string	Optional; a two character ISO country code that is supported by your VAN context
`type`	string	Optional; one of: `Mailing`, `Home`, `Voting`, `Work`, `Custom`; some types may not be available in certain contexts. Note that `Home` and `Voting` have identical meaning. If a mailing address has not been provided for a contact, then the home address for that contact will also be used as the contact’s mailing address.
`isPreferred`	bool	Read-only; indicates whether this address is the preferred address for the contact. The preferred address is automatically assigned when an address is created for a contact.
`isBest`	bool	Read-only; indicates whether this address is the best known address of the indicated type. The best known address is the most recently-updated address of a given address type.

Identifier

Used for known external identifiers (e.g., DWID, Voter File ID, etc.). External IDs in VAN are case-insensitive. Abcd1234 will always match ABCD1234.

Property	Type	Description
`type`	string	Required; a known external identifier that is available in the current context. Use `votervanid` for VoterFile VANID if making a MyCampaign call. Use `dwid` for Catalist DWIDs in either VoterFile or MyCampaign mode.
`externalId`	string	Required; case-insensitive

Custom Field Value

Providing an invalid customFieldId will result in a 400 Bad Request error response.

Property	Type	Description
`customFieldId`	int	Required; a known custom field identifier that is available in the current context.
`customFieldGroupId`	int	Required; a known custom field group identifier that identifies the Custom Field Group to which this Custom Field belongs, and that is available in the current context.
`assignedValue`	string	The value to be applied to the Custom Field. The value must be consistent with the type of the Custom Field

Match Responses

The various find endpoints return a common response object.

{
  "vanId": 1264324,
  "status": "UnmatchedStored"
}

vanId may be null if no match is found and a store is not requested.

The HTTP status code is set per status value.

Status	HTTP Code	Description
`Matched`	`302 Found`	A match was found (and updated, if relevant) and the `Location` header is set
`Stored`	`201 Created`	Not implemented
`Unmatched`	`404 Not Found`	No match was found
`UnmatchedStored`	`201 Created`	No match was found, but a new record was created (and the `Location` header is set)
`Processed`	`204 No Content`	Not implemented
`UnmatchedProcessed`	`204 No Content`	Not implemented

Person

Most GET endpoints return a full Person response object.

Property	Type	Description
`vanId`	int	Unique identifier of the My Campaign or My Voters record
`firstName`	string	A person’s first name
`middleName`	string	A person's middle name
`lastName`	string	A person's last name
`suffix`	string	Part of name following last name, e.g. "Jr."
`title`	string	An honorific
`sourceFileTitle`	string	Honorific provided in the source file (most often a voter file)
`sourceFileFirstName`	string	First name provided in the source file (most often a voter file)
`sourceFileMiddleName`	string	Middle Name provided in the source file (most often a voter file)
`sourceFileLastName`	string	Last Name provided in the source file (most often a voter file)
`sourceFileSuffix`	string	Suffix provided in the source file (most often a voter file)
`contactMode`	string	The type of contact; one of `Person` or `Organization`; applicable only in My Campaign databases where organizations as contacts is enabled
`organizationContactCommonName`	string	An organization's common name; applicable only in My Campaign databases where organizations as contacts is enabled
`organizationContactOfficialName`	string	An organization's official name; applicable only in My Campaign databases where organizations as contacts is enabled
`salutation`	string	Preferred greeting for correspondence; defaults to a person's `firstName`
`formalSalutation`	string	Preferred formal greeting for correspondence; defaults to `title` and `lastName` for people or "Friends" for organizations
`additionalSalutation`	string	Additional preferred greeting for correspondence; defaults to `organizationContactCommonName` for organizations
`pronouns`	object	A person's pronouns
`envelopeName`	string	Preferred name to use for mailings; defaults to the person's full name, including their middle initial, or `organizationContactCommonName` depending on the contact type
`formalEnvelopeName`	string	Preferred formal name to use for mailings; defaults to the person's full name, including their middle initial, `title`, and `suffix`, or `organizationContactOfficialName` depending on the contact type
`additionalEnvelopeName`	string	Additional preferred name to use for mailings
`contactMethodPreferenceCode`	string	A person's preferred method of contact; must be one of: `P` → phone, `E` → email, `M` → mail, `F` → fax, or `S` → SMS
`nickname`	string	A person's preferred informal name
`website`	string	A person's personal website
`professionalSuffix`	string	A person's professional suffix, e.g. "M.D."
`party`	string	A one-character string indicating party affiliation, e.g. “D”
`employer`	string	Name of the organization where the person works, e.g. "Kennedy High School"; may not be available in every context
`occupation`	string	Nature of the person’s work, e.g. "teacher"; may not be available in every context
`jobTitle`	string	Name of the position the person holds at an organization; maybe not be available in every context
`sex`	string	A one-character string indicating sex
`dateOfBirth`	datetime	A person’s ISO 8601 formatted date of birth
`selfReportedRaces`	array	A person’s reported race(s)
`selfReportedEthnicities`	array	A person’s reported ethnicity or ethnicities
`selfReportedGenders`	array	A person’s reported gender(s)
`selfReportedSexualOrientations`	array	A person’s reported sexual orientation(s)
`selfReportedLanguagePreference`	object	A person’s reported language preference
`emails`	array	An array of email objects associated with a contact
`phones`	array	An array of phone objects associated with a contact
`addresses`	array	An array of address objects associated with a contact; will contain only the best Home address and best Mailing address, if available
`recordedAddresses`	array	An array of address objects; will contain all known addresses associated with a contact
`identifiers`	array	An array of all known external identifiers associated with a contact
`codes`	array	An array of codes associated with a contact
`customFields`	array	An array of (custom fields)[ref:custom-fields] associated with a contact
`primaryCustomField`	object	The primary (custom field)[ref:custom-fields] associated with a contact
`contributionSummary`	object	A summary of a person's contribution activity
`suppressions`	array	An array of suppressions associated with a contact
`caseworkCases`	array	An array of casework cases associated with a contact
`caseworkIssues`	array	An array of casework issues associated with a contact
`caseworkStories`	array	An array of casework stories associated with a contact
`notes`	array	An array of notes associated with a contact
`scores`	array	An array of scores associated with a contact
`customProperties`	array	An array of custom properties associated with a contact
`electionRecords`	array	An array of election records associated with a contact
`membershipStatus`	object	A person's membership status
`organizationRoles`	array	An array of roles associated with an organization
`districts`	array	An array of districts associated with a contact
`disclosureFieldValues`	array	An array of disclosure field values associated with a contact
`surveyQuestionResponses`	array	An array of (survey question responses)[ref:survey-questions] associated with a contact. Reserved for future development - this endpoint does not currently return data for the survey question responses field.
`finderNumber`	string	The finder number associated with a contact
`biographyImageUrl`	string	The url for a contact's biography image
`primaryContact`	object	The primary contact at an organization
`pledgesSummaryDesignations`	array	A summary of a person's pledge activity

Suppression

Property	Type	Description
`suppressionCode`	string	Short code which identifies the suppression, e.g. "NC"
`suppressionName`	string	Full explanation of the suppression, e.g. "Do not call"

Disclosure Field Value

Disclosure Fields exist on a range of objects (e.g. People, Contributions) and are used for Disclosure Reports for FEC and state filing purposes.

Property	Type	Description
`disclosureFieldId`	int	Identifies the Disclosure Field. Together, the designation id and disclosure field id provide a unique identifier of a Disclosure Field.
`disclosureFieldValue`	string	The value of the Disclosure Field
`designationId`	int	The unique identifier of the Designation of the Disclosure Field