API Reference

This is reference documentation for all methods exposed by the Kiva API.

GET /lenders/:lender_ids

Retrieves detail for multiple lenders.

Example

https://api.kivaws.org/v1/lenders/matt.json

Parameters

lender_ids(list of strings)
Required. A list of Lender IDs for which to return details.
  • Max list items: 50
app_id(string)
The application id in reverse DNS notation.

    Response

      lender_detail – HTML , JSON , XML

    Status

      Production

    GET /lenders/:lender_id/loans

    Returns loans belonging to a particular lender.

    Example

    https://api.kivaws.org/v1/lenders/jeremy/loans.json

    Parameters

    lender_id(string)
    Required. The Lender 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.
        ids_only(string)
        Return IDs only to make the return object smaller.
        • One of: true, false
        • Default: false

        Response

          loan_listing – HTML , JSON , XML , RSS

        Status

          Production

        GET /lenders/:lender_id/teams

        Returns teams that a particular lender is a member of.

        Example

        https://api.kivaws.org/v1/lenders/jeremy/teams.json

        Parameters

        lender_id(string)
        Required. The Lender ID for which to return teams.
          page(number)
          The page position of results to return.
          • Default: 1
          app_id(string)
          The application id in reverse DNS notation.
            ids_only(string)
            Return IDs only to make the return object smaller.
            • One of: true, false
            • Default: false

            Response

              team_detail – 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

            https://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

              https://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: 100
              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. Due to borrower privacy concerns we only show journal entries on fund raising loans

                Example

                https://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

                  https://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.
                    ids_only(string)
                    Return IDs only to make the return object smaller.
                    • One of: true, false
                    • Default: false

                    Response

                      lender_listing – HTML , JSON , XML , RSS

                    Status

                      Production

                    GET /loans/:id/repayments

                    Returns the expected repayment schedule for a loan, only for fund raising loans.

                    Example

                    https://api.kivaws.org/v1/loans/2/repayments.json

                    Parameters

                    id(number)
                    Required. The loan ID for which to return repayments schedule.
                    app_id(string)
                    The application id in reverse DNS notation.
                      ids_only(string)
                      Return IDs only to make the return object smaller.
                      • One of: true, false
                      • Default: false

                      Response

                        loan_listing – HTML , JSON , XML , RSS

                      Status

                        Beta

                      GET /loans/:id/similar

                      Returns loans similar to the specified loan.

                      Example

                      https://api.kivaws.org/v1/loans/2/similar.json

                      Parameters

                      id(number)
                      Required. The loan ID for which to return similar loans.
                      count(number)
                      The amount of similar loans to return.
                      • Default: 3
                      app_id(string)
                      The application id in reverse DNS notation.
                        ids_only(string)
                        Return IDs only to make the return object smaller.
                        • One of: true, false
                        • Default: false

                        Response

                          loan_listing – HTML , JSON , XML , RSS

                        Status

                          Production

                        GET /loans/:id/teams

                        Returns teams that have lent to a particular loan.

                        Example

                        https://api.kivaws.org/v1/loans/613086/teams.json

                        Parameters

                        id(number)
                        Required. The Loan ID for which to return teams.
                        page(number)
                        The page position of results to return.
                        • Default: 1
                        app_id(string)
                        The application id in reverse DNS notation.
                          ids_only(string)
                          Return IDs only to make the return object smaller.
                          • One of: true, false
                          • Default: false

                          Response

                            team_detail – HTML , JSON , XML , RSS

                          Status

                            Production

                          GET /loans/newest

                          Returns a simple list of the most recent fundraising loans.

                          Example

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

                          Parameters

                          page(number)
                          The page position of results to return.
                          • Default: 1
                          per_page(number)
                          The page position of results to return.
                          • Default: 20
                          app_id(string)
                          The application id in reverse DNS notation.
                            ids_only(string)
                            Return IDs only to make the return object smaller.
                            • One of: true, false
                            • Default: false

                            Response

                              loan_listing – HTML , JSON , XML , RSS

                            Status

                              Production

                            GET /loans/search

                            Search and sort loan listings by multiple criteria.

                            Example

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

                            Parameters

                            status(list of strings)
                            The status of loans to return.
                            • One of: fundraising, funded, expired
                            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, we, an, oc
                            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, BR, BT, CA, CD, CI, CL, CM, CN, CO, CR, DO, EC, EG, FJ, GE, GH, GT, GU, GZ, HN, HT, ID, IL, IN, IQ, JO, KE, KG, KH, LA, LB, LK, LR, LS, MD, MG, ML, MM, MN, MR, MW, MX, MZ, NA, NG, NI, NP, PA, PE, PG, PH, PK, PR, PS, PY, RW, SB, SL, SN, SO, SS, SV, TD, TG, TH, TJ, TL, TO, TR, TZ, UA, UG, US, VC, VI, VN, VU, WS, XK, YE, ZA, ZM, ZW
                            sector(list of strings)
                            A list of business sectors for which to filter results.
                            • One of: Agriculture, Arts, Clothing, Construction, Education, Entertainment, Food, Health, Housing, Manufacturing, Personal Use, Retail, Services, Transportation, Wholesale
                            partner(list of numbers)
                            A list of partner IDs for which to filter results.
                            themes(list of strings)
                            A list of themes for which to filter results.
                            • One of: Green, Higher Education, Arab Youth, Kiva City LA, Islamic Finance, Youth, Start-Up, Water and Sanitation, Vulnerable Groups, Fair Trade, Rural Exclusion, Mobile Technology, Underfunded Areas, Conflict Zones, Job Creation, SME, Growing Businesses, Kiva City Detroit, Health, Disaster recovery, Flexible Credit Study, Innovative Loans, IPA Study, Refugees/Displaced, Social Enterprise, Earth Day Campaign, Clean Energy, Solar
                            borrower_type(string)
                            Show individuals, groups or both.
                            • One of: individuals, groups, both
                            • Default: both
                            partner_risk_rating_min(number)
                            The minimum partner risk.
                            • Range (inclusive): 0..5
                            • Default: 0
                            partner_risk_rating_max(number)
                            The maximum partner risk.
                            • Range (inclusive): 0..5
                            • Default: 5
                            partner_arrears_min(number)
                            The minimum partner delinquency.
                            • Range (inclusive): 0..41
                            • Default: 0
                            partner_arrears_max(number)
                            The maximum partner delinquency.
                            • Range (inclusive): 0..41
                            • Default: 41
                            partner_default_min(number)
                            The minimum partner default.
                            • Range (inclusive): 0..26
                            • Default: 0
                            partner_default_max(number)
                            The maximum partner default.
                            • Range (inclusive): 0..26
                            • Default: 26
                            partner_risk_include_nonrated(string)
                            Include non-rated partners.
                            • One of: true, false
                            • Default: true
                            include_curr_risk(string)
                            Include partners with currency risk.
                            • One of: true, false
                            • Default: true
                            sort_by(string)
                            The order by which to sort results.
                            • One of: popularity, loan_amount, expiration, newest, oldest, amount_remaining, repayment_term, random
                            • Default: newest
                            q(string)
                            A query string against which results should be matched.
                            page(number)
                            The page position of results to return.
                            • Default: 1
                            per_page(number)
                            The page position of results to return.
                            • Default: 20
                            app_id(string)
                            The application id in reverse DNS notation.
                              ids_only(string)
                              Return IDs only to make the return object smaller.
                              • One of: true, false
                              • Default: false

                              Response

                                loan_listing – HTML , JSON , XML , RSS

                              Status

                                Production

                              GET /methods

                              Lists all methods available via the Kiva API.

                              Example

                              https://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

                                https://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

                                    Production

                                  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

                                    Production

                                  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

                                    Production

                                  Requires OAuth

                                  GET /my/expected_repayments

                                  Returns the expected repayments by month for the Kiva User as authorized

                                  Requires "user_expected_repayments" scope for users email address.

                                  Example

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

                                  Output

                                  { "1685602800000": { "user_repayments": "159.01", "promo_repayments": "7.43", "loans_making_repayments": "98","repayment_date": "2015-02-01 00:00:00" } }

                                  Parameters

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

                                  Response

                                    user_expected_repayments – HTML , JSON , XML

                                  Status

                                    Production

                                  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

                                    Production

                                  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
                                  per_page(number)
                                  The page position of results to return.
                                  • Default: 20
                                  sort_by(string)
                                  The order by which to sort results.
                                  • One of: popularity, loan_amount, oldest, expiration, newest, amount_remaining, repayment_term, random
                                  • Default: newest
                                  app_id(string)
                                  A unique developer-defined Application ID, usually in reverse DNS notation.

                                  Response

                                    loan – HTML , JSON , XML

                                  Status

                                    Production

                                  Requires OAuth

                                  GET /my/loans/:ids

                                  Returns detailed information for multiple loans the lender has lent to. Including defaulted and deliquent 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. Requires "user_anon_lender_loans" scope.

                                  Example

                                  https://api.kivaws.org/v1/my/loans/2930.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, random
                                  • Default: newest
                                  ids(list of numbers)
                                  Required. A list of the loan IDs for which to return detail.
                                  • Max list items: 10
                                  app_id(string)
                                  A unique developer-defined Application ID, usually in reverse DNS notation.

                                  Response

                                    loan_detail – HTML , JSON , XML

                                  Status

                                    Production

                                  Requires OAuth

                                  GET /my/loans/:ids/balances

                                  Returns amount lent and outstanding balance for a loan.

                                  Requires "user_loan_balances" scope. Possible statues: The possible statuses are: refunded, fundraising, expired, funded, in_repayment, paid, defaulted, and ended_with_loss. Loans have the status 'ended_with_loss' when currency loss has occured, which will be presented in the return values. Any currency losses have already been deducted from amounts repaid here. Currency loss values are represented as negative numbers.

                                  Example

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

                                  Output

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

                                  Parameters

                                  ids(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

                                    Production

                                  Requires OAuth

                                  GET /my/stats

                                  Returns statistics about the lender.

                                  A list of statistics about the lenders loans, donations, etc. Requires "user_stats" scope.

                                  Example

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

                                  Parameters

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

                                  Response

                                    user_stats – 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: join_date, alphabetical
                                  • Default: join_date
                                  app_id(string)
                                  A unique developer-defined Application ID, usually in reverse DNS notation.

                                  Response

                                    team – HTML , JSON , XML

                                  Status

                                    Production

                                  Requires OAuth

                                  GET /partners

                                  Returns detailed listings for all Kiva field partners.

                                  Example

                                  https://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 /partners/:ids

                                    Returns detailed information about one or more partners.

                                    Example

                                    https://api.kivaws.org/v1/partners/2.json

                                    Parameters

                                    ids(list of numbers)
                                    Required. A list of partner IDs for which to return partner detail.
                                    • Max list items: 20
                                    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

                                      https://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 /teams/:ids

                                        Returns detailed information about one or more lending teams.

                                        Example

                                        https://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

                                          https://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.
                                            ids_only(string)
                                            Return IDs only to make the return object smaller.
                                            • One of: true, false
                                            • Default: false

                                            Response

                                              lender_listing – HTML , JSON , XML , RSS

                                            Status

                                              Production

                                            GET /teams/:id/loans

                                            Returns loans belonging to a particular team.

                                            Example

                                            https://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.
                                              ids_only(string)
                                              Return IDs only to make the return object smaller.
                                              • One of: true, false
                                              • Default: false

                                              Response

                                                loan_listing – HTML , JSON , XML , RSS

                                              Status

                                                Production

                                              GET /teams/search

                                              Sort through the list of lending teams using multiple criteria.

                                              Example

                                              https://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.
                                                ids_only(string)
                                                Return IDs only to make the return object smaller.
                                                • One of: true, false
                                                • Default: false

                                                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

                                                https://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.
                                                  ids_only(string)
                                                  Return IDs only to make the return object smaller.
                                                  • One of: true, false
                                                  • Default: false

                                                  Response

                                                    team_detail – HTML , JSON , XML

                                                  Status

                                                    Production

                                                  GET /templates/images

                                                  Lists all URL templates useful for fetching images on Kiva.

                                                  Example

                                                  https://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

                                                    Kiva
                                                    • © 2009 - 2018 Kiva. All rights reserved.
                                                    • Terms Of Service
                                                    • Kiva is a 501(c)(3) nonprofit.