Register a buyer

post https://api-preview.platform.breadpayments.com/api/buyer

Allows a user to register a buyer, which may result in creating a new buyer (201 Created) or updating an existing buyer (200 OK), depending on identity matching.

If a new buyer is created:

Values for name, phone, and email found in the request payload will automatically create a contact and set that contactID as the primaryContactID. The address on this contact will not be populated and must be updated via the appropriate endpoint.
Status and substatus are both set to "Active".

If an existing buyer is updated:

See "Update a buyer" for additional details on updating.
Partial updates are not supported. The user of this API must supply all buyer fields in order to avoid omitted fields being deleted.

Upon success, the details of the created or updated buyer will be returned.

Body Params

Buyer

activeAuthorizedThirdParties

array of objects

Subresource of buyer and acted on with its own set of endpoints

activeAuthorizedThirdParties

contacts

object

required

BuyerContactMap represents a mapping of buyer contact IDs to contacts

createdAt

date-time

required

The timestamp value formatted per RFC3339. This does not allow nulls.

employment

object

Optional. Employment represents the buyer's employment.

identity

object

required

Identity represents the identity of a buyer

languagePreference

string

required

length ≥ 2

The two language code as defined in ISO 639-1 along with subtags tag if applicable.

status

string

Status represents buyer status as string. Options available will depend
on tenant level configurations

subStatus

string

SubStatus represents buyer sub status as constant string. Options
available will depend on status value and tenant level configurations

tenantID

uuid

required

ID of the tenant associated with this buyer.

activeMilitary

boolean

Indicates if the buyer is a member of the armed forces.

bankruptcy

object

Bankruptcy represents a buyer's bankruptcy information

doNotSellOrShare

boolean

Indicates if the buyer has preference for their data not to be shared

primaryContact

object

BuyerContact represents a set of contact information.

doNotSellOrShareUpdatedAt

date-time

The timestamp value formatted per RFC3339. This does not allow nulls.

updatedAt

date-time

required

The timestamp value formatted per RFC3339. This does not allow nulls.

Responses

Response body

object

activeAuthorizedThirdParties

array of objects

Subresource of buyer and acted on with its own set of endpoints

activeAuthorizedThirdParties

object

buyerID

uuid

The ID of the buyer on whose behalf this authorized third party is allowed to act.

consentToCall

boolean

Defaults to false

Whether this authorized third party has consented to receive calls.

consentToEmail

boolean

Defaults to false

Whether this authorized third party has consented to receive emails.

consentToText

boolean

Defaults to false

Whether this authorized third party has consented to receive text messages.

createdAt

date-time

The timestamp value formatted per RFC3339. This does not allow nulls.

string

Email address

uuid

Unique ID associated with this authorized third party.

isActive

boolean

Defaults to false

Indicates whether this authorized third party is active.

name

object

required

Represents the full name

phone

string

required

Telephone number including country code

powerOfAttorney

boolean

Defaults to false

Indicates whether this authorized third party has power of attorney for the associated buyer. Power of attorney legally grants a third party the ability to represent the buyer in private affairs.

attorneyRepresentation

boolean

Defaults to false

Indicates whether this authorized third party is an attorney acting on behalf of the buyer.

type

string

AuthorizedThirdPartyType represents a authorized third party type as enum
Possible values: AUTHORIZED_THIRD_PARTY, POWER_OF_ATTORNEY, ATTORNEY_REPRESENTATION, GUARDIANSHIP

phoneType

string

PhoneType represents a phone type as enum
Possible values: MOBILE, WORK, HOME, OTHER

updatedAt

date-time

The timestamp value formatted per RFC3339. This does not allow nulls.

contacts

object

required

BuyerContactMap represents a mapping of buyer contact IDs to contacts

createdAt

date-time

required

The timestamp value formatted per RFC3339. This does not allow nulls.

employment

object

Optional. Employment represents the buyer's employment.

annualIncome

int64

Optional. The buyer's annual income in cents.

companyAddress

string

Required if employment type is EMPLOYED or SELF_EMPLOYED

companyName

string

Required if employment type is EMPLOYED or SELF_EMPLOYED

currency

string

length between 3 and 3

The three letter currency code as defined in ISO 4217.

description

string

Optional. Employment description.

occupation

string

Required if employment type is EMPLOYED or SELF_EMPLOYED

occupationDescription

string

Required if occupation is "Other"

type

string

required

EmploymentType represents a buyer employment type as enum
Possible values: EMPLOYED, SELF_EMPLOYED, UNEMPLOYED, STUDENT, RETIRED

uuid

required

Unique ID associated with this buyer.

identity

object

required

