Event Types

Once a loan is past the draft stage, all mutations to loans happen via events. The best way to understand what happened, historically, on a loan is to look at its event history.

Events are grouped into the following categories:

• Listing: Events related to adding the loan information, uploading documents, and listing the loan for sale.
• Review: Events related to purchaser review and due diligence.
• Sale: Events related to selling and committing the loan for purchase.
• Servicing: Events related to loan servicing, payment recording, setting ‘in default’, etc.
• Metadata: Amendments to the loan metadata, buyer tag amendments
• Termination: Writeoffs

Common properties

All events share a common set of properties that provide context and metadata about the event. These properties include:

• kind: The type of event (e.g., Add or ListedForSale).
• dateCreated: The timestamp when the event was created.
• id: A unique identifier for the event.
• loanId: The identifier of the loan associated with the event.
• sellerPartnerId: The identifier of the partner who is listed the loan and services it.
• sellerLoanId: The internal identifier given to the loan by the seller partner.

Structure

interface BaseEvent {
  kind: string;
  dateCreated: string; // ISO 8601 date string
  id: string; // Generated by the system, exclude from requests
  loanId: string;
  sellerPartnerId: string;
  sellerLoanId: string;
}

Listing Events

Add event

The Add event signifies the creation of a new loan in the system. This event is generated when a seller partner adds a new loan for sale on the Exchange platform. This is the first event that occurs in the lifecycle of a loan.

Properties

• listingMetadata: An object containing Non-PII metadata about the listing, such as:
  • loanAmount: The principal amount of the loan.
  • percent: The percentage of the loan being listed for sale.
  • multiplier: A back office multiplier used for pricing calculations, can be left off and defaults to 1.
  • dateFunded: The date when the loan was funded.
  • listingTag: IMPORTANT The string that differentiates which program a loan belongs to, and which buyers can see the loan. This is set by the seller partner when creating the listing.
  • interestRate: The interest rate of the loan.
  • termMonths: The term of the loan in months.
  • interestOnlyPaymentAmount: The amount of the interest-only payment, if applicable.
  • principalAndInterestPaymentAmount: The amount of the principal and interest payment.
  • dateFirstPayment: The date of the first payment due.
  • datePaymentTypeConversion: The date when the payment type changes, if applicable.
  • isRefinance: A boolean indicating if the loan is a refinance.
  • serviceFee: The proposed service fee structure associated with the loan - will be finalized during sale commitment.
  • businessType: The business type of the loan (e.g., SoleProprietorship, LLC, Corporation, NonProfit, Partnership, EmployeeOwned, Other).
  • businessAddressState: The state where the business is located.
  • businessAddressCity: The city where the business is located.
  • businessEmployeeCount: The number of employees in the business.
  • businessIndustry: The 5 or 6 digit NAICS industry code representing the business industry.
  • Other data… this is a flexible structure and can include additional non-PII metadata as supported by the specific listing tag/program
• privateMetadata: This object contains PII data about the borrower and loan, such as:
  • businessName: The name of the business.
  • businessAddress: The structured address of the business.
  • c2cLeadId: The lead ID which can be tied back to CRF Connect.
  • Other data… this is a flexible structure and can include additional PII metadata as supported by the specific listing tag/program

Structure

interface LoanEventAdd extends BaseEvent {
  kind: 'Add';
  listingMetadata: {
    loanAmount?: number;
    percent?: number; // between 0 and 1
    multiplier?: number;
    dateFunded?: string; // ISO 8601 date string
    listingTag?: string;
    interestRate?: number;
    termMonths?: number;
    interestOnlyPaymentAmount?: number;
    principalAndInterestPaymentAmount?: number;
    dateFirstPayment?: string; // ISO 8601 date string
    datePaymentTypeConversion?: string; // ISO 8601 date string
    isRefinance: boolean;
    serviceFee?: ServiceFeeStructure;
    businessType: 'SoleProprietorship' | 'LLC' | 'Corporation' | 'NonProfit' | 'Partnership' | 'EmployeeOwned' | 'Other';
    businessAddressState: string; // Full state name
    businessAddressCity: string;
    businessEmployeeCount: number;
    businessIndustry: string;
    // Additional non-PII metadata fields...
  };
  privateMetadata: {
    businessName: string;
    businessAddress: Address;
    c2cLeadId?: string;
    // Additional PII metadata fields...
  };
}

type ServiceFeeStructure = {
  type: 'Flat',
  feeAnnual: number; // Flat annual fee amount, e.g., 5000 for $5,000
} | {
  type: 'PercentWithFloor',
  percentAnnual: number; // Annual fee percentage, e.g., 0.05 for 5%
  floorFeeMonthly: number; // Monthly floor fee amount, e.g., 100 for $100
}

