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 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.
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:
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:
Above you see an ordered array of associate arrays, each representing a loan purchase request composed of
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:
There are, of course, some limitations:
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:
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:
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
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.
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:
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:
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:
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:
or this pattern if you have the team shortname:
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: