Peach Finance API (2023-11-29)

Peach Finance API

Introduction

This API is organized around REST.

Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the API in test mode, which does not affect your live data. The API key you use to authenticate the request determines whether the request is in live mode or test mode.

Pagination

Peach Finance API utilizes cursor-based pagination via the startingAfter and endingBefore parameters. Both parameters take an existing Object ID value and return objects in reverse chronological order. The endingBefore parameter returns objects listed before the named object. The startingAfter parameter returns objects listed after the named object. If both parameters are provided, only endingBefore is used.

The size of the page can be limited using the limit parameter. limit is optional; the default is 25 and can be between 1 and 100. Sending both startingBefore and endingAfter is not currently supported.

Some endpoints will allow sending a sortBy parameter, enumerating the fields that can be used to sort the results returned by that particular endpoint. For example, if the results can be sorted by createdAt and updatedAt, then sending sortBy=[updatedAt, -createdAt] will return the results sorted by updatedAt in ascending order and createdAt in descending order lexicographically.

Metadata

Some Peach objects have a metaData attribute. You can use this attribute to pass key-value data as part of an object.

Metadata can be used when you need to store additional information on an object. Metadata is not used by Peach. It is stored as part of an object and returned to you.

Do not store any personal identifiable information (such as SSN) as metadata. Use dedicated attributes for PII as these attributes are encrypted.

Note: Metadata attribute can hold up to 50 keys, with key names up to 100 characters long and values up to 500 characters long.

Attributes Formats

Some Peach attributes use common formats.

  1. Interest rate, promo rate and APR - Rates are annual. Format is decimal. For example, 0.005 is 0.5% annual rate, 0.01 is 1% annual rate, 0.2 is 20% annual rate.
  2. Dates - Dates are in format YYYY-MM-DD. Dates are computed relative to either
    • the company timezone, which is configured on the company config, or
    • the product timezone, which is configured on the Loan Type. Note: it is possible for a company to have multiple products with different timezones.
  3. Date-times - Timestamps are in ISO-8601 format expressed either in UTC like 2001-01-01T12:00:00Z or with UTC offset like 2001-01-01T12:00:00-07:00. Some date-times will include subsecond precision to an arbitrary number of digits like 2001-01-01T12:00:00.123Z.
  4. Amount - Amounts are in decimal format with 2 places after the decimal point. For example, 32.45 is thirty-two dollars and forty-five cents.

Identifiers

Peach objects always have unique identifiers created by Peach. Some objects support external IDs. If external ID is supported, the object will have externalId attribute. You can fetch objects using external ID (only objects that support external IDs). Peach IDs have the same format XX-YYYY-YYYY.

XX - is a prefix from the list below.

YYYY-YYYY - is a random set of numbers and letters (capital characters A-Z and digits 1-9). The digit zero is not used to avoid confusion with capital letter O.

External IDs

External IDs allows avoiding the need to map IDs between your system and Peach. You can pass your IDs when creating various objects at Peach and then use the same IDs to fetch the information back.

When fetching data with external IDs or when sending a request that requires a reference to an object using its external ID (for example, inside a body of a POST request), there is a need to add a ext- in front of the ID. This will make sure Peach knows these are external IDs being used.

For example, fetching a borrower using the external ID would look like GET /api/people/ext-MY_EXTERNAL_BORROWER_ID.

When creating objects with external IDs, the ext- prefix is not needed. For example, when creating a new borrower the body would look like:

POST /api/people
{
  "externalId" : "MY_EXTERNAL_BORROWER_ID"
  ...
}

List of Prefixes

