build.kiva: API Reference

One of: AF, AL, AM, AZ, BA, BD, BF, BG, BI, BJ, BO, BW, BZ, CD, CG, CI, CL, CM, CO, CR, DO, EC, GE, GH, GT, GZ, HN, HT, ID, IL, IN, IQ, JO, KE, KG, KH, LB, LK, LR, MD, ML, MN, MX, MZ, NA, NG, NI, NP, PE, PH, PK, PS, PY, QS, RW, SL, SN, SV, TD, TG, TH, TJ, TL, TR, TZ, UA, UG, US, VN, WS, XK, YE, ZA, ZM, ZW

sort_by(string)

The order by which to sort the results.

One of: oldest, newest
Default: newest

q(string)

A general search query parameter which matches against lenders’ names occupations, whereabouts, and reasons for lending.

occupation(string)

If supplied, results are filtered by those that match lenders’ occupation. This parameter is ignored if the "q" parameter is supplied.

page(number)

The page position of results to return.

Default: 1

app_id(string)

The application id in reverse DNS notation.

Response

lender_listing – HTML , JSON , XML , RSS

Status

Production

GET /lending_actions/recent

Lists the 100 most recent loans made on Kiva by public lenders.

This method returns the most recent loan purchases made on Kiva in reverse-chronological order. Loans made by users with private lender profiles are not shown, and there is no way to fetch history beyond the 100 most recent transactions.

Example

http://api.kivaws.org/v1/lending_actions/recent.json

Parameters

app_id(string)

The application id in reverse DNS notation.

Response

lending_action – HTML , JSON , XML

Status

Production

GET /loans/:ids

Returns detailed information for multiple loans.

Detailed loan records include a lot of data beyond the scope of a loan listing, including the list of borrowers, loan terms, and recorded payments.

Example

http://api.kivaws.org/v1/loans/2930.json

Parameters

ids(list of numbers)

Required. A list of the loan IDs for which to return detail.

Max list items: 10

app_id(string)

The application id in reverse DNS notation.

Response

loan_detail – HTML , JSON , XML , RSS

Status

Production

GET /loans/:id/journal_entries

Retrieve journal entries associated with a particular loan.

Example

http://api.kivaws.org/v1/loans/42939/journal_entries.json

Parameters

id(number)

Required. The ID of the loan for which you want journal entries.

page(number)

The page position of results to return.

Default: 1

app_id(string)

The application id in reverse DNS notation.

Response

journal_entry – HTML , JSON , XML

Status

Production

GET /loans/:id/lenders

Returns the list of public lenders to a loan.

Example

http://api.kivaws.org/v1/loans/38239/lenders.json

Parameters

id(number)

Required. The loan ID for which to return lenders.

page(number)

The page position of results to return.

Default: 1

app_id(string)

The application id in reverse DNS notation.

Response

lender_listing – HTML , JSON , XML , RSS

Status

Production

GET /loans/:id/updates

Returns all status updates for a loan, newest first.

The list of updates returned is currently comprised of payment notifications and journal entries. Output for this call is also available as RSS.

Example

http://api.kivaws.org/v1/loans/42939/updates.json

Parameters

id(number)

Required. The loan ID for which to return updates.

app_id(string)

The application id in reverse DNS notation.

Response

loan_updates – HTML , JSON , XML , RSS

Status

Production

GET /loans/newest

Returns a simple list of the most recent fundraising loans.

Example

http://api.kivaws.org/v1/loans/newest.json

Parameters

page(number)

The page position of results to return.

Default: 1

app_id(string)

The application id in reverse DNS notation.

Response

loan_listing – HTML , JSON , XML , RSS

Status

Production

GET /loans/search

Search and sort loan listings by multiple criteria.

Example

http://api.kivaws.org/v1/loans/search.json

Parameters

status(list of strings)

The status of loans to return.

One of: fundraising, funded, in_repayment, paid, ended_with_loss

gender(string)

If supplied, results are filtered to loans with entrepreneurs of the specified gender. In the case of group loans, this matches against the predominate gender in the group.

One of: male, female

region(list of strings)

A list of two-letter codes corresponding to regions in which Kiva operates. If supplied, results are filtered to loans only from the specified regions.

One of: na, ca, sa, af, as, me, ee

country_code(list of strings)

A list of two-character ISO codes of countries by which to filter results.

One of: AF, AL, AM, AZ, BA, BD, BF, BG, BI, BJ, BO, BW, BZ, CD, CG, CI, CL, CM, CO, CR, DO, EC, GE, GH, GT, GZ, HN, HT, ID, IL, IN, IQ, JO, KE, KG, KH, LB, LK, LR, MD, ML, MN, MX, MZ, NA, NG, NI, NP, PE, PH, PK, PS, PY, QS, RW, SL, SN, SV, TD, TG, TH, TJ, TL, TR, TZ, UA, UG, US, VN, WS, XK, YE, ZA, ZM, ZW

