# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com

# Create a client profile

## Create a client profile with minimal or full data

You can create a minimal client profile, using only the most basic information required first, and update over time. Once all of the information required is ready, you can send the final request for client background checks to begin.

### Create a client profile with minimal data

To create a client profile, you must send a `POST` request to `/onboarding/v1/clients` and include:

- A parties list of objects.

- A product with the value MERCHANT_SERVICES.

The `clients` object represents the overall business and its related parties.

The `parties` object contains both information about the client as an organization, and an individual party who can act as the controller for the client business.

In your `parties` objects, include:

- partyType: ORGANIZATION for the client organization.

- partyType: INDIVIDUAL to represent controllers, beneficial owners, and decision makers related to the organization or business

- externalId: Your own unique identifier for this client organization, individual, and subsequent individual party. This field is optional.

- roles: Represents the role of the party as it relates to the client object. Values vary based on:
  - partyType: ORGANIZATION – set to CLIENT for the party representing the client organization or business.
  - partyType: INDIVIDUAL – For individuals that act as the client’s controller, assign the role CONTROLLER. For individuals that own more than a 25% ownership of the company, you must also assign the role BENEFICIAL_OWNER.

- organizationDetails for the organization must include:
  - organizationType
  - organizationName
  - countryOfFormation
  - If the organization is a Publicly Traded Company (PTC) consult the [Reference for onboarding Publicly Traded Companies](/docs/commerce/optimization-protection/capabilities/digital-onboarding/how-to/publicly-traded-companies) to include any additional information.

- individualDetails for the individual party must include:
  - firstName
  - lastName
  - countryOfResidence

Sample create client request body with minimal data:

```json
{
  "parties": [
    {
      "partyType": "ORGANIZATION",
      "email": "monica@cpgetaways.com",
      "roles": [
        "CLIENT"
      ],
      "organizationDetails": {
        "organizationType": "SOLE_PROPRIETORSHIP",
        "organizationName": "Central Park Getaways",
        "countryOfFormation": "US"
      }
    },
    {
      "partyType": "INDIVIDUAL",
      "roles": [
        "CONTROLLER",
        "BENEFICIAL_OWNER"
      ],
      "individualDetails": {
        "firstName": "Monica",
        "lastName": "Gellar",
        "countryOfResidence": "US"
      }
    }
  ],
  "products": [
    "MERCHANT_SERVICES"
  ]
}
```

### Create a client profile with full data

Send a full payload with all the required information about your client and their organization.

#### Note on addresses

Include your principal place of business in at least one entry in organizationDetails.`addresses`. Organizations must use addresses.`addressType` of `LEGAL_ADDRESS` or `BUSINESS_ADDRESS`. Overall we allow the following values for addresses.`addressType`:

- LEGAL_ADDRESS: The official registered address of the legal entity on file with government authorities or the entity's registered agent. P.O. Boxes and Private Mail Boxes (P.M.B.) are not accepted for onboarding.

- MAILING_ADDRESS: The address where the organization receives postal correspondence, statements, and notices. This address may differ from the legal address or primary business location.

- BUSINESS_ADDRESS: The primary physical location where the organization conducts business operations. This is the principal place of business or designated primary site. P.O. Boxes and Private Mail Boxes (P.M.B.) are not accepted.

- RESIDENTIAL_ADDRESS: The physical home address used when the party is an individual or sole proprietor, or when required for key principals or beneficial owners associated with the organization. P.O. Boxes and Private Mail Boxes (P.M.B.) are not accepted.

> For addresses.`addressType` other than `MAILING_ADDRESS`, we do not permit the following address types:
> 
> 
> - Post Office (P.O.) boxes
> 
> - Private Mail Boxes (P.M.B.)
> 
> - Virtual office addresses
> 
> - Registered agent addresses
> 
> Set addresses.`addressType` to `BUSINESS_ADDRESS` for your principal place of business.
> 

#### Note on metadata for parties

The `parties` object includes a single `metadata` field per party, as a flexible array of key-value entries that you use to attach custom data to any party record. Metadata key-value pairs are passthrough data. The system stores them alongside the party record, returns them in responses, and does not use them for processing, evaluation, or onboarding decisions.

The `metadata` field is the following array of key-value pairs, where `key` is a string and `value` is any JSON type: string, number, boolean, or nested object.

```json
{
  "key1": "...",
  "value1": "...",
  "key2": "...",
  "value2": "..."
}
```