Prefix Object
UR User
BO Borrower
BN Person Name
BI Person Identity
CT Contact
LT Loan Type
IR Investor
LN Loan
LN Loan Draw
LA Installment Advances
CP Company
TX Transaction
EV Event
EM Event Message
PT Payment Instrument
PA Payment ID
DD Document Descriptor
FT Fee Type
MS Person Monitoring Status
CS Case
CE Case Type
AP Autopay
IN Interaction
DT Do Not Interact Type
DN Do Not Interact
NT Notification Type
NO Notification
TD Template Descriptor
TV Template Version
CO Code
CR Compliance Rule
SR Service
FD FEMA Disaster Details
NT Note
CN Consent
LR Legal Representative
RL Role
PM Permission
WT Workflow Type
ST Workflow Step Type
IT Workflow Item Type
WF Workflow
WS Workflow Step
WI Workflow Workitem
VT Verification Type
VE Verification
VA Verification Attempt
OB Obligation
RE Repayment Notification Descriptor
LP Loan People
RA InterestRate
PE Period (loan)
IA Loan Investor Association
SE Settlement
RF Loan Refund
SM Statement
SA Statement Activity
SD Statement Draw Info
LF Loan Fee
AE Autopay Expected Payment
FE FEMA Disaster
TY Loan Tape Type
TA Loan Tape
MR Merchant
LS Loan Reporting Status
CA Credit Agency
CL Collection Agency
CI Card Issuer
WH Webhook
AF ACHFile Upload Monitoring
FB Funding Account Balance
BC Borrower Campaign
RN Campaign Run
CX Contact Exporter
TC Transaction Chargeback
PS Promise to Pay Plan
P2 Promise to Pay Period
LL Loan Label
AK API Key
AT AI Call Transcription Result
SU AI Call Summary Result

Events

Our system supports pull events via our REST API. You can see more information here.

Compliance Guard

Compliance Guard covers core regulatory obligations related to servicing and collections. It does not cover rules required for debt collection agencies (though some of them are applicable to creditors and servicers as a best practice.)

Compliance Guard allows you to:

  • Run real-time regulatory checks before initiating an outbound communication with a borrower. Rules cover laws on the federal level and 50 states + DC. The system runs appropriate rules based on loan type, loan status, location of a borrower, borrower status, and past communications.
  • Monitor for bankruptcy, deceased, active military, and FEMA (disasters). You can monitor for all four or any combination of the four. On hits, we automatically create "cases" with all details, block future outbound communications (if needed), and notify you about the cases.

Configuring Compliance Guard

  • Peach will configure an appropriate loan type for you. It allows us to select a predefined set of regulatory rules
  • Peach will work with you to override regulatory rules based on your risk appetite. You can "mute" rules. You can add rules. This is typically done with your legal and compliance teams.
  • Peach will work with you to add business rules based on your needs. For example, don't allow outbound debt collection calls on Sundays. This is typically done with your operations and product teams.

Implementing Compliance Guard in your system

  • You need to create borrower and loan objects in the Peach system. For more details see Borrower Management and Loans Management.
  • You need to report all communications with a borrower. Not required for monitoring. This way Peach can track all interactions with the borrower. For more details see Communicator & Interactions.
  • When sending a communication through Peach it will automatically check Compliance Guard rules to determiend if the communication is compliant. If it is not compliant, the communication will not be rejected. (Some send endpoints do not perform Compliance Guard checks, but they should be clearly marked.)
  • You can also manually check if a communication is compliant by using the Can interact endpoint.

Locks

Peach ensures consistency of the loan's ledger and balances. In order to make sure that multiple operations are not writing to the ledger at the same time, Peach uses locks to protect the consistency of the loan.

In situations where an API call affects a loan's ledger, the system will lock the loan to protect its consistency. Subsequent calls that affect that loan's ledger might return a 423 Locked status if the loan is still locked. In these cases, you can make a call to Lock Status to check if the loan is still locked.

If you are trying to make a call and get 423 Locked, consider polling on the Lock Status to check when the lock is released. Most locks are short. Some API calls (e.g. retroactive interest adjustment or payment backdate) can trigger a loan replay. Loan replays can last several minutes, during which the loan will be locked.

Sync calls

Most of the API endpoints are asynchronous by design. There are situations in which you might want to wait until the API call/operation finishes. Some API endpoints have a special query parameter called sync.

For example:

When sync=true, the call will be blocked until the async operation has finished. If the operation takes too long, you will get a 408 Request Timeout response. In that case, you need to poll on that specific operations' result. For example: if you make a call to add a Payment Instrument, and it times out, you can poll the /payment-instruments endpoint to see if the new payment instrument has been added.

Request sandbox access