Skip to content
/
Direct API Access
Last updated

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

Previous page
Next page