/fileLoadingJobs

Initiates a file-loading job by specifying the URL for a zipped CSV file, containing data to be loaded, and the action(s) to be taken on it.

Request - continued

Action

Each Job Action Type has different supported and required for the Action property. See the individual Action Type docs for more info.

Currently supported actions include:

Notification

The object which is sent by POST to a webhook registered when the job is completed, if applicable.

Property

Type

Description

description

message

The job description specified when creating the job.

message

message

Detailed description of a job’s success (or failure)

Score Load Action

This is the Score Action Type.

Property

Type

Description

actionType

string

Required; This must be set to Score for Score Load jobs

personIdColumn

string

Required; The source file column name containing person identifiers.

personIdType

string

Required; A type of person identifier that is already available within the target context.; one of:
VANID → Always available, DWID → Only available in select VAN instances,
StateFileID → Available in AVEV data uploads

scoreColumn

string

Required; The source file column name containing score values, according to the score type.

Range Score updates must specify numeric values, within the range determined by minValue and maxValue on the Score configuration.

Value Score updates must specify the shortName property of the Score value. Valid values are available in the Score configuration (see "OK - Value Score").

scoreId

int

Required; The unique identifier of a score available within the target context.

approvalCriteria

object

Optional; A Score Approval Criteria object for automatically approving the score. Only available to API keys with permission to automatically approve scores. Only Range scores may be automatically approved.

Score Approval Criteria

A set of criteria which may be used to auto-approve scores. Only Range scores may be automatically approved.

Property

Type

Description

average

float

The average of the values in the score column. Must be a number between the maximum and minimum possible acceptable values of the score.

tolerance

float

The tolerance for approval. The API will compute the actual average of score values in the file; if the actual average is in the range [average - tolerance, average + tolerance], then the score will be automatically approved. Note that tolerance must be less than 10% of the difference between the maximum and minimum possible acceptable values of the score.

AV/EV Data File

This is the AVEVDataFile Action Type. File uploads for Absentee Vote and Early Vote data have a specific set of expected columns. All of the Required columns must be present but their values can be blank. The columns must be named exactly as specified, including casing, and in the order specified. Exactly one of the VanID or StateFileID columns must be present.

Property

Type

Description

VanID

string

Required; The VoterFile VANID of the VoterFile record. All AVEV data files require either a VanID or a StateFileID, but not both.

StateFileID

int

Required; The unique identifier for the record on the state file. All AVEV data files require either a VanID or a StateFileID, but not both.

RequestReceived

date

Required; The date the absentee ballot request was received.

BallotMailed

date

Required; The date the absentee ballot was mailed.

BallotReceived

date

Required; The date the completed ballot was received.

EarlyVoted

date

Required; The date that the person early voted.

BallotParty

string

Required; A one- or two-character code corresponding to the party the ballot belongs to.

BallotCancelled

date

Required; The date the absentee ballot was cancelled.

ApplicationMailed

date

Required; The date the absentee application was mailed.

GOTVVoted

date

Required; The date the person voted on election day.

DateApplicationReceived

date

Required; The date the absentee application was received.

BallotReturnStatus

int

Optional; ID for the ballot return status

BallotType

int

Optional; ID for the ballot type

BallotRequestType

int

Optional; ID for the ballot request type

BallotAddress1

string

Optional; First line of a Street Address (up to 40 characters)

BallotAddress2

string

Optional; Second line of a Street Address (up to 40 characters)

BallotAddress3

string

Optional; Third line of a Street Address (up to 40 characters)

BallotCity

string

Optional; City or Town (up to 25 characters)

BallotState

string

Optional; Two-character state code (e.g. MN, FL, etc)

BallotZip9

string

Optional; ZIP+4 for this address (up to 10 characters)

BallotCountry

string

Optional; A two-character ISO country code that is supported by your VAN context (e.g., US)

BallotReissued

date

Optional; The date the absentee ballot was reissued.

BallotRejectionReason

int

Optional; ID for the ballot rejection reason

BallotApplicationRequested

date

Optional; The date the absentee ballot was requested.

BallotRejected

date

Optional; The date the absentee ballot was rejected.

Example AVEV Data File Load

{
  "description": "Load AV/EV Data",
  "listeners": [{"type": "email", "value": "your email" }],
  "file":
  {
    "columnDelimiter": "Csv",
    "fileName": "avev-file.csv",
    "sourceUrl": "https://example.org/avev-file.zip",
    "hasHeader": false,
    "columns": [
      { "name": "VANID" },
      { "name": "RequestReceived" },
      { "name": "BallotMailed" },
      { "name": "BallotReceived" },
      { "name": "EarlyVoted" },
      { "name": "BallotParty" },
      { "name": "BallotCancelled" },
      { "name": "ApplicationMailed" },
      { "name": "GOTVVoted" },
      { "name": "DateApplicationReceived" },
      { "name": "BallotReturnStatus" },
      { "name": "BallotType"},
      { "name": "BallotRequestType"},
      { "name": "BallotAddress1"},
      { "name": "BallotAddress2"},
      { "name": "BallotAddress3"},
      { "name": "BallotCity"},
      { "name": "BallotState"},
      { "name": "BallotZip9"},
      { "name": "BallotCountry"},
      { "name": "BallotReissued"},
      { "name": "BallotRejectionReason"},
      { "name": "BallotApplicationRequested"},
      { "name": "BallotRejected"}
    ]
  },
  "actions":
  [
    {
      "actionType": "AVEVDataFile"
    }
  ]
}

Saved List Load

