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/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.