> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pylon.mortgage/llms.txt
> Use this file to discover all available pages before exploring further.

# Servicers

> Understanding the servicers on a loan - the servicer Contact records exposed by Loan.servicers

# What are Servicers?

**Servicers** are the servicer contacts associated with a loan. They are exposed through the `servicers` field on a **Loan**, which returns a list of **Contact** records. A servicer contact represents the company (and, where known, the individual) responsible for servicing the loan — collecting payments, managing escrow, and handling borrower communication after closing.

Every servicer contact is a **Contact** record with its `role` set to `SERVICER`. The same `Contact` shape is used across the API for other roles, so the `role` field is what distinguishes a servicer contact from other kinds of contacts on a loan.

<Info>
  **On each `Contact`, only `id` is guaranteed to be present.** Every other
  field — including `role`, `firstName`, `companyName`, `email`, and the entire
  `address` object — can be `null`. Always code defensively and treat every
  non-`id` field as optional. A loan with no servicer contacts returns `[]`.
</Info>

## Why does the servicers list exist?

Loan servicing is handled by one or more parties whose contact details a consuming application frequently needs to display or route to. Exposing servicers as a list of `Contact` records on the loan lets you:

1. **Identify the servicer** - Read the company and individual name parts to show who is servicing the loan.
2. **Contact the servicer** - Use the validated `email` and `phoneNumber` fields to reach the servicer.
3. **Verify licensing** - Read the company and individual license number and issuing state where compliance requires it.
4. **Locate the servicer** - Use the nested `address` object for mailing and correspondence.

## Nullability

Within each `Contact`, the only field guaranteed to be present is `id`. Every other field — name parts, company, contact details, licensing, and the entire nested `address` — may be `null`.

**Implications:** Never assume a field is populated. Guard against `null` on every field you read, and be prepared for a `Contact` that contains nothing but an `id`.

<Warning>
  **Do not build required logic on any non-`id` field.** Because only `id` is
  guaranteed, a servicer `Contact` may arrive with a `null` `companyName`,
  `email`, `role`, or `address`. Rendering and routing must degrade gracefully
  when a field is absent.
</Warning>

## Querying servicers

```graphql theme={null}
query LoanServicers($loanId: ID!) {
  loan(id: $loanId) {
    id
    servicers {
      id
      role
      firstName
      middleName
      lastName
      companyName
      email
      phoneNumber
      companyLicenseNumber
      companyLicenseState
      individualLicenseNumber
      individualLicenseState
      address {
        line
        line2
        city
        state
        zipCode
        country
      }
    }
  }
}
```

## Contact fields

Each entry in `Loan.servicers` is a `Contact`. Servicer contacts have `role: SERVICER`.

| Field                     | Type                | Description                                     |
| ------------------------- | ------------------- | ----------------------------------------------- |
| `id`                      | ID (always present) | Contact identifier — the only guaranteed field. |
| `role`                    | enum                | `SERVICER` for servicer contacts.               |
| `firstName`               | String              | Contact name part.                              |
| `middleName`              | String              | Contact name part.                              |
| `lastName`                | String              | Contact name part.                              |
| `companyName`             | String              | Company the contact is from.                    |
| `email`                   | String              | Email (validated).                              |
| `phoneNumber`             | String              | Phone (validated US).                           |
| `companyLicenseNumber`    | String              | Company's license number.                       |
| `companyLicenseState`     | enum                | State that issued the company license.          |
| `individualLicenseNumber` | String              | Individual's license number.                    |
| `individualLicenseState`  | enum                | State that issued the individual license.       |
| `address`                 | object              | Nested address (below).                         |

### Nested `address`

The `address` object and all of its fields are nullable.

| Field     | Type   | Description                  |
| --------- | ------ | ---------------------------- |
| `line`    | String | Street address.              |
| `line2`   | String | Street address, second line. |
| `city`    | String | City.                        |
| `state`   | enum   | State.                       |
| `zipCode` | String | ZIP code.                    |
| `country` | enum   | Country.                     |

## Key concepts to remember

<AccordionGroup>
  <Accordion title="Servicers are Contact records with role SERVICER">
    `Loan.servicers` returns a list of `Contact` records. The `role` field is
    set to `SERVICER`, which is how a servicer contact is distinguished from
    other contacts that share the same `Contact` shape.
  </Accordion>

  <Accordion title="Only id is guaranteed">
    Within each `Contact`, only `id` is guaranteed to be present. Every other
    field, including the entire nested `address`, can be `null`. Code
    defensively.
  </Accordion>
</AccordionGroup>

## Related entities

For more information on related entities, see the [GraphQL API Reference](https://pylon.mortgage/documentation/graphql/index.html):

* **Loan** - The loan whose `servicers` field exposes the servicer contacts.
* **Contact** - The record type returned for each servicer; servicer contacts have `role: SERVICER`.