# Pioneer Loan Platform API

# Pioneer Public API

The Pioneer API allows third-party systems to programmatically access loan data,
documents, and related entities.

## URL Structure

API requests use environment-specific domains (following existing portal pattern):

```
Production:  https://{api-portal}.{bank-domain}/api/public/{resource}
Staging:     https://{api-portal}.staging.{bank-domain}/api/public/{resource}
Dev:         https://{api-portal}.dev.{bank-domain}/api/public/{resource}
```

- **Production**: `https://api.pioneerft.com/api/public/...` (use `pk_live_*` keys)
- **Staging**: `https://api.staging.pioneerft.com/api/public/...` (use `pk_test_*` keys)
- **Dev** (Pioneer only): `https://api.dev.pioneerft.com/api/public/...` (use `pk_test_*` keys)

## Authentication

All API requests require authentication using an API key. Include your API key
in the `Authorization` header:

```
Authorization: Bearer pk_live_your_api_key_here
```

**Key Types:**
- `pk_test_*` - Test keys (only work on staging/dev URLs)
- `pk_live_*` - Live keys (only work on production URLs - no env prefix)

API keys can be generated in the Pioneer dashboard under Organization Settings.
Note: Production keys require explicit approval from Pioneer.

## Rate Limiting

API requests are limited to **100 requests per minute** per API key.
Rate limit information is included in response headers:

- `X-RateLimit-Limit`: Maximum requests per window
- `X-RateLimit-Remaining`: Requests remaining in current window
- `X-RateLimit-Reset`: Unix timestamp when window resets

When rate limited, you'll receive a `429 Too Many Requests` response with
a `Retry-After` header indicating seconds to wait.

**⚠️ Important:** Production API keys (`pk_live_*`) that exceed rate limits
3 or more times within 24 hours will be automatically revoked, and your
organization's production API access will be disabled. Contact Pioneer
support to re-enable access.

## Pagination

List endpoints support pagination via query parameters:

- `limit`: Number of items to return (default: 50, max: 100)
- `offset`: Number of items to skip

Response includes pagination metadata:

```json
{
  "data": [...],
  "meta": {
    "total": 150,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}
```

## Errors

Errors are returned with appropriate HTTP status codes and JSON body:

```json
{
  "code": "auth.invalid_key",
  "message": "Invalid or expired API key"
}
```

Common error codes:
- `auth.invalid_key`: API key is invalid or expired
- `auth.org_mismatch`: API key does not belong to the organization in the URL
- `auth.env_mismatch`: API key type does not match URL environment
- `auth.env_not_available`: Environment not available for this organization
- `auth.insufficient_permissions`: API key lacks required permission
- `auth.country_restricted`: Request IP not allowed for this API key
- `api_key.production_not_allowed`: Organization not approved for production API keys
- `input.invalid`: Request validation failed
- `rate_limit.exceeded`: Too many requests

Version: 1.0.0
License: Proprietary

## Servers

Production (pk_live_* keys)
```
https://api.pioneerft.com/api
```

Staging (pk_test_* keys)
```
https://api.staging.pioneerft.com/api
```

## Security

### ApiKeyAuth

API key obtained from Pioneer dashboard. Format: pk_live_xxx or pk_test_xxx

Type: http
Scheme: bearer
Bearer Format: API Key

## Download OpenAPI description

[Pioneer Loan Platform API](https://docs.pioneerft.com/_bundle/apis/public-api.yaml)

## Loans

Access loan data including details, summaries, and related entities

### List loans

 - [GET /public/loans](https://docs.pioneerft.com/apis/public-api/loans/listloans.md): Retrieve a paginated list of loans. Supports filtering by status and product ID.

### Get loan details

 - [GET /public/loans/{id}](https://docs.pioneerft.com/apis/public-api/loans/getloan.md): Retrieve detailed information about a specific loan by ID.

### Get loan summary

 - [GET /public/loans/{id}/summary](https://docs.pioneerft.com/apis/public-api/loans/getloansummary.md): Retrieve a summary of a loan including key metrics.

### Get loan entities

 - [GET /public/loans/{id}/entities](https://docs.pioneerft.com/apis/public-api/loans/getloanentities.md): Retrieve businesses and people associated with a loan. Sensitive data like full SSN/EIN is excluded.

### Search loans

 - [POST /public/loans/search](https://docs.pioneerft.com/apis/public-api/loans/searchloans.md): Advanced loan search with complex filtering capabilities including status, date ranges, and amounts.

## Documents

List and download loan documents

### List loan documents

 - [GET /public/loans/{id}/documents](https://docs.pioneerft.com/apis/public-api/documents/listloandocuments.md): Retrieve a list of documents associated with a loan.

### Get document download URL

 - [GET /public/documents/{id}/download](https://docs.pioneerft.com/apis/public-api/documents/getdocumentdownloadurl.md): Get a presigned download URL for a document. URL is valid for 5 minutes.

## Products

List available loan products

### List products

 - [GET /public/products](https://docs.pioneerft.com/apis/public-api/products/listproducts.md): Retrieve a list of available loan products.

### Get product details

 - [GET /public/products/{id}](https://docs.pioneerft.com/apis/public-api/products/getproduct.md): Retrieve detailed information about a specific loan product by ID.