Common Models

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

PropertyTypeMax lengthDescription
vanIdstringn/aOptional; unique identifier of the My Campaign or My Voters record if known in advance
firstNamestring75Optional; a person’s first name
middleNamestring75Optional; a person’s middle name
lastNamestring150Optional; a person’s last name
suffixstring50Optional; part of name following last name, e.g. "Jr."
titlestring10Optional; an honorific
salutationstring100Optional; preferred greeting for correspondence
envelopeNamestring350Optional; preferred name to use for mailings
pronounsobjectn/aOptional; a person's pronouns
nicknamestring50Optional; a person's preferred informal name
websitestring50Optional; a person's personal website
partystring1Optional; a one-character string indicating party affiliation, e.g. "D"
contactMethodPreferenceCodestring1Optional; a person's preferred method of contact; must be one of: P → phone, E → email, M → mail, F → fax, or S → SMS
employerstring50Optional; name of the organization where the person works, e.g. "Kennedy High School"; may not be available in every context
occupationstring50Optional; nature of the person’s work, e.g. "teacher"; may not be available in every context
jobTitlestring150Optional; name of the position the person holds at an organization; maybe not be available in every context
sexstring1Optional; a one-character string indicating sex; must be M or F
dateOfBirthdatetimen/aOptional; a person’s date of birth; must be ISO 8601 formatted and in the 20th or 21st century
yearOfBirthint4Optional; the year a person was born
collectedLocationIdintn/aOptional; location where a person's voter registration application was collected
electionTypestring2Optional; 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
cyclestring4Optional; a numeric string indicating the election year a person registered to vote
selfReportedRacesarrayn/aOptional; the person’s race(s); reportedRaceId must match one of the reported races available in the current context
selfReportedEthnicitiesarrayn/aOptional; a person’s ethnicity or ethnicities; reportedEthnicityId must match one of the reported ethnicities available in the current context
selfReportedGendersarrayn/aOptional; a person’s gender(s); reportedGenderId must match one of the reported genders available in the current context
selfReportedSexualOrientationsarrayn/aOptional; a person’s sexual orientation(s); reportedSexualOrientationId must match one of the reported sexual orientation available in the current context
selfReportedLanguagePreferenceobjectn/aOptional; a person’s language preference: reportedLanguagePreferenceId must match one of the reported language preferences available in the current context
emailsarrayn/aOptional; an array of email objects
phonesarrayn/aOptional; an array of phone objects
addressesarrayn/aOptional; an array of address objects
identifiersarrayn/aOptional; an array of identifier objects
customFieldValuesarrayn/aOptional; an array of customFieldValue objects
organizationContactCommonNamestring150Optional; an organization's common name; applicable only in My Campaign databases where organizations as contacts is enabled
organizationContactOfficialNamestring150Optional; an organization's official name; applicable only in My Campaign databases where organizations as contacts is enabled
contactModestringn/aOptional; 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

PropertyTypeDescription
emailstringRequired; a valid email address
typestringOptional; one of: P → personal, W → work, O → other. Default, if not supplied, is P.
isPreferredboolOptional; an indicator of whether the email address is the person’s preferred address; defaults to false
isSubscribedboolDeprecated 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.
subscriptionStatusstringOptional; 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

PropertyTypeDescription
phoneIdintRead-only; unique identifier of the phone.
phoneNumberstringRequired; 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.
phoneTypestringOptional; one of: H → home, W → work, C → cell (alias for mobile), M → main, F → fax
extstringOptional; no more than six numeric characters
isPreferredboolOptional; an indicator of whether the phone number is the person’s preferred phone number; defaults to false
phoneOptInStatusstringOptional; one of: I → opt in, U → unknown, O → opt out. Default, if not supplied, is U
isCellStatusobjectOptional; 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.
dialingPrefixstringOptional; 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.
countryCodestringOptional; 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

PropertyTypeDescription
addressIdlongRead-only; unique identifier of the address on this person
addressLine1stringOptional; 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.
addressLine2stringOptional; second line of a street address
addressLine3stringOptional; third line of a street address
citystringOptional; city or town
stateOrProvincestringOptional; two or three character State or Province code (e.g., MN, ON, NSW, etc.)
zipOrPostalCodestringOptional; ZIP, ZIP+4, Postal Code, Post code, etc.
countryCodestringOptional; a two character ISO country code that is supported by your VAN context
typestringOptional; 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.
isPreferredboolRead-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. This property is deprecated and planned for removal in 2023.

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.

PropertyTypeDescription
typestringRequired; 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.
externalIdstringRequired; case-insensitive

Custom Field Value

PropertyTypeDescription
customFieldIdintRequired; a known custom field identifier that is available in the current context.
customFieldGroupIdintRequired; 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.
assignedValuestringThe 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.

StatusHTTP CodeDescription
Matched302 FoundA match was found (and updated, if relevant) and the Location header is set
Stored201 CreatedNot implemented
Unmatched404 Not FoundNo match was found
UnmatchedStored201 CreatedNo match was found, but a new record was created (and the Location header is set)
Processed204 No ContentNot implemented
UnmatchedProcessed204 No ContentNot implemented

