Depending on applicable regulations or business limitations, specific API requests may not be available for your use.
Create a Member
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.
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.
- The CIP validation check can be shut off if your firm would like to perform your own CIP checks. Please contact your Folio Relationship Manager or Folio API Support for additional details.
- 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. |
| cipAlreadyVerified | No | false: CIP Check is preformed by Folio on Member creation. This is the default value. true: CIP check is skipped on Member creation. This is only applicable to firms who are preforming the CIP check outside of Folio. Additional configuration is required. Please contact your Folio representative or API Support for additional information. |
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 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).
- Required
- The length must be either 5 or 9.
- It must consist of all digits.
- If the first three digits are “340”, the associated state code must be “AA”.
- If the first two digits are “09” and the third digit is 0–8, the state code must be “AE”.
- 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
01/30/2020
- Added information about CIP shutoff feature
05/12/2017
- Updated the account opening affiliation question again as per the new requirement
03/24/2017
- Updated the account opening affiliation questions
01/17/2017
- Added Error codes
11/18/2016
- Added Request Query Parameter
09/02/2016
- Updated Notes Section
10/16/2015
- Updated response examples