Interactions API: Support for additional person identifiers

Interactions API now supports additional person identifiers for non-matched supporters

When a person's ID is not known in an interaction, additional person identifier fields such as phone, email, or address can now be sent as part of a contactInfo object to allow for tracking interactions with that person and enable possible future matches in the voter file. At least one of these identifiers is required if an id for a person is not present. First, middle, and last names as well as social handles can be included in this object for additional context.

While the contactInfo object itself is optional, at least one of email, phone, or address must be provided if contactInfo is included and the person object is not present.

contactInfo Details

Field Reference

Field	Type	Required	Description
`email`	array of strings	Conditional*	One or more email addresses for the contact
`phone`	array of strings	Conditional*	One or more phone numbers associated with the contact. * Phone numbers should be in E.164 format (starting with `+` and country code)
`address`	array of address objects	Conditional*	One or more physical addresses for the contact
`firstName`	string	Optional	Contact's first name
`middleName`	string	Optional	Contact's middle name
`lastName`	string	Optional	Contact's last name
`socialHandle`	array of strings	Optional	One or more social media handles associated with the contact

*At least one of email, phone, or address must be provided if person object is not included in the Interactions API payload.

Address Object Fields

Field	Type	Required	Description
`addressLine1`	string	Optional	Primary street address line
`addressLine2`	string	Optional	Secondary address line (e.g. suite, unit, floor)
`city`	string	Optional	City name
`state`	string	Optional	State or region
`postalCode`	string	Optional	Postal or ZIP code

Example

Here's an example JSON of a Person Interaction with contactInfo filled out:

{
  "contactInfo": {
    "email": ["[email protected]", "[email protected]"],
    "phone": ["+14155552671", "+14155559876"],
    "address": [
      {
        "addressLine1": "123 Main Street",
        "addressLine2": "Apt 4B",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94102",
        "country": "US"
      }
    ],
    "firstName": "John",
    "middleName": "Paul",
    "lastName": "Doe",
    "socialHandle": ["@jpdoe", "@johndoe"]
  },
  "stateCode": "CA",
  "attemptDateTime": "2026-02-19T15:30:00Z",
  "method": "email",
  "committee": [
    {
      "id": "12345",
      "type": "campaign"
    }
  ],
  "canvasser": [
    {
      "id": "67890",
      "type": "volunteer"
    }
  ],
  "vendorSource": "EmailVendor",
  "outcome": "successful_contact",
  "outcomesDetailed": [
    {
      "type": "survey_response",
      "id": "101",
      "responseId": "202"
    }
  ],
  "channel": {
    "type": "email",
    "value": "[email protected]"
  },
  "threadId": "thread-abc-123",
  "jsonMetadata": "{\"campaign_name\": \"Spring 2026\", \"message_subject\": \"Town Hall Invitation\"}"
}

Validation Rules

The contactInfo object is optional. If omitted, no validation is applied.
If person object is null or not present, contactInfo must be included and at least one of email, phone, or address must be present.
All string fields must be of type string. Arrays must contain only string values.
All fields not listed as conditional are optional and may be omitted.

Important Note for Data Going to VAN:

If VAN is a destination for your Interactions API data, the contactInfo object alone is not valid, you must include a VAN person ID.