Skip to content
/
Managing Borrower Identit...
Last updated

Managing Borrower Identities

This guide demonstrates how to manage borrower identities in the Peach platform by continuing with our borrower James Smith (created in the Quickstart guide). We'll explore adding and managing multiple forms of identification beyond his primary SSN.

Overview

Every borrower in Peach has:

  • One primary identity (like James' SSN)
  • Optional secondary identities (like driver's licenses or passports)
  • An immutable link between primary identity and borrower profile

Prerequisites

Before starting, ensure you have:

  • A Peach account with API access
  • Your API key
  • A personId (borrower Id)

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

Retrieving Identities

Let's first check James' current identity information.

Get Primary Identity

Retrieve James primary SSN identity:

GET /people/{personId}/identity
X-API-KEY: <YOUR-API-KEY>

Response:

{
  "status": 200,
  "message": "Success",
  "data": {
    "id": "ID-ABCD-1234",
    "object": "identity",
    "identityType": "SSN",
    "value": "111111111",
    "valid": true,
    "isPrimary": true,
    "isArchived": false,
    "createdAt": "2024-12-11T10:30:00Z",
    "updatedAt": "2024-12-11T10:30:00Z"
  }
}

List All Identities

Let's check if James has any secondary identities:

GET /people/{personId}/identities
X-API-KEY: <YOUR-API-KEY>

Currently, this will only return his SSN since we haven't added any secondary identities yet.

Adding James' Driver's License

Now let's add James' driver's license as a secondary form of identification:

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

{
  "identityType": "driversLicense",
  "value": "TX123456789",
  "valid": true,
  "issueDate": "2023-01-15",
  "expirationDate": "2027-01-15",
  "issuingCountry": "US",
  "isPrimary": false
}

Response:

{
  "status": 200,
  "message": "Success",
  "data": {
    "id": "ID-EFGH-5678",
    "object": "identity",
    "identityType": "driversLicense",
    "value": "TX123456789",
    "valid": true,
    "issueDate": "2023-01-15",
    "expirationDate": "2027-01-15",
    "issuingCountry": "US",
    "isPrimary": false,
    "isArchived": false,
    "createdAt": "2024-12-11T11:15:00Z",
    "updatedAt": "2024-12-11T11:15:00Z"
  }
}

Save the returned id (ID-EFGH-5678) - we'll need it for future operations for the personIdentityId path parameter.

Updating Identity Information

Let's say James moved to a new address and got an updated driver's license number:

PUT /people/{personId}/identities/{personIdentityId}
X-API-KEY: <YOUR-API-KEY>
Content-Type: application/json

{
  "value": "TX987654321",
  "issueDate": "2024-12-11",
  "expirationDate": "2028-12-11"
}

Note that we can't change:

  • The identity type (it remains a driver's license)
  • The primary status (it stays secondary)
  • The issuing country

Archiving Outdated Identities

When James's old driver's license is replaced, we should archive it:

DELETE /people/{personId}/identities/{personIdentityId}
X-API-KEY: <YOUR-API-KEY>

Identity Types Reference

When adding secondary identities, you can use these types:

  • SSN (Social Security Number - typically only used for primary identity)
  • driversLicense (Driver's License)
  • passport (Passport)
  • alienRegistration (Alien Registration)
  • customID (Custom identification type)

For custom IDs, always include a descriptive name:

{
  "identityType": "customID",
  "customIdentityTypeName": "StateID",
  "value": "ST123456"
}

Best Practices

  1. Document Verification

    • Verify identity documents before adding them to Peach
    • Set valid: true only after verification
    • Include accurate issue and expiration dates

  2. Identity Management

    • Archive outdated identities
    • Track identity changes with case IDs
    • Keep expiration dates current

  3. Error Prevention

    • Verify identity types match your documents
    • Include all required fields for your chosen identity type
    • Handle expired documents appropriately

See also

Previous page
Next page