Account - Corafone Docs

Account Object Shape

GET endpoints return an account object with this shape:

Field	Type	Notes
`id`	`string`	Internal Cora account id
`externalId`	`string`	Your external identifier
`organizationId`	`string`	Owning organization id
`status`	`string`	Account status
`clientStatus`	`string \| null`	Client-specific status
`phoneNumber`	`string \| null`	Primary phone number
`metadata`	`Metadata`	Flexible key/value object
`person`	`Person \| null`	Person profile details
`emailAddress`	`string \| null`	Primary email
`currentEmailAddressId`	`string \| null`	Current email object id
`emailAddressIds`	`string[]`	Linked email ids
`address`	`Address \| null`	Address details
`history`	`History \| null`	Account history payload
`typeOfDebt`	`string \| null`	Debt classification enum
`compliance`	`Compliance \| null`	Compliance metadata
`paymentRules`	`PaymentRules \| null`	Payment constraints
`bank`	`string \| null`	Banking metadata
`client`	`string \| null`	Client metadata
`originalCreditor`	`string \| object \| null`	Creditor info
`currentBalance`	`number \| string \| null`	Current balance
`tags`	`string[]`	Tag list
`contactInfo`	`ContactInfo \| null`	Contact preferences/details
`smsOptOut`	`SmsOptOut \| null`	SMS opt-out details
`createdAt`	`ISO datetime string`	Creation timestamp
`updatedAt`	`ISO datetime string`	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`

NEW, ACTIVE, PAID, PARTIAL, DECLINED, LEGAL_HOLD, CLOSED, ADMIN, PAUSED, REFUSED

`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 accepts only these top-level fields:

status
clientStatus
metadata
person
emailAddress
address
history
typeOfDebt
compliance
paymentRules
bank
client
originalCreditor
currentBalance
tags
contactInfo
smsOptOut
phoneNumber

If no valid field is provided, API returns:

400
code: NO_VALID_UPDATABLE_FIELDS

Request Body Shapes

Both payload shapes are supported. Direct:

{
  "status": "ACTIVE",
  "metadata": {
    "externalSystem": "crm-a"
  }
}

Wrapped:

{
  "update": {
    "status": "ACTIVE",
    "metadata": {
      "externalSystem": "crm-a"
    }
  }
}

Update Tracking Behavior

For successful PATCH updates:

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:

{
  "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:

{
  "success": false,
  "code": "ACCOUNT_NOT_FOUND",
  "message": "Account not found"
}

Accounts

​Account Object Shape

​Type Definitions

​Metadata Type

​Person Type

​Address Type

​History Type

​Compliance Type

​PaymentRules Type

​ContactInfo Type

​SmsOptOut Type

​Enumerated Values

​status

​typeOfDebt

​Updatable Top-Level Fields

​Request Body Shapes

​Update Tracking Behavior

​Common Response Envelope