Looking to send your Interactions data to VAN Canvass Response? Follow this guide to get started.

Tech Partners - learn more about Interactions API requests with VAN as a destination.

Explore our Interactions API reference.

Overview

Sending your Interactions API data to VAN's Canvass Responses endpoint requires a few quick setup steps outlined on this page.

🎥
We've prepared a video walkthrough of this process to compliment this guide. It's available on Loom here.

If you are a Tech Partner, please visit the Tech Partner integration section of this doc!

Storing your VAN API Key as an External Key in your Workspace

Log in to your Organizational Workspace in the Console.
Click the "View & Manage External Keys" button on the dashboard
Click the "Add External Key" button in the top right corner of the page
Give your VAN API key a name, paste in the key & click "Next"
Our system fetches data about the key you provided. Carefully review the details and confirm they are accurate and expected.
Click "Save Key" if the data is correct

Configuring a DDx API Key for VAN as a Destination

Navigate to your Organizational Workspace's dashboard by clicking the home icon in the top left of your screen
Click the "Create & Manage Keys" button under Interactions API
Click "+ Create DDx API Key" button
Configure your DDx API Key by giving it a name, selecting your data source, and selecting the "VAN API Canvass Responses" as the data destination.

Select the VAN API Key you want used to send data to VAN Canvass Responses.

Your VAN API Key will appear in the "VAN Key" dropdown twice if it supports both VAN database modes. Be sure to select the database mode where you want data to land.

Select "Next" and you're done creating your DDx API Key!

Viewing & Sharing Your DDx API Key

You will need to share your DDx API Key with your data source. These keys should be treated as a secret and shared securely with your data source.
To view a DDx API Key, select View DDx API Key from the action menu to the right of the table
Here you can view & copy your API Key. Store this key securely as the key is only viewable once.
When you're done, click close and securely store your key.

Troubleshooting

If you see an error adding your VAN API Key, click "Cancel" and try entering your key again. Ensure the VAN Key information is entered correctly, and if the error persists, check if the key is expired in VAN's system.

For any other issues or support getting set up, please contact our Support team at [email protected].

Tech Partners

Overview

This section covers information about Interactions API requests with VAN's Canvass Responses endpoint as a destination for Interactions API data.

Interactions App

Check out our Set Up for Sources section if you do not already have an Interactions API App required for sending data to VAN endpoints.

Validating VAN API Key configuration

The /v1/auth/me endpoint enables two things: confirmation that you're using your key correctly and the ability to confirm the workspace, source and destination details (particularly selectedDbModeAccess).

Additional API Request Validation

Interactions API requests using an API key configured with VAN Canvass Responses as a destination are subjected to additional validation. This includes:

The person array must include one object with type of "VAN".
All survey response outcomesDetailed objects (indicated by the "survey_response" type) must include questionId and responseId. These must be valid VAN survey question and response IDs.
All activist code outcomesDetailed objects (indicated by the "activist_code" type) must include activistCodeId. This value must be a valid VAN Activist Code ID.
The vanFields object must be provided and include integer values for contactTypeId (required) and resultCodeId (conditionally required; see below).
1. resultCodeId is required if no activist code or survey response objects are provided in outcomesDetailed.
2. If one or more activist code or survey response objects are provided, resultCodeId must be null or 14 ("Canvassed").

An example of a valid request can be found on the API Examples page (Scenario 6).

How is data mapped to VAN Canvass Responses requests?

The table below describes how data on the Interactions API request is mapped to a VAN Canvass Response request.

Interactions API request property	VAN Canvass Response request property	Notes
Static value of "11" ("API")	`inputTypeId`
`vanFields.contactTypeId`	`contactTypeId`	New field
`vanFields.resultCodeId`	`resultCodeId`	New field
`attemptDateTime`	`dateCanvassed`
`person.id`	`vanId` in request URL	Must have `type` of "VAN" in Interactions API request
`outcomesDetailed.value. activistCodeId`	`responses.activistCodeId` (in a Script Response object with `type` of "ActivistCode")	Must have `type` of "activist_code" in Interactions API request
`outcomesDetailed.value. questionId`	`responses.surveyQuestionId` (in a Script Response object with `type` of "SurveyResponse")	Must have `type` of "survey_response" in Interactions API request
`outcomesDetailed.value. responseId`	`responses.surveyResponseId` (in a Script Response object with `type` of "SurveyResponse")	Must have `type` of "survey_response" in Interactions API request
`outcomesDetailed.value. consentStatus`	`canvassContext.phone. smsOptInStatus`	Must have `type` of "communication_consent" in Interactions API request Only populated if `interaction.method` is "text" or "text_broadcast" "opted_in" is mapped to "I"; "opted_out" is mapped to "O"
`channel.value`	Mapped to `canvassContext.phone. dialingPrefix` and `canvassContext.phone. phoneNumber`	Must have `type` of "phone_number" in Interactions API request

Fetching VAN API transactional logs

Status and logs regarding integration with the VAN API can be fetched two ways:

By date, using the endpoint described here.
By interactionId, which can be found in successful POST /interactions responses, using the endpoint described here.

📣
For questions about sending data to VAN's Canvass Responses endpoint please reach out to us at [email protected]!