> The metadata field supports a maximum of 20 key-value entries.
> 

Send `metadata` through the [Create party](https://developer.payments.jpmorgan.com/api/commerce/optimization-protection/digital-onboarding/digital-onboarding#/operations/postParty), [Update party](https://developer.payments.jpmorgan.com/api/commerce/optimization-protection/digital-onboarding/digital-onboarding#/operations/updateParty), [Create client](https://developer.payments.jpmorgan.com/api/commerce/optimization-protection/digital-onboarding/digital-onboarding#/operations/smbdo-postClients), and [Update client](https://developer.payments.jpmorgan.com/api/commerce/optimization-protection/digital-onboarding/digital-onboarding#/operations/smbdo-updateClient) endpoints by including `metadata` in the `parties` object. When you include `metadata` in a request body, the entire `metadata` for the party is replaced by the `metadata` in the request. To modify existing `metadata`, send the complete `metadata`, including the existing entries with any edits.

If `metadata` is present, the [Get party](https://developer.payments.jpmorgan.com/api/commerce/optimization-protection/digital-onboarding/digital-onboarding#/operations/getParty) and [Get client](https://developer.payments.jpmorgan.com/api/commerce/optimization-protection/digital-onboarding/digital-onboarding#/operations/smbdo-getClient) responses return the `metadata` in the `parties` object.

In the following example, you can see a complete request with all required fields populated for a sole proprietorship organization. This includes details about the organization's industry type and industry category. For the United States, find this reference information with the [United States Census Bureau](https://www.census.gov/naics/).

Refer to the following sample request to create a client profile with complete data:

```json
{
  "parties": [
    {
      "partyType": "ORGANIZATION",
      "externalId": "TC1234",
      "email": "monica@cpgetaways.com",
      "roles": [
        "CLIENT"
      ],
      "organizationDetails": {
        "organizationType": "SOLE_PROPRIETORSHIP",
        "organizationName": "Central Park Getaways",
        "dbaName": "CP Getaways",
        "organizationDescription": "Relax, unwind and experience the comforting charm of our apartment while exploring New York",
        "industryCategory": "Accommodation and Food Services",
        "industryType": "All Other Traveler Accommodation",
        "countryOfFormation": "US",
        "yearOfFormation": "2020",
        "significantOwnership": true,
        "entitiesInOwnership": false,
        "addresses": [
          {
            "addressType": "BUSINESS_ADDRESS",
            "addressLines": [
              "90 Bedford Street"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "phone": {
          "phoneType": "BUSINESS_PHONE",
          "countryCode": "+1",
          "phoneNumber": "6316215110"
        },
        "organizationIds": [
          {
            "idType": "EIN",
            "issuer": "US",
            "value": "000000001"
          }
        ],
        "website": "https://topcookie.net"
      },
      "metadata": [
        { "key": "totalAnnualSalesRevenue", "value": 75000 },
        { "key": "paymentChannels", "value": "CARD_PRESENT" },
        { "key": "businessLocations", "value": 3 },
        { "key": "currencySupport", "value": "CAD" },
        { "key": "productsSolution", "value": "Standalone In-Store Payments Solution" },
        { "key": "externalAssociation", "value": true },
        { "key": "currentPaymentsProvider", "value": true },
        { "key": "readyToEvaluate", "value": true },
        {
          "key": "partnerCommission",
          "value": {
            "referralSource": "Scotiabank",
            "repId": "SR-4421",
            "campaignId": "Q1-2026-MERCHANT"
          }
        },
        { "key": "salesRegion", "value": "CANADA_WEST" }
      ]
    },
    {
      "partyType": "INDIVIDUAL",
      "externalId": "TCU12344",
      "email": "monicagellar@gmail.com",
      "roles": [
        "CONTROLLER",
        "BENEFICIAL_OWNER"
      ],
      "individualDetails": {
        "firstName": "Monica",
        "lastName": "Gellar",
        "birthDate": "1990-10-09",
        "countryOfResidence": "US",
        "natureOfOwnership": "Direct",
        "jobTitle": "Other",
        "jobTitleDescription": "CEO",
        "soleOwner": true,
        "addresses": [
          {
            "addressType": "RESIDENTIAL_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "individualIds": [
          {
            "idType": "SSN",
            "issuer": "US",
            "value": "100010001"
          }
        ]
      },
      "metadata": [
        { "key": "Additional Role", "value": "Coffee Evaluator" },
        { "key": "Hobby", "value": "Flower arrangements" },
        { "key": "Compensation type", "value": "Percentage" }
      ]
    }
  ],
  "products": [
    "MERCHANT_SERVICES"
  ]
}
```

### Create a client profile with full data and multiple related parties

To add more than one related party for a client, include multiple parties with the `partyType` of `INDIVIDUAL` in the `POST` request to `/onboarding/v1/clients`. Refer to the following example for a client with separate `CONTROLLER` and `BENEFICIAL_OWNER` parties:

```json
{
  "parties": [
    {
      "partyType": "ORGANIZATION",
      "externalId": "UDV23455",
      "roles": [
        "CLIENT"
      ],
      "email": "phil@banksfamilyllc.com",
      "organizationDetails": {
        "organizationType": "LIMITED_LIABILITY_COMPANY",
        "organizationName": "Banks Family LLC",
        "addresses": [
          {
            "addressType": "BUSINESS_ADDRESS",
            "addressLines": [
              "251 N Bristol Ave"
            ],
            "city": "Los Angeles",
            "state": "CA",
            "postalCode": "90049",
            "country": "US"
          }
        ],
        "countryOfFormation": "US",
        "dbaName": "Banks Family Decor",
        "industryCategory": "Retail Trade",
        "industryType": "All Other Home Furnishings Retailers",
        "organizationDescription": "Step in to a world of sophistication with stylish home goods",
        "phone": {
          "phoneType": "BUSINESS_PHONE",
          "phoneNumber": "7606810558",
          "countryCode": "+1"
        },
        "website": "https://banksfamilyllc.com",
        "yearOfFormation": "1984",
        "organizationIds": [
          {
            "idType": "EIN",
            "value": "300030003",
            "issuer": "US"
          }
        ]
      },
      "metadata": [
        { "key": "totalAnnualSalesRevenue", "value": 75000 },
        { "key": "paymentChannels", "value": "CARD_PRESENT" },
        {
          "key": "partnerCommission",
          "value": {
            "referralSource": "Scotiabank",
            "repId": "SR-4421",
            "campaignId": "Q1-2026-MERCHANT"
          }
        },
        { "key": "salesRegion", "value": "CANADA_WEST" }
      ]
    },
    {
      "partyType": "INDIVIDUAL",
      "roles": [
        "CONTROLLER"
      ],
      "individualDetails": {
        "firstName": "Philip",
        "lastName": "Banks",
        "birthDate": "1945-01-30",
        "addresses": [
          {
            "addressType": "RESIDENTIAL_ADDRESS",
            "addressLines": [
              "251 N Bristol Ave"
            ],
            "city": "Los Angeles",
            "state": "CA",
            "postalCode": "90049",
            "country": "US"
          }
        ],
        "countryOfResidence": "US",
        "phone": {
          "phoneType": "BUSINESS_PHONE",
          "phoneNumber": "7606810553",
          "countryCode": "+1"
        },
        "individualIds": [
          {
            "idType": "SSN",
            "value": "300040004",
            "issuer": "US"
          }
        ],
        "jobTitle": "CEO"
      },
      "metadata": [
        { "key": "frequentTravel", "value": "true" },
        { "key": "spendLimit", "value": 10000 },
        {
          "key": "TravelAssistant",
          "value": {
            "assistaneName": "Shane",
            "assistantID": "TR-1001"
          }
        }
      ]
    },
    {
      "partyType": "INDIVIDUAL",
      "roles": [
        "BENEFICIAL_OWNER"
      ],
      "individualDetails": {
        "firstName": "Dahlia",
        "lastName": "Banks",
        "birthDate": "1945-01-30",
        "addresses": [
          {
            "addressType": "RESIDENTIAL_ADDRESS",
            "addressLines": [
              "251 N Bristol Ave"
            ],
            "city": "Los Angeles",
            "state": "CA",
            "postalCode": "90049",
            "country": "US"
          }
        ],
        "countryOfResidence": "US",
        "phone": {
          "phoneType": "BUSINESS_PHONE",
          "phoneNumber": "7606810553",
          "countryCode": "+1"
        },
        "individualIds": [
          {
            "idType": "SSN",
            "value": "300050005",
            "issuer": "US"
          }
        ],
        "jobTitle": "CFO"
      }
    }
  ],
  "products": [
    "MERCHANT_SERVICES"
  ]
}
```

## Understand outstanding data

A successful 200 or 201 response to a `POST` request to `/onboarding/v1/clients` or `GET` request to `/onboarding/v1/clients/{id}` includes an `outstanding` object. This object tells you what still needs to be added or completed before you can submit your client's profile and complete the onboarding process. The object may include:

- questionIds - answers must be provided for each questionId listed. You can find out how to manage questions in this guide.

- partyIds - a required attribute related to the partyId is missing.

- partyRoles - a required party role has not been submitted with the client. For example, the role CONTROLLER has not been assigned to any party.

- attestationDocumentIds – the document IDs in which the client must review and attest to. Find out how to manage attestations in [this guide](/docs/commerce/optimization-protection/capabilities/digital-onboarding/how-to/present-attestations).

- documentRequestIds - the IDs for the documents that the client must submit for verification.

To update client and party details such as `partyIds` and `partyRoles`, send a `PATCH` request to `/onboarding/v1/parties/{partyId}` with the updated details.

## Update party data

In the response to a `GET` request to `/onboarding/v1/clients/{id}`, the missing fields are described in the party’s `validationResponse` field.

The following is a sample of missing fields in the `validationResponse` object:

```json
{
  "id": "1000010400",
  "outstanding": {
    "attestationDocumentIds": [],
    "documentRequestIds": [],
    "questionIds": [],
    "partyRoles": [],
    "partyIds": [
      "2000000112"
    ]
  },
  "parties": [
    {
      "id": "2000000112",
      "createdAt": "2025-08-06T01:22:22.607Z",
      "partyType": "INDIVIDUAL",
      "parentPartyId": "2000000111",
      "profileStatus": "NEW",
      "roles": [
        "CONTROLLER"
      ],
      "active": true,
      "individualDetails": {
        "countryOfResidence": "US",
        "firstName": "Philip",
        "lastName": "Banks"
      },
      "validationResponse": [
        {
          "validationStatus": "NEEDS_INFO",
          "validationType": "ENTITY_VALIDATION",
          "fields": [
            {
              "name": "individualIds"
            },
            {
              "name": "addresses"
            },
            {
              "name": "birthDate"
            }
          ]
        }
      ]
    }
  ],
  "questionResponses": [],
  "createdAt": "2025-08-06T01:22:23.035Z",
  "partyId": "2000000111",
  "products": [
    "MERCHANT_SERVICES"
  ],
  "status": "NEW",
  "results": {
    "customerIdentityStatus": "NOT_STARTED"
  }
}
```

Once you have collected the additional fields, send the fields using a `PATCH` request to `/onboarding/v1/parties/{partyId}` by specifying the party ID in the `partyId` path parameter along with the additional fields:

```json
{
  "individualDetails": {
    "birthDate": "1945-01-30",
    "addresses": [
      {
        "addressType": "RESIDENTIAL_ADDRESS",
        "addressLines": [
          "251 N Bristol Ave"
        ],
        "city": "Los Angeles",
        "state": "CA",
        "postalCode": "90049",
        "country": "US"
      }
    ],
    "individualIds": [
      {
        "idType": "SSN",
        "value": "300050005",
        "issuer": "US"
      }
    ]
  }
}
```

## Related

[United States Census Bureau](https://www.census.gov/naics/)

[Present attestations](/docs/commerce/optimization-protection/capabilities/digital-onboarding/how-to/present-attestations)

[Reference for onboarding Publicly Traded Companies](/docs/commerce/optimization-protection/capabilities/digital-onboarding/how-to/publicly-traded-companies)

[Create party](https://developer.payments.jpmorgan.com/api/commerce/optimization-protection/digital-onboarding/digital-onboarding#/operations/postParty)

[Update party](https://developer.payments.jpmorgan.com/api/commerce/optimization-protection/digital-onboarding/digital-onboarding#/operations/updateParty)

[Create client](https://developer.payments.jpmorgan.com/api/commerce/optimization-protection/digital-onboarding/digital-onboarding#/operations/smbdo-postClients)

[Update client](https://developer.payments.jpmorgan.com/api/commerce/optimization-protection/digital-onboarding/digital-onboarding#/operations/smbdo-updateClient)

[Get party](https://developer.payments.jpmorgan.com/api/commerce/optimization-protection/digital-onboarding/digital-onboarding#/operations/getParty)

[Get client](https://developer.payments.jpmorgan.com/api/commerce/optimization-protection/digital-onboarding/digital-onboarding#/operations/smbdo-getClient)

## Next steps

Once you have successfully created a client profile, you can present onboarding questions to your client.