> ## Documentation Index > Fetch the complete documentation index at: https://docs.corafone.com/llms.txt > Use this file to discover all available pages before exploring further. # Account > Field-level reference for account responses and supported update payloads. ## Account Object Shape `GET` endpoints return an `account` object with this shape: `Can Be Updated` indicates whether the field can be sent to `PATCH /external-api/accounts/:externalId` or to an existing account through `POST /external-api/accounts/bulk-upsert`. | Field | Type | Can Be Updated | Notes | | ----------------------- | -------------------------- | -------------- | ----------------------------------------------------- | | `id` | `string` | `false` | Internal Cora account id | | `externalId` | `string` | `false` | Your external identifier | | `organizationId` | `string` | `false` | Owning organization id | | `status` | `string` | `true` | Granular account status | | `status_category` | `string` | `false` | Broader account status category derived from `status` | | `clientStatus` | `string \| null` | `true` | Freely input your own status | | `phoneNumber` | `string \| null` | `true` | Primary phone number | | `metadata` | `Metadata` | `true` | Flexible key/value object | | `person` | `Person \| null` | `true` | Person profile details | | `emailAddress` | `string \| null` | `true` | Primary email | | `currentEmailAddressId` | `string \| null` | `false` | Current email object id | | `emailAddressIds` | `string[]` | `false` | Linked email ids | | `address` | `Address \| null` | `true` | Address details | | `history` | `History \| null` | `true` | Account history payload | | `typeOfDebt` | `string \| null` | `true` | Debt classification enum | | `compliance` | `Compliance \| null` | `true` | Compliance metadata | | `paymentRules` | `PaymentRules \| null` | `true` | Payment constraints | | `bank` | `string \| null` | `true` | Name of bank the debt originated from | | `client` | `string \| null` | `true` | Name of the current client | | `originalCreditor` | `string \| object \| null` | `true` | Name of the original creditor | | `currentBalance` | `number \| string \| null` | `true` | Current balance | | `tags` | `string[]` | `true` | Tag list | | `contactInfo` | `ContactInfo \| null` | `true` | Contact preferences/details | | `smsOptOut` | `SmsOptOut \| null` | `true` | SMS opt-out details | | `createdAt` | `ISO datetime string` | `false` | Creation timestamp | | `updatedAt` | `ISO datetime string` | `false` | Last update timestamp | ## Type Definitions ### `Metadata` Type | Field | Type | Notes | | ------------ | --------- | --------------------------- | | `metadata.*` | `unknown` | Arbitrary key/value payload | ### `Person` Type | Field | Type | Notes | | ------------------- | ---------------- | ----------------------------------------- | | `person.name.first` | `string \| null` | First name | | `person.name.last` | `string \| null` | Last name | | `person.birthdate` | `string \| null` | Birth date string (commonly `YYYY-MM-DD`) | | `person.ssn` | `string \| null` | Full SSN if provided | | `person.last4SSN` | `string \| null` | Last 4 SSN digits | ### `Address` Type | Field | Type | Notes | | -------------------------- | ---------------- | --------------------- | | `address.street` | `string \| null` | Primary street line | | `address.additionalStreet` | `string \| null` | Secondary street line | | `address.city` | `string \| null` | City | | `address.state` | `string \| null` | State/province | | `address.zip` | `string \| null` | Postal code | | `address.country` | `string \| null` | Country | ### `History` Type | Field | Type | Notes | | -------------------------------- | ----------------------------- | ------------------------------------------ | | `history.origin` | `string \| null` | Source/origin description | | `history.statuteLimitationsDate` | `ISO datetime string \| null` | Statute date | | `history.accountOpened.date` | `ISO datetime string \| null` | Account opened date | | `history.lastPayment.amount` | `number \| null` | Last payment amount | | `history.lastPayment.date` | `ISO datetime string \| null` | Last payment date | | `history.placed.balance` | `number \| null` | Balance at placement | | `history.placed.principal` | `number \| null` | Principal at placement | | `history.placed.interest` | `number \| null` | Interest at placement | | `history.placed.fees` | `number \| null` | Fees at placement | | `history.placed.date` | `ISO datetime string \| null` | Placement date | | `history.chargedOff.balance` | `number \| null` | Charge-off balance | | `history.chargedOff.principal` | `number \| null` | Charge-off principal | | `history.chargedOff.interest` | `number \| null` | Charge-off interest | | `history.chargedOff.fees` | `number \| null` | Charge-off fees | | `history.chargedOff.events` | `object[] \| null` | Charge-off event list (schema is flexible) | ### `Compliance` Type | Field | Type | Notes | | ------------------ | ---------------- | ------------------------ | | `compliance.state` | `string \| null` | Compliance state context | ### `PaymentRules` Type | Field | Type | Notes | | --------------------------------- | ---------------- | ---------------------------- | | `paymentRules.maxSettlementToday` | `number \| null` | Fraction between `0` and `1` | | `paymentRules.maxSettlementPlan` | `number \| null` | Fraction between `0` and `1` | | `paymentRules.maxMonths` | `number \| null` | Max plan duration in months | | `paymentRules.maxInstallments` | `number \| null` | Max number of installments | ### `ContactInfo` Type | Field | Type | Notes | | ---------------------------- | ----------------- | ------------------------- | | `contactInfo.email.address` | `string \| null` | Email contact | | `contactInfo.email.verified` | `boolean \| null` | Email verification status | | `contactInfo.phone.number` | `string \| null` | Phone contact | | `contactInfo.phone.verified` | `boolean \| null` | Phone verification status | ### `SmsOptOut` Type | Field | Type | Notes | | ------------------------------ | ----------------------------- | ----------------------------------- | | `smsOptOut.isOptedOut` | `boolean` | Whether SMS is opted out | | `smsOptOut.optedOutAt` | `ISO datetime string \| null` | Opt-out timestamp | | `smsOptOut.optedOutReason` | `string \| null` | Opt-out reason (for example `STOP`) | | `smsOptOut.lastOptOutResponse` | `string \| null` | Last inbound opt-out text | | `smsOptOut.lookupCarrier` | `string \| null` | Carrier lookup result, if available | | `smsOptOut.lookupCarrierAt` | `ISO datetime string \| null` | Carrier lookup timestamp | ## Enumerated Values ### `status` `LOADED`, `ACTIVE`, `PAID IN FULL`, `SETTLED IN FULL`, `PAYMENTS ON FILE`, `DECLINED`, `REFUSED`, `DISPUTE`, `CHARGEBACK`, `BANKRUPTCY`, `CEASE & DESIST`, `COMPLAINT FILED`, `FRAUD`, `LAWSUIT RISK`, `DO NOT CALL`, `DECEASED`, `JAIL`, `RECALLED`, `MANAGER REVIEW`, `FOLLOW UP`, `OTHER` ### `status_category` `NEW`, `ACTIVE`, `PAID`, `PARTIAL`, `DECLINED`, `REFUSED`, `LEGAL_HOLD`, `CLOSED`, `ADMIN` `status_category` is returned by account GET endpoints and is derived from `status`. Use `status`, not `status_category`, when updating an account through `PATCH /external-api/accounts/:externalId` or `POST /external-api/accounts/bulk-upsert`. ### `typeOfDebt` `credit_card`, `personal_loan`, `payday_loan`, `installment_loan`, `line_of_credit`, `auto_loan`, `auto_lease`, `medical`, `dental`, `utility`, `telecom`, `mortgage`, `rent`, `hoa`, `student_loan_private`, `student_loan_federal`, `retail_financing`, `bnpl`, `business_loan`, `commercial`, `parking_private`, `tolls`, `gym_membership`, `subscription`, `club_dues`, `municipal_fines`, `court_fines`, `taxes`, `nsf_check`, `other` ## Updatable Top-Level Fields PATCH and bulk updates to existing accounts accept these top-level fields: * `status` * `clientStatus` * `metadata` * `person` * `emailAddress` * `address` * `history` * `typeOfDebt` * `compliance` * `paymentRules` * `bank` * `client` * `originalCreditor` * `currentBalance` * `tags` * `contactInfo` * `smsOptOut` * `phoneNumber` For PATCH, if no valid field is provided, API returns: * `400` * `code: NO_VALID_UPDATABLE_FIELDS` For bulk upsert, an existing account with no changed updatable fields is reported as `unchanged`. A new account must include the creation fields documented in [Bulk upsert accounts](/accounts-bulk-upsert). ## Request Body Shapes Both payload shapes are supported. Direct: ```json theme={null} { "status": "ACTIVE", "metadata": { "externalSystem": "crm-a" } } ``` Wrapped: ```json theme={null} { "update": { "status": "ACTIVE", "metadata": { "externalSystem": "crm-a" } } } ``` ## Update Tracking Behavior For successful PATCH updates and successful bulk updates to existing accounts: * Account changes are written to account `auditTrail` with source `EXTERNAL_API` * Timeline event `ACCOUNT_UPDATED` with source `EXTERNAL_API` is created * Response includes updated account identity and timestamp ## Common Response Envelope Success: ```json theme={null} { "success": true, "code": "ACCOUNT_UPDATED", "message": "Account updated successfully", "account": { "id": "ACCOUNT_ID", "externalId": "FILE_123", "organizationId": "ORG_ID", "updatedAt": "2026-02-23T12:45:00.000Z" } } ``` Error: ```json theme={null} { "success": false, "code": "ACCOUNT_NOT_FOUND", "message": "Account not found" } ```