Request:
mutation {
setupCustomer (
input: {
name: ""
email: ""
accountSetupData: {
type: ""
formationDate: ""
taxId: ""
addresses: [
{
lineOne: ""
lineTwo: ""
lineThree: ""
lineFour: ""
city: ""
province: ""
postalCode: ""
country: ""
type: ""
}
]
parties: [
{
email: ""
firstName: ""
lastName: ""
taxId: ""
dateOfBirth: ""
usCitizen: true
isPrimary: true
allowLogin: true
addresses: [
{
lineOne: ""
lineTwo: ""
lineThree: ""
lineFour: ""
city: ""
province: ""
postalCode: ""
country: ""
type: ""
}
]
}
]
}
}
) {
customer {
id
investorId
}
}
}
The example above shows the full extent of the setupCustomer mutation, through which you submit details for a customer (investor). If the customer does not already exist, setupCustomer will generate the customer record (and corresponding investor account, if necessary). Customer details are specific to the vendor executing the mutation and will not interfere with another vendor’s details for the same investor. At this point the investor is not necessarily associated with any investment opportunity on the platform (unless the investor owns the shares of another vendor), but is connected to the vendor that created the record. Every customer record a vendor adds to the system establishes a unique vendor/customer combination.
The return payload, in this example, includes the UUIDs of the customer record and corresponding investor account, respectively.
Request:
mutation {
setupCustomer (
input: {
name: "Bob Smith"
email: "bob.smith@example.com"
accountSetupData: {
type: "Individual"
formationDate: "03/03/2023"
taxId: "123456789"
addresses: [
{
lineOne: "123 Main St"
lineTwo: ""
lineThree: ""
lineFour: ""
city: "Austin"
province: "Texas"
postalCode: "78739"
country: "d4dc0fe9-fcdb-4d4d-a2c1-f9a247897362"
type: "Primary"
}
]
parties: [
{
email: "bob.smith@example.com"
firstName: "Bob"
lastName: "Smith"
taxId: "123456789"
dateOfBirth: "01/01/1970"
usCitizen: true
isPrimary: true
allowLogin: false
addresses: [
{
lineOne: "123 Main St"
lineTwo: ""
lineThree: ""
lineFour: ""
city: "Austin"
province: "Texas"
postalCode: "78739"
country: "d4dc0fe9-fcdb-4d4d-a2c1-f9a247897362"
type: "Primary"
}
]
}
]
}
}
) {
customer {
id
investorId
}
}
}
In this (concrete) example, the details of an investor/customer (“Bob Smith”), as well as those of an associated party, are added to the platform.
IMPORTANT: At least ONE party must be defined in the mutation. In the case of an individual investor, you may simply duplicate the information from the primary fields as shown above (although this is not enforced). For other investor types (see below), enter the appropriate party information.
Countries
You will notice in the examples above that a UUID is required for the country field. A simple query allows you to fetch the UUIDs for all countries, or a specific country based on 2- or 3-character ISO code, defined in the platform:
query {
allCountries {
nodes {
id
name
alpha2
alpha3
}
}
}
query {
allCountries (condition: {alpha3: "USA"}) {
nodes {
id
}
}
}
IMPORTANT: UUIDs are unique to the Vertalo sandbox and production environments, respectively. You must be sure to pull the correct country UUIDs for each environment.
US States/Territories
For investors with a country UUID for the United States, the value of the province field must be the full name of a valid US state or territory (no abbreviations). A simple query allows you to fetch state/territory names:
query {
allCountryProvinces {
nodes {
name
code
}
}
}
Customer Types
The following is a list of supported customer types (case-insensitive):
- Corporation
- Corporation SEP IRA
- Corporation Simple IRA
- Estate
- Individual
- Individual IRA
- Individual Roth IRA
- Irrevocable Trust
- Joint TIC
- Joint TWROS
- Limited Partnership
- Limited Partnership SEP IRA
- Limited Partnership Simple IRA
- LLC
- LLC SEP IRA
- LLC Simple IRA
- Revocable Trust
- Sole Proprietorship
- Sole Proprietorship SEP IRA
- Sole Proprietorship Simple IRA
Address Types
The following is a list of supported address types (case-insentive):
- Primary
- Mailing