Depending on applicable regulations or business limitations, specific API requests may not be available for your use.

Create an Account

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:

  1. Create Member
  2. 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:

  1. Create Member
  2. Create Firm
  3. Create Trustee(s)
  4. 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 and revocable trust 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.
email 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,
1 -- Alcohol
2 -- Genocide
3 -- Gambling
4 -- Military Weapons and Firearms
5 -- Nuclear Power
6 -- Tobacco
7 -- RICA
8 -- K-1 Securities
9 -- Factory Farming

Allowed sector code are,
1 -- Consumer Staples
2 -- Consumer Discretionary
3 -- Retail/Wholesale
4 -- Medical
5 -- Auto/Tires/Trucks
6 -- Basic Materials
7 -- Industrial Products
8 -- Construction
9 -- Multi-Sector Conglomerates
10 -- Computer/Technology
11 -- Aerospace
12 -- Oils/Energy
13 -- Finance
14 -- Utilities
15 -- Transportation
16 -- Business Services
17 -- Unclassified

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

10/11/2018

  1. Added Security Exclusion/Issue Exclusion/Sector Exclusion Fields
  2. Updated Request Example for Individual Account
  3. Modified exclusionStartDate and exclusionEndDate definition and modified example

01/16/2018

  1. Added trustedContacts data field

06/23/2017

  1. Added accountType detail to Request Data Fields

05/12/2017

  1. New fields added - repCode and branchCode

03/24/2017

  1. Added a note to initContributionDate description

Getting Started

REST APIs

Resources

Developer Home