Skip to content
/
Borrower Quickstart Guide
Last updated

Borrower Quickstart Guide

This guide walks you through creating and setting up a borrower in the Peach platform. We'll follow a sample borrower, James Smith, through the essential setup process.

You can also do this through the sandbox Agent Portal. This quickstart covers the API approach.

Prerequisites

Before starting this guide, ensure you have:

  • A Peach account with API access
  • Your API key
  • Basic familiarity with REST APIs

Note: The following examples use commonly used fields, but for full details, including additional data and parameters, refer to the API Reference.

Step 1: Create a Borrower

First, let's create a borrower and provide the borrower data.

Request

POST /api/people
X-API-KEY: <YOUR-API-KEY>
Content-Type: application/json

{
    "borrowerType": "person",
    "externalId": "BORROWER-12345",
    "status": "active",
    "name": {
        "firstName": "James",
        "lastName": "Smith"
    },
    "dateOfBirth": "1990-01-01",
    "identity": {
        "identityType": "SSN",
        "value": "123-45-6789"
    }
}

Response

{
    "status": 200,
    "data": {
        "createdAt": "2024-12-03T18:16:08.286549+00:00",
        "updatedAt": "2024-12-03T18:16:08.816137+00:00",
        "deletedAt": null,
        "id": "BO-1212-ABAB",
        "object": "person",
        "externalId": "BORROWER-12345",
        "companyId": "CP-3434-EF12",
        "status": "active",
        "statusUpdatedAt": null,
        "borrowerType": "person",
        "identities": [
            {
                "createdAt": "2024-12-03T18:16:08.819842+00:00",
                "updatedAt": "2024-12-03T18:16:08.819850+00:00",
                "deletedAt": null,
                "id": "BI-RGMP-9RZB",
                "object": "identity",
                "identityType": "SSN",
                "valid": true,
                "value": "ct7klq70kahc73d6mel0",
                "isPrimary": true,
                "isArchived": false,
                "issueDate": null,
                "expirationDate": null,
                "issuingCountry": "",
                "customIdentityTypeName": null
            }
        ],
        "monitorStartDate": "2024-12-03",
        "collectionsIntensity": "normal",
        "commPreferences": {
            "sendRemindersWhenCurrent": true,
            "statementDeliveryChannels": []
        },
        "displayId": "BO-1212-ABAB",
        "user": null,
        "metaData": null,
        "dateOfBirth": "1990-01-01",
        "name": {
            "createdAt": "2024-12-03T18:16:08.296616+00:00",
            "updatedAt": "2024-12-03T18:16:08.296626+00:00",
            "deletedAt": null,
            "id": "BN-T678-EO6J",
            "object": "name",
            "status": "active",
            "prefix": null,
            "firstName": "James",
            "middleName": null,
            "lastName": "Smith",
            "maidenLastName": null,
            "suffix": null,
            "preferredFirstName": null,
            "effectiveAt": null,
            "originalValue": {},
            "source": "lender",
            "current": true
        }
    },
    "message": "Created person 269470"
}

Verify: Confirm the response includes id in the data object and that status is active.

Take note of the id (BO-1212-ABAB) as you'll need it for subsequent requests.

Step 2: Add Contact Information

Next, let's add James' contact details. We'll add his home address, email, and phone number.

Add Home Address

POST /api/people/{personId}/contacts
X-API-KEY: <YOUR-API-KEY>
Content-Type: application/json

{
  "contactType": "address",
  "label": "home",
  "affiliation": "self",
  "status": "primary",
  "address": {
    "addressLine1": "1 Main St",
    "addressLine2": "",
    "city": "Houston",
    "state": "TX",
    "postalCode": "77002",
    "country": "US"
  }
}

Verify: Run GET /api/people/{personId}/contacts to confirm the home address appears.

Add Email Address

POST /api/people/{personId}/contacts
X-API-KEY: <YOUR-API-KEY>
Content-Type: application/json

{
  "contactType": "email",
  "label": "personal",
  "affiliation": "self",
  "status": "primary",
  "value": "elmer.jones@example.com",
  "valid": true,
  "verified": true
}

Verify: Run GET /api/people/{personId}/contacts to confirm the email contact was created.

Note: Since we previously sent James a verification code in a external system we can mark this email address as verified=true. The same goes for his phone number.

Add Phone Number

POST /api/people/{personId}/contacts
X-API-KEY: <YOUR-API-KEY>
Content-Type: application/json

{
  "contactType": "phone",
  "label": "mobile",
  "affiliation": "self",
  "status": "primary",
  "value": "+14155551234",
  "valid": true,
  "verified": true,
  "receiveTextMessages": true
}

Verify: Run GET /api/people/{personId}/contacts to confirm the phone contact was created.

Step 3: Set Up Payment Instrument

Now let's add James' bank account as a payment instrument.

POST /api/people/{personId}/payment-instruments
X-API-KEY: <YOUR-API-KEY>
Content-Type: application/json

{
  "status": "active",
  "verified": false,
  "nickname": "Personal Checking",
  "instrumentType": "bankAccount",
  "accountNumber": "1232323",
  "routingNumber": "021313103",
  "accountType": "checking",
  "accountHolderType": "personal",
  "accountHolderName": "James Smith"
}

Verify: Run GET /api/people/{personId}/payment-instruments to confirm the bank account was added.

Step 4: Create User Account

Finally, let's create a user account so James can access the Borrower Portal.

POST /api/companies/{companyId}/users
X-API-KEY: <YOUR-API-KEY>
Content-Type: application/json

{
  "userType": "borrower",
  "authType": {
    "email": "james.smith@example.com"
  },
  "roles": [
    "ROLE-BORROWER-DEFAULT"
  ],
  "associatedPersonId": "BO-1212-ABAB"
}

Verify: Confirm the response includes a user id and that userType is borrower.

Note: You need to have configured a role previously to reference it here. Contact Peach support if you don't know which roles you should reference.

Next steps

  • Contact Information — Add additional emails and phone numbers to the borrower record.
  • Identities — Attach identity documents like SSN or driver's license.
Previous page
Next page