Linking Back to Kiva

Almost every consumer of the Kiva API eventually needs to link back to Kiva. In some cases it is to handle actions outside the scope of the application or the current capabilities of the API, in other cases it is the sole purpose of the app - bringing people directly to Kiva to incite awareness, action. In addition to documenting basic URL patterns, we also have developed techniques that give you control over more than just data presentation. These special API-targeted endpoints allow your application to do a lot of the work up front then simply transfer the user to www.kiva.org to finish a transaction - such as making a loan or buying a gift certificate.

While we touch on some techniques in other parts of the docs, we've also pulled it all together here for your convenience.

Using App IDs

Using App IDs is optional, both in calls to the Kiva API and in links to Kiva. However, it helps us track the impact of applications on Kiva's mission and allows us to provide with statistics on what your app is doing. There is a detailed explaination of the App ID format, but the simple rule is to a choose a reverse-DNS string, such as net.foo.myGreatApplication, based on a domain you control.

We've provided examples of how App IDs are used in each of the techniques described below.

Populating Baskets

One of the most important interactions at Kiva is finding and choosing loans. We figured one way to make API-based apps more powerful and useful was to allow them to assemble baskets for checkout at Kiva. In a way, this gives you complete flexibility over the shopping process, creating entirely new interactions for browsing and saving loans. You can even help the user choose a donation amount too, saving a step in the checkout process.

Imagine a mobile application that allowed a user to quickly browse and sort through all the loans currently available at Kiva. Whenever the user found a loan he liked, he might tap a button that saved that loan for purchase later. After quickly collecting 5 loans he liked (all without loading a single web page), he could click a button to be transferred to www.kiva.org with all 5 loans in his basket and various amounts to lend to each. Because he saved a preferred donation percentage in the app, the mobile app already added a 10% donation to his basket as well. All this is possible through a POST request to this URI:

http://www.kiva.org/basket/set

To set the contents of a basket, you need only the ID of the loan or loans you want to set and the amount, in dollars, to lend. This information is passed in a simple JSON structure assigned to the loans variable in the POST body of your request:

[ { "id":106957, "amount":100 }, { "id":106086 ,"amount":25 } ]

Above you see an ordered array of associate arrays, each representing a loan purchase request composed of id and amount. Simple. To add a donation, just supply the decimal amount to the donation value in the POST body. If your application is a web page, the easiest way to do this to pass each variable as an INPUT element in an HTML form:

<form method="POST" action="http://www.kiva.org/basket/set"> <input name="loans" value="[set by javascript?]" type="hidden" /> <input name="donation" value="12.34" /> <input name="app_id" value="com.foo.app" type="hidden" /> </form>

There are, of course, some limitations:

  • You can't reserve loans. On Kiva, loans are reserved for the user as soon as they go into the basket. Using basket modification, loans are only reserved once the user arrives at the Kiva website. This could cause a problem if the user takes too long between finding a loan on Kiva going to basket checkout. A way to mitigate confusion would be to verify the user's choices are still available before transferring him to Kiva, giving an option to modify the choices before moving on to checkout. If the loans requested are not available, we'll put as much of the request amount in the basket as is available.
  • You can only set, not get or add to, the basket. Baskets are associated with sessions in a browser. If you open a new browser window, it could create a new session with the basket contents. If your app simply loads the Kiva site in the same browser session, the current contents of the basket (if any) will be overwritten with the new contents. This is actually a feature as it allows applications predictable control over the basket contents while protecting the privacy of the user.

Returning to your app

You can have a link appear back to your app on the Thanks page, after the checkout is complete. When posting to the basket also set:

<input name="callback_url" value="http://example.com/kiva/checkout-complete" type="hidden" />

Note that the domain of the callback must match the domain of your app. Currently this is an experimental feature.

The result will look like this:

Passing a default team

When you send a user to the Kiva site, you can include a default team. If the user registers, they will be offered to join this team. Just include the default_team parameter in the URL

http://www.kiva.org/?default_team=bobharrisdotcom

Content Pages

Every data object in the Kiva API has a unique ID of some sort. Here's a list of recommended ways to link back to a specific object using its ID.

Loans

The most relevant page for any loan is the loan detail page. This page has comprehensive information about the loan and related lenders; it is the natural stepping stone to picking a new loan for checkout:

http://www.kiva.org/lend/<id>

Example: http://www.kiva.org/lend/107105?app_id=org.kiva.build

Lenders

If you want to provide a link in your application to a lender's Lender Page on the Kiva website, all you need is the lender_id and this URL template:

http://www.kiva.org/lender/<lender_id>

Example: http://www.kiva.org/lender/jeremy?app_id=org.kiva.build

Journal Entries

Linking to a journal entry currently requires the ID of the journal entry. This is the URI pattern for a page which shows the entry's contents and allows users to add comments:

http://www.kiva.org/updates/loan/journal_entry_id

Example: http://www.kiva.org/updates/loan/1114?app_id=org.kiva.build

Teams

There are two ways to link to team pages - you can use the team ID or the team shortname. Use this template if you only know the numeric team ID:

http://www.kiva.org/community/viewTeam?team_id=<id>

or this pattern if you have the team shortname:

http://www.kiva.org/team/<shortname>

Examples:
http://www.kiva.org/team/buildkiva

Finding the Lender ID

What if a lender doesn't know his Lender ID? We've added a handy page to the Kiva website to help lenders figure this out. Direct users this URL and they will be shown their lender ID after successful login to Kiva:

http://www.kiva.org/myLenderId
Kiva
  • © 2009 - 2014 Kiva. All rights reserved.
  • Terms Of Service
  • Kiva is a 501(c)(3) nonprofit.