type Address = {
  line1: string;
  line2?: string;
  city: string;
  state: string;
  postalCode: string;
};

DocumentUpload event

The DocumentUpload event indicates that a document related to the loan has been uploaded to the system. This event is generated whenever a seller partner uploads a new document for the loan, such as financial statements, tax returns, or other relevant paperwork.

Properties

• documentId: The unique identifier of the uploaded document.
• tags: An array of tags associated with the document, which can be used to categorize and identify the document type (e.g., ‘FinancialStatement’, ‘TaxReturn’, etc.). The tags are defined by the program/listing tag associated with the loan.

Structure

interface DocumentUploadEvent extends BaseEvent {
  kind: 'DocumentUpload';
  documentName: string;
  documentId: string;
  tags: string[];
}

DocumentAmend event

The DocumentAmend is used to bulk update then names and tags of multiple existing documents associated with the loan. This event is generated when a seller partner needs to amend document metadata in bulk.

Properties

• documents: An array of document amendments, each containing:
  • documentName: The existing document name
  • newDocumentName: The new name for the document
  • tags: An array of new tags to associate with the document

Structure

interface DocumentAmendEvent extends BaseEvent {
  kind: 'DocumentAmend';
  documents: {
    documentName: string;
    newDocumentName?: string; // Optional new name
    tags?: string[]; // Optional new tags
  }[];
}

DocumentRemove event

The DocumentRemove event indicates that a document related to the loan has been removed from the system. This event is generated whenever a seller partner deletes a document for the loan.

Properties

• documentName: The name of the document that was removed.

Structure

interface DocumentRemoveEvent extends BaseEvent {
  kind: 'DocumentRemove';
  documentName: string;
}

ListedForSale event

The ListedForSale event signifies that the loan has been officially listed for sale on the Exchange platform. This event is generated when a seller partner completes the listing process and makes the loan available for purchase by potential buyers.

Properties

No additional properties.

Structure

interface ListedForSaleEvent extends BaseEvent {
  kind: 'ListedForSale';
}

ListingWithdrawn event

The ListingWithdrawn event indicates that the loan listing has been withdrawn from the Exchange platform. This event is generated when a seller partner decides to remove the loan from the market, either temporarily or permanently.

Properties

No additional properties.

Structure

interface ListingWithdrawnEvent extends BaseEvent {
  kind: 'ListingWithdrawn';
}

Review Events

ReviewStart event

The ReviewStart event signifies the beginning of the review process for a loan by potential buyers. This event is generated when a buyer partner initiates the review of the loan listing. All events generated by the buyer must include a buyerPartnerId to identify which buyer is performing the action.

Properties

• saleId: The unique identifier of the sale associated with the review process. Generated by the system, exclude from requests
• buyerPartnerId: The identifier of the buyer partner who is reviewing the loan.

Structure

interface ReviewStartEvent extends BaseEvent {
  kind: 'ReviewStart';
  saleId: string;
  buyerPartnerId: string;
}

ReviewBuyerPreApproved event

The ReviewBuyerPreApproved event indicates that a buyer partner has pre-approved the loan during the review process. This event is generated when the buyer partner completes their initial assessment and decides to pre-approve the loan for purchase.

Properties

• buyerPartnerId: The identifier of the buyer partner who is pre-approving the loan.

Structure

interface ReviewBuyerPreApprovedEvent extends BaseEvent {
  kind: 'ReviewBuyerPreApproved';
  buyerPartnerId: string;
}

LoanEventReviewSellerRequest event

The LoanEventReviewSellerRequest event indicates that a seller partner has completed any remaining metadata or document changes requested by the buyer during the review process. This event is generated when the seller partner responds to buyer requests for additional information or documentation.

Properties

• buyerPartnerId: The identifier of the buyer partner who made the requests.

Structure

interface LoanEventReviewSellerRequestEvent extends BaseEvent {
  kind: 'LoanEventReviewSellerRequest';
  buyerPartnerId: string;
}

ReviewReject event

The ReviewReject event signifies that a buyer partner has rejected the loan during the review process. This event is generated when the buyer partner decides not to proceed with the purchase at this time after reviewing the loan listing.

Properties

• buyerPartnerId: The identifier of the buyer partner who is rejecting the loan.
• rejectReason: A string providing the reason for the rejection.

Structure

interface ReviewRejectEvent extends BaseEvent {
  kind: 'ReviewReject';
  buyerPartnerId: string;
  rejectReason?: string;
}

Sale Events

SaleCancelled event

The SaleCancelled event indicates that a previously initiated sale of the loan has been cancelled. This event is generated when either the buyer or seller partner decides to terminate the sale process before the loan is committed for purchase. This is also used to cancel the review process before a sale is initiated.

