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": "[email protected]",
"type": "P",
"isPreferred": true,
"isSubscribed": null,
"subscriptionStatus": "N"
},
{
"email": "[email protected]",
"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 |
---|---|---|---|
| string | n/a | Optional; unique identifier of the My Campaign or My Voters record if known in advancewn in advance. |
| string | 75 | Optional; a person’s first name |
| string | 75 | Optional; a person’s middle name |
| string | 150 | Optional; a person’s last name |
| string | 50 | Optional; part of name following last name, e.g. "Jr." |
| string | 10 | Optional; an honorific |
| string | 100 | Optional; preferred greeting for correspondence |
| string | 350 | Optional; preferred name to use for mailings |
| object | n/a | Optional; a person's pronouns |
| string | 50 | Optional; a person's preferred informal name |
| string | 50 | Optional; a person's personal website |
| string | 1 | Optional; a one-character string indicating party affiliation, e.g. "D" |
| string | 1 | Optional; a person's preferred method of contact; must be one of: |
| string | 50 | Optional; name of the organization where the person works, e.g. "Kennedy High School"; may not be available in every context |
| string | 50 | Optional; nature of the person’s work, e.g. "teacher"; may not be available in every context |
| string | 150 | Optional; name of the position the person holds at an organization; maybe not be available in every context |
| string | 1 | Optional; a one-character string indicating sex; must be |
| datetime | n/a | Optional; a person’s date of birth; must be ISO 8601 formatted and in the 20th or 21st century |
| int | n/a | Optional; location where a person's voter registration application was collected |
| string | 2 | Optional; type of election registered for; must be one of |
| string | 4 | Optional; a numeric string indicating the election year a person registered to vote |
| array | n/a | Optional; the person’s race(s); |
| array | n/a | Optional; a person’s ethnicity or ethnicities; |
| array | n/a | Optional; a person’s gender(s); |
| array | n/a | Optional; indicates the person’s sexual orientation(s). The |
| object | n/a | Optional; a person’s language preference: |
| array | n/a | Optional; an array of email objects |
| array | n/a | Optional; an array of phone objects |
| array | n/a | Optional; an array of address objects |
| array | n/a | Optional; an array of identifier objects |
| array | n/a | Optional; an array of customFieldValue objects |
| string | 150 | Optional; an organization's common name; applicable only in My Campaign databases where organizations as contacts is enabled |
| string | 150 | Optional; an organization's official name; applicable only in My Campaign databases where organizations as contacts is enabled |
| string | n/a | Optional; the type of contact; must be |
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 |
---|---|---|
| string | Required; a valid email address |
| string | Optional; one of: |
| bool | Optional; an indicator of whether the email address is the person’s preferred address; defaults to false |
| bool | Deprecated if Targeted Email is available. Optional; indicates whether the email address may be used in a broadcast email. Default value is |
| string | Optional; indicates the email address subscription status for Targeted Email. One of |
Phone
Property | Type | Description |
---|---|---|
| int | Read-only; unique identifier of the phone. |
| 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. |
| string | Optional; one of: |
| string | Optional; no more than six numeric characters |
| bool | Optional; an indicator of whether the phone number is the person’s preferred phone number; defaults to false |
| string | Optional; one of: |
| 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 |
| string | Optional; 1 to 3 numeric characters that indicate the country associated with the phone number. If this and |
| string | Optional; the ISO alpha-2 code for the country associated with the phone number. If this and |
Address
Property | Type | Description |
---|---|---|
| int | Read-only; unique identifier of the address on this person |
| 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. |
| string | Optional; second line of a street address |
| string | Optional; third line of a street address |
| string | Optional; city or town |
| string | Optional; two or three character State or Province code (e.g., MN, ON, NSW, etc.) |
| string | Optional; ZIP, ZIP+4, Postal Code, Post code, etc. |
| string | Optional; a two character ISO country code that is supported by your VAN context |
| string | Optional; one of: |
isPreferred | 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 |
---|---|---|
| string | Required; a known external identifier that is available in the current context. Use |
| string | Required; case-insensitive |
Custom Field Value
Property | Type | Description |
---|---|---|
| int | Required; a known custom field identifier that is available in the current context. |
| 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. |
| 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 |
---|---|---|
|
| A match was found (and updated, if relevant) and the |
|
| Not implemented |
|
| No match was found |
|
| No match was found, but a new record was created (and the |
|
| Not implemented |
|
| Not implemented |
Person
Most GET
endpoints return a full Person response object.
Property | Type | Description |
---|---|---|
| int | Unique identifier of the My Campaign or My Voters record |
| string | A person’s first name |
| string | A person's middle name |
| string | A person's last name |
| string | Part of name following last name, e.g. "Jr." |
| string | An honorific |
| string | Honorific provided in the source file (most often a voter file) |
| string | First name provided in the source file (most often a voter file) |
| string | Middle Name provided in the source file (most often a voter file) |
| string | Last Name provided in the source file (most often a voter file) |
| string | Suffix provided in the source file (most often a voter file) |
| string | The type of contact; one of |
| string | An organization's common name; applicable only in My Campaign databases where organizations as contacts is enabled |
| string | An organization's official name; applicable only in My Campaign databases where organizations as contacts is enabled |
| string | Preferred greeting for correspondence; defaults to a person's |
| string | Preferred formal greeting for correspondence; defaults to |
| string | Additional preferred greeting for correspondence; defaults to |
| object | A person's pronouns |
| string | Preferred name to use for mailings; defaults to the person's full name, including their middle initial, or |
| string | Preferred formal name to use for mailings; defaults to the person's full name, including their middle initial, |
| string | Additional preferred name to use for mailings |
| string | A person's preferred method of contact; must be one of: |
| string | A person's preferred informal name |
| string | A person's personal website |
| string | A person's professional suffix, e.g. "M.D." |
| string | A one-character string indicating party affiliation, e.g. “D” |
| string | Name of the organization where the person works, e.g. "Kennedy High School"; may not be available in every context |
| string | Nature of the person’s work, e.g. "teacher"; may not be available in every context |
| string | Name of the position the person holds at an organization; maybe not be available in every context |
| string | A one-character string indicating sex |
| datetime | A person’s ISO 8601 formatted date of birth |
| array | A person’s reported race(s) |
| array | A person’s reported ethnicity or ethnicities |
| array | A person’s reported gender(s) |
| array | A person’s reported sexual orientation(s) |
| object | A person’s reported language preference |
| array | An array of email objects associated with a contact |
| array | An array of phone objects associated with a contact |
| array | An array of address objects associated with a contact; will contain only the best Home address and best Mailing address, if available |
| array | An array of address objects; will contain all known addresses associated with a contact |
| array | An array of all known external identifiers associated with a contact |
| array | An array of codes associated with a contact |
| array | An array of (custom fields)[ref:custom-fields] associated with a contact |
| object | The primary (custom field)[ref:custom-fields] associated with a contact |
| object | A summary of a person's contribution activity |
| array | An array of suppressions associated with a contact |
| array | An array of casework cases associated with a contact |
| array | An array of casework issues associated with a contact |
| array | An array of casework stories associated with a contact |
| array | An array of notes associated with a contact |
| array | An array of scores associated with a contact |
| array | An array of custom properties associated with a contact |
| array | An array of election records associated with a contact |
| object | A person's membership status |
| array | An array of roles associated with an organization |
| array | An array of districts associated with a contact |
| array | An array of disclosure field values associated with a contact |
| array | An array of (survey question responses)[ref:survey-questions] associated with a contact |
| string | The finder number associated with a contact |
| string | The url for a contact's biography image |
| object | The primary contact at an organization |
| array | A summary of a person's pledge activity |
Suppression
Property | Type | Description |
---|---|---|
| string | Short code which identifies the suppression, e.g. "NC" |
| 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 |
---|---|---|
| int | Identifies the Disclosure Field. Together, the designation id and disclosure field id provide a unique identifier of a Disclosure Field. |
| string | The value of the Disclosure Field |
| int | The unique identifier of the Designation of the Disclosure Field |