Onboard an installment loan

This guide walks you from credentials-in-hand to an originated, activated, funded installment loan, using the same public API you call in production. Run every call in this guide against the sandbox host. By the end you have an active installment loan that has disbursed principal and, optionally, taken its first payment.

Do this in the sandbox. For how the sandbox is provisioned, the environment model, and the payment failure path, see Sandbox and test data — this guide does not restate them. It covers line-of-credit onboarding nowhere; for a line of credit and its draws, see Onboard a line of credit.

• An API key. Sent in the X-API-KEY header on every request. See Credentials and access.
• The sandbox base URL. https://sandboxapi.peach.finance/api. See Portals and environments for the host model.
• An installment loanTypeId. Configured by Peach and handed to you during onboarding — you cannot create or list loan types through the public API. See Credentials and access. This guide uses the placeholder LT-AAAA-BBBB.
• The borrower, loan, and loan-type concepts. See Core concepts.

Your loan type must be configured before any of these calls succeed. Loan creation resolves the loan type's asset type and the company's default investor; a missing asset type or a company with no default investor (and no investors passed in the request) is rejected.

Four calls take a borrower to a funded loan. The first three are required; the payment is optional.

Create the person the loan will belong to.

POST https://sandboxapi.peach.finance/api/people
X-API-KEY: <YOUR-API-KEY>
Content-Type: application/json

{
  "name": {
    "firstName": "Ada",
    "lastName": "Lovelace"
  },
  "identity": {
    "identityType": "SSN",
    "value": "000000000"
  }
}

The response returns a person id (for example, BO-AAAA-BBBB) with status: active. Save the id — it is the personId in every subsequent call.

This is also your first authenticated call, so treat a successful response as a smoke test: it confirms your API key, the sandbox host, and the X-API-KEY header are all correct.

Create an installment loan against your loanTypeId. Create it in originated status: the loan is signed and originated but does not accrue interest until you activate it in Step 3.

POST https://sandboxapi.peach.finance/api/people/{personId}/loans
X-API-KEY: <YOUR-API-KEY>
Content-Type: application/json

{
  "loanTypeId": "LT-AAAA-BBBB",
  "servicedBy": "creditor",
  "status": "originated",
  "atOrigination": {
    "amountFinanced": 5000,
    "duration": 12,
    "paymentFrequency": "monthly",
    "originationLicense": "nationalBank",
    "originatingCreditorName": "Example Bank",
    "interestRates": [
      { "interestType": "absolute", "days": null, "rate": 0.0899 }
    ],
    "personAddress": {
      "addressLine1": "1 Main St",
      "city": "Houston",
      "state": "TX",
      "postalCode": "77002",
      "country": "US"
    }
  }
}

For the complete field contract — every optional origination parameter, fee, and promo structure — see the Create loan endpoint in the API Reference.

An installment loan cannot be created without an address. In the create-loan request you must supply either atOrigination.personAddress (an inline address, as shown above) or atOrigination.personAddressId (the ID of an existing address contact on the borrower). Supplying neither returns a 400; supplying both is also rejected.

To reference an existing address instead of inlining one, first create an address contact on the borrower — POST /people/{personId}/contacts with contactType: address — then pass the returned contact id as atOrigination.personAddressId in the create-loan request. The personAddressId must resolve to an address-type contact on that borrower.

The response returns a loan id (for example, LN-AAAA-BBBB) with status: originated. Save the id — it is the loanId for activation.

Activate the originated loan to start it. Activation is what disburses principal and begins interest accrual. The request body is optional.

POST https://sandboxapi.peach.finance/api/people/{personId}/loans/{loanId}/activate
X-API-KEY: <YOUR-API-KEY>
Content-Type: application/json

{}

The loan must be in originated status to activate. Calling activate on a loan in any other status returns a 400. (Step 2 created the loan in originated, so it is ready.)

On activation, Peach creates the active loan schedule and periods, creates the expected payments, creates the obligation for the first period, sets the active address at origination, starts monitoring the borrower, writes the ledger entries for activation — including disbursing principal from cash to accounts receivable — and fires the loan-activated event.

Beyond disbursement, the activation call itself assesses fees only when your loan type configures them: an origination fee is booked unless the loan type charges it at origination, and any service fee is written at activation. Activation does not enrol autopay and does not itself deliver a borrower notice — it fires a loan.activated event, and any activation-notice delivery is a downstream, configuration-gated step handled by Peach's communications processing.

Activation amortizes the loan and builds its schedule. This guide does not document schedule computation or the standalone amortization-preview utility; see the amortization utility documentation.

Re-fetch the loan with GET /people/{personId}/loans/{loanId} and confirm status is now active. To confirm the disbursement moved money, check the loan balances — a disbursed loan carries an outstanding principal balance equal to the amount financed.

A payment is not required to complete origination, but you will usually want to exercise one. Create a One Time Payment transaction against the loan. A payment transaction is valid only when the loan is active (also accelerated or chargedOff in specific cases), which is why activation must come first.

POST https://sandboxapi.peach.finance/api/people/{personId}/loans/{loanId}/transactions
X-API-KEY: <YOUR-API-KEY>
Content-Type: application/json

To move money you attach a payment instrument — a card or bank account — to the borrower and reference it on the transaction. For the transaction contract, the test instruments and values, and how to drive a payment to a declined outcome, see Sandbox and test data. This guide does not restate them.

A One Time Payment requires a payment instrument. The create-transaction flow builds a one-time payment with a mandatory payment-instrument requirement and rejects the call when no instrument resolves from the paymentInstrumentId you send, so you cannot record a One Time Payment without one. (Which specific sandbox instrument values to use is a separate question — see Sandbox and test data.)

Run this whole sequence against the sandbox host and confirm each step's verify condition. For seeding wider test data, the test payment instruments, and exercising the payment failure path, see Sandbox and test data.

The request and response contracts are identical between sandbox and production — the only difference is the host you call and the credentials you use. When you move to production, point the same calls at the production base URL with production credentials. See Portals and environments for the host model and Credentials and access for environment-scoped keys.

• Onboard a line of credit — The equivalent recipe for a revolving line of credit and its draws.
• Sandbox and test data — Test instruments, magic values, and the payment failure path.
• Core concepts — The borrower, loan, and loan-type model behind these calls.