See this article for general API requirements.
Apiary Links
You will first need to validate the contact's address. That will return a perfected address with a checksum value.
You can then update the contact in VoterVoice. This requires that you use the perfected address / checksum and that you include a contact ID from your in-house database.
Detailed Instructions
The following step-by-step instructions use Postman for examples, but any software you use to perform the API calls should follow the same general process.
Master List of Standard Field Names for API
Contact ID = "contactId"
Prefix = "honorific"
First Name = "givenNames"
Last Name = "surname"
Suffix = “suffix”
Email Address = "emailAddress"
Phone Number = "phoneNumber"
Fax Number = "faxNumber"
Home Address = these require address validation and are submitted as a "homeAddress" set with the following fields: "checksum" "city" "coordinates" "latitude" "longitude" "country" "county" "state" "streetAddress" "zipCode" "zipCodeExtension"
Company = “businessCompanyName"
Title = "businessPositionName"
Business Address = these require address validation and are submitted as a "businessAddress" set with the following fields: "checksum" "city" "coordinates" "latitude" "longitude" "country" "county" "state" "streetAddress" "zipCode" "zipCodeExtension"
Any Custom Field = ID found in URL of admin site when viewing that custom field in People > Manage Custom Fields
Headers
Every API call requires the same two headers:
- your encrypted API key as the authorization
- application/json as the content type
Validating an Address in Postman
In order to update any contact data that includes a physical address, you will need to validate the addresses. Validation is done via the USPS and is required for both legislative contact and accurate matching.
Example:
- Create a new GET with the URL “https://www.votervoice.net/api/addresses”
-
Under the Params, enter the following values:
- address1 = home street address
- city = home city
- state = home state
-
zipcode = home ZIP without extension
- If you only have a ZIP code, include the parameter “&simpleLookup=true” to return a best-effort match.
- It should look like the screenshot below:
- If you hit the blue “Send” button toward the top, you should get a response like this:
{
"addresses": [
{
"checksum": "-534839494",
"city": "Baton Rouge",
"coordinates": {
"latitude": 30.423828,
"longitude": -91.129772
},
"country": "US",
"county": "East Baton Rouge",
"state": "LA",
"streetAddress": "6100 Corporate Blvd",
"zipCode": "70808",
"zipCodeExtension": "2717"
}
],
"message": null,
"suggestedZipCode": null
}
- When including the address information in the post for a new contact record, you will need to include the information returned here. You can include the coordinates if you want, but it is not necessary. Your address can simply look like this:
"businessAddress": {
"checksum": "-534839494",
"city": "Baton Rouge",
"country": "US",
"county": "East Baton Rouge",
"state": "LA",
"streetAddress": "6100 Corporate Blvd",
"zipCode": "70808",
"zipCodeExtension": "2717"
}
Updating a Contact
-
Click the plus icon to make a new "PUT.”
- In that URL bar, enter “https://www.votervoice.net/api/contacts?association=YourAssociationIDNAME&contactId=TheContactsID”
- The first parameter should prepopulate with association and the name of your system in VoterVoice. The second should populate as contactId and the value you entered
- Switch to the Body tab and click the “raw” option.
- Enter contact details in exactly the format below. For the address, use what you received from the address validation call.
{
"membership": {
"contactId": "FN24601"
},
"honorific": "Mr.",
"givenNames": "Jean",
"surname": "Valjean",
"emailAddress": "jean.valjean@fiscalnote.com",
"phoneNumber": "5551234567",
"homeAddress": {
"checksum": "2043293862",
"city": "Washington",
"country": "US",
"county": "District of Columbia",
"state": "DC",
"streetAddress": "1600 Pennsylvania Ave NW",
"zipCode": "20500",
"zipCodeExtension": "0005"
},
"businessCompanyName": "Madeleine Manufacturing",
"businessPositionName": "Mayor",
"businessAddress": {
"checksum": "-534839494",
"city": "Baton Rouge",
"country": "US",
"county": "East Baton Rouge",
"state": "LA",
"streetAddress": "6100 Corporate Blvd",
"zipCode": "70808",
"zipCodeExtension": "2717"
}
}
- When you hit send, the response (in green) should read “204: no content.”
Adding Custom Fields
- Custom fields can be included in the update of a contact record and can store any information you want to associate with the contact.
-
They are NOT identified by their name in the system, but rather the custom field ID found in the URL when viewing the custom field in the admin site. In this example, the custom field ID is shown in red.
- https://www.votervoice.net/AdminSite/XYZ/CustomFields#/16799
-
Formats:
- Short / Long Text: { "id": "XXXXX", "value": "any text here" },
- Yes/No: { "id": "XXXXX", "value": true or false },
- Multiple Choice with Single Answer: { "id": "XXXXX", "value": "expected text of a single option" },
- Multiple Choice with Multiple Answers: { "id": "XXXXX", "value": [ "expected text of an option", "expected text of another option"] },
- Number / Currency / Integer: { "id": "XXXXX", "value": "1234" },
- Date: { "id": "XXXXX", "value": "MM/DD/YY" },
- The beautified JSON will look like this:
"customFieldValues": [
{
"id": "16832",
"value": "biking"
},
{
"id": "16833",
"value": true
},
{
"id": "16836",
"value": "B"
},
{
"id": "16835",
"value": [
"B",
"D"
]
},
{
"id": "16834",
"value": "39"
},
{
"id": "16837",
"value": "05/17/88"
}
]
If you have questions concerning the API calls, please email your specific questions, including the curl and any errors to vvsupport@fiscalnote.com for a Support agent to review.
Comments
Article is closed for comments.