Use this endpoint to create a CSV (comma-separated values) file with details of contacts from a saved list.


Successful canvass file requests will provide the following properties in the response, in addition to those included in the request:

  • canvassFileRequestId: The id of the request, which can be used to retrieve the status of the request at a later date.
  • canavssFileRequestGuid: An alternative identifier for the request, which is typically used in the URL for the generated canvass file.
  • savedListId: Integer ID of the saved list containing people to be included in the canvass file. The API key requesting the canvass file must have access to the saved list.
  • webhookUrl: Valid HTTPS URL to receive a message POST request when canvass file generation is complete. The message will be a JSON object identical to the body of the GET /canvassFileRequests/{canvassFileId} response for this canvass file request.
  • downloadUrl: The URL where the generated CSV file may be downloaded, if the status is Completed.
  • status: The status of the request, which may be one of the following:
    • Requested: request was received but has not yet been processed
    • Pending: processing has begun but has not yet completed
    • Completed: processing has completed successfully; the file is available at the specified downloadUrl
    • Error: processing has completed unsuccessfully; a reference code for the error is indicated in errorCode
  • type: Integer ID of the type of canvass file to generate. The API key requesting the canvass file must be authorized to request the specified canvass file type.
  • dateExpired: A future date after which the URL is no longer guaranteed to exist.
  • errorCode: A reference code for any error which may have occurred during the processing, if the status is Error.

Columns in the canvass file will depend on the type requested.

The CSV file may contain the following columns with the relevant information about the contacts affected during the specified time period:

  • VanID: The contact's ID in VAN. Should be stored with the record if possible.
  • FirstName: The contact's first name.
  • LastName: The contact's last name.
  • StreetAddress: The contact's street address (if available). For example, "48 Grove Street".
  • City: The contact's city (if available). For example, "Somerville".
  • State: The contact's abbreviated state (if available). For example, "MA".
  • ZipCode: The contact's zip code (if available). For example, "02144".
  • OptInPhone: The contact's phone number.
  • OptInStatus: The opt-in/opt-out status of the contact's phone. Can be one of the following values:
    • Opted-In: The contact has opted in to be contacted via SMS.
    • Opted-Out: The contacted has opted out to be contacted via SMS.
    • Unknown: The contact's opt-in status is unknown. Depending on how the integration treats neutral states, we suggest treating this similarly to "Opted-Out." Regardless how it is stored in the CRM, phone numbers of this status should not be sent SMS messages.
Click Try It! to start a request and see the response here!