# Search borrowers

Search for borrowers. Returns same resources
as /people.

Endpoint: GET /people/search
Version: 2025-03-26
Security: oauth2, bearerAuth, apiKeyHeader

## Query parameters:

  - `_hasTheWords` (string)
    Performs fuzzy matching on all fuzzy-matchable search fields and exact matching on all
exact-matchable search fields.

For example, _hasTheWords=Rob will match a firstName of Robby a lastName of
Roberts and street address of 123 Robinson Dr.

  - `_notTheWords` (string)
    Performs fuzzy matching on all fuzzy-matchable search fields and exact matching on all
exact-matchable search fields, and ensure that entries matching that search will not
appear in results.

For example, _notTheWords=Rob will match a firstName of Robby a lastName of
Roberts and street address of 123 Robinson Dr and ensure those results are not
included in results.

  - `address` (string)
    Fuzzy matches addresses associated with a borrower. For example address=fake will match an
addressLine1 of 123 Fake St as well as a city of Fakeville.

Note that states are stored as their abbreviations, so you must search with
the abbreviation to match. For example, address=MO will match Missouri, but
address=Missouri will not.

  - `bankruptcyCourtCase` (string)
    Exactly matches a bankruptcy court case ID.

  - `borrowerType` (string)
    Exactly match the type of borrower.
    Enum: "business", "person"

  - `businessName` (string)
    Fuzzy matches the businessName or businessLegalName of business borrowers—never matches a person.

  - `caseId` (string)
    Exactly matches a case ID. Can be either the Peach ID (like CS-XXXX-XXXX) or
the external ID.

  - `city` (string)
    Fuzzy match the city in any of a borrower's addresses.

  - `dateOfBirth` (string)
    Exactly matches a borrower's date of birth. Specified like YYYY-MM-DD.

  - `email` (string)
    Fuzzy matches any of a borrower's email addresses.

  - `emailExact` (string)
    Exactly matches any of a borrower's email addresses.

  - `employeeEmail` (string)
    Fuzzy matches any of a business borrower's employees' email addresses.

  - `employeeEmailExact` (string)
    Exactly matches any of a business borrower's employees' email addresses.

  - `employeePhone` (string)
    Exactly matches any of a business borrower's employees' phone numbers.

Note that Peach currently only supports US phone numbers.

You may search with any US phone number format. For example (570)123-1234, +15701231234
are all treated as identical 570-123-1234 numbers.

  - `employeeName` (string)
    Fuzzy matches a business borrower's employee's name. This will never match a person borrower.

  - `firstName` (string)
    Fuzzy matches a borrower's first name.

  - `firstNamePartial` (string)
    Exactly matches a substring of the borrower's first name.

For example, if a borrower's first name were 'William',
- firstNamePartial=Will would match because it is exactly contained in the first name.
- firstNamePartial=lia would match because it is exactly contained in the first name.
- firstNamePartial=Bill would NOT match because, while close, it is not exactly contained in the first name.

  - `fullName` (string)
    Fuzzy matches all parts of a borrower's full name. (If the borrower is a business this will also
match against the business name and business legal name.)

  - `incorporatedState` (string)
    Exactly matches the incorporatedState of business borrowers.

  - `id` (string)
    Exactly matches a borrower's ID. Can be either the Peach ID (like BO-XXXX-XXXX) or
the external ID.

  - `interactionId` (string)
    Exactly matches the ID of an interaction sent to or receieved from the
borrower. Can be either the Peach ID (like IN-XXXX-XXXX) or the
external ID.
    Example: "IN-1234-ABCD"

  - `lastName` (string)
    Fuzzy matches a borrower's last name.

  - `lastNamePartial` (string)
    Exactly matches a substring of the borrower's last name, following the
same rules as for firstNamePartial.

  - `legalRepFirstName` (string)
    Fuzzy match the first name of any of a borrower's legal representatives.

  - `legalRepLastName` (string)
    Fuzzy match the last name of any of a borrower's legal representatives.

  - `legalRepEmail` (string)
    Fuzzy match any email of any of a borrower's legal representatives.

  - `legalRepPhone` (string)
    Exactly match any phone number of any of a borrower's legal representatives.

Note that Peach currently only supports US phone numbers.

You may search with any US phone number format. For example (570)123-1234, +15701231234
are all treated as identical 570-123-1234 numbers.

  - `loanId` (string)
    Exactly matches a loan's ID. Can be either the Peach ID (like LN-XXXX-XXXX) or
the external ID.
    Example: "LN-1234-ABCD"

  - `loanIdPartial` (string)
    Exactly matches a substring of the loan's external ID.

