# Add merchant demographics

Collect and submit business demographic details through the [Merchant Demographics](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/merchant-boarding-via-api/merchant-demographics). This process ensures that the merchant account includes all required information for verification and underwriting.

The process includes two steps:

{% stepper %}
{% step %}
**Create new merchant account**

<details>

<summary><strong>Create Merchant</strong></summary>

To collect merchant demographic information, use the [Create New Merchant](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/merchant-boarding-via-api/merchant-demographics/merchant#post-api-demographics-v1-merchants) endpoint to create a new merchant record within the application. It validates and stores critical merchant details such as `dbaName`, `hierarchyNodeKey`, and `emailAddress`.

Use `POST` method `/api/demographics/v1/Merchants` to submit and store all critical merchant information, ensuring streamlined operations throughout their lifecycle. Refer to the below sample code for reference:

{% code lineNumbers="true" %}

```javascript
{
  "businessID": 524398752,
  "hierarchyNodeKey": "1234567800000001",
  "dbaName": "Jane's Sandwiches",
  "merchantNumber": "1234567891234567",
  "emailAddress": "jane-doe@sandwiches.com",
  "webSite": "https:/www.janessandwiches.com",
  "phones": [
    {
      "phoneTypeCodeID": 1,
      "areaCode": "415",
      "phoneNumber": "5551234",
      "extension": "101"
    }
  ],
  "acceptsPaperStatements": true,
  "acceptsPaperTaxForms": false,
  "companyTypeId": 2,
  "isChainMerchant": false,
  "seasonalSchedule": {
    "january": true,
    "february": false,
    "march": true,
    "april": true,
    "may": true,
    "june": false,
    "july": true,
    "august": true,
    "september": false,
    "october": true,
    "november": true,
    "december": false
  },
  "salesInformation": {
    "salesInformationID": 1001,
    "businessID": 2002,
    "assignedUser": 3003,
    "referralPartner": "John Doe",
    "compensationType": 2
  }
}
```

{% endcode %}

The merchant will be successfully created after validation is completed and changes are queued for processing. The response includes the merchant's details, setting the foundation for adding demographic information by initiating other relevant endpoints in the subdomain.

</details>
{% endstep %}

{% step %}
**Add merchant demographics information**

{% hint style="warning" %}
When a merchant is initially created, the system pre-generates empty demographic records such as mailing address, physical address, taxpayer information, and sales profiles. These records are updated using the `PUT` method.
{% endhint %}

<details>

<summary><strong>Business Contact</strong></summary>

The [Business Contact](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/merchant-boarding-via-api/merchant-demographics/business-contact#post-api-demographics-v1-businesscontacts-merchantnumber) endpoint used to create a primary contact for a specific merchant. It allows you to submit key details such as the contact’s name, address, phone number, email, SSN, ownership percentage, and contact roles.

Use `POST` method `/api/demographics/v1/BusinessContacts/{merchantNumber}` to submit business contact information to create a new contact for a merchant. Refer to the below sample code for reference:

{% code lineNumbers="true" %}

```javascript
{
  "phoneNumbers": [
    {
      "phoneTypeCodeID": 1,
      "areaCode": "415",
      "phoneNumber": "5555678",
      "extension": "102"
    }
  ],
  "businessContactId": 1001,
  "contact": {
    "countryOfCitizenshipCode": 840,
    "address": {
      "line1": "456 Market St",
      "line2": "Suite 300",
      "line3": "",
      "city": "San Francisco",
      "countryCode": 840,
      "stateCode": "CA",
      "zip": "94103"
    },
    "ssnLastFour": "6789",
    "encryptedSSN": "ENCRYPTED_VALUE",
    "ssn": "123-45-6789",
    "contactId": 2002,
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1985-07-22T00:00:00.000Z"
  },
  "ownershipAmount": 50,
  "emailAddress": "john.doe@business.com",
  "title": "Managing Partner",
  "contactTypes": [
    {
      "businessContactContactTypeID": 3003,
      "businessContactID": 1001,
      "contactTypeID": 2
    }
  ],
  "isCompassUser": true,
  "isMerchantHomeUser": true,
  "isVirtualTerminalUser": true,
  "isAuthorizedToPurchase": true
}
```

{% endcode %}

</details>

<details>

<summary><strong>Physical Address</strong></summary>

The [Merchant Physical Address](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/merchant-boarding-via-api/merchant-demographics/merchant#put-api-demographics-v1-merchantphysicaladdresses-merchantnumber) endpoint is used to assign the merchant's official business location. This address represents where the business operates, such as a store, office, or other commercial site.

Use the `PUT` method `/api/demographics/v1/MerchantPhysicalAddresses/{merchantNumber}` to update the address details. The physical address must be a valid, registered business or retail location. Refer to the below sample code for reference:

{% code lineNumbers="true" %}

```javascript
{
  "stateCode": "CA",
  "zip": "94103",
  "countryCode": 840,
  "line1": "789 Mission St",
  "line2": "Suite 400",
  "line3": "",
  "city": "San Francisco"
}
```

{% endcode %}

</details>

<details>

<summary><strong>Mailing Address</strong></summary>

The [Mailing Address](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/merchant-boarding-via-api/merchant-demographics/merchant#get-api-demographics-v1-merchantmailingaddresses-merchantnumber) endpoint is used to assign the official mailing address for a merchant account. This address is used for official correspondence and official communications to the merchant account. A mailing address must be provided, even if it is the same as the physical address.

Use the `PUT` method `/api/demographics/v1/MerchantMailingAddresses/{merchantNumber}` to update a mailing address for a specific merchant. Refer to the below sample request code for reference:

{% code lineNumbers="true" %}

```javascript
{
  "stateCode": "CA",
  "zip": "94103",
  "countryCode": 840,
  "line1": "789 Mission St",
  "line2": "Suite 400",
  "line3": "",
  "city": "San Francisco"
}
```

{% endcode %}

</details>

<details>

<summary><strong>Taxpayer Information</strong></summary>

The [Taxpayer Information](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/merchant-boarding-via-api/merchant-demographics/tax-payer#put-api-demographics-v2-taxpayers-merchantnumber) endpoint is used to update essential taxpayer details for a specific merchant. This information is crucial for verifying the business’s tax status and ensuring compliance with financial and regulatory requirements.

Use the `PUT` method `/api/demographics/v2/Taxpayers/{merchantNumber}` to update taxpayer details. Refer to the below sample code for reference:

{% code lineNumbers="true" %}

```javascript
{
  "legalFirstName": "John",
  "legalLastName": "Doe",
  "tin": "12-3456789",
  "encryptedTIN": "ENCRYPTED_TIN_VALUE",
  "tinTypeID": 3,
  "businessLegalName": "Doe Enterprises LLC",
  "stateIncorporatedCode": "CA"
}
```

{% endcode %}

</details>

<details>

<summary><strong>Banking Information</strong></summary>

The [Bank Account Information](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/merchant-boarding-via-api/merchant-demographics/bank-account#post-api-demographics-v1-bankaccounts-merchantnumber) endpoint is used to add bank account details for a specific merchant. This is essential for enabling deposits, chargebacks, fees, and settlements associated with the merchant’s transactions.

Use the `POST` method `/api/demographics/v1/BankAccounts/{merchantNumber}` to create a bank account for a merchant. Refer to the below sample code for reference:

{% code lineNumbers="true" %}

```javascript
{
  "bankAccountID": 1001,
  "bankName": "Bank of America",
  "nameOnAccount": "Doe Enterprises LLC",
  "accountHolderFirstName": "John",
  "accountHolderLastName": "Doe",
  "bankAccountTypeID": 3,
  "bankAccountNameTypeID": 1,
  "aba": "091000019",
  "accountNumber": "123456789012",
  "lastFourAccountNumber": "9012",
  "encryptedAccountNumber": "ENCRYPTED_ACCOUNT_VALUE",
  "voidedCheckDocumentID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "hasFees": true,
  "hasFunds": true,
  "hasChargebacks": true,
  "isNameSameAsLegalOrDBAName": true,
  "currency": "USD",
  "purpose": "Settlement",
  "lastUpdatedUtc": "2024-10-15T10:18:39.702Z"
}
```

{% endcode %}

</details>

<details>

<summary><strong>Sales Profile</strong></summary>

The [Sales Profile](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/merchant-boarding-via-api/merchant-demographics/sales-profile#put-api-demographics-v2-salesprofiles-merchantnumber) endpoint is used to capture essential information about the merchant's business model, products/services, fulfillment operations, and expected transaction behaviors.

Use the `PUT` method `/api/demographics/v2/SalesProfiles/{merchantNumber}` to update sales profile details for a merchant. Refer to the below sample code for reference:

{% code lineNumbers="true" %}

```javascript
{
  "usesFulfillmentHouse": true,
  "offersNegativeOptionBilling": false,
  "fulfillmentHouseAddress": {
    "line1": "1011 Northwest Ave",
    "line2": "Suite 223",
    "line3": "",
    "city": "Kansas City",
    "countryCode": 840,
    "stateCode": "MO",
    "zip": "64105"
  },
  "fulfillmentHousePhone": {
    "areaCode": "816",
    "phoneNumber": "5556789",
    "extension": "105",
    "phoneTypeCodeID": 3
  },
  "vendorName": "Doe Distribution Inc.",
  "dateOfIncorporation": "2018-06-15T00:00:00",
  "useExtraCnpValidation": true,
  "isECommerce": true,
  "mccCode": "5812",
  "cardPresentPercentage": 40,
  "returnRefundPolicy": "Full refunds are available within 60 days.",
  "productsSold": "Organic food and beverages.",
  "previouslyAcceptedPaymentCards": true,
  "previousProcessorId": 12,
  "previouslyTerminatedOrIdentifiedByRiskMonitoring": false,
  "reasonPreviouslyTerminatedOrIdentifiedByRisk": "",
  "currentlyOpenForBusiness": true,
  "annualVolume": 750000,
  "averageTicket": 65.50,
  "highTicket": 850,
  "ownsProduct": true,
  "ordersProduct": true,
  "sellsFirearms": false,
  "cbdSalesTypeID": 2,
  "salesProfileCBD": {
    "annualCBDRevenuePercentage": 20,
    "cbdProductInventoryPercentage": 50,
    "salesProfileCBDCategory": 2,
    "cbdCategoryID": 1
  },
  "sellsFirearmAccessories": false,
  "futureDeliveryTypeID": true,
  "otherDeliveryType": "Standard shipping",
  "otherDeliveryTypeInDays": 7,
  "futureDeliveryPercentage": 60,
  "fireArmsLicense": "",
  "cardBrands": [1, 2, 3, 4],
  "ebtNumber": "1998882",
  "amexMID": "1998882"
}
```

{% endcode %}

</details>

<details>

<summary><strong>Site Survey</strong></summary>

The [Site Survey](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/merchant-boarding-via-api/merchant-demographics/site-survey#put-api-demographics-v1-sitesurveys-merchantnumber) endpoint used to update site verification records for a specific merchant. This data is typically collected during a physical visit by and is used to confirm the business’s operational legitimacy.

Use the `PUT` method `/api/demographics/v1/SiteSurveys/{merchantNumber}` to update a site survey for a merchant. Refer to the below sample code for reference:

{% code lineNumbers="true" %}

```javascript
{
  "siteTypeID": 4,
  "otherSiteTypeDescription": "Retail Storefront",
  "siteSurveyConductedInPerson": true,
  "merchantAcquisitionTypeID": 3,
  "validIDVerified": true,
  "inventoryMatchesProductSold": true,
  "inventoryMatchesProductSoldComments": "Inventory check completed; products match business description.",
  "agreementAccepted": true,
  "selfSignUpApplication": false
}
```

{% endcode %}

</details>

<details>

<summary><strong>Beneficial</strong> <strong>Ownership Agreement</strong></summary>

The [Ownership Agreement](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/merchant-boarding-via-api/merchant-demographics/business-contact#post-api-demographics-v1-businesscontacts-merchantnumber-beneficialowneragreement) endpoint is used to create an attestation that all individuals with 25% or more ownership in the merchant account have been disclosed. It helps to ensure regulatory compliance with ownership disclosure requirements.

Use the `POST` method `/api/demographics/v1/BusinessContacts/{merchantNumber}/beneficialowneragreement` to submit the agreement confirmation. Refer to the below sample code for reference:

{% code lineNumbers="true" %}

```javascript
{
  "allPersonsWithOverTwentyFivePercentOwnershipHaveBeenAdded": true
}
```

{% endcode %}

</details>

<details>

<summary><strong>Upload Document</strong></summary>

The [Upload Document](https://docs.xplorpay.com/api-reference/api/merchant-onboarding/merchant-boarding-via-api/merchant-demographics/documents#post-api-demographics-v1-documents-merchantnumber) endpoint is used to upload a document and associate it with a specific merchant account. It supports submission of document metadata such as the file name and document category, along with the actual file content.

Use the `POST` method `/api/demographics/v1/Documents/{merchantNumber}` to submit the documents. Refer to the below sample code for reference:

{% code lineNumbers="true" %}

```javascript
"string"
```

{% endcode %}

</details>
{% endstep %}
{% endstepper %}

For detailed request and response field descriptions, refer to the [Merchant Demographics API](https://app.gitbook.com/s/j9heLdoDRsfnChUQohvj/api/merchant-onboarding/onboard-merchant/merchant-demographics-old).