Depending on applicable regulations or business limitations, specific API requests may not be available for your use.
Create an Account
Please contact the Goldman Sachs Advisor Solutions Integrations Team at gs-ria-integrations@gs.com to request the most recent documentation for Create, Update & Get a Member, Firm and Account, which has significant and required changes from the information below.
An account is a brokerage account that people and corporate entities use for investing.
Note: New accounts are automatically restricted upon creation, pending the user signing the brokerage customer agreement. Accounts so restricted cannot take most actions. See the Get a Restriction endpoint for more information on restriction details and how to lift these restrictions in the test and production environments.
Natural Person Accounts
Natural persons accounts are accounts opened for a specific human being, as opposed to corporate accounts. This request can be used to create the following types of natural person accounts under a member: Individual, Joint (several types), IRA (several types), and Custodial UTMA/UGMA, as well as Revocable Trust.
Natural person account creation flow:
- Create Member
- Create Account
All joint account members must be created prior to creating the joint account.
Members are able to have multiple accounts, except those assigned as the firm rep on a corporate account.
Beneficiary IRAs may be set up using a special process described here.
Billing Note: In the case of joint accounts, the primaryAccountOwner will be the member that owns the account for billing purposes. In the event that there is an asset-based fee for each member, based upon aggregate assets of a membership, the joint account assets will be included in the primaryAccountOwner’s assets under management calculation.
Corporate Accounts
Corporate accounts are accounts opened for a specific entity that is not a human being, as opposed to natural persons accounts. This request can also be used to create the following types of corporate accounts under a firm: Business Trust (Irrevocable Trust), Corporation, LLC, Limited Partnership, General Partnership, Unincorporated Organization, Investment Club, and Sole Proprietorship.
Corporate account creation flow:
- Create Member
- Create Firm
- Create Trustee(s)
- Create Corporate Account
All trustees must be created prior to creating the corporate account.
Only a member associated with no accounts and no firms can be designated as the firm rep for a corporate account, and a firm can have only one firm rep. Further, a firm can only have one corporate account under it.
There are two additional fields for a corporate account that are not required for natural person accounts: trustees and accountRegistrationInfo.
Request URL
| Syntax | POST /restapi/accounts |
|---|---|
| Example URL | https://api.uat.foliofn.com/restapi/accounts |
Error Code
Please refer to Account Error Codes for the error codes that can be returned from this API.
Request Data Fields
| Field | Account Types | Required? | Description |
|---|---|---|---|
| accountName | All | Yes | The name of the account. Letters, digits, spaces, and special characters are allowed. The maximum length of the field is 16 characters. This field can be updated. |
| accountType | All | Yes | The type of account to create. See Account Types for list of available account types. |
| billingPlanOid | All | Yes | Only accept an advisory billing plan OID. See Get All Billing Plans for how to find an advisory billing plan OID. This field can be updated, if another code is available under the firm. |
| branchCode | All | No | Branch Code associated with the account or member. |
| defaultTaxLotSelection | Taxable | No | Default tax relief method used by the account. See Tax Lot Relief Methods for available codes. Taxable account can be assigned with any available code except “AVGC”. Non-taxable accounts only accept “AVGC”. When this field is not specified during the account creation, the default value will be “Maximize Losses / Minimize Gains” (LGHL) for taxable accounts, and “Average Cost” for non-taxable accounts. See What is a tax lot selection method? further explanations for the different methods available. |
| longTermTaxRate | Taxable | No | Long-term tax rate of the owner of the account. This is an input when using the “WLFS” or “WGFS” tax lot selection strategies. This field accepts a double value that ranges from 0.0 to 100.0. |
| repCode | All | No | Rep Code associated with the account or member. |
| shortTermTaxRate | Taxable | No | Short-term tax rate of the owner of the account. This is an input when using the “WLFS” or “WGFS” tax lot selection strategies. This field accepts a double value that ranges from 0.0 to 100.0. |
| primaryAccountOwner | All | Yes | The username of the primary account owner. For a corporate account, the primary account owner is the firm ID. There can only be one primary account owner for each account. |
| jointOwners | Joint | Yes for joint accounts | A list of joint account owner usernames. The joint account owners have to be the members that are already created. This can only be used with joint account types. |
| initContributionDate | SIMPLE IRA | Yes if it is an existing SIMPLE IRA account | The date of the first contribution to the SIMPLE IRA. The data format must follow ISO-8601 formatted date. Note: If the date is not provided, it will be considered to be a newly created SIMPLE IRA account. |
| trustedContacts | All | No |
A list of trusted contacts. See Trusted Contacts Fields. User text: You authorize us to contact your trusted contact person(s) and disclose to your trusted contact person(s) information about your account in the following circumstances: to address possible financial exploitation, to confirm the specifics of your current contact information, health status, or the identity of any legal guardian, executor, trustee or other holder of a power of attorney, or as otherwise permitted by FINRA Rule 2165 (Financial Exploitation of Specified Adults). |
| primaryBeneficiaries | Retirement | No |
A list of primary beneficiaries. See Beneficiary Fields. User text: You can designate primary and contingent beneficiaries for IRAs. If more than one beneficiary is designated, be sure that the total percentage share adds up to 100%.
User text for selecting no primary beneficiary: I do not want to designate any primary beneficiaries. I understand that when I die, the assets in my IRA will transfer to the default statutory designated beneficiary as specified in the IRA Custodial Agreement. We will charge your account the hourly fee for Special Services, for gathering, reviewing and processing documents required to validate and process IRA distribution requests if no beneficiaries are designated.
|
| contingentBeneficiaries | Retirement | No | A list of contingent beneficiaries. This field should be supplied only if primary beneficiaries is not empty. See Beneficiary Fields. |
| minor | Custodial | Yes for custodial accounts | Container object for a minor. See Minor Fields. |
| w9BackupWithholding | The type of backup withholding. The possible values are: “C” for subject to backup withholding and “N” or null for not-subject to backup withholding. |
||
| trustees | Corporate Accounts | Yes for corporate accounts |
A list of trustee usernames. The trustees have to be already created. This can only be used with corporate account types. |
| accountRegistrationInfo | Corporate Accounts and Revocable Trust | Yes for corporate accounts and revocable trust |
The complete official name of the corporate entity as it will appear on the registration for the account. This can only be used with corporate account types. |
| taxClassification | Corporation or LLC account types | Yes for corporation or LLC account types | Corporation and LLC account types require a taxClassification. See Tax Classification section for available codes. |
| securityExclusion | All | No | List of security tickers to be excluded and associated start date/end date |
| issueExclusion | All | No | List of issue codes to be excluded and associated start date/end date |
| sectorExclusion | All | No | List of sector codes to be excluded and associated start date/end date |
Trusted Contact Fields
| Field | Required? | Description |
|---|---|---|
| firstName | Yes | The first name of the trusted contact. |
| lastName | Yes | The last name of the trusted contact. |
| Yes | The email address of the trusted contact. | |
| telephone | Yes | The phone number of the trusted contact. |
| relationship | No | The relationship of the trusted contact to the primary account owner. The value can be “S” for spouse ,“O” for other, ,“A” for financial advisor, ,“G” for gaurdian, ,“F” for family member or “L” for lawyer/attorney. |
Beneficiary Fields
| Field | Required? | Description |
|---|---|---|
| title | No | The title of the beneficiary. See Create a Member for the data format. |
| firstName | Yes | The first name of the beneficiary. See Create a Member for the data format. |
| middleName | No | The middle name of the beneficiary. See Create a Member for the data format. |
| lastName | Yes | The last name of the beneficiary. See Create a Member for the data format. |
| suffix | No | The suffix of the beneficiary. See Create a Member for the data format. |
| relationship | Yes | The relationship of the beneficiary to the primary account owner. The value must be either “S” for spouse or “O” for other. |
| dateOfBirth | Yes | The beneficiary’s date of birth. See Create a Member for the data format. |
| ssn | Yes | The social security number. See Create a Member for the data format. |
| sharePct | Yes | The percentage of assets that would go to the beneficiary upon the account owner’s death. The value must be between .01 & 100. Up to two decimal places are allowed. A valid value must match the following regular expression: ^(100(.00?)?|[1-9]?d(.dd?)?)$ |
Minor Fields
| Field | Required? | Description |
|---|---|---|
| title | No | The title of the beneficiary. See Create a Member for the data format. |
| firstName | Yes | The first name of the beneficiary. See Create a Member for the data format. |
| middleName | No | The middle name of the beneficiary. See Create a Member for the data format. |
| lastName | Yes | The last name of the beneficiary. See Create a Member for the data format. |
| suffix | No | The suffix of the beneficiary. See Create a Member for the data format. |
| dateOfBirth | Yes | The minor’s date of birth. See Create a Member for the data format. |
| ssn | Yes | The social security number. See Create a Member for the data format. |
| citizenship | Yes | The citizenship status of the minor. See Create a Member for the data format. |
| state | Yes | The state in which the minor resides, or if the minor lives outside of the U.S., the state in which the minor most recently resided. The value of this field must be the two letter state abbreviation. |
Security Exclusion/Issue Exclusion/Sector Exclustion Fields
| Field | Required? | Description |
|---|---|---|
| exclusionValue | Yes | Ticker for securityExclusion or issue category code for issueExclusion or sector code for sector exclusion. Allowed issue category code are,
Allowed sector code are, |
| startDate | No | Exclusion starting date. If not specified, the current date will be used. Format: CCYY-MM-DD |
| endDate | No | Exclusion ending date. If not specified, the ending date will be set to 3999-12-31 00:00:00. Ending date should be a future date and should be after starting date. Format: CCYY-MM-DD. |
Request Example for Individual Account
POST /restapi/accounts HTTP/1.1
Content-Type: application/json
{
"accountName" : "Indie Account",
"accountType" : "I",
"billingPlanOid" : "1111111111111113",
"primaryAccountOwner" : "testusername"
"trustedContacts" : [
{
"firstName" : "Chuck",
"lastName" : "Powers",
"email" : "chuckyboy1982@aol.com",
"telephone" : "7032454000",
"relationship" : "O"
},
{
"firstName" : "Gob",
"lastName" : "Bluth",
"email" : "bananastand01@hotmail.com",
"telephone" : "7032454894",
"relationship" : "S"
}
],
"securityExclusions" : [
{
"exclusionValue" : "LMT",
"exclusionStartDate" : "2018-11-19",
"exclusionEndDate" : "2019-11-19"
}
],
"issueExclusions" : [
{
"exclusionValue" : "3"
},
{
"exclusionValue" : "5",
"exclusionStartDate" : "2018-12-05",
}
],
"sectorExclusions" : [
{
"exclusionValue" : "7"
}
]
}
Request Example for Joint Account
POST /restapi/accounts HTTP/1.1
Content-Type: application/json
{
"accountName" : "Joint Account",
"accountType" : "J",
"billingPlanOid" : "11111111111111113",
"jointOwners" : [ "jointusername" ],
"primaryAccountOwner" : "testusername"
}
Request Example for Revocable Trust Account
POST /restapi/accounts HTTP/1.1
Content-Type: application/json
{
"accountName" : "Revocable Trust",
"accountRegistrationInfo" : "Registration",
"accountType" : "X",
"billingPlanOid" : "11111111111111113",
"jointOwners" : [ "revtrustusername1" ],
"primaryAccountOwner" : "username"
}
Request Example for Retirement Account
POST /restapi/accounts HTTP/1.1
Content-Type: application/json
{
"accountName" : "IRA Account",
"accountType" : "9",
"initContributionDate" : "2010-01-01T00:00:00.000-05:00",
"billingPlanOid" : "11111111111111113",
"primaryBeneficiaries" : [ {
"ssn" : "123123123",
"citizenship" : "U",
"dateOfBirth" : "1988-12-05T00:00:00.000-05:00",
"firstName" : "firstname",
"lastName" : "lastname",
"relationship" : "O",
"sharePct" : "30"
}, {
"ssn" : "123123123",
"citizenship" : "U",
"dateOfBirth" : "1978-12-05T00:00:00.000-05:00",
"firstName" : "firstname",
"lastName" : "lastname",
"relationship" : "O",
"sharePct" : "70"
} ],
"primaryAccountOwner" : "testusername",
"defaultTaxLotSelection" : "AVGC"
}
Request Example for Custodial Account
POST /restapi/accounts HTTP/1.1
Content-Type: application/json
{
"accountName" : "Custodial Acct",
"accountType" : "U",
"billingPlanOid" : "111111111111111113",
"minor" : {
"ssn" : "888888888",
"citizenship" : "C",
"dateOfBirth" : "2003-08-22T00:00:00.000-05:00",
"firstName" : "John",
"lastName" : "Doe",
"state" : "VA"
},
"primaryAccountOwner" : "testusername"
}
Request Example for Corporate Account
POST /restapi/accounts HTTP/1.1
Content-Type: application/json
{
"accountName" : "Corporate Account",
"accountRegistrationInfo" : "Registration",
"accountType" : "A",
"billingPlanOid" : "0000000000000000000000",
"primaryAccountOwner" : "DJFSDKGFISDIFDSIJFIS",
"trustees" : [ "trusteeusername1" ],
"taxClassification" : "C"
}
Response Example
(note: responses for different types are the same.)
HTTP/1.1 201 Created
X-Powered-By: Servlet/2.5
Server: Sun GlassFish Enterprise Server v2.1.1
Location: https://api.uat.foliofn.com/restapi/accounts/RA1234ABCD
Content-Type: text/html; charset=iso-8859-1
Content-Length: 0
Date: Fri, 21 Feb 2014 18:08:56 GMT
Change Log
11/18/2021
- For jointOwners in the Request Data Fields table, updated text in Required? column
10/11/2018
- Added Security Exclusion/Issue Exclusion/Sector Exclusion Fields
- Updated Request Example for Individual Account
- Modified exclusionStartDate and exclusionEndDate definition and modified example
01/16/2018
- Added trustedContacts data field
06/23/2017
- Added accountType detail to Request Data Fields
05/12/2017
- New fields added - repCode and branchCode
03/24/2017
- Added a note to initContributionDate description