# Kiva — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and explore microfinance loans, borrower profiles, and lending partners on Kiva while tracking loan details, lender contributions, and real-time impact updates. Build applications that connect users with microfinance opportunities and monitor the global lending community's progress.

**Category:** Finance & Markets | **Website:** [kiva.org/](https://kiva.org/) | **Docs:** [parse.bot/marketplace/5579d0f6-8459-4333-b4fd-1001b4dab416/kiva-org-api](https://parse.bot/marketplace/5579d0f6-8459-4333-b4fd-1001b4dab416/kiva-org-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/kiva/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get loan details

Get full details for a specific loan including description text, borrower info, repayment terms, and payment schedule. Returns a single loan object wrapped in an array. The detail object includes borrowers list, terms with repayment schedule, and journal totals.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `loan_id` | integer | Yes | The unique ID of the loan (from search_loans results). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/kiva/get-loan-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"loan_id":"<integer>"}'
```

### Get loan lenders

Get the paginated list of lenders who contributed to a specific loan. Each lender includes lender_id, name, image, whereabouts, and country_code. Newly posted fundraising loans may have zero lenders.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `loan_id` | integer | Yes | The unique ID of the loan (from search_loans results). |
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/kiva/get-loan-lenders \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"loan_id":"<integer>","page":"<integer>"}'
```

### Get loan updates

Get journal entries and progress updates posted for a specific loan. Returns a paginated list. Many loans have zero journal entries; results depend on field partner reporting frequency.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `loan_id` | integer | Yes | The unique ID of the loan (from search_loans results). |
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/kiva/get-loan-updates \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"loan_id":"<integer>","page":"<integer>"}'
```

### Get partner details

Get details for a specific Kiva field partner including financial metrics, countries served, and operational status. Returns a single partner object wrapped in an array.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `partner_id` | integer | Yes | The unique ID of the partner (from get_partners results). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/kiva/get-partner-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"partner_id":"<integer>"}'
```

### Get partners

Get the paginated list of Kiva field partners with summary information including status, rating, countries served, and financial metrics such as default rate, delinquency rate, and total amount raised.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |
| `per_page` | integer | No | Number of results per page. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/kiva/get-partners \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","per_page":"<integer>"}'
```

### Search loans

Search for loans with various filters including status, sector, country, gender, and keyword. Returns paginated results sorted by the specified order. Supports filtering by fundraising status, sector, country, and borrower gender. Each loan includes summary fields: id, name, status, sector, activity, loan_amount, location, and borrower count. Pagination via page number; sort controls result ordering.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country_code` | string | No | ISO 2-letter country code to filter by (e.g. KE, UG, PH, ID). |
| `gender` | string | No | Gender filter. |
| `page` | integer | No | Page number for pagination. |
| `per_page` | integer | No | Number of results per page. |
| `query` | string | No | Keyword search query to filter loans. |
| `sector` | string | No | Sector name to filter by (e.g. Agriculture, Food, Education, Services, Transportation). |
| `sort` | string | No | Sort order for results. |
| `status` | string | No | Loan status filter. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/kiva/search-loans \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"country_code":"<string>","gender":"<string>","page":"<integer>","per_page":"<integer>","query":"<string>","sector":"<string>","sort":"<string>","status":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.