Identity represents the identity of a buyer

birthDate

date

The date value formatted per RFC3339. This does not allow nulls.

string

required

Email address

emailDuplicate

boolean

Indicates whether this email is verified on another buyer.

emailVerified

boolean

Indicates whether this email has been verified as belonging to this buyer. Write access to this field is limited based on authorization.

iin

string

Optional. The Individual Identification Number of this buyer.
Read access limited based on authorization.
Write access limited based on authorization unless no value currently exists.

hasIIN

boolean

Indicates whether a full IIN has been provided for this buyer.

iinShort

string

Optional. The short form of the buyer's Individual Identification Number. Will always match full IIN if full IIN exists.
Write access limited based on authorization unless no value currently exists.

name

object

required

Represents the full name

phone

string

required

Telephone number including country code

phoneDuplicate

boolean

Indicates whether this phone number is verified on another buyer.

phoneVerified

boolean

Indicates whether this phone number is has been verified as belonging to this buyer. Write access to this field is limited based on authorization.

languagePreference

string

required

length ≥ 2

The two language code as defined in ISO 639-1 along with subtags tag if applicable.

primaryContactID

uuid

required

Read-only. The ID of the primary contact information associated with this buyer; this is set on buyer creation.

status

string

Status represents buyer status as string. Options available will depend
on tenant level configurations

subStatus

string

SubStatus represents buyer sub status as constant string. Options
available will depend on status value and tenant level configurations

tenantID

uuid

required

ID of the tenant associated with this buyer.

activeMilitary

boolean

Indicates if the buyer is a member of the armed forces.

bankruptcy

object

Bankruptcy represents a buyer's bankruptcy information

uuid

Unique ID associated with this bankruptcy.

buyerId

uuid

Unique ID associated with the buyer.

filingStatus

string

required

The buyer's bankruptcy filing status.

notice

string

required

The bankruptcy notice chapter received by the buyer.

filingDate

date

required

The date value formatted per RFC3339. This does not allow nulls.

transitionDate

date

The date value formatted per RFC3339. This does not allow nulls.

createdAt

date-time

The timestamp value formatted per RFC3339. This does not allow nulls.

updatedAt

date-time

The timestamp value formatted per RFC3339. This does not allow nulls.

doNotSellOrShare

boolean

Indicates if the buyer has preference for their data not to be shared

primaryContact

object

BuyerContact represents a set of contact information.

address

object

Represents a fully defined address for an entity

buyerID

uuid

ID of the buyer associated with this contact.

contactType

string

Optional. Represents the type of contact.

PRIMARY HOME WORK OTHER BILLING SHIPPING

createdAt

date-time

The timestamp value formatted per RFC3339. This does not allow nulls.

string

required

Email address

uuid

Unique ID associated with this contact.

name

object

required

Represents the full name

phone

string

required

Telephone number including country code

updatedAt

date-time

The timestamp value formatted per RFC3339. This does not allow nulls.

doNotSellOrShareUpdatedAt

date-time

The timestamp value formatted per RFC3339. This does not allow nulls.

updatedAt

date-time

required

The timestamp value formatted per RFC3339. This does not allow nulls.

Response body

object

activeAuthorizedThirdParties

array of objects

Subresource of buyer and acted on with its own set of endpoints

activeAuthorizedThirdParties

object

buyerID

uuid

The ID of the buyer on whose behalf this authorized third party is allowed to act.

consentToCall

boolean

Defaults to false

Whether this authorized third party has consented to receive calls.

consentToEmail

boolean

Defaults to false

Whether this authorized third party has consented to receive emails.

consentToText

boolean

Defaults to false

Whether this authorized third party has consented to receive text messages.

createdAt

date-time

The timestamp value formatted per RFC3339. This does not allow nulls.

string

Email address

uuid

Unique ID associated with this authorized third party.

isActive

boolean

Defaults to false

Indicates whether this authorized third party is active.

name

object

required

Represents the full name

phone

string

required

Telephone number including country code

powerOfAttorney

boolean

Defaults to false

Indicates whether this authorized third party has power of attorney for the associated buyer. Power of attorney legally grants a third party the ability to represent the buyer in private affairs.

attorneyRepresentation

boolean

Defaults to false

Indicates whether this authorized third party is an attorney acting on behalf of the buyer.

type

string

AuthorizedThirdPartyType represents a authorized third party type as enum
Possible values: AUTHORIZED_THIRD_PARTY, POWER_OF_ATTORNEY, ATTORNEY_REPRESENTATION, GUARDIANSHIP

phoneType

string

PhoneType represents a phone type as enum
Possible values: MOBILE, WORK, HOME, OTHER

