VAN¶

Overview¶

The VAN module leverages the VAN API and generally follows the naming convention of their API endpoints. It is recommended that you reference their API documentation to additional details and information.

Note

API Keys

API Keys are specific to each committee and state, so you might need many.
Not all API Keys are provisioned for all end points. When requesting API keys, you should specify the endpoints that you need access to.

Warning

VANIDs: VANIDs are unique to each state and instance of the VAN. VANIDs used for the AV VAN will not match those of the SmartVAN or VoteBuilder.

QuickStart¶

To call the VAN class you can either store the api key as an environmental variable VAN_API_KEY or pass it in as an argument..

from parsons import VAN

 van = VAN(db='MyVoters') # Initiate class via environmental variable api key

 van = VAN(api_key='asdfa-sdfadsf-adsfasdf',db='MyVoters') # Pass api key directly

You can then call various endpoints:

from parsons import VAN

 van = VAN()

 # List events with a date filter
 events = van.get_events(starting_before='2018-02-01')

 # List all folders shared with API Key User
 folders = van.get_folders()

 # Return a dataframe rather than a list of dicts
 saved_lists = van.get_saved_lists().to_dataframe()

This a is just a small sampling of all of the VAN endpoints that you can leverage. We recommend reviewing the documentation for all functions.

Common Workflows¶

Score: Loading and Updating¶

Loading a score a multi-step process. Once a score is set to approved, loading takes place overnight.

from parsons import VAN

#Instatiate Class
van = VAN(db="MyVoters")

#List all of the scores / slots
print json.dumps(van.get_scores(), indent=4)

#Input the score slot id
score_slot_id = 34115

#Load the file via the file to VAN
r = van.file_load('score.csv',
              'https://box.com/scores.zip',
              ['vanid','myscore'],
              'vanid',
              'VANID',
               score_slot_id,
               'myscore',
               email='anemailaddress@gmail.com')


# Update Status - The email that you get when it is loaded will include a score update
# id. Pass this to approve the score to be loaded.
#   - Might take a few minutes to get the email
#   - Email will also include some nice stats to QC, included matched rows

van.score_update_status(47187,'approved') # Pass the score update id and set to approved

People: Add Survey Response¶

The following workflow can be used to apply survey questions, activist codes and canvass reponses.

from parsons import VAN

# Instatiate Class
van = VAN(db="MyVoters")

sq_id = 311838 # Valid survey question id
sr = 1288926 # Valid survey response id
ct = 36 # Valid contact type id
it_id = 4 # Valid input type id

# Create a valid survey question response
sq_response = van.people_sq_response(sq_id,sr_id)
van.people_canvass_response(dwid,
                            key_type='dwid',
                            contact_type_id=ct_id,
                            input_type_id=it_id,
                            responses=sq_response)

Event: Creating and Modifying¶

Events are made up of sub objects that need to exist to create an event

Event Object - The event itself
Event Type - The type of event, such as a Canvass or Phone Bank. These are created in the VAN UI and can be reused for multiple events.
Locations - An event can have multiple locations. While not required to initially create an event, these are required to add signups to an event.
Roles - The various roles that a person can have at an event, such as Lead or Canvasser. These are set as part of the event type.
Shifts - Each event can have multiple shits in which a person can be assigned. These are specified in the event creation.

from parsons import VAN

# Instatiate class
van = VAN(db="EveryAction")

# Create A Location
loc_id = van.location(name='Big `Ol Canvass', address='100 W Washington', city='Chicago', state='IL')

# Create Event
name = 'GOTV Canvass' # Name of event
short_name = 'GOTVCan' # Short name of event, 12 chars or less
start_time = '2018-11-01T15:00:00' # ISO formatted date
end_time = '2018-11-01T18:00:00' # ISO formatted date after start time
event_type_id = 296199 # A valid event type id
roles = [259236] # A list of valid role ids
location_ids = [loc_id] # An optional list of locations ids for the event
description = 'CPD Super Volunteers Canvass' # Optional description of 200 chars or less
shifts = [{'name': 'Shift 1',
           'start_time': '2018-11-01T15:00:00',
           'end_time': '2018-11-11T17:00:00'}] # Shifts must fall within event start/end time.

new_event = van.event_create(name, short_name, start_time, end_time, event_type_id, roles,
                             location_ids=location_ids, shifts=shifts, description=description)

Signup: Adding and Modifying¶

from parsons import VAN

# Instatiate class
van = VAN(db="EveryAction")

# Create a new signup

vanid = 100349920
event_id = 750001004
shift_id = 19076
role_id = 263920
location_id = 3
role_id = 263920
status_id = 11

# Create the signup. Will return a signup id
signup_id  = van.signup_create(vanid, event_id, shift_id, role_id, status_id, location_id

# Modify a status of the signup
new_status_id = 6
van.signup_update(signup_id, status_id=new_status_id)

People¶

class parsons.ngpvan.van.People(van_connection)[source]¶

find_person(first_name=None, last_name=None, date_of_birth=None, email=None, phone=None, street_number=None, street_name=None, zip=None, match_map=None)[source]¶

Find a person record.

Note

Person find must include the following minimum combinations to conduct a search.

first_name, last_name, email
first_name, last_name, phone
first_name, last_name, zip5, date_of_birth
first_name, last_name, street_number, street_name, zip5
email_address

Note

The arguments that can be passed are a selection of the possible values that can be used in a search. A full list of possible values can be found here. To use these values, pass in a dictionary using the match_map argument.

Args:

first_name: str: The person’s first name
last_name: str: The person’s last name
dob: str: ISO 8601 formatted date of birth (e.g. 1981-02-01)
email: str: The person’s email address
phone: str: Phone number of any type (Work, Cell, Home)
street_number: str: Street Number
street_name: str: Street Name
zip: str: 5 digit zip code
match_map: dict: A dictionary of values to match against. Will override all other arguments if provided.

fields: The fields to return. Leave as default for all available fields

Returns:

A person dict

upsert_person(first_name=None, last_name=None, date_of_birth=None, email=None, phone=None, street_number=None, street_name=None, zip=None, match_map=None)[source]¶

Create or update a person record.

Note

Person find must include the following minimum combinations.

first_name, last_name, email
first_name, last_name, phone
first_name, last_name, zip5, date_of_birth
first_name, last_name, street_number, street_name, zip5
email_address

Note

Warning

This method can only be run on MyMembers, EveryAction, MyCampaign databases.

Args:

first_name: str: The person’s first name
last_name: str: The person’s last name
dob: str: ISO 8601 formatted date of birth (e.g. 1981-02-01)
email: str: The person’s email address
phone: str: Phone number of any type (Work, Cell, Home)
street_number: str: Street Number
street_name: str: Street Name
zip: str: 5 digit zip code
match_map: dict: A dictionary of values to match against. Will override all other arguments if provided.

Returns:

A person dict

get_person(id, id_type='vanid', fields=['emails', 'phones', 'custom_fields', 'external_ids', 'addresses', 'recorded_addresses', 'preferences', 'suppressions', 'reported_demographics', 'disclosure_field_values'])[source]¶

Returns a single person record using their VANID or external id.

Args:

id: str: A valid id
id_type: str: A known person identifier type available on this VAN instance such as dwid

fields: The fields to return. Leave as default for all available fields

Returns:

A person dict

apply_canvass_result(id, result_code_id, id_type='vanid', contact_type_id=None, input_type_id=None, date_canvassed=None)[source]¶

Apply a canvass result to a person. Use this end point for attempts that do not result in a survey response or an activist code (e.g. Not Home).

Args:

id: str: A valid person id
result_code_idint: Specifies the result code of the attempt. Valid ids can be found by using the get_canvass_responses_result_codes()
id_type: str: A known person identifier type available on this VAN instance such as dwid
contact_type_idint: Optional; A valid contact type id
input_type_idint: Optional; Defaults to 11 (API Input)
date_canvassedstr: Optional; ISO 8601 formatted date. Defaults to todays date

apply_survey_response(id, survey_question_id, survey_response_id, id_type='vanid', result_code_id=None, contact_type_id=None, input_type_id=None, date_canvassed=None)[source]¶

Apply a single survey response to a person.

Args:

id: str: A valid person id
survey_question_id: int: A valid survey question id
survey_response_id: int: A valid survey response id
id_type: str: A known person identifier type available on this VAN instance such as dwid
result_code_idint: Optional; Specifies the result code of the response. If not included,responses must be specified. Conversely, if responses are specified, result_code_id must be null. Valid ids can be found by using the get_canvass_responses_result_codes()
contact_type_idint: Optional; A valid contact type id
input_type_idint: Optional; Defaults to 11 (API Input)
date_canvassedstr: Optional; ISO 8601 formatted date. Defaults to todays date

toggle_activist_code(id, activist_code_id, action, id_type='vanid', result_code_id=None, contact_type_id=None, input_type_id=None, date_canvassed=None)[source]¶

Apply or remove an activist code to or from a person.

Args:

id: str: A valid person id
activist_code_id: int: A valid activist code id
action: str: Either ‘apply’ or ‘remove’
id_type: str: A known person identifier type available on this VAN instance such as dwid
result_code_idint: Optional; Specifies the result code of the response. If not included,responses must be specified. Conversely, if responses are specified, result_code_id must be null. Valid ids can be found by using the get_canvass_responses_result_codes()
contact_type_idint: Optional; A valid contact type id
input_type_idint: Optional; Defaults to 11 (API Input)
date_canvassedstr: Optional; ISO 8601 formatted date. Defaults to todays date

toggle_volunteer_action(id, volunteer_activity_id, action, id_type='vanid', result_code_id=None, contact_type_id=None, input_type_id=None, date_canvassed=None)[source]¶

Apply or remove a volunteer action to or from a person.

Args:

id: str: A valid person id
id_type: str: A known person identifier type available on this VAN instance such as dwid
volunteer_activity_id: int: A valid volunteer activity id
action: str: Either ‘apply’ or ‘remove’
result_code_idint: Optional; Specifies the result code of the response. If not included,responses must be specified. Conversely, if responses are specified, result_code_id must be null. Valid ids can be found by using the get_canvass_responses_result_codes()
contact_type_id: int: Optional; A valid contact type id
input_type_id: int: Optional; Defaults to 11 (API Input)
date_canvassed: str: Optional; ISO 8601 formatted date. Defaults to todays date

** NOT IMPLEMENTED **

apply_response(id, response, id_type='vanid', contact_type_id=None, input_type_id=None, date_canvassed=None, result_code_id=None)[source]¶

Apply responses such as survey questions, activist codes, and volunteer actions to a person record. This method allows you apply multiple responses (e.g. two survey questions) at the same time. It is a low level method that requires that you conform to the VAN API response object format.

Args:

id: str: A valid person id
response: dict: A list of dicts with each dict containing a valid action.
id_type: str: A known person identifier type available on this VAN instance such as dwid
result_code_idint: Optional; Specifies the result code of the response. If not included,responses must be specified. Conversely, if responses are specified, result_code_id must be null. Valid ids can be found by using the get_canvass_responses_result_codes()
contact_type_idint: Optional; A valid contact type id
input_type_idint: Optional; Defaults to 11 (API Input)
date_canvassedstr: Optional; ISO 8601 formatted date. Defaults to todays date

responses : list or dict

Returns:

True if successful

response = [{"activistCodeId": 18917,
             "action": "Apply",
             "type": "ActivistCode"},
            {"surveyQuestionId": 109149,
             "surveyResponseId": 465468,
             "action": "SurveyResponse"}
            ]
van.apply_response(5222, response)

create_relationship(vanid_1, vanid_2, relationship_id)[source]¶

Create a relationship between two individuals

Args:

vanid_1int: The vanid of the primary individual; aka the node
vanid_2int: The vanid of the secondary individual; the spoke
relationship_idint: The relationship id indicating the type of relationship

Returns:

Tuple of (204, No Content) if successful, (404, Not Found).

Bulk Import¶

class parsons.ngpvan.van.BulkImport[source]¶

get_bulk_import_resources()[source]¶

Get bulk import resources that available to the user. These define the types of bulk imports that you can run. These might include Contacts, ActivistCodes, ContactsActivistCodes and others.

Returns:

list: A list of resources.

Activist Codes¶

class parsons.ngpvan.van.ActivistCodes(van_connection)[source]¶

Note

To apply or remove activist codes, use the toggle_activist_code() method.

get_activist_codes()[source]¶

Get activist codes.

Returns:

Parsons Table: See Parsons Table for output options.

get_activist_code(activist_code_id)[source]¶

Get an activist code.

Args:

activist_code_idint: The activist code id.

Returns:

dict: The activist code

Survey Questions¶

class parsons.ngpvan.van.SurveyQuestions(van_connection)[source]¶

get_survey_questions(statuses=['Active'], name=None, sq_type=None, question=None, cycle=None)[source]¶

Get survey questions.

Args:

statuses: str: Filter to a list of statuses of survey questions. One or more of Active, Archived, and Inactive.
name: str: Filter to survey questions with names begin with the input.
type: str: Filter to survey questions of a given type.
question: str: Filter to survey questions with script questions that contain the given input.
cycle: str: Filter to survey suestions with the given cycle. A year in the format “YYYY”.

Returns:

Parsons Table: See Parsons Table for output options.

get_survey_question(survey_question_id)[source]¶

Get a survey question.

Args:

survey_question_id: int: The survey question id.

Returns:

Parsons Table: See Parsons Table for output options.

Events¶

class parsons.ngpvan.van.Events(van_connection)[source]¶

get_events(code_ids=None, event_type_ids=None, rep_event_id=None, starting_after=None, starting_before=None, district_field=None, expand=['locations', 'codes', 'shifts', 'roles', 'notes', 'onlineForms'])[source]¶

Get events.

Args:

code_ids: str: Filter by code id.
event_type_ids: str: Filter by event_type_ids.
rep_event_id: str: Filters to recurring events that are recurrences the passed event id.
starting_after: str: Events beginning after iso8601 formatted date.
starting_before: str: Events beginning before iso8601 formatted date.
district_field: str: Filter by district field.
expandlist: A list of nested jsons to include in returned event object. Can be locations, codes, shifts, roles, notes, onlineForms.

Returns:

Parsons Table: See Parsons Table for output options.

get_event(event_id, expand=['locations', 'codes', 'shifts', 'roles', 'notes', 'onlineForms'])[source]¶

Get an event.

Args:

event_id: int: The event id.
expand: list: A list of nested jsons to include in returned event object. Can be locations, codes, shifts, roles, notes, onlineForms.

Returns:

Parsons Table: See Parsons Table for output options.

create_event(name, short_name, start_date, end_date, event_type_id, roles, shifts=None, description=None, editable=False, publicly_viewable=False, location_ids=None, code_ids=None, notes=None, district_field_value=None, voter_registration_batches=None)[source]¶

Create an event

Args:

name: str

A name for this event, no longer than 500 characters.

short_name: str

A shorter name for this event, no longer than 12 characters.

start_date: str

The start date and time for this event.

end_date: str

The end date and time for this event that is after start_date

event_type_id: int

A valid event type id.

roles: list

A list of valid role ids that correspond the with the event type.

shifts:

A list of dicts with shifts formatted as:

[
    {
     'name': 'Shift 1',
     'start_time': '12-31-2018T12:00:00',
     'end_time': '12-31-2018T13:00:00'
    }
    {
     'name': 'Shift 2',
     'start_time': '12-31-2018T13:00:00',
     'end_time': '12-31-2018T14:00:00'
    }
]

description: str

An optional description for this Event, no longer than 500 characters.

editable: boolean

If True, prevents modification of this event by any users other than the user associated the API key. Setting this to true effectively makes the event read-only in the VAN interface.

publicly_viewable: boolean

Used by NGP VAN’s website platform to indicate whether this event can be viewed publicly.

location_ids: list

A list of location_ids where the event is taking place

code_ids: list

A list of codes that are applied to this event for organizational purposes. Note that at most one source code and any number of tags, may be applied to an event.

notes: list

A list of notes

Returns:

The event code

delete_event(event_id)[source]¶

Delete an event.

Args:

event_id: int: The event id.

Returns:

None

add_event_shift(event_id, shift_name, start_time, end_time)[source]¶

Add shifts to an event

Args:

event_id: int: The event id.
shift_name: str: The name of the shift
start_time: str: The start time for the shift.
end_time: str: The end time of the shift.

Returns:

None

get_event_types()[source]¶

Get event types.

Returns:

Parsons Table: See Parsons Table for output options.

Locations¶

class parsons.ngpvan.van.Locations(van_connection)[source]¶

get_locations(name=None)[source]¶

Get locations.

Args:

name: str: Filter locations by name.

Returns:

Parsons Table: See Parsons Table for output options.

get_location(location_id)[source]¶

Get a location.

Args:

location_id: int: The location id.

Returns:

dict

create_location(name, address_line1=None, address_line2=None, city=None, state=None, zip_code=None)[source]¶

Find or create a location. If location already exists, will return location id.

Args:

name: str: A name for this location, no longer than 50 characters.
address_line1: str: First line of a street address.
address_line2: str: Second line of a street address.
city: str: City or town name.
state: str: Two or three character state or province code (e.g., MN, ON, NSW, etc.).
zip_code: str: ZIP, ZIP+4, Postal Code, Post code, etc.
Returns:: A location id

delete_location(location_id)[source]¶

Delete a location.

Args:

location_id: int: The location id

Returns:

200: OK if successful and 404 Not Found if location not found

Signups¶

class parsons.ngpvan.van.Signups(van_connection)[source]¶

get_signups_statuses(event_id=None, event_type_id=None)[source]¶

Get a list of valid signup statuses for a given event type or event. You must pass one of event_id or event_type_id but not both.

Args:

event_id: int: A valid event id.
event_type_id: int: A valid event type id.

Returns:

Parsons Table: See Parsons Table for output options.

get_person_signups(vanid)[source]¶

Get the signup history of a person.

Args:

vanid: int: A valid vanid associated with a person.

Returns:

Parsons Table: See Parsons Table for output options.

get_event_signups(event_id)[source]¶

Get the signup history of an event.

Args:

event_id: int: A valid event_id associated with an event

Returns:

Parsons Table: See Parsons Table for output options.

get_signup(event_signup_id)[source]¶

Get a single signup object.

Args:

event_signup_id: int: A valid event_signup_id associated with a signup.

Returns:

Parsons Table: See Parsons Table for output options.

create_signup(vanid, event_id, shift_id, role_id, status_id, location_id)[source]¶

Create a new signup for an event.

Args:

vanid: int: A valid vanid of the person to signup for the event.
event_id: int: A valid event_id to associate the person with the event
shift_id:: A shift_id, associated with the event to assign the person
role_id:: A role_id, associated with the event to assign the person
status_id:: A status_id of the person
location_id:: A location_id for the event

Returns:

Int: The event signup id

update_signup(event_signup_id, shift_id=None, role_id=None, status_id=None, location_id=None)[source]¶

Update a signup object. All of the kwargs will update the values associated with them.

Args:

event_signup_id: int: A valid event signup id
shift_id: int: The shift_id to update
role_id: int: The role_id to update
status_id: int: The status_id to update
location_id: int: The location_id to update

Returns:

tuple: If successful (204, No Content)

delete_signup(event_signup_id)[source]¶

Delete a signup object

Args:

event_signup_id: int: A valid event signup id

Returns:

tuple: If successful (204, No Content)

Codes¶

class parsons.ngpvan.van.Codes(van_connection)[source]¶

get_codes(name=None, supported_entities=None, parent_code_id=None, code_type=None)[source]¶

Get codes.

Args:

namestr: Filter by name of code.
supported_entities: str: Filter by supported entities.
parent_code_id: str: Filter by parent code id.
code_type: str: Filter by code type.

Returns:

Parsons Table: See Parsons Table for output options.

get_code(code_id)[source]¶

Get a code.

Args:

code_idint: The code id.

Returns:

Parsons Table: See Parsons Table for output options.

get_code_types()[source]¶

Get code types.

Returns:

list: A list of code types.

create_code(name=None, parent_code_id=None, description=None, code_type='SourceCode', supported_entities=None)[source]¶

Create a code.

Args:

name: str

The name of the code.

parent_code_id: int

A unique identifier for this code’s parent.

description: str

A description for this code, no longer than 200 characters.

code_type: str

The code type. Tag and SourceCode are valid values.

supported_entities: list

A list of dicts that enumerate the searchability and applicability rules of the code. You can find supported entities with the code_supported_entities()

[
    {
     'name': 'Event',
     'is_searchable': True,
     'is_applicable': True
    }
    {
     'name': 'Locations',
     'start_time': '12-31-2018T13:00:00',
     'end_time': '12-31-2018T14:00:00'
    }
]

update_code(code_id, name=None, parent_code_id=None, description=None, code_type='SourceCode', supported_entities=None)[source]¶

Update a code.

Args:

code_id: int

The code id.

name: str

The name of the code.

parent_code_id: int

A unique identifier for this code’s parent.

description: str

A description for this code, no longer than 200 characters.

code_type: str

The code type. Tag and SourceCode are valid values.

supported_entities: list

A list of dicts that enumerate the searchability and applicability rules of the code. You can find supported entities with the code_supported_entities()

[
    {
     'name': 'Event',
     'is_searchable': True,
     'is_applicable': True
    }
    {
     'name': 'Locations',
     'start_time': '12-31-2018T13:00:00',
     'end_time': '12-31-2018T14:00:00'
    }
]

delete_code(code_id)[source]¶

Delete a code.

Args:

code_id: int: The code id.

Returns:

(204, 'No Content') if successful

get_code_supported_entities()[source]¶

Get code supported entities.

Returns:

list: A list of code supported entities.

Canvass Responses¶

class parsons.ngpvan.van.CanvassResponses(van_connection)[source]¶

get_canvass_responses_contact_types()[source]¶

Get canvass response contact types.

Returns:

Parsons Table: See Parsons Table for output options.

get_canvass_responses_input_types()[source]¶

Get canvass response input types.

Returns:

Parsons Table: See Parsons Table for output options.

get_canvass_responses_result_codes()[source]¶

Get canvass response result codes.

Returns:

Parsons Table: See Parsons Table for output options.

Supporter Groups¶

class parsons.ngpvan.van.SupporterGroups(van_connection)[source]¶

get_supporter_groups()[source]¶

Get supporter groups.

Returns:

Parsons Table: See Parsons Table for output options.

get_supporter_group(supporter_group_id)[source]¶

Get a supporter group.

Args:

supporter_group_id: int: The supporter group id.

Returns:

Parsons Table: See Parsons Table for output options.

create_supporter_group(name, description)[source]¶

Create a new supporter group

Args:

name: str: The name of the supporter group. 100 character limit
description: str: Optional; A description of the supporter group. 200 character limit.

Returns

Parsons Table with the newly createed supporter group id, name and description

add_person_supporter_group(supporter_group_id, vanid)[source]¶

Add a person to a supporter group

Args:

supporter_group_id: int: The supporter group id
vanid: int: The vanid of the person to apply

delete_person_supporter_group(supporter_group_id, vanid)[source]¶

Remove a person from a supporter group

Args:

supporter_group_id: int: The supporter group id
vanid: int: The vanid of the person to remove

Saved Lists¶

Note

A saved list must be shared with the user associated with your API key to be listed.

class parsons.ngpvan.van.SavedLists(van_connection)[source]¶

get_saved_lists(folder_id=None)[source]¶

Get saved lists.

Args:

folder_id: int: Filter by the id for a VAN folder. If included returns only the saved lists in the folder

Returns:

Parsons Table: See Parsons Table for output options.

get_saved_list(saved_list_id)[source]¶

Returns a saved list object.

Args:

saved_list_id: int: The saved list id.

Returns:

dict

download_saved_list(saved_list_id)[source]¶

Download the vanids associated with a saved list.

Args:

saved_list_id: int: The saved list id.

Returns:

Parsons Table: See Parsons Table for output options.

Folders¶

Note

A folder must be shared with the user associated with your API key to be listed.

class parsons.ngpvan.van.Folders(van_connection)[source]¶

get_folders()[source]¶

Get all folders owned or shared with the API user.

Returns:

Parsons Table: See Parsons Table for output options.

get_folder(folder_id)[source]¶

Get a folder owned by or shared with the API user.

Args:

folder_id: int: The folder id.

Returns:

Parsons Table: See Parsons Table for output options.

Export Jobs¶

class parsons.ngpvan.van.ExportJobs(van_connection)[source]¶

get_export_job_types()[source]¶

Get export job types

Returns:

Parsons Table: See Parsons Table for output options.

export_job_create(list_id, export_type=4, webhookUrl='https://www.nothing.com')[source]¶

Creates an export job

Currently, this is only used for exporting saved lists. It is recommended that you use the saved_list_download() method instead.

Args:

list_id: int: This is where you should input the list id
export_type: int: The export type id, which defines the columns to export
webhookUrl:: A webhook to include to notify as to the status of the export

Returns:

Parsons Table: See Parsons Table for output options. Includes a download link for the file.

get_export_job(export_job_id)[source]¶

Get an export job.

Args:

export_job_id: int: The xxport job id.

Returns:

Parsons Table: See Parsons Table for output options.

Scores¶

Prior to loading a score for the first time, you must contact VAN support to request a score slot.

Note

Score Auto Approval: Scores can be automatically set to approved through the file_load function allowing you to skip calling the file_load() function. To automatically approve scores, if the average of the scores is within the fault tolerance specified by the user.It is only available to API keys with permission to automatically approve scores.

class parsons.ngpvan.van.Scores(van_connection)[source]¶

get_scores()[source]¶

Get all scores.

Returns:

Parsons Table: See Parsons Table for output options.

get_score(score_id)[source]¶

Get an individual score.

Args:

score_id: int: The score id

Returns:

dict

get_score_updates(created_before=None, created_after=None, score_id=None)[source]¶

Get score updates.

Args:

created_before: str: Filter score updates to those created before date. Use “YYYY-MM-DD” format.
created_after: str: Filter score updates to those created after date. Use “YYYY-MM-DD” format.

Returns:

Parsons Table: See Parsons Table for output options.

get_score_update(score_update_id)[source]¶

Get a score update object

Args:

score_update_idint
The score update id

Returns:
dict

update_score_status(score_update_id, status)[source]¶

Change the status of a score update object. This end point is used to approve a score loading job.

Args:

score_update_id: str: The score update id
status: str: One of ‘pending approval’, ‘approved’, ‘disapproved’

Returns:

boolean: True if the status update is accepted

Score Updates¶

File Loading Jobs¶

class parsons.ngpvan.van.FileLoadingJobs(van_connection)[source]¶

create_file_load(file_name, file_url, columns, id_column, id_type, score_id, score_column, delimiter='csv', header=True, description=None, email=None, auto_average=None, auto_tolerance=None)[source]¶

Loads a file. Only used for loading scores at this time. Scores must be compressed using zip.

Args:

file_name: str: The name of the file contained in the zip file.
file_url: str: The url path to directly download the file. Can also be a path to an FTP site.
columns: list: A list of column names contained in the file.
id_column: str: The column name of the id column in the file.
id_type: str: A valid primary key, such as VANID or DWID. Varies by VAN instance.
score_id: int: The score slot id
score_column: str: The column holding the score
delimiter: str: The file delimiter used.
email: str: A valid email address in which file loading status will be sent.
auto_average: float: The average of scores to be loaded.
auto_tolerance: float: The fault tolerance of the VAN calculated average compared to the auto_average. The tolerance must be less than 10% of the difference between the maximum and minimum possible acceptable values of the score.

Returns:

dict: The file load id

create_file_load_multi(file_name, file_url, columns, id_column, id_type, score_map, delimiter='csv', header=True, description=None, email=None)[source]¶

An iteration of the file_load() method that allows you to load multiple scores at the same time.

Args:

file_namestr

The name of the file contained in the zip file.

file_urlstr

The url path to directly download the file. Can also be a path to an FTP site.

columns: list

A list of column names contained in the file.

id_columnstr

The column name of the id column in the file.

id_typestr

A valid primary key, such as VANID or DWID. Varies by VAN instance.

score_maplist

A list of dicts that adheres to the following syntax

[{'score_id' : int,
  'score_column': str,
  'auto_average': float,
  'auto_tolerance': float }]

email: str

A valid email address in which file loading status will be sent.

Returns:

The file load job id