# Direct API Access ## Overview Peach's Direct API Access provides real-time data retrieval through a RESTful API interface. Built on an API-first architecture, this access method lets you integrate Peach data directly into your systems and applications. The same APIs that power Peach's internal systems are available to you—ensuring consistent data access. This guide walks you through the key aspects of using Peach's API for data access. ## Prerequisites Before integrating with Peach's API, ensure you have: * API credentials from your Peach implementation engineer * Basic familiarity with RESTful API concepts * A REST client (like Postman or cURL) for testing API calls * Understanding of your specific data access requirements * Knowledge of your external IDs (if you'll be using them for integration) ## Use Cases Peach's API supports a wide range of data access and operational scenarios: ### Data Retrieval * **Real-time Information Access**: Get real-time information on loans, borrowers, and balances to populate your own user interfaces * **Borrower and Loan Data**: Access comprehensive details about your borrowers and their loans * **Balance Information**: Retrieve current outstanding balances, paid amounts, delinquency data, and other financial details * **Transaction History**: Access recent payment data to display borrower-facing interfaces like websites or mobile apps * **Payment Instrument References**: Retrieve reference data for payment instruments to facilitate external payment processing without exposing sensitive financial information ### Webhooks * **Real-time Updates**: Receive instant notifications for events like loan status changes, payments, balance changes, and more * **Automated Actions**: Trigger actions in your system or user experience based on these events Peach's API-first strategy ensures that virtually all platform functionality is accessible through these interfaces, allowing you to build tailored integrations that precisely meet your business requirements. ## Authentication All API requests to Peach require authentication using your API key in the request header: ``` X-API-KEY: your_api_key_here ``` Your API key allows access to your organization's data. Your API Key is a *secret*. *NEVER* expose your API key publicly. ### Authentication Example ``` curl --request GET \ --url 'https://api.peachfinance.com/v1/people/{personId}/loans/{loanId}' \ --header 'X-API-KEY: your_api_key_here' ``` ## Data Access Endpoint Examples 1. **Retrieving Borrower Data** Accessing borrower information is typically the starting point for many integrations. The Borrower API provides comprehensive borrower details. **Request**: ``` GET /api/people/{personId} ``` **Response**: Upon success, Peach returns a 200 status code with the borrower data. ``` { "status": 200, "data": [ { "id": "BO-L9BN-5J52", "status": "active", "borrowerType": "person", "externalId": null, "name": { "firstName": "Bobbo", "middleName": "Frank", "lastName": "Borrower", "preferredFirstName": "Bobby" }, "dateOfBirth": "2020-12-02", "createdAt": "2019-09-26T07:41:28.442830+00:00", "identities": [ { "identityType": "SSN", "valid": true, "isPrimary": true } ] }, { "id": "BO-E9BR-GKY6", "status": "active", "borrowerType": "person", "externalId": null, "name": { "firstName": "Lenny", "lastName": "Lendee" }, "dateOfBirth": "2000-01-01", "createdAt": "2020-09-15T01:46:38.015384+00:00", "identities": [] } ], "total": 282976, "count": 2, "nextUrl": "https://api.peachfinance.com/v1/people?limit=2&startingAfter=BO-E9BR-GKY6", "previousUrl": null } ``` Use the following endpoint to retrieve a borrower using your own external ID: ``` GET /api/people/{externalId} ``` 1. **Accessing Loan Information** Loan data provides details about loan terms, status, and balances. This is essential for displaying accurate account information. Request: ``` GET /api/people/{personId}/loans/{loanId} ``` Response: ``` { "id": "LN-WXYZ-7890", "status": "active", "type": "installment", "externalId": "LOAN-54321", "atOrigination": { "amountFinanced": 5000.00, "interestRates": [{"days": null, "rate": 0.0499}], "aprEffective": 0.0512 }, "timestamps": { "activatedAt": "2023-01-20T14:30:00Z" } } ... ``` 1. **Retrieving Current Balances** The Loan Balances endpoint provides up-to-date balance information critical for accurate reporting and user interfaces. Request: ``` GET /api/people/{personId}/loans/{loanId}/balances ``` Response: ``` { "outstandingBalances": { "outstandingPrincipalAmount": 4250.75, "outstandingInterestAmount": 35.22, "outstandingFeesAmount": 0.00, "outstandingTotalAmount": 4285.97 }, "paidBalances": { "paidPrincipalAmount": 749.25, "paidInterestAmount": 89.78, "paidFeesAmount": 15.00, "paidTotalAmount": 854.03 } } ... ``` 1. **Accessing Transaction History** Transaction history provides a record of all payments and financial activities for a loan. Request: ``` GET /api/people/{personId}/loans/{loanId}/transactions ``` Parameters: * transactionType: Filter by transaction type (e.g., "payment", "serviceCredit") * status: Filter by transaction status (e.g., "succeeded", "failed") * startDate: Filter transactions from this date * endDate: Filter transactions until this date Response: ``` { "status": 200, "total": 1000, "count": 2, "nextUrl": "https://api.peachfinance.com/v1/transactions?startingAfter=TX-LAST-ID", "previousUrl": null, "data": [ { "id": "TX-ABCD-1234", "status": "scheduled", "transactionType": "payment", "actualAmount": 500.00, "scheduledAmount": 500.00, "timestamps": { "effectiveDate": "2024-03-15", "scheduledDate": "2024-03-15", "createdAt": "2024-03-01T10:00:00Z" }, "paymentDetails": { "type": "ach", "reason": "scheduledPayment", "fromInstrument": { "instrumentType": "bankAccount", "accountNumberLastFour": "8224" } }, "paidPrincipalAmount": 450.00, "paidInterestAmount": 45.00, "paidFeesAmount": 5.00 }, { "id": "TX-EFGH-5678", "status": "failed", "transactionType": "serviceCredit", "actualAmount": 100.00, "failureReason": "invalidRouting", "timestamps": { "effectiveDate": "2024-03-10", "failedAt": "2024-03-10T15:30:00Z" }, "serviceCreditDetails": { "type": "settlementOfDebt", "sponsor": "merchant", "reason": "oneTimePayment" ... } } ] } ``` 1. **Retrieving Interest Accrual Information** Use the following endpoint to retrieve interest accrual over specific periods for a loan: Request: ``` GET /api/people/{personId}/loans/{loanId}/interest?fromEffectiveDate=2023-01-01&toEffectiveDate=2023-01-31 ``` Response: ``` { "interestAccruedAmount": 42.50, "interestDiscountAmount": 5.00, "netInterestAccruedAmount": 37.50, "foregoneInterestCapAmount": 0.00 ... } ``` 1. **Accessing Case Information** For servicing and collections operations, case data is essential: Request: ``` GET /api/people/{personId}/cases ``` Response: ``` { "cases": [ { "id": "CS-IJKL-9012", "caseType": "hardship", "status": "open", "createdAt": "2023-03-10T09:15:22Z", "associatedLoans": ["LN-WXYZ-7890"] ... } ] } ``` ## See also - **[Replica Database](/data-reporting/replica-database)** — Bulk file-based delivery for reporting and analytics workloads. - **[Data Access overview](/data-reporting)** — Index of data access methods Peach offers.