updatedAt

date-time

The timestamp value formatted per RFC3339. This does not allow nulls.

contacts

object

required

BuyerContactMap represents a mapping of buyer contact IDs to contacts

createdAt

date-time

required

The timestamp value formatted per RFC3339. This does not allow nulls.

employment

object

Optional. Employment represents the buyer's employment.

annualIncome

int64

Optional. The buyer's annual income in cents.

companyAddress

string

Required if employment type is EMPLOYED or SELF_EMPLOYED

companyName

string

Required if employment type is EMPLOYED or SELF_EMPLOYED

currency

string

length between 3 and 3

The three letter currency code as defined in ISO 4217.

description

string

Optional. Employment description.

occupation

string

Required if employment type is EMPLOYED or SELF_EMPLOYED

occupationDescription

string

Required if occupation is "Other"

type

string

required

EmploymentType represents a buyer employment type as enum
Possible values: EMPLOYED, SELF_EMPLOYED, UNEMPLOYED, STUDENT, RETIRED

uuid

required

Unique ID associated with this buyer.

identity

object

required

Identity represents the identity of a buyer

birthDate

date

The date value formatted per RFC3339. This does not allow nulls.

string

required

Email address

emailDuplicate

boolean

Indicates whether this email is verified on another buyer.

emailVerified

boolean

Indicates whether this email has been verified as belonging to this buyer. Write access to this field is limited based on authorization.

iin

string

Optional. The Individual Identification Number of this buyer.
Read access limited based on authorization.
Write access limited based on authorization unless no value currently exists.

hasIIN

boolean

Indicates whether a full IIN has been provided for this buyer.

iinShort

string

Optional. The short form of the buyer's Individual Identification Number. Will always match full IIN if full IIN exists.
Write access limited based on authorization unless no value currently exists.

name

object

required

Represents the full name

phone

string

required

Telephone number including country code

phoneDuplicate

boolean

Indicates whether this phone number is verified on another buyer.

phoneVerified

boolean

Indicates whether this phone number is has been verified as belonging to this buyer. Write access to this field is limited based on authorization.

languagePreference

string

required

length ≥ 2

The two language code as defined in ISO 639-1 along with subtags tag if applicable.

primaryContactID

uuid

required

Read-only. The ID of the primary contact information associated with this buyer; this is set on buyer creation.

status

string

Status represents buyer status as string. Options available will depend
on tenant level configurations

subStatus

string

SubStatus represents buyer sub status as constant string. Options
available will depend on status value and tenant level configurations

tenantID

uuid

required

ID of the tenant associated with this buyer.

activeMilitary

boolean

Indicates if the buyer is a member of the armed forces.

bankruptcy

object

Bankruptcy represents a buyer's bankruptcy information

uuid

Unique ID associated with this bankruptcy.

buyerId

uuid

Unique ID associated with the buyer.

filingStatus

string

required

The buyer's bankruptcy filing status.

notice

string

required

The bankruptcy notice chapter received by the buyer.

filingDate

date

required

The date value formatted per RFC3339. This does not allow nulls.

transitionDate

date

The date value formatted per RFC3339. This does not allow nulls.

createdAt

date-time

The timestamp value formatted per RFC3339. This does not allow nulls.

updatedAt

date-time

The timestamp value formatted per RFC3339. This does not allow nulls.

doNotSellOrShare

boolean

Indicates if the buyer has preference for their data not to be shared

primaryContact

object

BuyerContact represents a set of contact information.

address

object

Represents a fully defined address for an entity

buyerID

uuid

ID of the buyer associated with this contact.

contactType

string

Optional. Represents the type of contact.

PRIMARY HOME WORK OTHER BILLING SHIPPING

createdAt

date-time

The timestamp value formatted per RFC3339. This does not allow nulls.

string

required

Email address

uuid

Unique ID associated with this contact.

name

object

required

Represents the full name

phone

string

required

Telephone number including country code

updatedAt

date-time

The timestamp value formatted per RFC3339. This does not allow nulls.

doNotSellOrShareUpdatedAt

date-time

The timestamp value formatted per RFC3339. This does not allow nulls.

updatedAt

date-time

required

The timestamp value formatted per RFC3339. This does not allow nulls.

Language

Credentials

Bearer

JWT

URL


xxxxxxxxxx
1
curl --request POST \
2
     --url https://api-preview.platform.breadpayments.com/api/buyer \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

text/plain

200The updated existing buyer.

201The newly created buyer.

400Response for errors returned by buyer service.

401Unauthorized. Indicates that provided credentials is not valid

403Forbidden. Indicates that request cannot be authorized

500Response for errors returned by buyer service.