Person

Most GET endpoints return a full Person response object.

PropertyTypeDescription
vanIdintUnique identifier of the My Campaign or My Voters record
firstNamestringA person’s first name
middleNamestringA person's middle name
lastNamestringA person's last name
suffixstringPart of name following last name, e.g. "Jr."
titlestringAn honorific
sourceFileTitlestringHonorific provided in the source file (most often a voter file)
sourceFileFirstNamestringFirst name provided in the source file (most often a voter file)
sourceFileMiddleNamestringMiddle Name provided in the source file (most often a voter file)
sourceFileLastNamestringLast Name provided in the source file (most often a voter file)
sourceFileSuffixstringSuffix provided in the source file (most often a voter file)
contactModestringThe type of contact; one of Person or Organization; applicable only in My Campaign databases where organizations as contacts is enabled
organizationContactCommonNamestringAn organization's common name; applicable only in My Campaign databases where organizations as contacts is enabled
organizationContactOfficialNamestringAn organization's official name; applicable only in My Campaign databases where organizations as contacts is enabled
salutationstringPreferred greeting for correspondence; defaults to a person's firstName
formalSalutationstringPreferred formal greeting for correspondence; defaults to title and lastName for people or "Friends" for organizations
additionalSalutationstringAdditional preferred greeting for correspondence; defaults to organizationContactCommonName for organizations
pronounsobjectA person's pronouns
envelopeNamestringPreferred name to use for mailings; defaults to the person's full name, including their middle initial, or organizationContactCommonName depending on the contact type
formalEnvelopeNamestringPreferred 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
additionalEnvelopeNamestringAdditional preferred name to use for mailings
contactMethodPreferenceCodestringA person's preferred method of contact; must be one of: P → phone, E → email, M → mail, F → fax, or S → SMS
nicknamestringA person's preferred informal name
websitestringA person's personal website
professionalSuffixstringA person's professional suffix, e.g. "M.D."
partystringA one-character string indicating party affiliation, e.g. “D”
employerstringName of the organization where the person works, e.g. "Kennedy High School"; may not be available in every context
occupationstringNature of the person’s work, e.g. "teacher"; may not be available in every context
jobTitlestringName of the position the person holds at an organization; maybe not be available in every context
sexstringA one-character string indicating sex
dateOfBirthdatetimeA person’s ISO 8601 formatted date of birth
selfReportedRacesarrayA person’s reported race(s)
selfReportedEthnicitiesarrayA person’s reported ethnicity or ethnicities
selfReportedGendersarrayA person’s reported gender(s)
selfReportedSexualOrientations*arrayA person’s reported sexual orientation(s)
selfReportedLanguagePreferenceobjectA person’s reported language preference
emailsarrayAn array of email objects associated with a contact
phonesarrayAn array of phone objects associated with a contact
addressesarrayAn array of address objects associated with a contact; will contain only the best Home address and best Mailing address, if available
recordedAddressesarrayAn array of address objects; will contain all known addresses associated with a contact
identifiersarrayAn array of all known external identifiers associated with a contact
codesarrayAn array of codes associated with a contact
customFieldsarrayAn array of (custom fields)[ref:custom-fields] associated with a contact
primaryCustomFieldobjectThe primary (custom field)[ref:custom-fields] associated with a contact
contributionSummaryobjectA summary of a person's contribution activity
suppressionsarrayAn array of suppressions associated with a contact
caseworkCasesarrayAn array of casework cases associated with a contact
caseworkIssuesarrayAn array of casework issues associated with a contact
caseworkStoriesarrayAn array of casework stories associated with a contact
notesarrayAn array of notes associated with a contact
scoresarrayAn array of scores associated with a contact
customPropertiesarrayAn array of custom properties associated with a contact
electionRecordsarrayAn array of election records associated with a contact
membershipStatusobjectA person's membership status
organizationRolesarrayAn array of roles associated with an organization
districtsarrayAn array of districts associated with a contact
disclosureFieldValuesarrayAn array of disclosure field values associated with a contact
surveyQuestionResponsesarrayAn 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.
finderNumberstringThe finder number associated with a contact
biographyImageUrlstringThe url for a contact's biography image
primaryContactobjectThe primary contact at an organization
pledgesSummaryDesignationsarrayA summary of a person's pledge activity

Suppression

PropertyTypeDescription
suppressionCodestringShort code which identifies the suppression, e.g. "NC"
suppressionNamestringFull explanation of the suppression, e.g. "Do not call"

Disclosure Field Value

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

PropertyTypeDescription
disclosureFieldIdintIdentifies the Disclosure Field. Together, the designation id and disclosure field id provide a unique identifier of a Disclosure Field.
disclosureFieldValuestringThe value of the Disclosure Field
designationIdintThe unique identifier of the (Designation)[ref:designations] of the Disclosure Field