# 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


```http
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


```json
{
    "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


```http
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


```http
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


```http
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.


```http
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.


```http
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](/borrowers/contact-information)** — Add additional emails and phone numbers to the borrower record.
- **[Identities](/borrowers/identities)** — Attach identity documents like SSN or driver's license.