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

Create a Member

This request creates an individual member.

A single member may own multiple accounts (e.g., individual, IRA, joint, custodial, etc.). Similarly, a member may be included on the accounts of another member, as is the case of a member being a joint owner on a joint account, or an authorized user permissioned onto another person’s account.

Notes:

  • You must provide the client's personal email address. Email addresses created or provided by the firm are not permitted. Folio cannot accept any client email address or phone number with the same domain name or phone number that is associated with your Firm, unless that account is owned by your Firm. Further, you must establish processes to ensure that all client profile information, including but not limited to physical mailing address(es), email address, phone number(s), and other personal data, is accurate and complete, and that you update the Folio system with all client profile changes when they are received by your Firm.
  • After a member is created you must use the Update Member call to update any changes in client information. Member information at Folio must match what is stored locally at your firm.
  • We process customer validations for our Customer Information Program (CIP) (e.g., Social Security Number (SSN) or Tax Identification Number (TIN), Know Your Customer (KYC), Anti-Money Laundering (AML), Office of Foreign Asset Control (OFAC), etc.) in real-time when we receive the Create a Member call. If a prospective member fails this validation you will receive an error message.
  • After a member is created, we generally automatically send an email to the user with a special password token link to set their password for the Folio site. Introducing broker dealer firms that are using this API to support their own site with their own user authentication processes can instruct us to not send this email, during the initial API setup configuration for the firm.
  • The fields annualIncome, netWorth and liquidNetWorth are not required to be completed by the client but required to be asked in the member creation process.

Request URL

Syntax POST /restapi/members?asynchronousSSNValidation={value}
Example URL https://api.uat.foliofn.com/restapi/members?asynchronousSSNValidation=false

Request Query Parameter

Parameter Required? Description
asynchronousSSNValidation No

false: SSN Validation is performed synchronously during the member creation process. This is the default value.

true: SSN Validation is performed asynchronously. Member is created with pending validation flag. The validation is performed asynchronously as soon as possible.

Error Code

Please refer to Member Error Codes for the error codes that can be returned from this API.

Request Data Fields

Field Required? Description
loginId Yes

The username of the member to be created. The length must be between 8 and 32 characters. Only letters and digits are allowed. All letters are treated as lower case. This field is not editable by the member or the firm after it is created.

User text:

Your username must be 8–32 characters. It cannot contain symbols or spaces and is not case sensitive. You will not be able to change your username once this application is complete.
membershipType Yes The membership type of the member. Managed client, “N”, is the only valid value at the moment.
title No The title of the member. See Title Codes for available codes.
firstName Yes

The first name of the member. Maximum of 20 characters.

Valid first, middle and last characters are capital and lower case letters (Aa through Zz) as well as space ( ), dash (-) and period (.) — not underscore, comma, brackets, or other characters.

In cases where there is more than one first, middle, or last name for a person, the names should be separated by a space or dash, space permitting.

middleName No The middle name of the member. Maximum of 20 characters.
lastName Yes The last name of the member. Maximum of 35 characters.
suffix No The suffix of the name of the member. See Suffix Codes for available codes.
dateOfBirth Yes

The member’s date of birth. Must follow ISO-8601 formatted date. Requests to create members under 18 years of age will be rejected. Note that this field cannot be changed once set without special manual processing at Folio based upon user provided document review.

The following user text may be displayed to explain this field:

A minor cannot open an online brokerage account on his/her own. However, it is possible for someone under the age of 18 to buy and sell stock using an account with his/her name attached to it. In order for a minor to open a brokerage account, a parent or a guardian must also be on the account.
tid Yes

Social security number. The length must be 9 digits. See Social Security Number Rules. This field cannot be changed once set without special manual processing at Folio based upon user provided document review.

The following user text may be displayed to explain this field:

Enter your social security number for identity verification and tax reporting. Resident aliens must enter their individual tax ID.
email1 Yes

The primary email address of the member. This field must be a well-formed email address (i.e. example@example.com). We ask that you have the user enter this field twice and ensure that both entries match.

User text:

A valid email address is required for all customers. You must provide the client's personal email address; email addresses created or provided by the firm are not permitted; Folio cannot accept any client email address or phone number with the same domain name or phone number that is associated with your Firm, unless that account is owned by your Firm.
email2 No The secondary email address of the member. If supplied, this field must be well-formed email address. (i.e. example@example.com)
primaryAddress Yes

The primary address of the member. This must be a U.S. street address, no P.O. Boxes or non-U.S. addresses accepted. See Address Fields for the format of each address field. Use the name “Primary Address” on client applications.

