# 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.
> 

In the example below, 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"
      }
    },
    {
      "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"
          }
        ]
      }
    }
  ],
  "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"
          }
        ]
      }
    },
    {
      "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"
      }
    },
    {
      "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)

## Next steps

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