Peach Finance

Interactions

Interactions represent communications with a borrower.

Whenever Peach communicates with a borrower an interaction is recorded.

Additionally, communications taking place outside of Peach should be recorded as interactions.

Past interactions information is used by Compliance Guard to make decisions about when and how it is appropriate to communicate again with a borrower.

Create interaction

Creating interactions tracks the history of communication between lenders/servicers and borrowers.

Note that this does NOT send a message—merely tracks that it occurred. If you need to send a message, use the /communicator/send endpoint.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

query Parameters
searchable
boolean
Default: false

If true, format the entire response as one suitable for an ElasticSearch search index.

Request Body schema: application/json
required
Any of:
channel
required
string

The channel by which an interaction occurs.

Enum: "fax" "gui" "document"
content
object or null

The content and attributes of the message sent. Normally in JSON format.

id
string
createdAt
string <date-time>
updatedAt
string or null <date-time>
deletedAt
string or null <date-time>
contactId
string
personId
string or null

The ID of the borrower to which this interaction is associated

startedAt
string <date-time>

Start time of the interaction. If not provided we'll assume it's a timestamp of the API call. If time of day is not required provide only date.

For CRM-managed voice interactions, an inbound call is considered started when the CRM system answers the call, and an outbound call is considered started when the CRM system initiates the call.

scheduledAtFrom
string <date-time>

Time to start the scheduled interaction.

scheduledAtTo
string <date-time>

Time to end the scheduled interaction.

subject
string (InteractionSubject)

The subject of the interaction. The subject identifies the category of the content in the message.

Most subjects have an associated implicit theme. e.g., loanOverdueFirstNotice has a theme of opsCollDebt. For these subjects it is not necessary to specify a theme.

Some subjects like freeForm and custom<N> do not have an implicit theme. When using these subjects you must specify a theme.

Note that locStatementGenerated and locStatementRegenerated are deprecated. They will be automatically converted into statementGenerated and statementRegenerated respectively. You should should switch to those subjects directly.

Enum: "annualPrivacyPolicyNotice" "autopayAgreement" "autopayAmountChanged" "autopayCanceledBySystem" "autopayEnabled" "autopayEnableReminder" "autopayPaymentCanceled" "autopayPaymentMethodUpdated" "autopayPaymentReminder" "autopayPaymentRescheduled" "cardExpiresReminder" "caseEscalation" "ceaseCommunicationAcknowledgement" "ceaseCommunicationRefuseToPay" "confirmationCode" "contactTakeover" "creditNegativeInfoReported" "creditPositiveInfoReported" "custom1" "custom2" "custom3" "custom4" "custom5" "custom6" "custom7" "custom8" "custom9" "custom10" "custom11" "custom12" "custom13" "custom14" "custom15" "custom16" "custom17" "custom18" "custom19" "custom20" "debtValidationNotice" "debtValidationNoticeArizona" "debtValidationNoticeAutomatic" "debtValidationNoticeNYCYonkers" "debtValidationNoticePuertoRico" "deceasedConfirmationOfPayoff" "deceasedNoticeToRepresentative" "deceasedNotificationUponDeath" "disputeOfDebtConfirmed" "disputeOfDebtSubmitDocumentation" "disputeOfDebtSubmitDocumentationReminder" "disputeOfDebtUnableToConfirm" "disputeOfDebtUnableToResolve" "documentUploadFailed" "downpaymentFailed" "drawFundsDisclosure" "electronicConsentOptOut" "failedSettlementInvestor" "failedSettlementPeach" "freeForm" "freeFormBranded" "futurepayCanceled" "futurepayPaymentDueReminder" "identityTheftIncompleteDocumentation" "identityTheftNotValidated" "identityTheftSubmitDocumentation" "identityTheftSubmitDocumentationFirstReminder" "identityTheftSubmitDocumentationSecondReminder" "identityTheftValidated" "letterReturnedToSender" "loanAccelerated" "loanCanceled" "loanChargedOffUnsecured" "loanDetails" "loanFeeCharged" "loanFreeze" "loanManualPaymentDisclosure" "loanOverdueFifthNotice" "loanOverdueFirstNotice" "loanOverdueFourthNotice" "loanOverdueSecondNotice" "loanOverdueSixthNotice" "loanOverdueThirdNotice" "loanPaidOff" "loanPaymentScheduleChanged" "loanPayoffStatement" "loanRefundProcessed" "loanRightToCurePersonalUnsecured" "loanTermsChangeAgreement" "loanUnfreeze" "locCreditLimitChanged" "locInterestRateChanged" "locLineClosed" "locStatementGenerated" "locStatementRegenerated" "loginFirstPaymentReminder" "microdepositFailed" "microdepositProcessing" "microdepositReminder" "oneTimeCode" "paydayConsumerRightsNotice" "paydayFirstPaymentWithdrawal" "paymentDisputed" "paymentDueDateReminder" "paymentFailed" "paymentMethodAdded" "paymentMethodUpdated" "paymentProcessing" "paymentRescheduled" "paymentReversalFailed" "paymentReversalProcessing" "paymentSuccessful" "payoffStatementDocument" "promiseToPayPeriodKept" "promiseToPayPeriodMissed" "promiseToPayPlanCanceled" "promiseToPayPlanCreated" "promoProgramCanceled" "promoProgramEligibilityAtRisk" "promoProgramExercised" "promoProgramReminder" "reimbursementFailed" "reimbursementProcessed" "reimbursementScheduled" "scraApplicationDenied" "scraBenefitsApplied" "scraBenefitsExpiringNotice" "scraCGFlaggedDocumentRequest" "scraServicemanNotifiedDocumentRequest" "settlementOffer" "settlementOfferFirstReminder" "statement" "statementLOC" "statementGenerated" "statementRegenerated" "unmonitoredEmailAddress" "updateBankAccountConnection"
theme
required
string or null (InteractionTheme)

The reason why an interaction occurred.

For example:

  • An outbound debt collection call should be marked as opsCollDebt.
  • An annual privacy policy update email should be marked as opsServicing.
  • A customer service response to borrower's inquiry should be marked as opsServicing.
  • Statements or payment reminders should be marked as outOpsLoan.

The values inbHumanLove and inbBug are deprecated; use inbGeneralInquiry instead.

Enum: "agentNotification" "opsCollDebt" "opsCollLocateBorrower" "opsCollVerifyEmployment" "opsCollContactEmployerNotice" "opsServicingDebtValidation" "opsServicingNegativeCreditReportNotice" "opsServicingTimeBarredNotice" "opsServicing" "opsAccountCredentials" "inbMissingFeature" "inbEducation" "inbBug" "inbRequest" "inbHumanLove" "inbUnknown" "inbOther" "inbServicing" "inbCollections" "inbPayments" "inbFraud" "inbGeneralInquiry"
borrowerSelectedTheme
string or null (InteractionTheme)

The reason why an interaction occurred.

For example:

  • An outbound debt collection call should be marked as opsCollDebt.
  • An annual privacy policy update email should be marked as opsServicing.
  • A customer service response to borrower's inquiry should be marked as opsServicing.
  • Statements or payment reminders should be marked as outOpsLoan.

The values inbHumanLove and inbBug are deprecated; use inbGeneralInquiry instead.

Enum: "agentNotification" "opsCollDebt" "opsCollLocateBorrower" "opsCollVerifyEmployment" "opsCollContactEmployerNotice" "opsServicingDebtValidation" "opsServicingNegativeCreditReportNotice" "opsServicingTimeBarredNotice" "opsServicing" "opsAccountCredentials" "inbMissingFeature" "inbEducation" "inbBug" "inbRequest" "inbHumanLove" "inbUnknown" "inbOther" "inbServicing" "inbCollections" "inbPayments" "inbFraud" "inbGeneralInquiry"
status
required
string (InteractionStatus)

The status of an interaction.

status is important, as it can impact future interactions. For instance, in jurisdictions which cap the number of outbound collection communications to a borrower, status=failed interactions do not count against the legal allotment.

Interaction status can be updated as the interaction status changes. For example, when an email is sent, set the status to attempted. If the email is opened, set the status to succeeded. If the email bounces, set the status to failed. attempted is assumed to be a successful interaction. Optionally, you can also use 'statusDetails' to provide additional details about status.

