Communicator

Send and receive communications like email and text messages with borrowers and their contacts. When sending and receiving communications an interaction is usually created.

Send message

Send a message and save it as a new interaction.

The message is checked against Compliance Guard and may be rejected if it violates any rules.

If the message is accepted, it is queued for send. You can check the status of the queued interaction by calling GET on /interactions/{interactionId} endpoint with the interaction ID returned by this endpoint.

Note this is different from POSTing to a /interactions endpoint because those endpoints create the interaction object, but do NOT send an actual message.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
Request Body schema: application/json
required
subject
required
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.

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" "paymentDueDateReminder" "paymentFailed" "paymentMethodAdded" "paymentMethodUpdated" "paymentProcessing" "paymentRescheduled" "paymentReversalFailed" "paymentReversalProcessing" "paymentSuccessful" "payoffStatementDocument" "promiseToPayPlanCreated" "promoProgramCanceled" "promoProgramEligibilityAtRisk" "promoProgramExercised" "promoProgramReminder" "reimbursementFailed" "reimbursementProcessed" "reimbursementScheduled" "scraApplicationDenied" "scraBenefitsApplied" "scraBenefitsExpiringNotice" "scraCGFlaggedDocumentRequest" "scraServicemanNotifiedDocumentRequest" "settlementOffer" "settlementOfferFirstReminder" "statement" "statementLOC" "unmonitoredEmailAddress" "updateBankAccountConnection"
channel
string or null (InteractionChannel)

The channel where interactions with a borrower occur. For example, an outbound call with a borrower is considered voice.

Enum: "voice" "email" "fax" "text" "chat" "mail" "gui" "document"
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"
personId
required
string

The Borrower ID of the borrower to which this message should be sent.

contactId
string

The Contact ID of the borrower to which this message should be sent.

