Contact Information

This object allows you to add and manage a Borrower's contact information. A Borrower can have an "unlimited" number of contacts. However, it is important to properly create key contact objects.

Peach Borrower Portal (if used by the lender), shows the following contacts only:

EMAIL contactType=email, label=personal or work, affiliation=self, status=primary.

MOBILE PHONE contactType=phone, label=personal, affiliation=self, status=primary.

HOME PHONE contactType=phone, label=home, affiliation=self, status=secondary.

HOME ADDRESS contactType=address, label=home, affiliation=self, status=primary.

The Peach system sends notices (e.g. payment reminder) to borrowers (if configured by the lender). In order for a notice to be sent successfully, both contact object and template must exist. If a contact cannot be found, the system will not send a notice. The system will try to find the following contact objects:

Email notices: contactType=email, valid=true, affiliation=self, status=primary (if "primary" is not found, the system searches for "secondary" and then for "additional")

Text message/SMS notices: contactType=phone, valid=true, affiliation=self, receiveTextMessages=true, label=personal, status=primary (if "primary" is not found, the system searches for "secondary" and then for "additional")

Create contact information

Add new contact information and associate it with a borrower.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string^ext-|^[A-Z]{2}-[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
validate
boolean
Default: true

Validate the contact through an external API. This is only used for addresses currently.

confirmationCode
string^\d{6}$

The previously emailed or texted confirmation code.

Request Body schema: application/json
externalId
string or null [ 1 .. 255 ] characters

A lender's identifier for an object. 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.

contactType
string

The type of contact.

phone and whatsApp should be provided in E.164 format.

email should be provided in aaa@bbb.com format.

address is the mailing address.

fbMessenger can be phone or email.

Enum: "phone" "email" "address" "whatsApp" "fbMessenger"
label
string

The contact label.

A person's mobile phone should be labeled as personal.

A person's home address should be labeled as home.

A servicemember's military unit or commander contact should be labeled as military.

Automated text messages (e.g. payment reminder) can only be sent to contactType=phone, label=personal and affiliation=self.

Enum: "personal" "home" "work" "military"
affiliation
string

The contact affiliation.

self - denotes direct contact of the person. All self contacts are cosidered to be first-party.

spouse, parent, guardian, executor, administrator, legal and otherRelative - are considered to be a third-party. Some regulations define these to be the consumer (aka the person) for purposes of debt collection efforts. This means that a debt collector may communicate about the debt with the consumer’s spouse, parent (if the consumer is a minor), guardian, executor, or administrator (or with the attorney of any of these persons).

Automated text messages (e.g. payment reminder) can only be sent to contactType=phone, label=personal and affiliation=self.

Enum: "self" "spouse" "parent" "guardian" "executor" "administrator" "otherRelative" "legal" "businessOwner" "businessExecutive" "businessEmployee"
name
string or null [ 0 .. 50 ] characters

Full name of a third-party contact. Only applicable for third-party contacts, such as spouse, parent, etc.

value
string

The value of a contact. This attribute should be used for all contact types except for address, which has dedicated attributes such as addressLine1, addressCity, etc. You should use either value or address attributes depending on the contact type. For example, +14155552671 for a contact type=phone. Or, john.smith@domain.com for a contact type=email. We'll validate the format based on the contact type.

object

The mailing address.

valid
boolean
Default: true

Identifies a contact as valid or invalid. A contact can become invalid for multiple reasons, such as wrong format, invalid email domain, etc. This attribute can be changed by you or by Peach. If no value is provided, we will assume valid=true.

verified
boolean
Default: false

Identifies a contact as verified or unverified. Contact can be verified via a verification code, verification link or a first-party outbound call. The value can be changed by you or by Peach. If no value is provided, we will assume verified=false.

receiveTextMessages
boolean
Default: false

Allows using a phone type contact for text messaging.

authorizedThirdParty
boolean
Default: false

Signifies an individual authorized by the borrower to make purchases and changes against the account that is the subject of the collection efforts. This attribute is not applicable to contacts with affiliation self.

powerOfAttorney
boolean
Default: false

Designated an individual with power of attorney. This attribute can only be set by agents upon receiving appropriate documents from the borrower or their attorney. This attribute is not applicable to contacts with affiliation self.

status
string

Describes the contact status as primary, secondary, additional or archived. Within a set of contacts with the same contactType and affilation only one primary and only one secondary contacts are allowed. There may be multiple additional and archived contacts.

If a new contact is created as primary and there is an existing primary contact with the same contactType and affilation, the status of the exising contact will be automatically changed to additional.

If a new contact is created as secondary and there is an existing secondary contact with the same contactType and affilation, the status of the existing contact will be automatically changed to additional.

Enum: "primary" "secondary" "additional" "archived"
Responses
200

Success

post/people/{personId}/contacts
Request samples
application/json
{
  • "externalId": "string",
  • "contactType": "phone",
  • "label": "personal",
  • "affiliation": "self",
  • "name": "string",
  • "value": "string",
  • "address": {
    },
  • "valid": true,
  • "verified": false,
  • "receiveTextMessages": false,
  • "authorizedThirdParty": false,
  • "powerOfAttorney": false,
  • "status": "primary"
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Get contacts information

Get all contact information items associated with a borrower.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string^ext-|^[A-Z]{2}-[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.

sortBy
Array of strings

The data attributes by which to sort the results.

collidesWithEmail
string

Filters for contacts which would collide with this email if it were used to create a new borrower contact.

collidesWithPhone
string

Filters for contacts which would collide with this phone number if it were used to create a new borrower contact.

contactType
string

The contact type to filter by.

Enum: "phone" "email" "address" "whatsApp" "fbMessenger"
affiliation
string

The contact affiliation to filter by.

Enum: "self" "spouse" "parent" "guardian" "executor" "administrator" "otherRelative" "legal" "businessOwner" "businessExecutive" "businessEmployee"
label
string

The contact label to filter by.

Enum: "personal" "home" "work" "military"
status
string

The contact status to filter by.

Enum: "primary" "secondary" "additional" "archived"
includeArchived
boolean
Default: false

Include archived contacts into the result.

includeLegal
boolean
Default: true

Whether or not to include legal representation contact objects.

receiveTextMessages
boolean

If passed, only returns contacts with receiveTextMessages set to that value.

Responses
200

Success

get/people/{personId}/contacts
Response samples
application/json
{
  • "count": 0,
  • "data": [
    ]
}

Get contact information by ID

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string^ext-|^[A-Z]{2}-[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.

contactId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

The contact ID.

Responses
200

Success

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

Update contact information

Update a borrower's contact information.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string^ext-|^[A-Z]{2}-[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.

contactId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

The contact ID.

query Parameters
confirmationCode
string^\d{6}$

The previously emailed or texted confirmation code.

validate
boolean
Default: true

Validate the contact through an external API. This is only used for addresses currently.

Request Body schema: application/json
externalId
string or null [ 1 .. 255 ] characters

A lender's identifier for an object. 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.

contactType
string

The type of contact.

phone and whatsApp should be provided in E.164 format.

email should be provided in aaa@bbb.com format.

address is the mailing address.

fbMessenger can be phone or email.

Enum: "phone" "email" "address" "whatsApp" "fbMessenger"
label
string

The contact label.

A person's mobile phone should be labeled as personal.

A person's home address should be labeled as home.

A servicemember's military unit or commander contact should be labeled as military.

Automated text messages (e.g. payment reminder) can only be sent to contactType=phone, label=personal and affiliation=self.

Enum: "personal" "home" "work" "military"
affiliation
string

The contact affiliation.

self - denotes direct contact of the person. All self contacts are cosidered to be first-party.

spouse, parent, guardian, executor, administrator, legal and otherRelative - are considered to be a third-party. Some regulations define these to be the consumer (aka the person) for purposes of debt collection efforts. This means that a debt collector may communicate about the debt with the consumer’s spouse, parent (if the consumer is a minor), guardian, executor, or administrator (or with the attorney of any of these persons).

Automated text messages (e.g. payment reminder) can only be sent to contactType=phone, label=personal and affiliation=self.

Enum: "self" "spouse" "parent" "guardian" "executor" "administrator" "otherRelative" "legal" "businessOwner" "businessExecutive" "businessEmployee"
name
string or null [ 0 .. 50 ] characters

Full name of a third-party contact. Only applicable for third-party contacts, such as spouse, parent, etc.

value
string

The value of a contact. This attribute should be used for all contact types except for address, which has dedicated attributes such as addressLine1, addressCity, etc. You should use either value or address attributes depending on the contact type. For example, +14155552671 for a contact type=phone. Or, john.smith@domain.com for a contact type=email. We'll validate the format based on the contact type.

object

The mailing address.

valid
boolean
Default: true

Identifies a contact as valid or invalid. A contact can become invalid for multiple reasons, such as wrong format, invalid email domain, etc. This attribute can be changed by you or by Peach. If no value is provided, we will assume valid=true.

verified
boolean
Default: false

Identifies a contact as verified or unverified. Contact can be verified via a verification code, verification link or a first-party outbound call. The value can be changed by you or by Peach. If no value is provided, we will assume verified=false.

receiveTextMessages
boolean
Default: false

Allows using a phone type contact for text messaging.

authorizedThirdParty
boolean
Default: false

Signifies an individual authorized by the borrower to make purchases and changes against the account that is the subject of the collection efforts. This attribute is not applicable to contacts with affiliation self.

powerOfAttorney
boolean
Default: false

Designated an individual with power of attorney. This attribute can only be set by agents upon receiving appropriate documents from the borrower or their attorney. This attribute is not applicable to contacts with affiliation self.

object
Responses
200

Success

put/people/{personId}/contacts/{contactId}
Request samples
application/json
{
  • "externalId": "string",
  • "contactType": "phone",
  • "label": "personal",
  • "affiliation": "self",
  • "name": "string",
  • "value": "string",
  • "address": {
    },
  • "valid": true,
  • "verified": false,
  • "receiveTextMessages": false,
  • "authorizedThirdParty": false,
  • "powerOfAttorney": false,
  • "phoneDisconnectionDetails": {
    }
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Delete contact information

Delete a borrower's contact information.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string^ext-|^[A-Z]{2}-[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.

contactId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

The contact ID.

Responses
204

Success no content

delete/people/{personId}/contacts/{contactId}

Clone contact information

Clones the borrower's contact information. Copies all properties from the existing contact and applies the passed properties. Sets externalId of the existing contact to null. Sets the status of the existing contact to archived. Returns the new contact with a new Peach Id.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string^ext-|^[A-Z]{2}-[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.

contactId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

The contact ID.

query Parameters
confirmationCode
string^\d{6}$

The previously emailed or texted confirmation code.

validate
boolean
Default: true

Validate the contact through an external API. This is only used for addresses currently.

Request Body schema: application/json
externalId
string or null [ 1 .. 255 ] characters

A lender's identifier for an object. 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.

contactType
string

The type of contact.

phone and whatsApp should be provided in E.164 format.

email should be provided in aaa@bbb.com format.

address is the mailing address.

fbMessenger can be phone or email.

Enum: "phone" "email" "address" "whatsApp" "fbMessenger"
label
string

The contact label.

A person's mobile phone should be labeled as personal.

A person's home address should be labeled as home.

A servicemember's military unit or commander contact should be labeled as military.

Automated text messages (e.g. payment reminder) can only be sent to contactType=phone, label=personal and affiliation=self.

Enum: "personal" "home" "work" "military"
affiliation
string

The contact affiliation.

self - denotes direct contact of the person. All self contacts are cosidered to be first-party.

spouse, parent, guardian, executor, administrator, legal and otherRelative - are considered to be a third-party. Some regulations define these to be the consumer (aka the person) for purposes of debt collection efforts. This means that a debt collector may communicate about the debt with the consumer’s spouse, parent (if the consumer is a minor), guardian, executor, or administrator (or with the attorney of any of these persons).

Automated text messages (e.g. payment reminder) can only be sent to contactType=phone, label=personal and affiliation=self.

Enum: "self" "spouse" "parent" "guardian" "executor" "administrator" "otherRelative" "legal" "businessOwner" "businessExecutive" "businessEmployee"
name
string or null [ 0 .. 50 ] characters

Full name of a third-party contact. Only applicable for third-party contacts, such as spouse, parent, etc.

value
string

The value of a contact. This attribute should be used for all contact types except for address, which has dedicated attributes such as addressLine1, addressCity, etc. You should use either value or address attributes depending on the contact type. For example, +14155552671 for a contact type=phone. Or, john.smith@domain.com for a contact type=email. We'll validate the format based on the contact type.

object

The mailing address.

valid
boolean
Default: true

Identifies a contact as valid or invalid. A contact can become invalid for multiple reasons, such as wrong format, invalid email domain, etc. This attribute can be changed by you or by Peach. If no value is provided, we will assume valid=true.

verified
boolean
Default: false

Identifies a contact as verified or unverified. Contact can be verified via a verification code, verification link or a first-party outbound call. The value can be changed by you or by Peach. If no value is provided, we will assume verified=false.

receiveTextMessages
boolean
Default: false

Allows using a phone type contact for text messaging.

authorizedThirdParty
boolean
Default: false

Signifies an individual authorized by the borrower to make purchases and changes against the account that is the subject of the collection efforts. This attribute is not applicable to contacts with affiliation self.

powerOfAttorney
boolean
Default: false

Designated an individual with power of attorney. This attribute can only be set by agents upon receiving appropriate documents from the borrower or their attorney. This attribute is not applicable to contacts with affiliation self.

status
string

Describes the contact status as primary, secondary, additional or archived. Within a set of contacts with the same contactType and affilation only one primary and only one secondary contacts are allowed. There may be multiple additional and archived contacts.

If a new contact is created as primary and there is an existing primary contact with the same contactType and affilation, the status of the exising contact will be automatically changed to additional.

If a new contact is created as secondary and there is an existing secondary contact with the same contactType and affilation, the status of the existing contact will be automatically changed to additional.

Enum: "primary" "secondary" "additional" "archived"
Responses
200

Success

post/people/{personId}/contacts/{contactId}/clone
Request samples
application/json
{
  • "externalId": "string",
  • "contactType": "phone",
  • "label": "personal",
  • "affiliation": "self",
  • "name": "string",
  • "value": "string",
  • "address": {
    },
  • "valid": true,
  • "verified": false,
  • "receiveTextMessages": false,
  • "authorizedThirdParty": false,
  • "powerOfAttorney": false,
  • "status": "primary"
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}