Properties

• saleId: The unique identifier of the sale that is being cancelled.
• buyerPartnerId: The identifier of the buyer partner involved in the cancelled sale.

Structure

interface SaleCancelledEvent extends BaseEvent {
  kind: 'SaleCancelled';
  saleId: string;
  buyerPartnerId: string;
}

SaleBuyerCommitted event

The SaleBuyerCommitted event signifies that a buyer partner has committed to purchasing the loan. This event is generated when the buyer partner finalizes their decision to buy the loan after completing the review process.

Properties

• saleId: The unique identifier of the sale associated with the commitment.
• buyerPartnerId: The identifier of the buyer partner who is committing to the purchase.
• buyerCommitmentId: The unique identifier for the buyer’s commitment to purchase the loan.
• percent: The percent agreed upon for purchase.
• multiplier: The back office multiplier agreed upon for pricing calculations agreed upon for purchase.
• serviceFee: The finalized service fee structure associated with the loan purchase.
• dateRecommendedSaleClosed: The recommended date for closing the sale.
• isSaleClosed: A boolean indicating whether the sale has been closed - the listing tag may allow the buyer to unilaterally close the sale, in which case this can be set to true by the buyer partner.

Structure

interface SaleBuyerCommittedEvent extends BaseEvent {
  kind: 'SaleBuyerCommitted';
  saleId: string;
  buyerPartnerId: string;
  buyerCommitmentId: string;
  percent: number;
  multiplier: number;
  serviceFee?: ServiceFeeStructure; // Finalized service fee structure, if there is a service fee
  dateRecommendedSaleClosed?: string; // ISO 8601 date string
  isSaleClosed?: boolean;
}

SaleSellerCommitted event

Indicates that the seller partner has committed to selling the loan to the buyer partner. This event is generated when the seller partner finalizes their decision to sell the loan after the buyer has committed to the purchase.

Properties

• saleId: The unique identifier of the sale associated with the commitment.
• buyerPartnerId: The identifier of the buyer partner involved in the sale.
• buyerCommitmentId: The unique identifier for the buyer’s commitment to purchase the loan.

Structure

interface SaleSellerCommittedEvent extends BaseEvent {
  kind: 'SaleSellerCommitted';
  saleId: string;
  buyerPartnerId: string;
  buyerCommitmentId: string;
}

SaleClosed event

The SaleClosed event signifies that the sale of the loan has been officially closed. This event is generated when both the buyer and seller partners have completed all necessary steps to finalize the transfer of ownership of the loan. It can be generated after funds are transferred, but typically it is generated when the seller commits to the sale if the listing tag allows unilateral closing.

Properties

• saleId: The unique identifier of the sale that has been closed.
• buyerPartnerId: The identifier of the buyer partner involved in the sale.
• dateSaleClosed: The date when the sale was closed.

Structure

interface SaleClosedEvent extends BaseEvent {
  kind: 'SaleClosed';
  saleId: string;
  buyerPartnerId: string;
  dateSaleClosed: string; // ISO 8601 date string
}

SaleReverted event

The SaleReverted event indicates that a previously closed sale of the loan has been reverted. This event is generated by the seller, typically at the behest of the buyer, when issues are discovered post-sale that necessitate returning the loan to the seller.

Properties

• saleId: The unique identifier of the sale that is being reverted.
• buyerPartnerId: The identifier of the buyer partner involved in the reverted sale.

Structure

interface SaleRevertedEvent extends BaseEvent {
  kind: 'SaleReverted';
  saleId: string;
  buyerPartnerId: string;
}

Servicing Events

Payment event

The Payment event signifies that a payment has been made on the loan. This event is added by the seller/servicer to record payments received from the borrower.

Properties

• datePaid: The date when the payment was made.
• paymentMetadata: An object containing details about the payment, such as:
  • unpaidPrincipalBeginningBalance: The unpaid principal balance prior to the payment.
  • unpaidInterestBeginningBalance: The unpaid interest balance prior to the payment.
  • paymentAmount: The total amount of the payment made, in dollars.
  • unpaidPrincipalEndingBalance: The unpaid principal balance after the payment.
  • unpaidInterestEndingBalance: The unpaid interest balance after the payment.
  • serviceFees: The service fees associated with the payment, in dollars.
  • principalDueBuyer: The principal amount due to the buyer, in dollars.
  • interestDueBuyer: The interest amount due to the buyer, in dollars.
  • paymentDueDate: The date the payment was due.
  • daysDelinquent: The number of days the payment is delinquent, if applicable.
  • isInDefault: A boolean indicating whether the loan is in default as of this payment.
  • lateFee: The late fee amount associated with the payment, in dollars.
  • lateFeeDueBuyer: The late fee amount due to the buyer, in dollars.
  • paymentType: The type of payment (e.g., ‘OnTime’, ‘PrePayment’, ‘CatchUp’, ‘Recovery’, ‘NonPayment’, ‘PartialPayment’, ‘BalanceUpdate’).