User text:

(U.S. street addresses only; no P.O. Boxes)
mailingAddress No

The mailing address of the member. See Address Fields. Use the name "Mailing Address" on client applications.

User text:

(P.O. Boxes allowed)
eveningTelephone Yes

The evening phone number. The length should be between 10 and 14 digits.

User text:

Enter numbers only. For extensions, add the extension number to the end (ex. 70324540001234).
dayTelephone Yes

The day time phone number. The length should be between 10 and 14 digits.

User text:

Enter numbers only. For extensions, add the extension number to the end (ex. 70324540001234).
employmentStatus Yes

The employment status of the member. See Employment Status Codes for available options.

User text:

We are required to record your employment status. Please note, if you’re employed or self-employed, we will also ask for your occupation, as well as employer’s name and address.
occupationType No The occupation type of the member. See Occupation Codes for available options.
employerName Yes if employmentStatus is “Employed” or “Self-Employed”. The name of the employer. The length should be between 1 and 45 characters.
employerAddress Yes if employmentStatus is “Employed” or “Self-Employed”. The address of the employer. See Address Fields.
finraAffiliated Yes

A binary indicator of whether the member is employed by or associated with a FINRA-registered company. “true” or “false”.

User text:

Are you employed by or associated with a member firm of FINRA or an exchange, if so please select Yes below:

If you are employed by or associated with an investment adviser, a bank, or a credit union and if this entity requires that you obtain its approval for you to open this account, please select Yes below:

Additional text for use if “true”:

FINRA Affiliation
You have indicated a FINRA affiliation that requires us to restrict your account until the employer of the FINRA affiliated person approves.

Please download, complete and send us the Compliance Officer Form to unrestrict the account.

finraCompany May be supplied if finraAffiliated is “true”. The company the member is affiliated with. Letters, digits, special characters, or spaces are allowed. The length should be between 1 and 45.
directorOrTenPercentShareholder Yes

A binary indicator of whether member is a director or 10% shareholder at a publicly-traded company. “true” or “false”.

User text:

Are you or someone in your household or immediate family a 10% shareholder, policymaking officer or member of the board of directors of a publicly-traded company?

Additional text for use if “true”:

Enter Trading Symbols:
directorOrTenPercentShareholderCompany Yes if directorOrTenPercentShareholder is “true”.

A comma separated array of exchange listed publicly traded security tickers. Letters, digits and dot are allowed (e.g., ['GOOG.C']).

Tickers specified here will be added to the security level exclusions for accounts of the member.

accreditedInvestorNetWorth No

A binary indicator of whether the member is accredited for private placements based on the net worth criterion. “true” or “false”.

User text:

Are you an individual whose individual net worth, or joint net worth with your spouse, exceeds $1,000,000, excluding the value of your primary residence?
accreditedInvestorAnnualIncome No

A binary indicator of whether the member is accredited for private placements based on the annual income criterion. “true” or “false”.

User text:

Have you had individual income in excess of $200,000 in each of the most recent 2 years or joint income with your spouse in excess of $300,000 in each of the same years, and do you reasonably expect to reach the same income level in the current year?
previousPrivatePlacementExperience No A binary indicator of whether the member has previous experience in private placements. “true” or “false”.
previousExperienceSector No

Industrial sector of private placement if previousPrivatePlacementExperience is “true”. See Industry Sector Codes for available codes.

User text:

Have you had previous experience investing in private placements?

Additional text for use if “true”:

If yes, please indicate the industries and sectors you have participated in:
annualIncome No Annual income range. See Annual Income Ranges for available codes.
netWorth No Net worth range. See Net Worth Ranges for available codes. Provide users the text definition of net worth provided here: How is total net worth calculated?
liquidNetWorth No Liquid net worth range. See Liquid Net Worth Ranges for available codes. Provide users the text definition of liquid net worth provided here: How is liquid net worth calculated?
citizenship Yes The citizenship of the member. We only allow U.S. citizen and resident alien members. The available values are “C” for a U.S. citizen and “R” for a resident alien. The following user text may be displayed to explain this: How do you define a U.S. person?
residenceCountry Yes The 2 letter code of the country in which the member lives. Must follow ISO-3166-1 alpha-2 formatting.
dependentCount No The number of dependents that a member indicated (e.g., children, non-working spouse, etc.).
memberProfileItems no The profile for the member. Marital Status and Top Marginal Tax Bracket are the available options at the moment. Other values will be ignored.

Address Fields