In-Progress interactions

Some interactions—like an email—take place at a single point in time, others might be ongoing for many minutes—like a phone call.

Ongoing interactions like voice and chat may have their status set to inProgress.

Scheduled interactions

Some interactions might be scheduled for the future. These interactions have a status of scheduled. If this scheduled interaction is unscheduled then it has a status of canceled.

Null

Note that null is not a valid status name but rather can be used to specify a query for interactions with a status of null

Enum: "attempted" "succeeded" "failed" "scheduled" "canceled" "inProgress" "null"
statusDetails
string or null (InteractionStatusDetails)

Provides more details about the status of an interaction.

Note that statusDetails related to the "technical" status of an interaction: e.g., Did it connect? Did it fail to send? Was it blocked by Compliance Guard?

For the "human" outcome of an interaction see agentOutcome: e.g., Did you talk the person you intended to? Did the other chat recipient become unresponsive?

Status

Certain status details must have a particular status associated with them; attempting to use them otherwise will result in an error.

Succeeded

The following status details are considered status=succeeded

  • emailDelivered - The email was successfully delivered
  • emailOpened - The email was opened
  • emailClick - A link in the email was clicked
  • letterDelivered - The letter is successfully delivered
  • chatRead - The chat message was read

Attempted

The following status details are considered status=attempted.

  • voiceReceivedOutsideOpenHours - Caller tried to contact the lender outside designated business hours
  • voiceConnected - Voice call connected successfully
  • emailSent - Email was sent, but delivery cannot be confirmed
  • letterCreated - Letter is successfully created
  • letterRenderedPdf - Letter's PDF proof is successfully rendered
  • letterRenderedThumbnails - Letter's thumbnails are successfully rendered
  • letterInTransit - Letter received an "In Transit" event
  • letterInLocalArea - Letter is in the local area
  • letterProcessedForDelivery - Letter is in the local area
  • letterRerouted - Letter is re-routed
  • chatPosted - Chat message sent
  • textConvoTimeoutAutoclose - This text conversation was closed automatically due to a timeout.
  • textConvoClosedStale - (DEPRECATED) An open but outdated text conversation was closed automatically when a new text conversation was started. New text conversations should never enter into this state, but old conversations may be in this state.
  • textConvoClosedByAgent - The agent manually marked the text conversation as ended.

Failed

The following status details are considered status=failed.

Generally an interaction is failed if some part of connecting or completing the interaction failed due to a technical failure, misconfiguration, or attempt to communicate in a way disallowed by rules.

  • emailBlocked - Receiving server could not or would not accept the message temporarily
  • emailBounced - Receiving server could not or would not accept mail to this recipient permanently
  • emailDropped - Email rejected for a number of reasons: rejected as SPAM, Unsubscribed Address, Bounced Address, Email Invalid
  • emailFailedToSend - Not currently in use - reserved for future use
  • emailReportedAsSpam - Email was delivered, but later reported as SPAM by recipient
  • letterDeleted - Letter is successfully canceled
  • letterFailedToCreate - Request to create the letter failed. Provider did not return 200 OK status code
  • letterReturnedToSender - Letter is returned to the sender
  • textA2PCampaignUnregistered - The text was not sent because the lender has not registered this phone number with an A2P campaign.
  • textAccountSuspended - The account was suspended between message queuing and delivery.
  • textCarrierViolation - The message was flagged as 'objectionable' or 'spam' by the phone carrier and was blocked.
  • textConvoUnknownNumberRejected - This text was received from an unknown number, and so was rejected.
  • textDeviceUnreachable - The destination phone number temporarily could not be reached - it was turned off, out of service area, etc.
  • textLandlineOrUnreachableCarrier - The destination phone number could not receive the message. Reasons include the destination number being a landline phone or the carrier being temporarily unavailable.
  • textLenderDisabledInboundTexts - The inbound text was not received because the lender does not have inbound texting enabled.
  • textMessageBlocked - The destination phone number is blocked from receiving the message.
  • textMessagePriceExceedsMax - The price of the message exceeds the max price parameter.
  • textMissingSegment - One or more parts of a multipart message were not received.
  • textNumberDisconnected - The destination phone number could not be reached and may be disconnected.
  • textQueueOverflow - Too many messages were queued to be sent, and some were dropped as a result.
  • textRegionInvalid - Permission to send an SMS or MMS has not been enabled for the region indicated by the 'To' number
  • textUnknownError - An unknown error occurred when attempting to send the message.
  • textUnsubscribedRecipient - The person you are trying to message has opted out of receiving messages from your Twilio phone number, Channels sender, or Messaging Service.
  • voiceFailedToInitiate - Outbound voice call could not start for some reason
  • voiceLenderDisabledInboundCalls - Inbound call received while lender has inbound voice call disabled
  • voiceNumberDisconnected - Outbound voice call to disconnected phone number
  • voiceNumberInvalid - Invalid 'To' Phone Number
  • voiceReceivedNoAgentsAvailable - Inbound call received while lender had no agents to answer it

Channels

  • Most status details can only be used with their respective channels. e.g., voiceNumberDisconnected can only be used for interactions with channel=voice. Using them otherwise will result in an error
  • invalidContact and blockedByComplianceGuard are valid for all channels

Direction

Certain status details are only valid with certain direction settings. Using them with an invalid direction will result in an error. For example...

  • voiceReceivedNoAgentsAvailable can only be set for inbound phone calls
  • voiceNumberDisconnected can only be set for outbound phone calls
  • voiceUnexpectedDisconnect can be set for either direction

Null

Note that null is not a valid status name but rather can be used to specify a query for interactions with a status of null

Enum: "voiceSpokeWithFirstParty" "voiceSpokeWithThirdParty" "voiceLeftVoicemailFirstParty" "voiceLeftVoicemailThirdParty" "voiceLeftVoicemail" "voiceLineBusyNoRing" "voiceReachedVoicemailNoMessageLeft" "voiceRangNoPickup" "voicePickedHungUp" "voiceFailedToInitiate" "voiceNumberDisconnected" "voiceReceivedOutsideOpenHours" "voiceUnexpectedDisconnect" "voiceDisconnectedWhileQueuedOnHold" "voiceReceivedNoAgentsAvailable" "voiceLenderDisabledInboundCalls" "voiceConnected" "voiceNumberInvalid" "emailSent" "emailDelivered" "emailBlocked" "emailBounced" "emailOpened" "emailClick" "emailDropped" "emailFailedToSend" "emailReportedAsSpam" "letterCreated" "letterFailedToCreate" "letterRenderedPdf" "letterRenderedThumbnails" "letterProcessedForDelivery" "letterRerouted" "letterInLocalArea" "letterInTransit" "letterDelivered" "letterReturnedToSender" "letterDeleted" "chatPosted" "chatRead" "chatBorrowerInactivity" "chatReceivedOutsideOpenHours" "textConvoTimeoutAutoclose" "textConvoClosedStale" "textConvoUnknownNumberRejected" "textConvoClosedByAgent" "textLenderDisabledInboundTexts" "textUnsubscribedRecipient" "textQueueOverflow" "textAccountSuspended" "textDeviceUnreachable" "textMessageBlocked" "textNumberDisconnected" "textLandlineOrUnreachableCarrier" "textCarrierViolation" "textUnknownError" "textMissingSegment" "textMessagePriceExceedsMax" "textA2PCampaignUnregistered" "textRegionInvalid" "blockedByComplianceGuard" "invalidContact" "null"
metaData
object or null (MetaData)

Store any type of key/value pairs in the form of a JSON dictionary.

direction
required
string (InteractionDirection)
Enum: "outbound" "inbound"
loanId
string (AssociatedLoanId)

The ID of a Loan. This marks a particular loan as associated with this interaction.

loanIds
Array of strings (AssociatedLoanIds)

The IDs of several loans. This marks several loans as associated with this interaction.

sensitive
boolean or null
Default: false

Set this flag if this interaction has sensitive information. The flag is used for proper authorization of access to the information.

isExternal
boolean