• isPartialMonth: A boolean indicating whether the payment covers a partial month.
• Other data… this is a flexible structure and can include additional payment metadata as supported by the specific listing tag/program

Structure

interface PaymentEvent extends BaseEvent {
  kind: 'Payment';
  datePaid: string; // ISO 8601 date string
  paymentMetadata: {
    unpaidPrincipalBeginningBalance?: number;
    unpaidInterestBeginningBalance?: number;
    paymentAmount?: number;
    unpaidPrincipalEndingBalance?: number;
    unpaidInterestEndingBalance?: number;
    serviceFees?: number;
    principalDueBuyer?: number;
    interestDueBuyer?: number;
    paymentDueDate?: string; // ISO 8601 date string
    daysDelinquent?: number;
    isInDefault?: boolean;
    lateFee?: number;
    lateFeeDueBuyer?: number;
    paymentType?: 'OnTime' | 'PrePayment' | 'CatchUp' | 'Recovery' | 'NonPayment' | 'PartialPayment' | 'BalanceUpdate';
    // Additional payment metadata fields...
  };
  isPartialMonth?: boolean;
}

PaymentAmend event

The PaymentAmend event indicates that a previously recorded payment on the loan has been amended. This event is generated when the seller/servicer needs to correct or update the details of a payment that was already recorded.

Properties

• datePaid: The date when the original payment was made.
• paymentMetadata: An object containing the amended details about the payment, the same as in the Payment event.

Structure

interface PaymentAmendEvent extends BaseEvent {
  kind: 'PaymentAmend';
  datePaid: string; // ISO 8601 date string
  paymentMetadata: PaymentEvent['paymentMetadata'];
}

PaymentRevert event

The PaymentRevert event signifies that a previously recorded payment on the loan has been reverted. This event is generated when the seller/servicer needs to undo a payment that was recorded in error. This can be tempting to use instead of PaymentAmend, but it is recommended to use PaymentAmend whenever possible to maintain a clear payment history. Reverts are for situations where the payment is further back than the most recent payment and amending would be too complex.

Properties

• revertedEventId: The unique identifier of the payment event that is being reverted.

Structure

interface PaymentRevertEvent extends BaseEvent {
  kind: 'PaymentRevert';
  revertedEventId: string;
}

InDefault event

The InDefault event indicates that the loan has been marked as in default. This event is generated when the seller/servicer determines that the borrower has failed to meet the terms of the loan agreement, such as missing payments or violating covenants.

Properties

• dateInDefault: The date when the loan was marked as in default.

Structure

interface InDefaultEvent extends BaseEvent {
  kind: 'InDefault';
  dateInDefault?: string; // ISO 8601 date string
}

Metadata Events

SellerAmend event

The SellerAmend event signifies that the seller partner has amended the metadata of the loan. This event is generated when the seller partner needs to update or correct information about the loan that is not related to payments or documents.

Properties

• listingAmendment: An object containing the amended listing metadata, refer to the listingMetadata property in the Add event for possible fields.
• privateAmendment: An object containing the amended private metadata, refer to the privateMetadata property in the Add event for possible fields.

Structure

interface SellerAmendEvent extends BaseEvent {
  kind: 'SellerAmend';
  listingAmendment?: Partial<LoanEventAdd['listingMetadata']>;
  privateAmendment?: Partial<LoanEventAdd['privateMetadata']>;
}

BuyerTagAmend event

The BuyerTagAmend event indicates that the buyer tag associated with the loan has been amended. This event is hidden from seller partners and is used exclusively by buyer partners to update the buyer tag for the loan for organizational purposes.

Properties

• buyerPartnerId: The identifier of the buyer partner who is amending the buyer tag.
• tags: An array of new tags to associate with the loan.

Structure

interface BuyerTagAmendEvent extends BaseEvent {
  kind: 'BuyerTagAmend';
  buyerPartnerId: string;
  tags: string[];
}

Termination Events

WrittenOff event

The WrittenOff event signifies that the loan has been written off. This event is generated when the seller/servicer determines that the loan is uncollectible and decides to write it off as a loss.

Properties

• dateWrittenOff: The date when the loan was written off.

Structure

interface WrittenOffEvent extends BaseEvent {
  kind: 'WrittenOff';
  dateWrittenOff: string; // ISO 8601 date string
}