Skip to main content

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 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
    • At least one entry in addresses.
    • If the organization is a Publicly Traded Company (PTC) you may need to include additional information. Take a look at this PTC reference for more information. 
  • individualDetails for the individual party must include:
    • firstName
    • lastName
    • countryOfResidence

Sample createClient request body with minimum data:

createClient
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

You can also send a full payload with all the required information about your client and their organization.

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 USA, you can find this reference information in the United States Census Bureau. 

Sample createClient request body with complete data:

Sample createClient request body 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"
  ]
}

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

Create a client with multiple 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": [
        "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 - 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. You can find out how to manage attestations in this guide.
  • 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.