Boolean indicating the source of an Interaction. If true, the interaction was supplied by the lender via API. If false, the interaction was created by Peach.

externalId
string or null [ 1 .. 255 ] characters

The lender's identifier for the interaction.

After the object is successfully created, a lender can use ID or externalId identifiers to fetch the object.

To fetch the object using externalId you need to add ext- to the URL.

Note: Don't add ext- to the identifier value. For example: if the external identifier is ABCDE, then pass externalId=ACBCE and NOT ext-ABCDE when creating the object.

previousInteractionId
string or null

If a previous interaction identifier is provided, the current and previous interactions will be linked. This can either be Peach's or a lender's external identifier.

twilioErrorCode
string or null <= 10 characters

Raw error code from Twilio SMS service. The full list of codes can be found at https://www.twilio.com/docs/api/errors .

isTransactional
boolean or null

true when this interaction is considered "transactional".

Transactional interactions are those which are sent via an automated system in response to an event or some action taken. e.g., an email sent to confirm a payment was made is transactional; likewise an email sent to confirm a password change is transacrtional. Examples of non-transactional messages would be: those sent by an agent in response to a customer request, for collections, or for marketing.

It's important to mark these messages correctly, because different laws may apply to messages depending on if they're considered "transactional".

Note: Can be null for interactions sent before the transactional-ness was added to the API.

contactExternalId
string or null

The lender's identifier of the contact information.

This should not include any ext- prefix as we know this is an external ID field.

agentOutcome
string or null (InteractionAgentOutcome)

Provides details on the outcome of the interaction according to an agent.

Note this captures the "human" outcome of an interaction: e.g., Did you talk the person you intended to? Did the other chat recipient become unresponsive?

For the "technical" status of an interaction, see statusDetails. e.g., : Did it fail to send? Was it blocked by Compliance Guard?

  • voiceSpokeWithFirstParty - Agent spoke with borrower
  • voiceSpokeWithThirdParty - Agent spoke with someone other than the borrower
  • voiceLeftVoicemail - Agent left voicemail
  • voiceReachedVoicemailNoMessageLeft - Agent reached voicemail but did not leave a message
  • voiceRangNoPickup - Phone rang, no voicemail was reached, and the call ended, or the agent hung up
  • voiceLineBusyNoRing - Agent reached busy phone line
  • voicePickedHungUp - Agent heard call pick up and immediate hang up
  • voiceDisconnectedWhileQueuedOnHold - Caller hung up while on hold
  • voiceUnexpectedDisconnect - The call was unexpectedly disconnected
  • voiceFailedToInitiate - Outbound voice call could not start for some reason
  • voiceNumberDisconnected - Outbound voice call to disconnected phone number
Enum: "voiceSpokeWithFirstParty" "voiceSpokeWithThirdParty" "voiceLeftVoicemail" "voiceLineBusyNoRing" "voiceReachedVoicemailNoMessageLeft" "voiceRangNoPickup" "voicePickedHungUp" "voiceFailedToInitiate" "voiceNumberDisconnected" "voiceUnexpectedDisconnect"
endedAt
string or null <date-time>

End time of the interaction. This attribute is optional and is used for logging only.

For CRM-managed voice interactions, a call is considered ended when either the borrower or the agent disconnects.

failureDescriptionShort
string or null

Short text describing the failure reason. Normally displayed in UI.

failureDescriptionLong
string or null

Detailed text describing the failure reason and any appropriate actions the user may take to fix the issue.

complianceGuardRuleId
string or null

The Compliance Guard rule identifier that blocked the interaction. Only applicable if the statusDetails=blockedByComplianceGuard and a rule actually blocked the interaction. In some cases the interaction can be blocked before rules are checked (e.g. a borrower is missing an address). In such a case the complianceGuardRuleId will be empty/null.

object (BasePersonNoIdentity)

Represents various users such as a borrower, co-borrower, co-signer, etc. A lender can choose to provide PII or not. If no PII is provided, Peach cannot monitor for bankruptcy, deceased and SCRA.

object (contactInformation)

The contact details. A contact can be email, phone, address, etc. The name attribute is optional, and is useful for third-party contacts such as spouse, attorney, etc.

Responses
200

Success

