Account - Corafone Docs

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.

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

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

​Account Object Shape

​Type Definitions

​Metadata Type

​Person Type

​Address Type

​History Type

​Compliance Type

​PaymentRules Type

​ContactInfo Type

​SmsOptOut Type

​Enumerated Values

​status

​status_category

​typeOfDebt

​Updatable Top-Level Fields

​Request Body Shapes

​Update Tracking Behavior

​Common Response Envelope