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

# Create a client profile

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 minimum data

To create a client, you must send a `POST /do/v1/clients` request with:

- A parties list of objects.

- A product with the value EMBEDDED_PAYMENTS.

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) you may need to include additional information. [Take a look at this PTC reference](/docs/embedded-finance-solutions/embedded-payments/capabilities/onboard-a-client/how-to/publicly-traded-companies) for more information.

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

Sample of create a client request body with minimum 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": [
    "EMBEDDED_PAYMENTS"
  ]
}
```

## 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, Update party, Create client and Update client 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 and Get client 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 USA, you can find this reference information in 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"
          }
        ],
        "websiteAvailable": true,
        "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": [
    "EMBEDDED_PAYMENTS"
  ]
}
```

## Create a client with multiple related parties

When you have multiple individual parties related to a client, you can add them to your `POST /clients` request like this: 

```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": [
        "EMBEDDED_PAYMENTS"
    ]
}
```

## Understand outstanding data

A successful 200 or 201 response to any `POST /clients` or `GET /clients/{id}` request 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:

- questionId : An answers must be provided for each questionId listed. You can find out how to manage questions in [this guide](/docs/embedded-finance-solutions/embedded-payments/capabilities/onboard-a-client/how-to/present-onboarding-questions).

- 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. You can find out how to manage attestations in [this guide](/docs/embedded-finance-solutions/embedded-payments/capabilities/onboard-a-client/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 `partyId` and `partyRoles`, send a `POST clients/{id}` request with the updated details. 

## Update party data

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

Sample of missing fields in `validationResponse` object:

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

Once you have collected the additional fields, send the fields using `POST /do/v1/parties/{id}` by specifying the party ID in the request URL path, along with the additional fields:

Example of updated party:

```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"
            }
        ]
    }
}
```

## Next steps

Once you have successfully created a client profile, you can [present onboarding questions to your client](/docs/embedded-finance-solutions/embedded-payments/capabilities/onboard-a-client/how-to/present-onboarding-questions).