Table of Contents

Administrating the API

The API is a paid service that serves to raise critical funds for Vote Smart's Operations. Accordingly, prospective API users should be thought of as sales leads. Know that as paid subscribers, current subscribers are expecting a certain level of customer service. We should be particularly responsive and accommodating to our higher-paid subscribers, as this will increase their chance of re-subscribing. For more information on what the API is and the data available, visit API Overview

Who takes care of what
DevComm handles user registration, administrating keys, taking payment, and answering payment questions.
National Director handles high-level API contracts (ex. National Journal) and coordinates the other department contacts
Research Director(s) handle research questions about which data is available via API.
IT handles technical issues and bugs with the API

DevComm should reach out to these 3 entities for assistance in handling subscriber issues.

Current Policies for Standard API Subscriptions


General Terms:

The API Registration Process

In mid-October 2012, a new registration system through Django Admin was instituted to streamline registration with a MyVotesmart account.

1. User creates MyVoteSmart Account
2. User visits http://votesmart.org/share/api/register
3. This is the portal where users select their tier, fill out the API survey, pay, then receive an email from officmgr@ with their API key which is automatically activated.
4. Previous subscribers wishing to resubscribe should be able to simply login to their account and submit their payment due in order to reactivate the key.
5. DevComm adds subscriber into DonorPerfect via Cybersource.