For example, if a loan's external ID were 6eeab840-3cbc-4c40-a19b-df3e9c040a54,
- loanIdPartial=6eeab840 would match because it is exactly contained in the external ID.
- loanIdPartial=cbc-4c40-a1 would match because it is exactly contained in the external ID.
- loanIdPartial=9bdf3e would NOT match because, while close, it is not exactly contained in the external ID.

  - `maidenName` (string)
    Fuzzy matches a borrower's maiden name.

  - `maidenNamePartial` (string)
    Exactly matches a substring of the borrower's maiden name, following the
same rules as for firstNamePartial.

  - `middleName` (string)
    Fuzzy matches a borrower's middle name.

  - `middleNamePartial` (string)
    Exactly matches a substring of the borrower's middle name, following the
same rules as for firstNamePartial.

  - `paymentMethod` (string)
    Exactly match the last four digits of the borrower's payment methods on file.

  - `phone` (string)
    Exactly matches any of a borrower's phone numbers.

Note that Peach currently only supports US phone numbers.

You may search with any US phone number format. For example (570)123-1234, +15701231234
are all treated as identical 570-123-1234 numbers.

  - `postalCode` (string)
    Exactly match the postal code in any of a borrower's addresses.

  - `state` (string)
    Exactly match the state (as an abbreviation) for any of a borrower's addresses.

Note that the full name of a state will NOT match.

  - `taxId` (string)
    Exactly matches the last four digits of any of the borrower's tax ID document numbers.
The Tax ID document is either a Social Security Number (SSN), an Individual Taxpayer
Identification Number (ITIN), or a passport number.

  - `_forceIndex` (string)
    For testing new search systems before wider deploy, specify the index to use for searching.

## Response 200 fields (application/json):

  - `data` (array)

  - `data.createdAt` (string)

  - `data.deletedAt` (string,null)

  - `data.id` (string)

  - `data.updatedAt` (string,null)

  - `data.borrowerType` (string)
    The type of borrower.
    Enum: "person", "business"

  - `data.collectionsIntensity` (string)
    Defines the maximum number of interactions per period(s) on a compliance
level related to FDCPA or state debt collection rules. Lenders can configure intensities
based on their business needs. For example, prime borrowers can be defined as light,
and a lender can define the maximum number of attempts or successful interactions to be
2 in any 7-calendar-day period.
    Enum: "light", "normal", "heavy"

  - `data.commPreferences` (object)
    The borrower's communication preferences.

  - `data.commPreferences.sendRemindersWhenCurrent` (boolean)
    When set to true, the system sends payment reminders when the loan is current.
When set to false the system sends payment reminders only when the loan is overdue.

  - `data.commPreferences.statementDeliveryChannels` (array)
    A list of channels that loan statements will be delivered.
If value(s) are not passed, the system will use the statement default channel from company's configuration.
Borrower can modify their preferences later.
    Enum: "email", "mail"

  - `data.companyId` (string)
    The unique company identifier.

  - `data.displayId` (string)
    The loan ID to show in the UI (Peach public or external).

  - `data.externalId` (string,null)
    A lender's identifier for a borrower. After the object is successfully created, a lender can use ID or externalId identifiers to fetch the object.

To fetch the object using externalId you need to add ext- to the URL.

Note: Don't add ext- to the identifier value. For example: if the external identifier is ABCDE, then pass externalId=ACBCE and NOT ext-ABCDE when creating the object.

  - `data.metaData` (object,null)
    Store any type of key/value pairs in the form of a JSON dictionary.

  - `data.monitorStartDate` (string,null)
    This attribute is only applicable to lenders who use Compliance Guard Monitor to monitor borrowers without active loans.
monitorStartDate is currently used for Bankruptcy monitoring only in the following way.

Bankruptcy:

The system will return only bankruptcy cases that were filed on or after the monitorStartDate.
If date is passed (recommended), any bankruptcy cases filed prior to the date will be filtered and not returned.
We recommend lenders to pass origination date of the earliest active loan in their system.
If date is not passed, the system will set the date equal the borrower creation date.

  - `data.status` (string)
    When a new borrower object is created, we set the value to
active by default. Set to inactive at any time.
    Enum: "active", "inactive"

  - `data.statusUpdatedAt` (string,null)
    The time of a status update.

  - `data.user` (object)

  - `data.user.createdAt` (string)

  - `data.user.deletedAt` (string,null)

  - `data.user.id` (string)

  - `data.user.updatedAt` (string,null)

  - `data.user.companyId` (string)

  - `data.user.externalId` (string,null)

  - `data.user.roleIds` (array,null)
    List of role IDs associated with this user.

  - `data.user.status` (string)
    Enum: "active", "inactive"

  - `data.user.type` (string)
    The type of user to create:

