Add Merchant Owner

post

https://api.preczn.com/v1/merchants/{merchantId}/owners

The Add Owners endpoint allows you to add owner details to a merchant record.

You may add multiple owners to a merchant record, however the API accepts only 1 owner at a time. Use the owner ID in the response to subsequently Add Owner Attachments or Update the Owner in the future.

Use the Add Owner Attachmentendpoint to add owner attachments such as drivers license to the owner record.

📘
Important Notes:

There can be only one primaryRepresentative owners per merchant record.

There may be many significantResponsibility owners per merchant record.

Total ownershipPercentage cannot exceed 100 across all owners.

Path Params

merchantId

string

required

Body Params

firstName

string

^[a-z ,.'-]*$

First name.

middleName

string

^[a-z ,.'-]*$

Middle name.

lastName

string

^[a-z ,.'-]*$

Last name.

string

Email address.

phone

string

^1?\d{10}$

Phone number. Format: North American phone digits only, optionally prefixed with '1'. No spaces, parentheses, or hyphens. Example: 19999999999.

address

object

Address of the contact

businessTitle

string

^[a-z ,.'-]*$

Business Title.

citizenshipCountry

string

enum

ISO 3166-1 alpha-3 country code (e.g., USA). Membership in the ISO-3 list is currently not enforced by validation (reserved for future tightening).

ownershipDate

string

^(?:\d{4})[-/](?:0[1-9]|1[0-2])[-/](?:0[1-9]|[12][0-9]|3[01])$

Date when an owner became an owner. ISO 8601 date, YYYY-MM-DD.

dob

string

^[^*]*$

Date of birth as an ISO 8601 date, YYYY-MM-DD. Must be a real calendar date for an owner who is at least 18 and under 100 years old, evaluated in UTC. Other values return 400. Masked values are rejected: to keep the stored date, omit dob. Responses return a masked value: the birth year followed by **(e.g., 1970**).

ssn

string

length between 9 and 9

^(\d{9})?$

Social security number. 9 digits, no hyphens or spaces. Responses return a masked value: ** followed by the last 4 digits (e.g., **5555); the field is omitted when no SSN is on file.

ssnLast4

string

length between 4 and 4

^(\d{4})?$

Last 4 digits of the social security number. Exactly 4 digits. When ssn is also provided in the same request, this value must match the last 4 digits of ssn.

ownershipPercent

number

Percentage of ownership as a whole integer, expected range 0 to 100 (e.g., 85). The range and integer form are currently not enforced by validation (reserved for future tightening).

type

string

enum

Owner type

Allowed:

politicallyExposed

boolean

Defaults to false

Publically exposed owner flag.

primaryRepresentative

boolean

enum

Defaults to false

Sponsoring stakeholder from the merchant.

Allowed:

driversLicenseNumber

string

length ≥ 1

^[a-zA-Z0-9]*$

Driver's license number. Alphanumeric characters only; must not be an empty string. Responses return a masked value: **** followed by the last 4 characters.

driversLicenseState

string

length ≥ 1

State or province code where the driver's license was issued, in 2-character abbreviation (e.g., NY). The set of valid codes depends on the sibling address.country field: US state codes when country is USA (the default), Canadian province codes when country is CAN.

driversLicenseExpiration

string

length ≥ 1

^(?:\d{4})[-/](?:0[1-9]|1[0-2])[-/](?:0[1-9]|[12][0-9]|3[01])$

Driver's license expiration date. ISO 8601 date, YYYY-MM-DD.

significantResponsibility

boolean

Defaults to true

Significant Responsibility.

Headers

idempotency-key

string

Unique key to ensure idempotency of requests. If provided, the server will return the same response for subsequent requests with the same key.

Responses

Add Merchant Owner

Important Notes:

What’s Next

What’s Next

Important Notes:

201Owner Created for Merchant.

401Invalid API key.

403Resource Forbidden.

404Merchant not found.

500Unable to service request due to server-side error. Please reattempt request.

What’s Next

What’s Next