If the subscriber indicates that they are unsure which payment level to choose, then an email will be sent to membership@votesmart.org – [pypvs] API Subscription Intervention Needed. The email will contain a link to the fee schedule. After reviewing the registration form (found in Django administration, http://skittles.votesmart.org/admin/ - Survey Answers, checking the user and submission date) check the box next to the correct payment level, click submit, and an email will be sent to the user. Note: for those subscribers who may be at a level higher than the $3,000 subscription level, you should defer to the National Director to assign the appropriate fee.

API Subscription Activation Review

Membership@votesmart.org receives emails with the subject line “[pypvs] API Subscription Activation Review”. These emails are auto-generated from people on our site stating that they are a member and are requesting access for our API. Though, the majority of these people are not members, so it is DevComm’s job to confirm whether or not they have a membership with us. Membership for the API is defined as any current member (donating in the past 3 years) of Vote Smart.

How To:
Sometimes they reply, sometimes they don’t. I don’t know if the non-repliers pay. For those that reply: some are confused about MyVoteSmart and how that membership doesn’t actually give them a real membership; some are students that can’t afford it; some just want a one time data dump; it’s a case by case adventure. One way to figure out how much a person should pay is to look at their survey - link located on the bottom of the second page of their admin pages. You will have to haggle with some people over email about what payment option fits best for them. Payment options: http://votesmart.org/share/api/register

After negotiating a payment amount with the user: If they don’t fall into the normal tiers, don’t have a key and they haven’t paid yet: To make a payment on our website, they login to MyVoteSmart, select the fee type we decided on and hit "Next" and "Checkout" and then make their payment and they should be automatically assigned and sent a key.

Pricing:

Available to the public on http://votesmart.org/share/api/register. This is the portal where users select their tier, fill out the API survey, pay, then receive an email from officmgr@ with their API key. If a person makes a payment by going to votesmart.org/donate, or they pay over the phone, they don’t get automatically assigned a key. For this, go to http://skittles.votesmart.org/admin/ and assign them a key. Email them what their key is.

Tiers

These tiers should be examined every two years at the end of an election cycle. They can be updated through Django admin.

High-End API Users
The National Director should be involved with any cases that are $2,750+. Those wishing to relicense or resell data must pay a minimum of $15,000. High-volume users, name-brand users, users looking to relicense or resell data, users looking for a separate contract, users looking for additional data not available in the standard API, or other unusual questions should be run by the National Director prior to setting a fee amount. The National Director will need approval from the President for any non-standard agreements. Sometimes a separate agreement may be necessary, or we may want to develop more of a two-way partnership with them. The National Director should also be involved with those who have payment schedules. $2,500+ needs to be in a contract, on the API Subscription Notices calendar, and also be sent invoices.

Never send high-tier payment schedules to organizations. If any organization asks, it is “case to case and need to consult with the National Director.”

Current Partnerships and Potential Partnerships: Partnerships and Large API Users Contact Notes. Actual contracts are located in the Outreach Drive.

Special Cases: App Developers
We run into scenarios a lot, where an app developer wants to use our API data publicly, but has no idea how many users to expect/profit will be gained and therefore wants an exception to our subscription fee. They often cannot pay the $2,500 we expect for publicly disseminating our data. They often want to have subscription fees that increase in tandem with users and profit, starting at a manageable fee and increasing over time.

This is where your judgment comes into play. We make exceptions for users who fall into at least two of the three categories:
Pro: We make money as they do, which could turn into a real profit for us. There's no downfall for us if their site doesn't generate profit/users.
Con: We truly have little way/resources to be monitoring their users. So we would be trusting the user to report user/profit increases.

A good way to deal with people like this is staggered fees.
Temporary Keys
The same process as administering a real key (see above). Only difference? Temporary keys expire quicker.
The calendar "API Subscription Notices" is filled with reminders to deactivate API keys along with reminders about payments coming due for larger users. (example: National Journal). If you give someone a temporary key, put on this calendar the expiration date so you remember to deactivate. When passing on the API, make sure you share this calendar with the new people. Calendar settings > share this calendar > add by email with permission settings “Make changes AND manage sharing”

Backend of API Administration


Getting to a user's profile on Django Admin
1. Make a MyVoteSmart Account and login to MyVoteSmart using your username and password.
2. Login to http://skittles.votesmart.org/admin/
3. Under "user, use a username, first/ last name, or email address to search for a user
4. Make the changes needed in the profile - see below for specific changes.
5. Use the “save and add another” save instead of the “save and continue editing” save.“Save and continue editing” won’t save on the first try (nor will it have saved anything you did, so you have to re-do everything you did and then maybe it’ll save on the second try). It’s a terror. Best to just you “save and add another” which will take you off the page you were on. To double-check that it saved, just go back to the page you were on via users.

Assigning a new key for someone
Most people will get a key automatically assigned to them when they register through the API portal. Manually assigning someone a key is mostly done when giving temporary keys to users who want to see if our API is what they want. It is also done by people who call into the office to make a payment.

How To:
1. Log in to the user's profile
2. Next to "user API", click the little green plus sign
3. Find a key you already know is in use and change a few letters/numbers around in it. This has a 100% success rate thus far.
4. Do NOT ever select a key from the drop down list. This is a key that is already in use 5. You’ll have to add other info: subscription type, Reg subscription other amount:, reg date, Reg subscription start. You’ll have to check “Active” & “Accepted tos” boxes for the key to work.
6. Hit save on the popup and also “save and add another” in the user profile for the key to save. By doing the “save and add another” save, API admin will alert you if you tried adding an already in-use key. Double check that it saved by going back into that user and checking if the key is listed in the "User API" box.

ALWAYS test the key out prior to letting the people know what their key is.
To test: http://api.votesmart.org/Election.getElectionByYearState?&key=KEY&year=2016 Where it says KEY paste that key you just created and hit enter. If the message is “Authorization failed” it means that key didn’t work and you’ll have to try again.

API Admin Quirks
- Multiple Users, Same API Key: Dupes - Free Keys:

Subscription Renewal

As of 2016, subscriptions are based on the election cycle. This is a Bi-annual subscription which begins at registration and generally lasts through December 31 of even-numbered (general election) years. Those who sign up between November 1 and December 31 of even-numbered years will have their subscription extended through December 31 of two years later. So, for example, those who sign up between November 1, 2014 and October 31, 2016 will have a subscription term starting upon sign-up and ending December 31, 2016. Those that sign up from November 1, 2016 through October 31, 2018 would have a subscription term starting upon sign-up and ending December 31, 2018.

Prior to November 1 of an election year (the current start of a new cycle), we will need to reestablish the Standard Subscription Terms and Pricing with the President and make changes as necessary.

December Even Years Project
We send an email to API users before December 31st telling them that their key was going to be deactivated but that they could resubscribe. DevComm crafts the letter with the help of the National Director and sent it with iContact to all of our API subscribers from the beginning of time until November 1, 20xx. We sent the letter out in mid-December. The letter needs to be enticing. To accomplish this: talk about fun things we did with our data - speeches added, ratings added, etc. Maybe other fun things our API got used with.

This renewal contact should be accompanied with a usage survey similar to the current Registration survey for first-time subscribers. This will allow us to evaluate any subscribers whose usage may have changed.

Key Deactivation
Next round: December 31, 2022 (this excludes people who are on the "API Subscriptions Calendar" - they get deactivated before this date.
How to deactivate a key:
1. Go to the person's account in My Vote Smart under "user"
2. Click on the green plus sign next to "User API"
3. Unchck the "Active" box inside API registration.
4. Click "Save"
5. Click the “Save and Add Another” button in the user profile because it saves on the first time.

Note: there are 2 “Actives.” One under "Permissions" on the first page and One under "API Registration". "Permissions" is for the MyVoteSmart account. If you make this one inactive and the one under API Registration stays Active, the person will still have access to their API key. To fix this, just make the “Active” under API Registration inactive.

Receipts

Some people ask for a receipt. You can either send them a copy of their CyberSource receipt or send them a copy of their thank you letter for their API subscription
There is also a more formal template form is located at /outreach/PARTNERSHIPS & API SALES/API Information/Pricing/API invoice template with logo.doc.

Future Potential Projects

There are no comments on this page.
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki