Communicator

The channel by which an interaction occurs.

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

The ID of the borrower to which this interaction is associated

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.

Time to start the scheduled interaction.

Time to end the scheduled interaction.

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.

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.

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.

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

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

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

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

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

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

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.

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.

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.

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

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.

The lender's identifier of the contact information.

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

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

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.

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

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

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.

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.

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.