/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.

PropertyTypeDescription
descriptionmessageThe job description specified when creating the job.
messagemessageDetailed description of a job’s success (or failure)

Score Load Action

This is the Score Action Type.

PropertyTypeDescription
actionTypestringRequired; This must be set to Score for Score Load jobs
personIdColumnstringRequired; The source file column name containing person identifiers.
personIdTypestringRequired; 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
scoreColumnstringRequired; 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").
scoreIdintRequired; The unique identifier of a score available within the target context.
approvalCriteriaobjectOptional; 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.

PropertyTypeDescription
averagefloatThe average of the values in the score column. Must be a number between the maximum and minimum possible acceptable values of the score.
tolerancefloatThe 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.

PropertyTypeDescription
VanIDstringRequired; The VoterFile VANID of the VoterFile record. All AVEV data files require either a VanID or a StateFileID, but not both.
StateFileIDintRequired; The unique identifier for the record on the state file. All AVEV data files require either a VanID or a StateFileID, but not both.
RequestReceiveddateRequired; The date the absentee ballot request was received.
BallotMaileddateRequired; The date the absentee ballot was mailed.
BallotReceiveddateRequired; The date the completed ballot was received.
EarlyVoteddateRequired; The date that the person early voted.
BallotPartystringRequired; A one- or two-character code corresponding to the party the ballot belongs to.
BallotCancelleddateRequired; The date the absentee ballot was cancelled.
ApplicationMaileddateRequired; The date the absentee application was mailed.
GOTVVoteddateRequired; The date the person voted on election day.
DateApplicationReceiveddateRequired; The date the absentee application was received.
BallotReturnStatusintOptional; ID for the ballot return status
BallotTypeintOptional; ID for the ballot type
BallotRequestTypeintOptional; ID for the ballot request type
BallotAddress1stringOptional; First line of a Street Address (up to 40 characters)
BallotAddress2stringOptional; Second line of a Street Address (up to 40 characters)
BallotAddress3stringOptional; Third line of a Street Address (up to 40 characters)
BallotCitystringOptional; City or Town (up to 25 characters)
BallotStatestringOptional; Two-character state code (e.g. MN, FL, etc)
BallotZip9stringOptional; ZIP+4 for this address (up to 10 characters)
BallotCountrystringOptional; A two-character ISO country code that is supported by your VAN context (e.g., US)

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"}
    ]
  },
  "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.

PropertyTypeDescription
actionTypestringRequired; This must be LoadSavedListFile.
listNamestringRequired; The user-facing name of the Saved List. Must be unique within the target folder. Must be fewer than 50 characters.
listDescriptionstringOptional; The user-facing description of the Saved List. Must be fewer than 250 characters.
personIdTypestringRequired; This must be VANID.
personIdColumnstringRequired; This must be VANID.
folderIdintRequired; 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.
overwriteExistingListIdintOptional; 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.

PropertyTypeDescription
savedListIdintThe ID of the Saved List that was created or overwritten.
originalRowCountstringThe count of rows that were in the source file, before validation, duplicate removal, and access checks.
matchedRowsCountstringThe count of rows that were loaded into the Saved List, after validation, duplicate removal, and access checks.
unmatchedRowsCountstringThe 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.

PropertyTypeDescription
VANIDintRequired; the unique VANID of the contact record to which the phone will be added
PhoneTypestringRequired; may be one of Home, Cell, or Work. Blank or invalid values will default to Home.
PhoneSourcestringRequired; may be one of Voter File, User Added, Bulk, Appended, or Voter Registration. Blank or invalid values will default to Bulk.
PhonestringRequired; a 10-character valid phone number matching the NANP regex (^1?[2-9][0-8]\d[2-9]\d{6,6}$)
PreferredPhoneintRequired; may be 0, 1, or true, where 1 and true have the same meaning. Only one phone per contact may be designated as preferred.
PhoneExtstringRequired; a string of up to 6 characters, if applicable
PhoneOptInStatusstringOptional; may be one of Opt In, Unknown, or Opt Out. Blank or invalid values will default to Unknown.
SonarScoreintOptional; 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
Authorization
Basic
base64
:
Click Try It! to start a request and see the response here!