This is the LoadSavedListFile Action Type. This method creates a new Saved List and loads it with the specified data. It may optionally overwrite an existing Saved List to which the user has access.

Property

Type

Description

actionType

string

Required; This must be LoadSavedListFile.

listName

string

Required; The user-facing name of the Saved List. Must be unique within the target folder. Must be fewer than 50 characters.

listDescription

string

Optional; The user-facing description of the Saved List. Must be fewer than 250 characters.

personIdType

string

Required; This must be VANID.

personIdColumn

string

Required; This must be VANID.

folderId

int

Required; The folder to store the Saved List in. The campaign or organization must have shared this folder to the API User and marked it as an API-writable folder.

overwriteExistingListId

int

Optional; If specified, overwrites the specified Saved List rather than creating a new one, replacing Name and Description. The list must have been created by the API User to overwrite it.

Callback Data

Successful list loads will send a standard webhook to the configured HTTP listener, if any. List-specific data will be provided in the savedList property.

Property

Type

Description

savedListId

int

The ID of the Saved List that was created or overwritten.

originalRowCount

string

The count of rows that were in the source file, before validation, duplicate removal, and access checks.

matchedRowsCount

string

The count of rows that were loaded into the Saved List, after validation, duplicate removal, and access checks.

unmatchedRowsCount

string

The count of rows that were not loaded into the Saved List, due to failing validation, duplicate removal, or access checks.

Example:

{
  "savedList": {
    "savedListId": 2345,
    "originalRowCount": 500,
    "matchedRowsCount": 473,
    "unmatchedRowsCount": 27
  },
  "message": "Saved List File loaded",
  "description": "Saved List Load",
  "status": "Successful"
}

Example

In this example, score 112233 will be loaded from the second column of haberdasher.csv, and the resulting Score Update must be approved separately. However, score 112234 will be loaded from the third column; the API will calculate the average of this column, and if the observed average is between 73.9 and 76.5 (i.e., the average of 75.2 plus or minus the tolerance of 1.3), then the Score Update will be set to status Approved with no further action needed. If the API computes an average for the third column which is less than 73.9 or great than 76.5, then the resulting Score Update must be approved separately, as is the case with score 112233.

POST /fileLoadingJobs
{
    "description": "Load habberdasher score",
    "file": {
        "columnDelimiter": "Csv",
        "columns": [
            {"name": "hatWearerId"},
            {"name": "hatWearingScore"},
            {"name": "needsAnotherHatScore"}
        ],
        "fileName": "haberdashery.csv",
        "hasHeader": true,
        "sourceUrl": "sftp://keep:[email protected]/haberdasher.csv.zip"
    },
    "actions": [
        {
            "actionType": "score",
            "personIdColumn": "hatWearerId",
            "personIdType": "VANID",
            "scoreColumn": "hatWearingScore",
            "scoreId": 112233,
        },
        {
            "actionType": "score",
            "personIdColumn": "hatWearerId",
            "personIdType": "VANID",
            "scoreColumn": "needsAnotherHatScore",
            "scoreId": 112234,
            "approvalCriteria": {
                "average": 75.2,
                "tolerance": 1.3
            }
        }
    ],
    "listeners": [
        {
            "type": "URL",
            "value": "https://haberdashery.example.org/listener"
        },
        {
            "type": "EMAIL",
            "value": "[email protected]"
        }
    ]
}

Once the job is processed, the following data will be sent to the registered webhook:

POST https://haberdashery.example.org/listener
{
    "description": "Load habberdasher score",
    "message": "success"
}

Phones File

This is the phonesFile Action Type. The Phone Loading API will add phone numbers and their attributes to the associated VANID specified in the file. The Phone Loading API is supported in both My Voters and My Campaign.

Property

Type

Description

VANID

int

Required; the unique VANID of the contact record to which the phone will be added

PhoneType

string

Required; may be one of Home, Cell, or Work. Blank or invalid values will default to Home.

PhoneSource

string

Required; may be one of Voter File, User Added, Bulk, Appended, or Voter Registration. Blank or invalid values will default to Bulk.

Phone

string

Required; a 10-character valid phone number matching the NANP regex (^1?[2-9][0-8]\d[2-9]\d{6,6}$)

PreferredPhone

int

Required; may be 0, 1, or true, where 1 and true have the same meaning. Only one phone per contact may be designated as preferred.

PhoneExt

string

Required; a string of up to 6 characters, if applicable

PhoneOptInStatus

string

Optional; may be one of Opt In, Unknown, or Opt Out. Blank or invalid values will default to Unknown.

SonarScore

int

Optional; an integer value from 1to 5 indicating phone quality with higher values represent greater confidence in phone quality. Blank values will automatically receive a score of 5. Phone quality scores are supported in voter file databases only.

Example

POST /fileLoadingJobs
{
  "description": "VF Phone Load",
  "listeners": [{"type": "email", "value": "[email protected]" }],
  "file":
  {
    "columnDelimiter": "Csv",
    "fileName": "vf-phone-load.csv",
    "sourceUrl": "https://example.org/vf-phone-load.zip",
    "hasHeader": true,
    "columns": [
      { "name": "VANID" },
      { "name": "PhoneType" },
      { "name": "PhoneSource" },
      { "name": "Phone" },
      { "name": "PreferredPhone" },
      { "name": "PhoneExt" },
      { "name": "PhoneOptInStatus" },
      { "name": "SonarScore" }
    ]
  },
  "actions":
  [
    {
      "actionType": "phonesFile"
    }
  ]
}
Language
Authentication
Basic
base64
:
Click Try It! to start a request and see the response here!