sector(list of strings)

A list of business sectors for which to filter results.

partner(list of numbers)

A list of partner IDs for which to filter results.

sort_by(string)

The order by which to sort results.

One of: popularity, loan_amount, oldest, expiration, newest, amount_remaining, repayment_term
Default: newest

q(string)

A query string against which results should be matched.

page(number)

The page position of results to return.

Default: 1

app_id(string)

The application id in reverse DNS notation.

Response

loan_listing – HTML , JSON , XML , RSS

Status

Production

GET /methods

Lists all methods available via the Kiva API.

Example

http://api.kivaws.org/v1/methods.json

Parameters

app_id(string)

The application id in reverse DNS notation.

Response

method_summary – HTML , JSON , XML

Status

Production

GET /methods/:ids

Returns documentation for specific methods of the Kiva API.

Example

http://api.kivaws.org/v1/methods/GET*|loans|newest.json

Parameters

ids(list of strings)

Required. The IDs of methods for which to return specifications.

Max list items: 50

app_id(string)

The application id in reverse DNS notation.

Response

method_summary – HTML , JSON , XML

Status

Production

GET /my/account

Returns private account information for the Kiva User as authorized.

Requires "access" scope for basic information.

Example

https://api.kivaws.org/v1/my/account.json

Output

{ "user_account": { "id": 123456, "is_public": true, "first_name": "Martin", "last_name": "Johnson", "lender_id": "martin1234" } }

Parameters

app_id(string): A unique developer-defined Application ID, usually in reverse DNS notation.

Response

user_account – HTML , JSON , XML

Status

Beta

Requires OAuth

GET /my/balance

Returns private account information for the Kiva User as authorized.

Requires "user_balance" scope for user balance.

Example

https://api.kivaws.org/v1/my/balance.json

Output

{ "user_balance": { "id": 123456, "balance": "250.00" } }

Parameters

app_id(string): A unique developer-defined Application ID, usually in reverse DNS notation.

Response

user_balance – HTML , JSON , XML

Status

Beta

Requires OAuth

GET /my/email

Returns private account information for the Kiva User as authorized.

Requires "user_email" scope for users email address.

Example

https://api.kivaws.org/v1/my/email.json

Output

{ "user_email": { "id": 123456, "email": "martin@lenderweb.org" } }

Parameters

app_id(string): A unique developer-defined Application ID, usually in reverse DNS notation.

Response

user_email – HTML , JSON , XML

Status

Beta

Requires OAuth

GET /my/lender

Returns lender object, even for anonymous lenders.

Requires "user_anon_lender_data" scope.

Example

https://api.kivaws.org/v1/my/lender.json

Parameters

app_id(string): A unique developer-defined Application ID, usually in reverse DNS notation.

Response

lender – HTML , JSON , XML

Status

Beta

Requires OAuth

GET /my/loans

Returns loans for a lender, even for anonymous lenders.

Requires "user_anon_lender_loans" scope.

Example

https://api.kivaws.org/v1/my/loans.json

Parameters

page(number)

The page position of results to return.

Default: 1

sort_by(string)

The order by which to sort results.

One of: popularity, loan_amount, oldest, expiration, newest, amount_remaining, repayment_term
Default: newest

app_id(string)

A unique developer-defined Application ID, usually in reverse DNS notation.

Response

loan – HTML , JSON , XML

Status

Beta

Requires OAuth

GET /my/loans/:id/balances

Returns amount lent and outstanding balance for a loan.

Requires "user_loan_balances" scope. Note, the amount_repaid_to_lender is the full expected amount so you have to deduct the currency_loss_to_lender separately to get the actual total repaid. The same is true for the promo amounts. Possible statues: The possible statuses are: refunded, fundraising, expired, funded, in_repayment, paid and ended_with_loss. Loans can have the status 'ended_with_loss' for two reasons. a) currency loss, which will be presented in the return values or b) default, which is the remainder when the numbers don't add up.

Example

https://api.kivaws.org/v1/my/loans/:id/balances.json

Output

{ "balances" : { "id": 449097 "total_amount_purchased": 25, "amount_repaid_to_lender": 0, "currency_loss_to_lender": 0, "amount_repaid_to_promo": 6.51, "currency_loss_to_promo": 0, "arrears_amount": 0, "status": "in_repayment" } }

Parameters

id(string): Required. none
app_id(string): A unique developer-defined Application ID, usually in reverse DNS notation.

Response

user_loan_balances – HTML , JSON , XML

Status

Beta

Requires OAuth

GET /my/teams

Returns teams for a lender, even for anonymous lenders.

Requires "user_anon_lender_teams" scope.