If not provided then the system will try to select an appropriate contact based on the type of message being sent. (e.g., if this is an email select the primary email address; if this is a text message select the borrower's mobile phone.)

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.

caseId
string

Mark a particular case as associated with this message.

statementId
string

Mark a particular statement as associated with this message.

context
object (ContextObject)

The data used to render the template. Provided in JSON format, it must be a mapping of context variables to values.

The context variables of borrower, loan, case and statement do not need to be provided since the system will automatically add these objects to context assuming you provide personId, loanId, caseId and statementId to the endpoint.

For example if your provided the context...

{
  "dateSigned": "Aug 27, 2021"
  "lenderName": "Peachy Lender"
  "paymentMethod": "bankAccount"
  "paymentMethodLastFour": "1110"
  "supportEmail": "support@peach.com"
  "supportPhone": "888-888-8888"
}

...then a template like Hello from {{lenderName}}! would render like Hello from Peachy Lender!

attachments
Array of strings

List of document IDs for documents to attach to the outgoing email.

supercaseBulkOperationId
string
previousInteractionId
string
isTransactional
boolean (SendIsTransactionalDefaultTrue)
Default: true

If true, then sent this interaction as "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".

Additionally, a transactional interaction may be sent with different "From:" and "Reply-To:" fields depending on configuration. The purpose here being that it may be desirable to send messages from an email address that is clearly marked as "unmonitored", so that recipients do not try to respond directly to those email addresses.

useTemplate
boolean
Default: true

Only applicable when channel=mail. If false, will not generate content from a template and will instead only use the documents referenced in the attachments field.

interactionExternalId
string

The external ID of the interaction that will be created as a result of this request. Subsequent attempts to send with the same external ID will be blocked.

sendAt
string <date-time>

This attribute determines when the message should be sent. If set to null, and the message's timing conflicts with Compliance Guard's time-of-day restrictions, Communicator will automatically reschedule it to an allowable time. If this auto-rescheduling occurs, the sendAt field in the Interaction response will show the new scheduled time, and the Interaction status will be marked as scheduled.

To bypass auto-rescheduling, input the current time for sendAt when calling the endpoint.

Additional Information:

  • Regardless of when the message is scheduled to send, its content will be generated immediately upon calling this endpoint.
  • You can manually set a future send time of up to 7 days in the future.
sendJitter
integer <int32>

The maximum number of seconds to add to the send time for this communication. The actual time added will be between 0 and this value. This is useful for spreading out the delivery of a large batch of messages over a period of time in order to avoid delaying other time-sensitive communcations.

strictUndefined
boolean
Default: false

If true an error will be returned if the template contains a variable that is not defined in the context. For historical reasons this is false by default, but it is recommended to set this to true.

Responses
202

OK

409

The request was well-formed but was unable to be processed due to failed business logic validations. This includes scenarios where:

  • The template for this type of message is disabled.
  • No suitable email or phone contact found.
  • The contact does not belong to the specified borrower.
  • The borrower is inactive or not eligible for the type of interaction attempted.
  • Communication consent for the requested channel has been revoked by the borrower.
  • The contact information is marked as invalid or archived.
  • The borrower has opted out of receiving certain types of messages (e.g., text messages) to the specified contact method.
  • The interaction is blocked by Compliance Guard due to federal, state, or business rules violations.
  • The request fails due to time-of-day restrictions outside permitted communication hours, though this case will specifically include a sendAt attribute indicating the next allowable time.
  • The loan associated with the communication is missing critical details or does not belong to the borrower.
  • An invalid address prevents determining applicable state rules for communication. Each failure is accompanied by a detailed message explaining the specific reason the interaction cannot proceed.
post/communicator/send
Request samples
application/json
{
  • "subject": "annualPrivacyPolicyNotice",
  • "channel": "voice",
  • "theme": "agentNotification",
  • "personId": "BO-AAAA-BBBB",
  • "contactId": "BO-AAAA-BBBB",
  • "loanId": "LN-AAAA-BBBB",
  • "loanIds": [
    ],
  • "caseId": "CS-AAAA-BBBB",
  • "statementId": "SM-AAAA-BBBB",
  • "context": { },
  • "attachments": [
    ],
  • "supercaseBulkOperationId": "string",
  • "previousInteractionId": "string",
  • "isTransactional": true,
  • "useTemplate": true,
  • "interactionExternalId": "string",
  • "sendAt": "2019-08-24T14:15:22Z",
  • "sendJitter": 0,
  • "strictUndefined": false
}
Response samples
application/json
{
  • "message": "string"
}

Receive message

Receive a message.

This is different from a normal /interactions creation because it creates the interaction and also performs associated "inbound message" actions:

  • if the message is an email sent to an email address configured as "unmonitored", it will autorespond that the email was not received because it was sent to an "unmonitored address".
  • it will publish a taskrouter task for inbound interactions (either handleInboundInteraction or handleUnboundInboundInteraction).
Securityoauth2 or bearerAuth or apiKeyHeader
Request
Request Body schema: application/json
required
Any of:
channel
required
string

The channel by which an interaction occurs.

Enum: "fax" "mail" "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

An identifier of an existing contact.

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.

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.

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" "paymentDueDateReminder" "paymentFailed" "paymentMethodAdded" "paymentMethodUpdated" "paymentProcessing" "paymentRescheduled" "paymentReversalFailed" "paymentReversalProcessing" "paymentSuccessful" "payoffStatementDocument" "promiseToPayPlanCreated" "promoProgramCanceled" "promoProgramEligibilityAtRisk" "promoProgramExercised" "promoProgramReminder" "reimbursementFailed" "reimbursementProcessed" "reimbursementScheduled" "scraApplicationDenied" "scraBenefitsApplied" "scraBenefitsExpiringNotice" "scraCGFlaggedDocumentRequest" "scraServicemanNotifiedDocumentRequest" "settlementOffer" "settlementOfferFirstReminder" "statement" "statementLOC" "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"
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.

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"
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 .

metaData
object or null (MetaData)

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

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.

direction
string (InteractionDirection)
Enum: "outbound" "inbound"
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"
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"
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.

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.

scheduledAtFrom
string <date-time>

Time to start the scheduled interaction.

scheduledAtTo
string <date-time>

Time to end the scheduled interaction.

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.

personId
string or null

The ID of the borrower to which this interaction is associated

Responses
200

Success

post/communicator/receive
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",
  • "loanId": "LN-AAAA-BBBB",
  • "loanIds": [
    ],
  • "subject": "annualPrivacyPolicyNotice",
  • "theme": "agentNotification",
  • "borrowerSelectedTheme": "agentNotification",
  • "sensitive": false,
  • "isExternal": true,
  • "externalId": "string",
  • "previousInteractionId": "string",
  • "status": "attempted",
  • "twilioErrorCode": "string",
  • "metaData": { },
  • "isTransactional": true,
  • "direction": "outbound",
  • "contactExternalId": "string",
  • "agentOutcome": "voiceSpokeWithFirstParty",
  • "statusDetails": "voiceSpokeWithFirstParty",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "endedAt": "2019-08-24T14:15:22Z",
  • "scheduledAtFrom": "2019-08-24T14:15:22Z",
  • "scheduledAtTo": "2019-08-24T14:15:22Z",
  • "failureDescriptionShort": "string",
  • "failureDescriptionLong": "string",
  • "complianceGuardRuleId": "string",
  • "borrower": {
    },
  • "contact": {
    },
  • "personId": "string"
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Resend existing interaction

Copy the fields from an existing interaction into a new interaction and queue that new interaction for sending.

WARNING: This message is not checked against Compliance Guard.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
Request Body schema: application/json
required
interactionId
required
string

The interaction to resend.

Responses
202

Accepted

404

Not Found

post/communicator/resend
Request samples
application/json
{
  • "interactionId": "string"
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Render to download

Render a file (text, html or pdf) from template and download it.

It selects an appropriate Template Descriptor (matching subject, channel), and renders the active Template Version with the given context. Only the content matching the fmt query parameter is returned in the file.

The rendered template file is then downloaded as an attachment. (i.e., a response is sent with the header Content-Disposition: attachment.)

Note: that a Document Descriptor is NOT created.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
query Parameters
fmt
string
Default: "html"

The desired output format.

Enum: "text" "html" "pdf"
Request Body schema: application/json
required

Template selectors and the data

subject
required
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.

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" "paymentDueDateReminder" "paymentFailed" "paymentMethodAdded" "paymentMethodUpdated" "paymentProcessing" "paymentRescheduled" "paymentReversalFailed" "paymentReversalProcessing" "paymentSuccessful" "payoffStatementDocument" "promiseToPayPlanCreated" "promoProgramCanceled" "promoProgramEligibilityAtRisk" "promoProgramExercised" "promoProgramReminder" "reimbursementFailed" "reimbursementProcessed" "reimbursementScheduled" "scraApplicationDenied" "scraBenefitsApplied" "scraBenefitsExpiringNotice" "scraCGFlaggedDocumentRequest" "scraServicemanNotifiedDocumentRequest" "settlementOffer" "settlementOfferFirstReminder" "statement" "statementLOC" "unmonitoredEmailAddress" "updateBankAccountConnection"
channel
required
string

Templates with the same subject can have multiple versions per channel. For example: paymentFailed can have email and text message (aka SMS) versions.

Enum: "email" "text" "mail" "gui" "document"
personId
required
string

The unique identifier of the Borrower. Can be Peach or a lender's external identifier. The borrower attributes will be used as dynamic fields in the template.

loanId
string

The unique identifier of the Loan. Can be Peach or lender's external identifier. The loan attributes will be used as dynamic fields in the template.

caseId
string

The unique identifier of the Case. Can be Peach or lender's external identifier. The case attributes will be used as dynamic fields in the template.

context
object (ContextObject)

The data used to render the template. Provided in JSON format, it must be a mapping of context variables to values.

The context variables of borrower, loan, case and statement do not need to be provided since the system will automatically add these objects to context assuming you provide personId, loanId, caseId and statementId to the endpoint.

For example if your provided the context...

{
  "dateSigned": "Aug 27, 2021"
  "lenderName": "Peachy Lender"
  "paymentMethod": "bankAccount"
  "paymentMethodLastFour": "1110"
  "supportEmail": "support@peach.com"
  "supportPhone": "888-888-8888"
}

...then a template like Hello from {{lenderName}}! would render like Hello from Peachy Lender!

Responses
200

OK

post/communicator/render
Request samples
application/json
{
  • "subject": "annualPrivacyPolicyNotice",
  • "channel": "email",
  • "personId": "string",
  • "loanId": "string",
  • "caseId": "string",
  • "context": { }
}

Render to document

Render a file (text, html or pdf) from template and write it to a document descriptor.

It selects an appropriate Template Descriptor (matching subject, channel), and renders the active Template Version with the given context. Only the content matching the fmt query parameter is returned in the file.

The rendered template file is then associated with the given documentId. (i.e., this new content can be downloaded via that Document Descriptor.)

WARNING: if there is existing document content for that document it will be overwritten.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
query Parameters
fmt
string
Default: "html"

The desired output format.

Enum: "text" "html" "pdf"
Request Body schema: application/json
required

Template selectors, context and the document ID.

subject
required
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.

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" "paymentDueDateReminder" "paymentFailed" "paymentMethodAdded" "paymentMethodUpdated" "paymentProcessing" "paymentRescheduled" "paymentReversalFailed" "paymentReversalProcessing" "paymentSuccessful" "payoffStatementDocument" "promiseToPayPlanCreated" "promoProgramCanceled" "promoProgramEligibilityAtRisk" "promoProgramExercised" "promoProgramReminder" "reimbursementFailed" "reimbursementProcessed" "reimbursementScheduled" "scraApplicationDenied" "scraBenefitsApplied" "scraBenefitsExpiringNotice" "scraCGFlaggedDocumentRequest" "scraServicemanNotifiedDocumentRequest" "settlementOffer" "settlementOfferFirstReminder" "statement" "statementLOC" "unmonitoredEmailAddress" "updateBankAccountConnection"
channel
required
string

Templates with the same subject can have multiple versions per channel. For example: paymentFailed can have email and text message (aka SMS) versions.

Enum: "email" "text" "mail" "gui" "document"
personId
required
string

The unique identifier of the Borrower. Can be Peach or a lender's external identifier. The borrower attributes will be used as dynamic fields in the template.

loanId
string

The unique identifier of the Loan. Can be Peach or lender's external identifier. The loan attributes will be used as dynamic fields in the template.

caseId
string

The unique identifier of the Case. Can be Peach or lender's external identifier. The case attributes will be used as dynamic fields in the template.

context
object (ContextObject)

The data used to render the template. Provided in JSON format, it must be a mapping of context variables to values.

The context variables of borrower, loan, case and statement do not need to be provided since the system will automatically add these objects to context assuming you provide personId, loanId, caseId and statementId to the endpoint.

For example if your provided the context...

{
  "dateSigned": "Aug 27, 2021"
  "lenderName": "Peachy Lender"
  "paymentMethod": "bankAccount"
  "paymentMethodLastFour": "1110"
  "supportEmail": "support@peach.com"
  "supportPhone": "888-888-8888"
}

...then a template like Hello from {{lenderName}}! would render like Hello from Peachy Lender!

statementId
string

The unique identifier of the Statement. Can be Peach or lender's external identifier. The statement attributes will be used as dynamic fields in the template.

documentId
required
string

The unique identifier of the Document Descriptor. Can be Peach or lender's external identifier. The rendered content will create a file in HTML or text format and associate it with the documentId. To convert the rendered document to PDF please use another endpoint, convert_person_document, as an extra step.

Responses
200

OK

post/communicator/render-to-document
Request samples
application/json
{
  • "subject": "annualPrivacyPolicyNotice",
  • "channel": "email",
  • "personId": "string",
  • "loanId": "string",
  • "caseId": "string",
  • "context": { },
  • "statementId": "string",
  • "documentId": "string"
}

Render template preview for subject

Render the template and return as a JSON response.

It selects an appropriate Template Descriptor (matching subject, channel), and renders the active Template Version with the given context.

The three contents are returned in a single JSON response, they are contentHtml, contentText and subjectLine.

NOTE: This is different from the /render endpoints because it does not return a file but rather the simple text-respresentation of the rendered templates that would be used in rendering a file. It is generally easier to test and debug the rendered templates as JSON strings rather than, for instance a PDF file.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
Request Body schema: application/json
required

Template selectors and the data.

subject
required
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.

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" "paymentDueDateReminder" "paymentFailed" "paymentMethodAdded" "paymentMethodUpdated" "paymentProcessing" "paymentRescheduled" "paymentReversalFailed" "paymentReversalProcessing" "paymentSuccessful" "payoffStatementDocument" "promiseToPayPlanCreated" "promoProgramCanceled" "promoProgramEligibilityAtRisk" "promoProgramExercised" "promoProgramReminder" "reimbursementFailed" "reimbursementProcessed" "reimbursementScheduled" "scraApplicationDenied" "scraBenefitsApplied" "scraBenefitsExpiringNotice" "scraCGFlaggedDocumentRequest" "scraServicemanNotifiedDocumentRequest" "settlementOffer" "settlementOfferFirstReminder" "statement" "statementLOC" "unmonitoredEmailAddress" "updateBankAccountConnection"
channel
required
string or null (InteractionChannel)

The channel where interactions with a borrower occur. For example, an outbound call with a borrower is considered voice.

Enum: "voice" "email" "fax" "text" "chat" "mail" "gui" "document"
personId
required
string
loanId
string
caseId
string
context
object
Responses
200

OK

post/communicator/preview
Request samples
application/json
{
  • "subject": "annualPrivacyPolicyNotice",
  • "channel": "voice",
  • "personId": "string",
  • "loanId": "string",
  • "caseId": "string",
  • "context": { }
}
Response samples
application/json
{
  • "subjectLine": "string",
  • "contentHtml": "string",
  • "contentText": "string"
}

Send free-form email

Sends an email with the freeFormBranded template.

This selects the Template Descriptor with subject=freeFormBranded and its currently active Template Version. The `freeFormBranded`` template allows for the insertion of completely custom content within a standard branded email template.

WARNING: This endpoint is not checked against Compliance Guard.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
Request Body schema: application/json
required
personalizations
required
Array of any

Specifies the email destination. See the body of POST /mail/send at https://sendgrid.com/docs/api-reference/.

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"
language
string (language) = 2 characters
Default: "en"

The ISO 639-1 two character code of the email language.

subjectLine
string

The subject line of the email.

contentHtml
string

The content of the email in the HTML format.

contentPlain
string

The content of the email in the plain text format.

previousInteractionId
string

The ID of an existing interaction to link the new interaction to.

isTransactional
boolean (SendIsTransactionalDefaultFalse)
Default: false

If true, then sent this interaction as "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".

Additionally, a transactional interaction may be sent with different "From:" and "Reply-To:" fields depending on configuration. The purpose here being that it may be desirable to send messages from an email address that is clearly marked as "unmonitored", so that recipients do not try to respond directly to those email addresses.

Responses
202

Accepted

post/communicator/send-free-form-email
Request samples
application/json
{
  • "personalizations": [
    ],
  • "theme": "agentNotification",
  • "language": "en",
  • "subjectLine": "string",
  • "contentHtml": "string",
  • "contentPlain": "string",
  • "previousInteractionId": "string",
  • "isTransactional": false
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Preview free-form email

Render a template for "free-form" emails and return is as JSON.

A free-form message is one that can contain any content.

Templates previewed via this endpoint will be free-form but still be branded. i.e., they will use the freeFormBranded interaction subject, not freeForm.

This returns the three contents of a template in a single JSON response, they are contentHtml, contentText and subjectLine.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
Request Body schema: application/json
required

Subject line and content of the free form email.

subjectLine
string

The subject line of the email.

contentHtml
string

The content of the email in the HTML format.

contentPlain
string

The content of the email in the plain text format.

Responses
200

OK

post/communicator/preview-free-form-email
Request samples
application/json
{
  • "subjectLine": "string",
  • "contentHtml": "string",
  • "contentPlain": "string"
}
Response samples
application/json
{
  • "subjectLine": "string",
  • "contentHtml": "string",
  • "contentText": "string"
}

Send confirmation code for contact verification

Send a verification code to an email or phone number.

This creates a confirmation code in the system which can be used via the .../contacts endpoint to verify the contact. (i.e., this sets the verified attribute of the contact to true.)

This endpoint is rate limited to 10 requests per borrower per hour.

An interaction is created with InteractionSubject confirmationCode.

NOTE: This endpoint is not checked against Compliance Guard, however it should never be necessary to restrict sending confirmation codes due to compliance guard rules.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
Request Body schema: application/json
required
personId
required
string

The borrower's unique identifier. Can be Peach or lender's external identifier.

email
string

The destination email address.

phone
string

The destination phone number.

channel
string or null (InteractionChannel)

The channel where interactions with a borrower occur. For example, an outbound call with a borrower is considered voice.

Enum: "voice" "email" "fax" "text" "chat" "mail" "gui" "document"
context
object

Template specific properties to substitute in the corresponding ConfirmationCode template.

Responses
202

OK

post/communicator/send-confirmation-code
Request samples
application/json
{
  • "personId": "string",
  • "email": "string",
  • "phone": "string",
  • "channel": "voice",
  • "context": { }
}

List subject desciptors

List all the currently available Interaction Subject descriptors.

An interaction subject is the category or topic to which an interaction pertains. (Note this is different from the subject line of an email message.)

For example, an email or a text message will necessarily contain different content due to their nature, but they still might pertain to the subject of paymentReminder. Similarly, a phone call despite not being text based at all might also pertain to the subject of paymentReminder.

Securityoauth2 or bearerAuth or apiKeyHeader
Responses
200

OK

get/communicator/subjects
Response samples
application/json
[
  • {
    }
]

Get subject descriptor

Get the descriptor for a specific Interaction Subject.

Note that subject descriptors do not have an id field but are instead identified by their unique subject field.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
subject
required
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.

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" "paymentDueDateReminder" "paymentFailed" "paymentMethodAdded" "paymentMethodUpdated" "paymentProcessing" "paymentRescheduled" "paymentReversalFailed" "paymentReversalProcessing" "paymentSuccessful" "payoffStatementDocument" "promiseToPayPlanCreated" "promoProgramCanceled" "promoProgramEligibilityAtRisk" "promoProgramExercised" "promoProgramReminder" "reimbursementFailed" "reimbursementProcessed" "reimbursementScheduled" "scraApplicationDenied" "scraBenefitsApplied" "scraBenefitsExpiringNotice" "scraCGFlaggedDocumentRequest" "scraServicemanNotifiedDocumentRequest" "settlementOffer" "settlementOfferFirstReminder" "statement" "statementLOC" "unmonitoredEmailAddress" "updateBankAccountConnection"
Responses
200

OK

get/communicator/subjects/{subject}
Response samples
application/json
{
  • "subject": "annualPrivacyPolicyNotice",
  • "title": "string",
  • "theme": "agentNotification",
  • "caseTypes": [
    ],
  • "agentCanSend": true,
  • "previewOnly": true
}

Update subject descriptor

Update the descriptor for a specific Interaction Subject.

Note that subject descriptors do not have an id field but are instead identified by their unique subject field.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
subject
required
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.

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" "paymentDueDateReminder" "paymentFailed" "paymentMethodAdded" "paymentMethodUpdated" "paymentProcessing" "paymentRescheduled" "paymentReversalFailed" "paymentReversalProcessing" "paymentSuccessful" "payoffStatementDocument" "promiseToPayPlanCreated" "promoProgramCanceled" "promoProgramEligibilityAtRisk" "promoProgramExercised" "promoProgramReminder" "reimbursementFailed" "reimbursementProcessed" "reimbursementScheduled" "scraApplicationDenied" "scraBenefitsApplied" "scraBenefitsExpiringNotice" "scraCGFlaggedDocumentRequest" "scraServicemanNotifiedDocumentRequest" "settlementOffer" "settlementOfferFirstReminder" "statement" "statementLOC" "unmonitoredEmailAddress" "updateBankAccountConnection"
Request Body schema: application/json
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"
caseTypes
Array of strings (BaseCaseType)
Items Enum: "generic" "bankruptcy" "ceaseCommunication" "collection" "deceased" "disputeOfDebt" "federalEmergency" "identityTheft" "legalAction" "militaryDuty" "debtValidation" "oFACSanctionedIndividual" "disputeOfPurchase" "creditBureauDispute"
agentCanSend
boolean

If set to true, agent can send message with this subject from CRM.

previewOnly
boolean

If true, the output of templates with this subject must be edited before sending.

Responses
200

OK

put/communicator/subjects/{subject}
Request samples
application/json
{
  • "theme": "agentNotification",
  • "caseTypes": [
    ],
  • "agentCanSend": true,
  • "previewOnly": true
}
Response samples
application/json
{
  • "subject": "annualPrivacyPolicyNotice",
  • "title": "string",
  • "theme": "agentNotification",
  • "caseTypes": [
    ],
  • "agentCanSend": true,
  • "previewOnly": true
}