{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Managing Borrower Identities","siteUrl":"https://docs.peachfinance.com","description":"API and product documentation for Peach Finance, a lending-as-a-service platform.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"managing-borrower-identities","__idx":0},"children":["Managing Borrower Identities"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every borrower in Peach has:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["One primary identity (like James' SSN)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Optional secondary identities (like driver's licenses or passports)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An immutable link between primary identity and borrower profile"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":2},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before starting, ensure you have:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A Peach account with API access"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your API key"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A personId (borrower Id)"]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note"]},": The following examples use commonly used fields, but for full details, including additional data and parameters, refer to the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/api-docs/api-public"},"children":["API Reference"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retrieving-identities","__idx":3},"children":["Retrieving Identities"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Let's first check James' current identity information."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get-primary-identity","__idx":4},"children":["Get Primary Identity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve James primary SSN identity:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /people/{personId}/identity\nX-API-KEY: <YOUR-API-KEY>\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Response:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"status\": 200,\n  \"message\": \"Success\",\n  \"data\": {\n    \"id\": \"ID-ABCD-1234\",\n    \"object\": \"identity\",\n    \"identityType\": \"SSN\",\n    \"value\": \"111111111\",\n    \"valid\": true,\n    \"isPrimary\": true,\n    \"isArchived\": false,\n    \"createdAt\": \"2024-12-11T10:30:00Z\",\n    \"updatedAt\": \"2024-12-11T10:30:00Z\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"list-all-identities","__idx":5},"children":["List All Identities"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Let's check if James has any secondary identities:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /people/{personId}/identities\nX-API-KEY: <YOUR-API-KEY>\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Currently, this will only return his SSN since we haven't added any secondary identities yet."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"adding-james-drivers-license","__idx":6},"children":["Adding James' Driver's License"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now let's add James' driver's license as a secondary form of identification:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /people/{personId}/identities\nX-API-KEY: <YOUR-API-KEY>\nContent-Type: application/json\n\n{\n  \"identityType\": \"driversLicense\",\n  \"value\": \"TX123456789\",\n  \"valid\": true,\n  \"issueDate\": \"2023-01-15\",\n  \"expirationDate\": \"2027-01-15\",\n  \"issuingCountry\": \"US\",\n  \"isPrimary\": false\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Response:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"status\": 200,\n  \"message\": \"Success\",\n  \"data\": {\n    \"id\": \"ID-EFGH-5678\",\n    \"object\": \"identity\",\n    \"identityType\": \"driversLicense\",\n    \"value\": \"TX123456789\",\n    \"valid\": true,\n    \"issueDate\": \"2023-01-15\",\n    \"expirationDate\": \"2027-01-15\",\n    \"issuingCountry\": \"US\",\n    \"isPrimary\": false,\n    \"isArchived\": false,\n    \"createdAt\": \"2024-12-11T11:15:00Z\",\n    \"updatedAt\": \"2024-12-11T11:15:00Z\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," (ID-EFGH-5678) - we'll need it for future operations for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["personIdentityId"]}," path parameter."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"updating-identity-information","__idx":7},"children":["Updating Identity Information"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Let's say James moved to a new address and got an updated driver's license number:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"PUT /people/{personId}/identities/{personIdentityId}\nX-API-KEY: <YOUR-API-KEY>\nContent-Type: application/json\n\n{\n  \"value\": \"TX987654321\",\n  \"issueDate\": \"2024-12-11\",\n  \"expirationDate\": \"2028-12-11\"\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note that we can't change:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The identity type (it remains a driver's license)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The primary status (it stays secondary)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The issuing country"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"archiving-outdated-identities","__idx":8},"children":["Archiving Outdated Identities"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When James's old driver's license is replaced, we should archive it:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"DELETE /people/{personId}/identities/{personIdentityId}\nX-API-KEY: <YOUR-API-KEY>\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"identity-types-reference","__idx":9},"children":["Identity Types Reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When adding secondary identities, you can use these types:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SSN"]}," (Social Security Number - typically only used for primary identity)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["driversLicense"]}," (Driver's License)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["passport"]}," (Passport)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["alienRegistration"]}," (Alien Registration)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customID"]}," (Custom identification type)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For custom IDs, always include a descriptive name:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"identityType\": \"customID\",\n  \"customIdentityTypeName\": \"StateID\",\n  \"value\": \"ST123456\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":10},"children":["Best Practices"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Document Verification"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify identity documents before adding them to Peach"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["valid: true"]}," only after verification"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include accurate issue and expiration dates"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity Management"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Archive outdated identities"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Track identity changes with case IDs"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keep expiration dates current"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Error Prevention"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify identity types match your documents"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include all required fields for your chosen identity type"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Handle expired documents appropriately"]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"see-also","__idx":11},"children":["See also"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/borrowers/payment-instruments"},"children":["Payment Instruments"]}]}," — Attach bank accounts and cards to a borrower record."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/borrowers"},"children":["Borrowers overview"]}]}," — Index of borrower-related entities and operations."]}]}]},"headings":[{"value":"Managing Borrower Identities","id":"managing-borrower-identities","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Retrieving Identities","id":"retrieving-identities","depth":2},{"value":"Get Primary Identity","id":"get-primary-identity","depth":3},{"value":"List All Identities","id":"list-all-identities","depth":3},{"value":"Adding James' Driver's License","id":"adding-james-drivers-license","depth":2},{"value":"Updating Identity Information","id":"updating-identity-information","depth":2},{"value":"Archiving Outdated Identities","id":"archiving-outdated-identities","depth":2},{"value":"Identity Types Reference","id":"identity-types-reference","depth":2},{"value":"Best Practices","id":"best-practices","depth":2},{"value":"See also","id":"see-also","depth":2}],"frontmatter":{"seo":{"title":"Managing Borrower Identities"}},"lastModified":"2026-05-01T14:33:55.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/borrowers/identities","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}