- borrower - This user allows a borrower to log in to the system.
- agent - This user allows an agent to log in to the system.
- service - This user is used in conjunction with an API key to perform background tasks.
    Enum: "borrower", "agent", "service"

  - `data.user.auths` (array)

  - `data.user.auths.authType` (string)
    Enum: "basic", "google", "oneTimeCodeEmail", "oneTimeCodeText", "SAML"

  - `data.user.auths.authValueType` (string)
    Enum: "email", "username", "phone", "samlSubjectNameId"

  - `data.user.auths.value` (string)

  - `data.user.object` (string)
    Enum: "user"

  - `data.user.userId` (number)
    The ID of the associated user

  - `data.user.userName` (string)

  - `data.dateOfBirth` (string,null)
    The date of birth.

Returned as null for callers lacking the person:read.pii permission.

  - `data.name` (object, required)
    Name of the person.

  - `data.name.createdAt` (string)

  - `data.name.current` (boolean)
    Name is flagged as current.

  - `data.name.deletedAt` (string,null)

  - `data.name.effectiveAt` (string,null)

  - `data.name.firstName` (string, required)
    A person's first name.

  - `data.name.id` (string)

  - `data.name.lastName` (string, required)
    A person's last name.

Redacted to the first initial (e.g. S.) for callers lacking the
person:read.pii permission.

  - `data.name.maidenLastName` (string,null)
    A person's maiden name, if applicable.

Redacted to the first initial (e.g. J.) for callers lacking the
person:read.pii permission.

  - `data.name.middleName` (string,null)
    A person's middle name.

Redacted to the first initial (e.g. A.) for callers lacking the
person:read.pii permission.

  - `data.name.object` (string)
    Enum: "name"

  - `data.name.originalValue` (object)
    The original value for name before an update.

  - `data.name.preferredFirstName` (string,null)
    A person's preferred first name. This name will be used for interactions
like emails, text messages, outbound calls, online portal, etc.
If no preferred name is provided, firstName will be used.

  - `data.name.prefix` (string,null)
    A person's name prefix.

  - `data.name.source` (string)
    Enum: "peach", "lender", "externalAPI"

  - `data.name.status` (string)
    Enum: "active", "inactive"

  - `data.name.suffix` (string,null)
    A person's name suffix.

  - `data.name.updatedAt` (string,null)

  - `data.object` (string)
    Enum: "person"

  - `data.identities` (array)

  - `data.identities.createdAt` (string)

  - `data.identities.customIdentityTypeName` (string)
    The name of a personal or business ID. Required if identityType=customID. This needs to be "one word"
only US (a-zA-Z) letters. No numbers.

For example: Metrica Consular Card for Mexicans living abroad.
- identityType=customID
- customIdentityTypeName=metricaConsularCard

  - `data.identities.deletedAt` (string,null)

  - `data.identities.expirationDate` (string,null)
    Date the identification expires.

  - `data.identities.id` (string)

  - `data.identities.identityType` (string)
    Personal and business identifiers that are supported.
customID can be used for personal or business IDs that are not explicitly listed as one of the enum values.
If you pass identityType=customID, a customIdentityTypeName is also required.

For example: Metrica Consular Card for Mexicans living abroad.
- identityType=customID
- customIdentityTypeName=metricaConsularCard
    Enum: "SSN", "ITIN", "passport", "driversLicense", "taxID", "FEIN", "stateID", "customID"

  - `data.identities.issueDate` (string,null)
    Date the identification was issued.

  - `data.identities.issuingCountry` (string)
    Country that issued the identification. English short name according to ISO 3166-1 standard.

  - `data.identities.object` (string)
    Enum: "identity"

  - `data.identities.updatedAt` (string,null)

  - `data.identities.valid` (boolean)
    Whether the identity is valid.

  - `data.identities.value` (string)
    The value of a personal identifier. For example, 123456789.

  - `data.identities.isArchived` (boolean)
    Determines whether the identity has been archived. By default, only non-archived
identities are shown. Cannot be changed for primary identities.

  - `data.identities.isPrimary` (boolean)
    Whether the identity is the borrower's primary identity or not. A borrower may
only have one primary identity. Primary identities can be created when
creating a borrower, or separately.

  - `search` (object)

  - `search.maxScore` (number)
    Number representing the maximum scoring result in the results.

  - `search.scores` (object)
    Object mapping result ID's to their score in the search results.