Example

https://api.kivaws.org/v1/my/teams.json

Parameters

page(number)

The page position of results to return.

Default: 1

sort_by(string)

The order by which to sort results.

One of: newest, oldest, member_count, loan_count, loaned_amount, query_relevance
Default: newest

app_id(string)

A unique developer-defined Application ID, usually in reverse DNS notation.

Response

team – HTML , JSON , XML

Status

Beta

Requires OAuth

GET /partners

Returns detailed listings for all Kiva field partners.

Example

http://api.kivaws.org/v1/partners.json

Parameters

page(number)

The page position of results to return.

Default: 1

app_id(string)

The application id in reverse DNS notation.

Response

partner_listing – HTML , JSON , XML , RSS

Status

Production

GET /releases/api/current

Returns versioning information on the current Kiva API release.

Example

http://api.kivaws.org/v1/releases/api/current.json

Parameters

app_id(string)

The application id in reverse DNS notation.

Response

release – HTML , JSON , XML

Status

Production

GET /statistics/:stat_name

Returns a statistic based on the name requested.

Example

http://api.kivaws.org/v1/statistics/gender_num_female.json

Parameters

page(number)

The page position of results to return.

Default: 1

app_id(string)

The application id in reverse DNS notation.

stat_name(string)

Required. Acceptable values: total (dollar amount of Kiva loans made to date), count (number of Kiva loans made to date), gender_num_female (total number of female lenders), num_entreps (total number of Kiva borrowers), average_per_entrep (average loan size for Kiva borrowers).

One of: total, count, gender_num_female, num_entreps, average_per_entrep

Response

statistic – HTML , JSON , XML

Status

Beta

GET /teams/:ids

Returns detailed information about one or more lending teams.

Example

http://api.kivaws.org/v1/teams/2.json

Parameters

ids(list of numbers)

Required. A list of team IDs for which to return team detail.

Max list items: 20

app_id(string)

The application id in reverse DNS notation.

Response

team_detail – HTML , JSON , XML , RSS

Status

Production

GET /teams/:id/lenders

Returns the list of public lenders belonging to a specific team.

Example

http://api.kivaws.org/v1/teams/2/lenders.json

Parameters

id(number)

Required. The numeric team ID for which to return lenders.

sort_by(string)

The order by which to sort results.

One of: oldest, newest
Default: newest

page(number)

The page position of results to return.

Default: 1

app_id(string)

The application id in reverse DNS notation.

Response

lender_listing – HTML , JSON , XML , RSS

Status

Production

GET /teams/:id/loans

Returns loans belonging to a particular team.

Example

http://api.kivaws.org/v1/teams/2/loans.json

Parameters

id(number)

Required. The team ID for which to return loans.

page(number)

The page position of results to return.

Default: 1

sort_by(string)

The order by which to sort results.

One of: oldest, newest
Default: newest

app_id(string)

The application id in reverse DNS notation.

Response

loan_listing – HTML , JSON , XML , RSS

Status

Production

GET /teams/search

Sort through the list of lending teams using multiple criteria.

Example

http://api.kivaws.org/v1/teams/search.json

Parameters

membership_type(string)

If supplied, only teams with the specified membership policy are returned.

One of: open, closed

category(string)

If supplied, only teams with the specified category are returned.

One of: Alumni Groups, Businesses, Businesses - Internal Groups, Clubs, Colleges/Universities, Common Interest, Events, Families, Field Partner Fans, Friends, Local Area, Memorials, Religious Congregations, Schools, Sports Groups, Youth Groups, Other

sort_by(string)

The order by which to sort results.

One of: newest, oldest, member_count, loan_count, loaned_amount, query_relevance
Default: newest

page(number)

The page position of results to return.

Default: 1

q(string)

A query string by which to match results.

app_id(string)

The application id in reverse DNS notation.

Response

team_listing – HTML , JSON , XML , RSS

Status

Production

GET /teams/using_shortname/:shortnames

Returns detailed information about one or more teams, identified by shortname.

Usually data about teams is retrieved using the team‘s numerical ID. This method is useful for looking up that ID and other information when only the shortname of the team is known.

Example

http://api.kivaws.org/v1/teams/using_shortname/buildkiva.json

Parameters

shortnames(list of strings)

Required. A list of team shortnames for which to return team detail.

Max list items: 20

app_id(string)

The application id in reverse DNS notation.

Response

team_detail – HTML , JSON , XML

Status

Production

GET /templates/images

Lists all URL templates useful for fetching images on Kiva.

Example

http://api.kivaws.org/v1/templates/images.json

Parameters

app_id(string)

The application id in reverse DNS notation.

Response

image_template – HTML , JSON , XML

Status

Production

Terms Of Service
Kiva is a 501(c)(3) nonprofit.