# Create contact

Create contact for a borrower.

Endpoint: POST /people/{personId}/contacts
Version: 2025-03-26
Security: oauth2, bearerAuth, apiKeyHeader

## Path parameters:

  - `personId` (string, required)
    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)
    Validate the contact through an external API. This is only used for addresses currently.

  - `confirmationCode` (string)
    The previously emailed or texted confirmation code.

## Request fields (application/json):

  - `address` (object)
    The mailing address.

  - `address.POBox` (string,null)
    Post Office Box

  - `address.addressLine1` (string)
    Address line 1.

If company.allowPartialAddress=false, then this field is required, else it is not required

  - `address.addressLine2` (string,null)
    Address line 2.

  - `address.city` (string)
    City.

  - `address.country` (string, required)
    Country. English short name according to
[ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) standard.

  - `address.countyOrRegion` (string,null)
    County or region.

  - `address.postalCode` (string, required)
    Postal code. Also known as ZIP code.

  - `address.state` (string,null)
    State/Province. This is a required field if the country is US or CA.

  - `affiliation` (string)
    All contacts are associated with one borrower. Sometimes the contact represents information
about the borrower person themselves—e.g., the borrower's address. Sometimes the contact
represents information about a person affiliated with the borrower.

self - denotes contact information about the borrower. All self contacts are considered 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 people).

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"

  - `authorizedThirdParty` (boolean)
    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.

  - `contactType` (string)
    The type of contact.

phone and whatsApp should be provided in _[E.164](https://en.wikipedia.org/wiki/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"

  - `externalId` (string,null)
    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.

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

  - `name` (string,null)
    Full name of a third-party contact. Only applicable for third-party contacts, such as spouse, parent, etc.

  - `phoneDisconnectionDetails` (object)

  - `phoneDisconnectionDetails.lastKnownConnectionDate` (string,null)
    The date obtained by the borrower to contact them or a past date in which the lender is
reasonably certain that the borrower could still be reached at that number. When contact
is created the lastKnownConnectionDate is equal to createdAt::date. This date is used
to monitor the disconnect status in the Reassigned Numbers Database (RND).

  - `powerOfAttorney` (boolean)
    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.

  - `receiveTextMessages` (boolean)
    Allows using a phone type contact for text messaging.

  - `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 existing 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"

  - `valid` (boolean)
    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.

  - `value` (string,null)
    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.

For callers lacking the person:read.pii permission this value is redacted
based on contactType: phone and whatsApp are masked to the last four
digits (e.g. 1234), email is masked (e.g. j*@example.com), and
address and all other types are returned as null.

  - `verified` (boolean)
    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.

## Response 200 fields (application/json):

  - `message` (string)
    Description of the server action or error.

  - `status` (integer)
    HTTP status code.

  - `data` (object)
    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.