post/people/{personId}/interactions
Request samples
application/json
{
  • "channel": "fax",
  • "content": { },
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "contactId": "string",
  • "personId": "string",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "scheduledAtFrom": "2019-08-24T14:15:22Z",
  • "scheduledAtTo": "2019-08-24T14:15:22Z",
  • "subject": "annualPrivacyPolicyNotice",
  • "theme": "agentNotification",
  • "borrowerSelectedTheme": "agentNotification",
  • "status": "attempted",
  • "statusDetails": "voiceSpokeWithFirstParty",
  • "metaData": { },
  • "direction": "outbound",
  • "loanId": "LN-AAAA-BBBB",
  • "loanIds": [
    ],
  • "sensitive": false,
  • "isExternal": true,
  • "externalId": "string",
  • "previousInteractionId": "string",
  • "twilioErrorCode": "string",
  • "isTransactional": true,
  • "contactExternalId": "string",
  • "agentOutcome": "voiceSpokeWithFirstParty",
  • "endedAt": "2019-08-24T14:15:22Z",
  • "failureDescriptionShort": "string",
  • "failureDescriptionLong": "string",
  • "complianceGuardRuleId": "string",
  • "borrower": {
    },
  • "contact": {
    }
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Get borrower interactions

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 25

The maximum count of results to retrieve.

startingAfter
string

Return results starting after the provided object identifier.

endingBefore
string

Return results ending before the provided object identifier.

offset
integer >= 0

Offset from the start of results.

channel
Array of strings or null (InteractionChannel)

Exactly match the channel over which the interaction took place.

Items Enum: "voice" "email" "fax" "text" "chat" "mail" "gui" "document"
direction
string (InteractionDirection)

Exactly match the direction the interaction—either inbound or outbound.

Enum: "outbound" "inbound"
status
Array of strings (InteractionStatus)

Exactly match the status of an interaction.

Items Enum: "attempted" "succeeded" "failed" "scheduled" "canceled" "inProgress" "null"
statusDetails
Array of strings or null (InteractionStatusDetails)

Exactly match the status details of an interaction.

Items Enum: "voiceSpokeWithFirstParty" "voiceSpokeWithThirdParty" "voiceLeftVoicemailFirstParty" "voiceLeftVoicemailThirdParty" "voiceLeftVoicemail" "voiceLineBusyNoRing" "voiceReachedVoicemailNoMessageLeft" "voiceRangNoPickup" "voicePickedHungUp" "voiceFailedToInitiate" "voiceNumberDisconnected" "voiceReceivedOutsideOpenHours" "voiceUnexpectedDisconnect" "voiceDisconnectedWhileQueuedOnHold" "voiceReceivedNoAgentsAvailable" "voiceLenderDisabledInboundCalls" "voiceConnected" "voiceNumberInvalid" "emailSent" "emailDelivered" "emailBlocked" "emailBounced" "emailOpened" "emailClick" "emailDropped" "emailFailedToSend" "emailReportedAsSpam" "letterCreated" "letterFailedToCreate" "letterRenderedPdf" "letterRenderedThumbnails" "letterProcessedForDelivery" "letterRerouted" "letterInLocalArea" "letterInTransit" "letterDelivered" "letterReturnedToSender" "letterDeleted" "chatPosted" "chatRead" "chatBorrowerInactivity" "chatReceivedOutsideOpenHours" "textConvoTimeoutAutoclose" "textConvoClosedStale" "textConvoUnknownNumberRejected" "textConvoClosedByAgent" "textLenderDisabledInboundTexts" "textUnsubscribedRecipient" "textQueueOverflow" "textAccountSuspended" "textDeviceUnreachable" "textMessageBlocked" "textNumberDisconnected" "textLandlineOrUnreachableCarrier" "textCarrierViolation" "textUnknownError" "textMissingSegment" "textMessagePriceExceedsMax" "textA2PCampaignUnregistered" "textRegionInvalid" "blockedByComplianceGuard" "invalidContact" "null"
agentOutcome
Array of strings or null (InteractionAgentOutcome)

Exactly match the agentOutcome of an interaction.

Items Enum: "voiceSpokeWithFirstParty" "voiceSpokeWithThirdParty" "voiceLeftVoicemail" "voiceLineBusyNoRing" "voiceReachedVoicemailNoMessageLeft" "voiceRangNoPickup" "voicePickedHungUp" "voiceFailedToInitiate" "voiceNumberDisconnected" "voiceUnexpectedDisconnect"
subject
Array of strings

The interaction subject value(s) by which to filter. To match interactions without a subject pass the string "null".

theme
Array of strings or null (InteractionTheme)
Items Enum: "agentNotification" "opsCollDebt" "opsCollLocateBorrower" "opsCollVerifyEmployment" "opsCollContactEmployerNotice" "opsServicingDebtValidation" "opsServicingNegativeCreditReportNotice" "opsServicingTimeBarredNotice" "opsServicing" "opsAccountCredentials" "inbMissingFeature" "inbEducation" "inbBug" "inbRequest" "inbHumanLove" "inbUnknown" "inbOther" "inbServicing" "inbCollections" "inbPayments" "inbFraud" "inbGeneralInquiry"
caseIds
Array of strings

Exactly matches one of several Peach case IDs (CS-XXXX-XXXX).

contentContains
string

Search for an exact match in the content of the interaction

sortBy
Array of strings

The field(s) to sort by.

All fields can be prefixed with a - to indicate the sort should be in descending order, or with a + to indicate the sort should be in ascending order. (Without specifying the order is descending.)

The valid sort by field names are:

id — order by the object creation order. createdAt — order by the createdAt field. startedAt — order by the startedAt field. holdDuration — order by the duration of the voice call on-hold (the holdDuration field.) contactName — order by the name field of the contact for the interaction. scheduledAtFrom — order by the scheduledAtFrom field. scheduledAtTo — order by the scheduledAtTo field. channel — order by the channel field. direction — order by the direction field. status — order by the status field. createdBy.employeeFirstName — order by the firstName field of the employee which created the interaction (only if creator was an employee). createdBy.employeeLastName — order by the lastName field of the employee which created the interaction (only if creator was an employee). createdBy.employeeEmail — order by the email field of the employee which created the interaction (only if creator was an employee). createdBy.employeeFullNameOrEmail — order by the full name ({firstName} {lastName}) or, if absent, the email of the employee whihch created the interaction (only if creator was an employee).

include
Array of strings non-empty

A comma separated list of interaction relationships to return. When "includeFields=borrower,contact" both the borrower and contact fields will be populated in the response object (see response body for details)

Items Enum: "borrower" "contact"
createdAtBefore
string <date-time>

Filter only objects that were not created at or before the specified timestamp. This timestamp is in UTC.

createdAtAfter
string <date-time>

Filter only objects that were not created at or after the specified timestamp. This timestamp is in UTC.

startedAtBefore
string <date-time>

Filter only objects that were not started at or before the specified timestamp. This timestamp is in UTC.

startedAtAfter
string <date-time>

Filter only objects that were not started at or after the specified timestamp. This timestamp is in UTC.

scheduledAtFromBefore
string <date-time>

Include only interactions which have a scheduledAtFrom set to before (or equal to) this timestamp. The timestamp must include a timezone (or UTC offset).

scheduledAtFromAfter
string <date-time>

Include only interactions which have a scheduledAtFrom set to after (or equal to) this timestamp. The timestamp must include a timezone (or UTC offset).

scheduledAtToBefore
string <date-time>

Include only interactions which have a scheduledAtTo set to before (or equal to) this timestamp. The timestamp must include a timezone (or UTC offset).

scheduledAtToAfter
string <date-time>

Include only interactions which have a scheduledAtTo set to after (or equal to) this timestamp. The timestamp must include a timezone (or UTC offset).

createdBy
string or null

The User ID or Employee ID of the user which created the interaction.

If null is specified then match all interactions with createdBy of null.

hasVoicemail
boolean

If true, include only interactions with voicemails—only valid for channel=voicecase. If false, include only interactions without voicemails. If unset, then include any interaction regardless of it having voicemail or not.

Note that a voicemail is different from a call recording. A voicemail is an audio message left by a caller when no pickup by the company was possible. e.g., the call was made while the office was closed or while there were no agents available to answer the call.

hasRecording
boolean

If true match only interactions with call recordings—only valid for channel=voice. If false match only interactions without call recordings. If unset, match any interaction regardless of it have a recording or not.

Note that a call recording is when an agent chooses to record a call, which is different from a voicemail.

sensitive
boolean or null

If true, include only interactions with the sensitive property set to true. If false, include only interactions with the sensitive property set to false. If unset, include any interaction regardless of sensitive property.

isExternal
boolean or null

If true, include only interactions with the isExternal property set to true. If false, include only interactions with the isExternal property set to false. If unset, include any interaction regardless of isExternal property.

Responses
200

Success

get/people/{personId}/interactions
Response samples
application/json
{
  • "status": 0,
  • "total": 0,
  • "count": 0,
  • "nextUrl": "string",
  • "previousUrl": "string",
  • "data": [
    ]
}

Get interaction by ID

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

interactionId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Interaction's unique identifier to track interactions for. Can be Peach or lender's external identifier.

query Parameters
searchable
boolean
Default: false

If true, format the entire response as one suitable for an ElasticSearch search index.

Responses
200

Success

get/people/{personId}/interactions/{interactionId}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Update interaction

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

interactionId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Interaction's unique identifier to track interactions for. Can be Peach or lender's external identifier.

Request Body schema: application/json
required
Any of:
channel
string

The channel by which an interaction occurs.

Enum: "fax" "gui" "document"
content
object or null

The content and attributes of the message sent. Normally in JSON format.

id
string
createdAt
string <date-time>
updatedAt
string or null <date-time>
deletedAt
string or null <date-time>
contactId
string
personId
string or null

The ID of the borrower to which this interaction is associated

startedAt
string <date-time>

Start time of the interaction. If not provided we'll assume it's a timestamp of the API call. If time of day is not required provide only date.

For CRM-managed voice interactions, an inbound call is considered started when the CRM system answers the call, and an outbound call is considered started when the CRM system initiates the call.

scheduledAtFrom
string <date-time>

Time to start the scheduled interaction.

scheduledAtTo
string <date-time>

Time to end the scheduled interaction.

subject
string (InteractionSubject)

The subject of the interaction. The subject identifies the category of the content in the message.

Most subjects have an associated implicit theme. e.g., loanOverdueFirstNotice has a theme of opsCollDebt. For these subjects it is not necessary to specify a theme.

Some subjects like freeForm and custom<N> do not have an implicit theme. When using these subjects you must specify a theme.

Note that locStatementGenerated and locStatementRegenerated are deprecated. They will be automatically converted into statementGenerated and statementRegenerated respectively. You should should switch to those subjects directly.

Enum: "annualPrivacyPolicyNotice" "autopayAgreement" "autopayAmountChanged" "autopayCanceledBySystem" "autopayEnabled" "autopayEnableReminder" "autopayPaymentCanceled" "autopayPaymentMethodUpdated" "autopayPaymentReminder" "autopayPaymentRescheduled" "cardExpiresReminder" "caseEscalation" "ceaseCommunicationAcknowledgement" "ceaseCommunicationRefuseToPay" "confirmationCode" "contactTakeover" "creditNegativeInfoReported" "creditPositiveInfoReported" "custom1" "custom2" "custom3" "custom4" "custom5" "custom6" "custom7" "custom8" "custom9" "custom10" "custom11" "custom12" "custom13" "custom14" "custom15" "custom16" "custom17" "custom18" "custom19" "custom20" "debtValidationNotice" "debtValidationNoticeArizona" "debtValidationNoticeAutomatic" "debtValidationNoticeNYCYonkers" "debtValidationNoticePuertoRico" "deceasedConfirmationOfPayoff" "deceasedNoticeToRepresentative" "deceasedNotificationUponDeath" "disputeOfDebtConfirmed" "disputeOfDebtSubmitDocumentation" "disputeOfDebtSubmitDocumentationReminder" "disputeOfDebtUnableToConfirm" "disputeOfDebtUnableToResolve" "documentUploadFailed" "downpaymentFailed" "drawFundsDisclosure" "electronicConsentOptOut" "failedSettlementInvestor" "failedSettlementPeach" "freeForm" "freeFormBranded" "futurepayCanceled" "futurepayPaymentDueReminder" "identityTheftIncompleteDocumentation" "identityTheftNotValidated" "identityTheftSubmitDocumentation" "identityTheftSubmitDocumentationFirstReminder" "identityTheftSubmitDocumentationSecondReminder" "identityTheftValidated" "letterReturnedToSender" "loanAccelerated" "loanCanceled" "loanChargedOffUnsecured" "loanDetails" "loanFeeCharged" "loanFreeze" "loanManualPaymentDisclosure" "loanOverdueFifthNotice" "loanOverdueFirstNotice" "loanOverdueFourthNotice" "loanOverdueSecondNotice" "loanOverdueSixthNotice" "loanOverdueThirdNotice" "loanPaidOff" "loanPaymentScheduleChanged" "loanPayoffStatement" "loanRefundProcessed" "loanRightToCurePersonalUnsecured" "loanTermsChangeAgreement" "loanUnfreeze" "locCreditLimitChanged" "locInterestRateChanged" "locLineClosed" "locStatementGenerated" "locStatementRegenerated" "loginFirstPaymentReminder" "microdepositFailed" "microdepositProcessing" "microdepositReminder" "oneTimeCode" "paydayConsumerRightsNotice" "paydayFirstPaymentWithdrawal" "paymentDisputed" "paymentDueDateReminder" "paymentFailed" "paymentMethodAdded" "paymentMethodUpdated" "paymentProcessing" "paymentRescheduled" "paymentReversalFailed" "paymentReversalProcessing" "paymentSuccessful" "payoffStatementDocument" "promiseToPayPeriodKept" "promiseToPayPeriodMissed" "promiseToPayPlanCanceled" "promiseToPayPlanCreated" "promoProgramCanceled" "promoProgramEligibilityAtRisk" "promoProgramExercised" "promoProgramReminder" "reimbursementFailed" "reimbursementProcessed" "reimbursementScheduled" "scraApplicationDenied" "scraBenefitsApplied" "scraBenefitsExpiringNotice" "scraCGFlaggedDocumentRequest" "scraServicemanNotifiedDocumentRequest" "settlementOffer" "settlementOfferFirstReminder" "statement" "statementLOC" "statementGenerated" "statementRegenerated" "unmonitoredEmailAddress" "updateBankAccountConnection"
theme
string or null (InteractionTheme)

The reason why an interaction occurred.

For example:

  • An outbound debt collection call should be marked as opsCollDebt.
  • An annual privacy policy update email should be marked as opsServicing.
  • A customer service response to borrower's inquiry should be marked as opsServicing.
  • Statements or payment reminders should be marked as outOpsLoan.

The values inbHumanLove and inbBug are deprecated; use inbGeneralInquiry instead.

Enum: "agentNotification" "opsCollDebt" "opsCollLocateBorrower" "opsCollVerifyEmployment" "opsCollContactEmployerNotice" "opsServicingDebtValidation" "opsServicingNegativeCreditReportNotice" "opsServicingTimeBarredNotice" "opsServicing" "opsAccountCredentials" "inbMissingFeature" "inbEducation" "inbBug" "inbRequest" "inbHumanLove" "inbUnknown" "inbOther" "inbServicing" "inbCollections" "inbPayments" "inbFraud" "inbGeneralInquiry"
borrowerSelectedTheme
string or null (InteractionTheme)

The reason why an interaction occurred.

For example:

  • An outbound debt collection call should be marked as opsCollDebt.
  • An annual privacy policy update email should be marked as opsServicing.
  • A customer service response to borrower's inquiry should be marked as opsServicing.
  • Statements or payment reminders should be marked as outOpsLoan.

The values inbHumanLove and inbBug are deprecated; use inbGeneralInquiry instead.

Enum: "agentNotification" "opsCollDebt" "opsCollLocateBorrower" "opsCollVerifyEmployment" "opsCollContactEmployerNotice" "opsServicingDebtValidation" "opsServicingNegativeCreditReportNotice" "opsServicingTimeBarredNotice" "opsServicing" "opsAccountCredentials" "inbMissingFeature" "inbEducation" "inbBug" "inbRequest" "inbHumanLove" "inbUnknown" "inbOther" "inbServicing" "inbCollections" "inbPayments" "inbFraud" "inbGeneralInquiry"
status
string (InteractionStatus)

The status of an interaction.

status is important, as it can impact future interactions. For instance, in jurisdictions which cap the number of outbound collection communications to a borrower, status=failed interactions do not count against the legal allotment.

Interaction status can be updated as the interaction status changes. For example, when an email is sent, set the status to attempted. If the email is opened, set the status to succeeded. If the email bounces, set the status to failed. attempted is assumed to be a successful interaction. Optionally, you can also use 'statusDetails' to provide additional details about status.

In-Progress interactions

Some interactions—like an email—take place at a single point in time, others might be ongoing for many minutes—like a phone call.

Ongoing interactions like voice and chat may have their status set to inProgress.

Scheduled interactions

Some interactions might be scheduled for the future. These interactions have a status of scheduled. If this scheduled interaction is unscheduled then it has a status of canceled.

Null

Note that null is not a valid status name but rather can be used to specify a query for interactions with a status of null

Enum: "attempted" "succeeded" "failed" "scheduled" "canceled" "inProgress" "null"
statusDetails
string or null (InteractionStatusDetails)

Provides more details about the status of an interaction.

Note that statusDetails related to the "technical" status of an interaction: e.g., Did it connect? Did it fail to send? Was it blocked by Compliance Guard?

For the "human" outcome of an interaction see agentOutcome: e.g., Did you talk the person you intended to? Did the other chat recipient become unresponsive?

Status

Certain status details must have a particular status associated with them; attempting to use them otherwise will result in an error.

Succeeded

The following status details are considered status=succeeded

  • emailDelivered - The email was successfully delivered
  • emailOpened - The email was opened
  • emailClick - A link in the email was clicked
  • letterDelivered - The letter is successfully delivered
  • chatRead - The chat message was read

Attempted

The following status details are considered status=attempted.

  • voiceReceivedOutsideOpenHours - Caller tried to contact the lender outside designated business hours
  • voiceConnected - Voice call connected successfully
  • emailSent - Email was sent, but delivery cannot be confirmed
  • letterCreated - Letter is successfully created
  • letterRenderedPdf - Letter's PDF proof is successfully rendered
  • letterRenderedThumbnails - Letter's thumbnails are successfully rendered
  • letterInTransit - Letter received an "In Transit" event
  • letterInLocalArea - Letter is in the local area
  • letterProcessedForDelivery - Letter is in the local area
  • letterRerouted - Letter is re-routed
  • chatPosted - Chat message sent
  • textConvoTimeoutAutoclose - This text conversation was closed automatically due to a timeout.
  • textConvoClosedStale - (DEPRECATED) An open but outdated text conversation was closed automatically when a new text conversation was started. New text conversations should never enter into this state, but old conversations may be in this state.
  • textConvoClosedByAgent - The agent manually marked the text conversation as ended.

Failed

The following status details are considered status=failed.

Generally an interaction is failed if some part of connecting or completing the interaction failed due to a technical failure, misconfiguration, or attempt to communicate in a way disallowed by rules.

  • emailBlocked - Receiving server could not or would not accept the message temporarily
  • emailBounced - Receiving server could not or would not accept mail to this recipient permanently
  • emailDropped - Email rejected for a number of reasons: rejected as SPAM, Unsubscribed Address, Bounced Address, Email Invalid
  • emailFailedToSend - Not currently in use - reserved for future use
  • emailReportedAsSpam - Email was delivered, but later reported as SPAM by recipient
  • letterDeleted - Letter is successfully canceled
  • letterFailedToCreate - Request to create the letter failed. Provider did not return 200 OK status code
  • letterReturnedToSender - Letter is returned to the sender
  • textA2PCampaignUnregistered - The text was not sent because the lender has not registered this phone number with an A2P campaign.
  • textAccountSuspended - The account was suspended between message queuing and delivery.
  • textCarrierViolation - The message was flagged as 'objectionable' or 'spam' by the phone carrier and was blocked.
  • textConvoUnknownNumberRejected - This text was received from an unknown number, and so was rejected.
  • textDeviceUnreachable - The destination phone number temporarily could not be reached - it was turned off, out of service area, etc.
  • textLandlineOrUnreachableCarrier - The destination phone number could not receive the message. Reasons include the destination number being a landline phone or the carrier being temporarily unavailable.
  • textLenderDisabledInboundTexts - The inbound text was not received because the lender does not have inbound texting enabled.
  • textMessageBlocked - The destination phone number is blocked from receiving the message.
  • textMessagePriceExceedsMax - The price of the message exceeds the max price parameter.
  • textMissingSegment - One or more parts of a multipart message were not received.
  • textNumberDisconnected - The destination phone number could not be reached and may be disconnected.
  • textQueueOverflow - Too many messages were queued to be sent, and some were dropped as a result.
  • textRegionInvalid - Permission to send an SMS or MMS has not been enabled for the region indicated by the 'To' number
  • textUnknownError - An unknown error occurred when attempting to send the message.
  • textUnsubscribedRecipient - The person you are trying to message has opted out of receiving messages from your Twilio phone number, Channels sender, or Messaging Service.
  • voiceFailedToInitiate - Outbound voice call could not start for some reason
  • voiceLenderDisabledInboundCalls - Inbound call received while lender has inbound voice call disabled
  • voiceNumberDisconnected - Outbound voice call to disconnected phone number
  • voiceNumberInvalid - Invalid 'To' Phone Number
  • voiceReceivedNoAgentsAvailable - Inbound call received while lender had no agents to answer it

Channels

  • Most status details can only be used with their respective channels. e.g., voiceNumberDisconnected can only be used for interactions with channel=voice. Using them otherwise will result in an error
  • invalidContact and blockedByComplianceGuard are valid for all channels

Direction

Certain status details are only valid with certain direction settings. Using them with an invalid direction will result in an error. For example...

  • voiceReceivedNoAgentsAvailable can only be set for inbound phone calls
  • voiceNumberDisconnected can only be set for outbound phone calls
  • voiceUnexpectedDisconnect can be set for either direction

Null

Note that null is not a valid status name but rather can be used to specify a query for interactions with a status of null

Enum: "voiceSpokeWithFirstParty" "voiceSpokeWithThirdParty" "voiceLeftVoicemailFirstParty" "voiceLeftVoicemailThirdParty" "voiceLeftVoicemail" "voiceLineBusyNoRing" "voiceReachedVoicemailNoMessageLeft" "voiceRangNoPickup" "voicePickedHungUp" "voiceFailedToInitiate" "voiceNumberDisconnected" "voiceReceivedOutsideOpenHours" "voiceUnexpectedDisconnect" "voiceDisconnectedWhileQueuedOnHold" "voiceReceivedNoAgentsAvailable" "voiceLenderDisabledInboundCalls" "voiceConnected" "voiceNumberInvalid" "emailSent" "emailDelivered" "emailBlocked" "emailBounced" "emailOpened" "emailClick" "emailDropped" "emailFailedToSend" "emailReportedAsSpam" "letterCreated" "letterFailedToCreate" "letterRenderedPdf" "letterRenderedThumbnails" "letterProcessedForDelivery" "letterRerouted" "letterInLocalArea" "letterInTransit" "letterDelivered" "letterReturnedToSender" "letterDeleted" "chatPosted" "chatRead" "chatBorrowerInactivity" "chatReceivedOutsideOpenHours" "textConvoTimeoutAutoclose" "textConvoClosedStale" "textConvoUnknownNumberRejected" "textConvoClosedByAgent" "textLenderDisabledInboundTexts" "textUnsubscribedRecipient" "textQueueOverflow" "textAccountSuspended" "textDeviceUnreachable" "textMessageBlocked" "textNumberDisconnected" "textLandlineOrUnreachableCarrier" "textCarrierViolation" "textUnknownError" "textMissingSegment" "textMessagePriceExceedsMax" "textA2PCampaignUnregistered" "textRegionInvalid" "blockedByComplianceGuard" "invalidContact" "null"
metaData
object or null (MetaData)

Store any type of key/value pairs in the form of a JSON dictionary.

direction
string (InteractionDirection)
Enum: "outbound" "inbound"
loanId
string (AssociatedLoanId)

The ID of a Loan. This marks a particular loan as associated with this interaction.

loanIds
Array of strings (AssociatedLoanIds)

The IDs of several loans. This marks several loans as associated with this interaction.

sensitive
boolean or null
Default: false

Set this flag if this interaction has sensitive information. The flag is used for proper authorization of access to the information.

isExternal
boolean

Boolean indicating the source of an Interaction. If true, the interaction was supplied by the lender via API. If false, the interaction was created by Peach.

externalId
string or null [ 1 .. 255 ] characters

The lender's identifier for the interaction.

After the object is successfully created, a lender can use ID or externalId identifiers to fetch the object.

To fetch the object using externalId you need to add ext- to the URL.

Note: Don't add ext- to the identifier value. For example: if the external identifier is ABCDE, then pass externalId=ACBCE and NOT ext-ABCDE when creating the object.

previousInteractionId
string or null

If a previous interaction identifier is provided, the current and previous interactions will be linked. This can either be Peach's or a lender's external identifier.

twilioErrorCode
string or null <= 10 characters

Raw error code from Twilio SMS service. The full list of codes can be found at https://www.twilio.com/docs/api/errors .

isTransactional
boolean or null

true when this interaction is considered "transactional".

Transactional interactions are those which are sent via an automated system in response to an event or some action taken. e.g., an email sent to confirm a payment was made is transactional; likewise an email sent to confirm a password change is transacrtional. Examples of non-transactional messages would be: those sent by an agent in response to a customer request, for collections, or for marketing.

It's important to mark these messages correctly, because different laws may apply to messages depending on if they're considered "transactional".

Note: Can be null for interactions sent before the transactional-ness was added to the API.

contactExternalId
string or null

The lender's identifier of the contact information.

This should not include any ext- prefix as we know this is an external ID field.

agentOutcome
string or null (InteractionAgentOutcome)

Provides details on the outcome of the interaction according to an agent.

Note this captures the "human" outcome of an interaction: e.g., Did you talk the person you intended to? Did the other chat recipient become unresponsive?

For the "technical" status of an interaction, see statusDetails. e.g., : Did it fail to send? Was it blocked by Compliance Guard?

  • voiceSpokeWithFirstParty - Agent spoke with borrower
  • voiceSpokeWithThirdParty - Agent spoke with someone other than the borrower
  • voiceLeftVoicemail - Agent left voicemail
  • voiceReachedVoicemailNoMessageLeft - Agent reached voicemail but did not leave a message
  • voiceRangNoPickup - Phone rang, no voicemail was reached, and the call ended, or the agent hung up
  • voiceLineBusyNoRing - Agent reached busy phone line
  • voicePickedHungUp - Agent heard call pick up and immediate hang up
  • voiceDisconnectedWhileQueuedOnHold - Caller hung up while on hold
  • voiceUnexpectedDisconnect - The call was unexpectedly disconnected
  • voiceFailedToInitiate - Outbound voice call could not start for some reason
  • voiceNumberDisconnected - Outbound voice call to disconnected phone number
Enum: "voiceSpokeWithFirstParty" "voiceSpokeWithThirdParty" "voiceLeftVoicemail" "voiceLineBusyNoRing" "voiceReachedVoicemailNoMessageLeft" "voiceRangNoPickup" "voicePickedHungUp" "voiceFailedToInitiate" "voiceNumberDisconnected" "voiceUnexpectedDisconnect"
endedAt
string or null <date-time>

End time of the interaction. This attribute is optional and is used for logging only.

For CRM-managed voice interactions, a call is considered ended when either the borrower or the agent disconnects.

failureDescriptionShort
string or null

Short text describing the failure reason. Normally displayed in UI.

failureDescriptionLong
string or null

Detailed text describing the failure reason and any appropriate actions the user may take to fix the issue.

complianceGuardRuleId
string or null

The Compliance Guard rule identifier that blocked the interaction. Only applicable if the statusDetails=blockedByComplianceGuard and a rule actually blocked the interaction. In some cases the interaction can be blocked before rules are checked (e.g. a borrower is missing an address). In such a case the complianceGuardRuleId will be empty/null.

object (BasePersonNoIdentity)

Represents various users such as a borrower, co-borrower, co-signer, etc. A lender can choose to provide PII or not. If no PII is provided, Peach cannot monitor for bankruptcy, deceased and SCRA.

object (contactInformation)

The contact details. A contact can be email, phone, address, etc. The name attribute is optional, and is useful for third-party contacts such as spouse, attorney, etc.

Responses
200

Success

put/people/{personId}/interactions/{interactionId}
Request samples
application/json
{
  • "channel": "fax",
  • "content": { },
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "contactId": "string",
  • "personId": "string",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "scheduledAtFrom": "2019-08-24T14:15:22Z",
  • "scheduledAtTo": "2019-08-24T14:15:22Z",
  • "subject": "annualPrivacyPolicyNotice",
  • "theme": "agentNotification",
  • "borrowerSelectedTheme": "agentNotification",
  • "status": "attempted",
  • "statusDetails": "voiceSpokeWithFirstParty",
  • "metaData": { },
  • "direction": "outbound",
  • "loanId": "LN-AAAA-BBBB",
  • "loanIds": [
    ],
  • "sensitive": false,
  • "isExternal": true,
  • "externalId": "string",
  • "previousInteractionId": "string",
  • "twilioErrorCode": "string",
  • "isTransactional": true,
  • "contactExternalId": "string",
  • "agentOutcome": "voiceSpokeWithFirstParty",
  • "endedAt": "2019-08-24T14:15:22Z",
  • "failureDescriptionShort": "string",
  • "failureDescriptionLong": "string",
  • "complianceGuardRuleId": "string",
  • "borrower": {
    },
  • "contact": {
    }
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Delete interaction

Delete an interaction. Only external interactions (interactions created by lenders via API) can be deleted.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

interactionId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Interaction's unique identifier to track interactions for. Can be Peach or lender's external identifier.

Responses
200

Success

delete/people/{personId}/interactions/{interactionId}

Get previous interactions

For this interaction, get all the previous interactions linked to it via the previousInteractionId field.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

interactionId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Interaction's unique identifier to track interactions for. Can be Peach or lender's external identifier.

query Parameters
include
Array of strings non-empty

A comma separated list of interaction relationships to return. When "includeFields=borrower,contact" both the borrower and contact fields will be populated in the response object (see response body for details)

Items Enum: "borrower" "contact"
Responses
200

Success

get/people/{personId}/interactions/{interactionId}/previous
Response samples
application/json
{
  • "message": "string",
  • "status": 0,
  • "data": [
    ]
}

Download interaction recording

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

interactionId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Interaction's unique identifier to track interactions for. Can be Peach or lender's external identifier.

query Parameters
disposition
string

Tells the response from the file download to set the Content-Disposition header to the given value.

  • attachment means "download the file"
  • inline means "open the file in the default manner". e.g., if the file were an .mp3 the browser's default audio player would open.
Enum: "inline" "attachment"
returnUrl
boolean
Default: false

If true, will return a URL to the content instead of redirecting to the content.

Responses
200

If the returnUrl parameter is true then return the url rather than redirecting.

302

Redirected to the recorded content

get/people/{personId}/interactions/{interactionId}/recording-content
Response samples
application/json
{}

Download interaction voicemail

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

interactionId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Interaction's unique identifier to track interactions for. Can be Peach or lender's external identifier.

query Parameters
disposition
string

Tells the response from the file download to set the Content-Disposition header to the given value.

  • attachment means "download the file"
  • inline means "open the file in the default manner". e.g., if the file were an .mp3 the browser's default audio player would open.
Enum: "inline" "attachment"
returnUrl
boolean
Default: false

If true, will return a URL to the content instead of redirecting to the content.

Responses
200

If the returnUrl parameter is true then return the url rather than redirecting.

302

Redirected to the recorded content

get/people/{personId}/interactions/{interactionId}/voicemail-content
Response samples
application/json
{}

Get cases associated with an interaction

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

interactionId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Interaction's unique identifier to track interactions for. Can be Peach or lender's external identifier.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 25

The maximum count of results to retrieve.

startingAfter
string

Return results starting after the provided object identifier.

endingBefore
string

Return results ending before the provided object identifier.

offset
integer >= 0

Offset from the start of results.

Responses
200

Success

get/people/{personId}/interactions/{interactionId}/cases
Response samples
application/json
{
  • "status": 0,
  • "total": 0,
  • "count": 0,
  • "nextUrl": "string",
  • "previousUrl": "string",
  • "data": [
    ]
}

Get interactions

Securityoauth2 or bearerAuth or apiKeyHeader
Request
query Parameters
limit
integer [ 1 .. 100 ]
Default: 25

The maximum count of results to retrieve.

startingAfter
string

Return results starting after the provided object identifier.

endingBefore
string

Return results ending before the provided object identifier.

offset
integer >= 0

Offset from the start of results.

hasNoPerson
boolean

If true, include only unassociated interactions—those not associated with a borrower. If false, include only interactions associated with a borrower. If unset, include any interaction regardless of it being associated with a borrower or not.

channel
Array of strings or null (InteractionChannel)

Exactly match the channel over which the interaction took place.

Items Enum: "voice" "email" "fax" "text" "chat" "mail" "gui" "document"
direction
string (InteractionDirection)

Exactly match the direction the interaction—either inbound or outbound.

Enum: "outbound" "inbound"
status
Array of strings (InteractionStatus)

Exactly match the status of an interaction.

Items Enum: "attempted" "succeeded" "failed" "scheduled" "canceled" "inProgress" "null"
statusDetails
Array of strings or null (InteractionStatusDetails)

Exactly match the status details of an interaction.

Items Enum: "voiceSpokeWithFirstParty" "voiceSpokeWithThirdParty" "voiceLeftVoicemailFirstParty" "voiceLeftVoicemailThirdParty" "voiceLeftVoicemail" "voiceLineBusyNoRing" "voiceReachedVoicemailNoMessageLeft" "voiceRangNoPickup" "voicePickedHungUp" "voiceFailedToInitiate" "voiceNumberDisconnected" "voiceReceivedOutsideOpenHours" "voiceUnexpectedDisconnect" "voiceDisconnectedWhileQueuedOnHold" "voiceReceivedNoAgentsAvailable" "voiceLenderDisabledInboundCalls" "voiceConnected" "voiceNumberInvalid" "emailSent" "emailDelivered" "emailBlocked" "emailBounced" "emailOpened" "emailClick" "emailDropped" "emailFailedToSend" "emailReportedAsSpam" "letterCreated" "letterFailedToCreate" "letterRenderedPdf" "letterRenderedThumbnails" "letterProcessedForDelivery" "letterRerouted" "letterInLocalArea" "letterInTransit" "letterDelivered" "letterReturnedToSender" "letterDeleted" "chatPosted" "chatRead" "chatBorrowerInactivity" "chatReceivedOutsideOpenHours" "textConvoTimeoutAutoclose" "textConvoClosedStale" "textConvoUnknownNumberRejected" "textConvoClosedByAgent" "textLenderDisabledInboundTexts" "textUnsubscribedRecipient" "textQueueOverflow" "textAccountSuspended" "textDeviceUnreachable" "textMessageBlocked" "textNumberDisconnected" "textLandlineOrUnreachableCarrier" "textCarrierViolation" "textUnknownError" "textMissingSegment" "textMessagePriceExceedsMax" "textA2PCampaignUnregistered" "textRegionInvalid" "blockedByComplianceGuard" "invalidContact" "null"
agentOutcome
Array of strings or null (InteractionAgentOutcome)

Exactly match the agentOutcome of an interaction.

Items Enum: "voiceSpokeWithFirstParty" "voiceSpokeWithThirdParty" "voiceLeftVoicemail" "voiceLineBusyNoRing" "voiceReachedVoicemailNoMessageLeft" "voiceRangNoPickup" "voicePickedHungUp" "voiceFailedToInitiate" "voiceNumberDisconnected" "voiceUnexpectedDisconnect"
subject
Array of strings

The interaction subject value(s) by which to filter. To match interactions without a subject pass the string "null".

theme
Array of strings or null (InteractionTheme)
Items Enum: "agentNotification" "opsCollDebt" "opsCollLocateBorrower" "opsCollVerifyEmployment" "opsCollContactEmployerNotice" "opsServicingDebtValidation" "opsServicingNegativeCreditReportNotice" "opsServicingTimeBarredNotice" "opsServicing" "opsAccountCredentials" "inbMissingFeature" "inbEducation" "inbBug" "inbRequest" "inbHumanLove" "inbUnknown" "inbOther" "inbServicing" "inbCollections" "inbPayments" "inbFraud" "inbGeneralInquiry"
caseIds
Array of strings

Exactly matches one of several Peach case IDs (CS-XXXX-XXXX).

contentContains
string

Search for an exact match in the content of the interaction

sortBy
Array of strings

The data attributes by which to sort the results.

createdAtBefore
string <date-time>

Filter only objects that were not created at or before the specified timestamp. This timestamp is in UTC.

createdAtAfter
string <date-time>

Filter only objects that were not created at or after the specified timestamp. This timestamp is in UTC.

startedAtBefore
string <date-time>

Filter only objects that were not started at or before the specified timestamp. This timestamp is in UTC.

startedAtAfter
string <date-time>

Filter only objects that were not started at or after the specified timestamp. This timestamp is in UTC.

scheduledAtFromBefore
string <date-time>

Include only interactions which have a scheduledAtFrom set to before (or equal to) this timestamp. The timestamp must include a timezone (or UTC offset).

scheduledAtFromAfter
string <date-time>

Include only interactions which have a scheduledAtFrom set to after (or equal to) this timestamp. The timestamp must include a timezone (or UTC offset).

scheduledAtToBefore
string <date-time>

Include only interactions which have a scheduledAtTo set to before (or equal to) this timestamp. The timestamp must include a timezone (or UTC offset).

scheduledAtToAfter
string <date-time>

Include only interactions which have a scheduledAtTo set to after (or equal to) this timestamp. The timestamp must include a timezone (or UTC offset).

createdBy
string or null

The User ID or Employee ID of the user which created the interaction.

If null is specified then match all interactions with createdBy of null.

hasVoicemail
boolean

If true, include only interactions with voicemails—only valid for channel=voicecase. If false, include only interactions without voicemails. If unset, then include any interaction regardless of it having voicemail or not.

Note that a voicemail is different from a call recording. A voicemail is an audio message left by a caller when no pickup by the company was possible. e.g., the call was made while the office was closed or while there were no agents available to answer the call.

hasRecording
boolean

If true match only interactions with call recordings—only valid for channel=voice. If false match only interactions without call recordings. If unset, match any interaction regardless of it have a recording or not.

Note that a call recording is when an agent chooses to record a call, which is different from a voicemail.

include
Array of strings non-empty

A comma separated list of interaction relationships to return. When "includeFields=borrower,contact" both the borrower and contact fields will be populated in the response object (see response body for details)

Items Enum: "borrower" "contact"
sensitive
boolean or null

If true, include only interactions with the sensitive property set to true. If false, include only interactions with the sensitive property set to false. If unset, include any interaction regardless of sensitive property.

isExternal
boolean or null

If true, include only interactions with the isExternal property set to true. If false, include only interactions with the isExternal property set to false. If unset, include any interaction regardless of isExternal property.

Responses
200

Success

get/interactions
Response samples
application/json
{
  • "status": 0,
  • "total": 0,
  • "count": 0,
  • "nextUrl": "string",
  • "previousUrl": "string",
  • "data": [
    ]
}

Get interaction by ID

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
interactionId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Interaction's unique identifier to track interactions for. Can be Peach or lender's external identifier.

query Parameters
searchable
boolean
Default: false

If true, format the entire response as one suitable for an ElasticSearch search index.

Responses
200

Success

get/interactions/{interactionId}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Get previous interactions

For this interaction, get all the previous interactions linked to it via the previousInteractionId field.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
interactionId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Interaction's unique identifier to track interactions for. Can be Peach or lender's external identifier.

query Parameters
include
Array of strings non-empty

A comma separated list of interaction relationships to return. When "includeFields=borrower,contact" both the borrower and contact fields will be populated in the response object (see response body for details)

Items Enum: "borrower" "contact"
Responses
200

Success

get/interactions/{interactionId}/previous
Response samples
application/json
{
  • "message": "string",
  • "status": 0,
  • "data": [
    ]
}

Get interaction convo

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
interactionId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Interaction's unique identifier to track interactions for. Can be Peach or lender's external identifier.

Responses
200

Success

get/interactions/{interactionId}/convo

Join interaction convo

Add the user making the request to the conversation associated with this interaction.

Note that only users of type Agent can join conversations. (i.e., Service and Borrower users cannot join conversations.)

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
interactionId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Interaction's unique identifier to track interactions for. Can be Peach or lender's external identifier.

Request Body schema: application/json
joinType
string
Default: "solo"

The method of joining the conversation.

  • solo - only add agent to conversation if there are no other agents in conversations
  • add - simply add agent to conversation
  • takeover - remove all other agents from conversation, the add agent
Enum: "solo" "add" "takeover"
Responses
200

Success

post/interactions/{interactionId}/convo/join
Request samples
application/json
{
  • "joinType": "solo"
}

Close interaction convo

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
interactionId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Interaction's unique identifier to track interactions for. Can be Peach or lender's external identifier.

Responses
200

Success

post/interactions/{interactionId}/convo/close

Leave interaction convo

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
interactionId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Interaction's unique identifier to track interactions for. Can be Peach or lender's external identifier.

Responses
200

Success

post/interactions/{interactionId}/convo/leave

Download interaction recording

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
interactionId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Interaction's unique identifier to track interactions for. Can be Peach or lender's external identifier.

query Parameters
disposition
string

Tells the response from the file download to set the Content-Disposition header to the given value.

  • attachment means "download the file"
  • inline means "open the file in the default manner". e.g., if the file were an .mp3 the browser's default audio player would open.
Enum: "inline" "attachment"
returnUrl
boolean
Default: false

If true, will return a URL to the content instead of redirecting to the content.

Responses
200

If the returnUrl parameter is true then return the url rather than redirecting.

302

Redirected to the recorded content

get/interactions/{interactionId}/recording-content
Response samples
application/json
{}

Download interaction voicemail

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
interactionId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Interaction's unique identifier to track interactions for. Can be Peach or lender's external identifier.

query Parameters
disposition
string

Tells the response from the file download to set the Content-Disposition header to the given value.

  • attachment means "download the file"
  • inline means "open the file in the default manner". e.g., if the file were an .mp3 the browser's default audio player would open.
Enum: "inline" "attachment"
returnUrl
boolean
Default: false

If true, will return a URL to the content instead of redirecting to the content.

Responses
200

If the returnUrl parameter is true then return the url rather than redirecting.

302

Redirected to the recorded content

get/interactions/{interactionId}/voicemail-content
Response samples
application/json
{}

Get previous interactions

For this interaction, get all the previous interactions linked to it via the previousInteractionId field.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
companyId
required
string

The unique company identifier.

interactionId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

Interaction's unique identifier to track interactions for. Can be Peach or lender's external identifier.

query Parameters
include
Array of strings non-empty

A comma separated list of interaction relationships to return. When "includeFields=borrower,contact" both the borrower and contact fields will be populated in the response object (see response body for details)

Items Enum: "borrower" "contact"
Responses
200

Success

get/companies/{companyId}/interactions/{interactionId}/previous
Response samples
application/json
{
  • "message": "string",
  • "status": 0,
  • "data": [
    ]
}
➔ Next to Compliance Guard