Field Required? Description
line1 Yes This field can have letters, digits, special characters, and spaces. The length must be between 1 and 35.
line2 No This field can have letters, digits, special characters, and spaces. The length must be between 1 and 35.
city Yes This field can have letters, digits, special characters, and spaces. The length must be between 1 and 25.
state Yes The value of this field must be the two letter state abbreviation.
zipcode Yes if the country is U.S. See Zip Code Rules.
country Yes

The 2 letter code of the country. Must follow ISO-3166-1 alpha-2 formatting.

Note that primary address must be in the U.S.

Zip Code Rules

The following rules apply if the zip code is a U.S. zip code (as determined by the “country” field in the associated address).

  1. Required
  2. The length must be either 5 or 9.
  3. It must consist of all digits.
  4. If the first three digits are “340”, the associated state code must be “AA”.
  5. If the first two digits are “09” and the third digit is 0–8, the state code must be “AE”.
  6. If the first two digits are 96, and the third digit is 2–6, the state code must be “AP”.

If these rules are not met, an “INVALID_ZIPCODE” error code is sent.

Social Security Number Rules

The REST API will take in any string for a social security number, but will strip out any character which is not a digit. The length of the remaining string must be 9 digits long. In addition, none of the three parts in an SSN (AAA-BB-CCCC) may consist of all zeros. For example 000-XX-XXXX, XXX-00-XXXX, and XXX-XX-0000 are all invalid. However, XXX-XX-0001 is valid.

Request Example


POST /restapi/members HTTP/1.1
Content-Type: application/json

{
  "loginId" : "testusername",
  "membershipType" : "N",
  "firstName" : "John",
  "lastName" : "Doe",
  "dateOfBirth" : "1960-01-01T00:00:00.000-05:00",
  "email1" : "johndoe@email.com",
  "primaryAddress" :
  {
    "line1" : "home address 1",
    "city" : "city",
    "state" : "VA",
    "zipcode" : "12345",
    "country" : "US"
  },
  "eveningTelephone" : "789-789-7890",
  "dayTelephone" : "7897897891",
  "employmentStatus" : "Employed",
  "occupationType" : "engineering",
  "employerName" : "folio",
  "employerAddress" : {
    "city" : "city",
    "country" : "US",
    "line1" : "employer address 1",
    "state" : "VA",
    "zipcode" : "12345"
  },
  "finraAffiliated" : true,
  "finraCompany" : "ABC",
  "directorOrTenPercentShareholder" : true,
  "directorOrTenPercentShareholderCompany" : [ "TICKER" ],
  "accreditedInvestorNetWorth" : true,
  "accreditedInvestorAnnualIncome" : true,
  "previousPrivatePlacementExperience" : true,
  "previousExperienceSector" : "BAN",
  "annualIncome" : 6,
  "netWorth" : 7,
  "liquidNetWorth" : 7,
  "tid" : "123456789",
  "citizenship" : "C",
  "residenceCountry" : "US"
}

Response Example

When the member fails Customer Identification Program verification:


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/members/testusername
Link: <https://api.uat.foliofn.com/restapi/members/testusername>; rel="GET"; type="application/json"; title="getMember", <http://localhost:6880/restapi/members/testusername>; rel="PUT"; type="application/json"; title="updateMember", <http://localhost:6880/restapi/members/testusername/verifications>; rel="POST"; type="application/json"; title="reverifiyMember"
Content-Type: text/html; charset=iso-8859-1
Content-Length: 0
Date: Wed, 19 Feb 2014 19:18:58 GMT

When the member passes Customer Identification Program verification:


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/members/testusername
Link: <https://api.uat.foliofn.com/restapi/members/testusername>; rel="GET"; type="application/json"; title="getMember", <http://localhost:6880/restapi/members/testusername>; rel="PUT"; type="application/json"; title="updateMember", <http://localhost:6880/restapi/members/testusername/verifications>; rel="GET"; type="application/json"; title="getVerificationStatus"
Content-Type: text/html; charset=iso-8859-1
Content-Length: 0
Date: Wed, 19 Feb 2014 19:18:58 GMT

Error Codes

HTTP Code Status Field Code Message Description
400 - member.riskwise.rule - The member fails CIP verification.
503 - - Customer Identification Program is unavailable now. The specified service is not available.

Change Log

05/12/2017

  1. Updated the account opening affiliation question again as per the new requirement

03/24/2017

  1. Updated the account opening affiliation questions

01/17/2017

  1. Added Error codes

11/18/2016

  1. Added Request Query Parameter

09/02/2016

  1. Updated Notes Section

10/16/2015

  1. Updated response examples

Getting Started

REST APIs

Resources

Developer Home