Onboard Individuals¶

An individual investor is one person investing in their own name. You create a party for the person, an account for the investment, and a link that makes the party the account's owner and primary signer. Use this flow for every single-owner investor; joint and entity investors build on it.

Before You Start¶

• An offering exists. See Set Up an Offering.
• Webhooks are registered for createParty, createAccount, and createLink if you want event notifications. See Register Webhooks.
• Your API key has permission for createParty, createAccount, and createLink. Required parameters are enforced only for fields enabled on your key; fields that are not enabled are ignored and stored empty.

Steps¶

1. Create the party¶

Create an individual party with the person's identity and address details.

Required: firstName, lastName, dob (MM-DD-YYYY), primAddress1, primCity (no digits), primState (two-letter code, or NOUS outside the U.S.; not required when domicile is non-resident), primZip, primCountry, and emailAddress (must be a valid address). Send domicile as U.S. citizen, U.S. resident, or non-resident. socialSecurityNumber is optional here but is needed for most KYC checks.

curl -X PUT "$TAPI_HOST/v3/createParty" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d "domicile=U.S. citizen" \
  -d "firstName=Jane" \
  -d "lastName=Smith" \
  -d "socialSecurityNumber=000-00-0000" \
  -d "dob=03-24-1980" \
  -d "primAddress1=100 Main Street" \
  -d "primCity=Atlanta" \
  -d "primState=GA" \
  -d "primZip=30318" \
  -d "primCountry=USA" \
  -d "emailAddress=jane.smith@example.com"

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "partyDetails": [
    true,
    [
      {
        "partyId": "P12345",
        "KYCstatus": "",
        "AMLstatus": ""
      }
    ]
  ]
}

Keep partyDetails[1][0].partyId. KYCstatus and AMLstatus echo what you sent and are empty if you sent nothing. See createParty for every field.

2. Create the account¶

Create the account that will own the investment. For an individual, accountRegistration is usually the person's name.

Required: accountRegistration, type, domesticYN (domestic_account or international_account), streetAddress1, city (no digits), state (not required for international_account), zip, country, KYCstatus, AMLstatus, AccreditedStatus, and approvalStatus. New accounts usually send Pending for the four status fields; qualification updates them later.

curl -X PUT "$TAPI_HOST/v3/createAccount" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d "accountRegistration=Jane Smith" \
  -d "type=Individual" \
  -d "domesticYN=domestic_account" \
  -d "streetAddress1=100 Main Street" \
  -d "city=Atlanta" \
  -d "state=GA" \
  -d "zip=30318" \
  -d "country=USA" \
  -d "KYCstatus=Pending" \
  -d "AMLstatus=Pending" \
  -d "AccreditedStatus=Pending" \
  -d "approvalStatus=Pending"

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "accountDetails": [
    {
      "accountId": "A12345",
      "kycStatus": "Pending",
      "amlStatus": "Pending",
      "accreditedStatus": "Pending",
      "approvalStatus": "Pending"
    }
  ]
}

Keep accountDetails[0].accountId; trades are placed against it. See createAccount.

3. Link the party to the account¶

Link the party to the account as its owner. Set primary_value=1 so the party is treated as the account's signer and receives subscription documents.

Required: firstEntryType (Account), firstEntry (the account ID), relatedEntryType (IndivACParty), relatedEntry (the party ID), and linkType.

curl -X PUT "$TAPI_HOST/v3/createLink" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d "firstEntryType=Account" \
  -d "firstEntry=A12345" \
  -d "relatedEntryType=IndivACParty" \
  -d "relatedEntry=P12345" \
  -d "linkType=owner" \
  -d "primary_value=1"

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "linkDetails": [
    true,
    [
      {
        "id": "12345"
      }
    ]
  ]
}

Keep linkDetails[1][0].id if you may need to remove the link later with deleteLink. See createLink.

4. Read the records back (optional)¶

Fetch the party and account by ID to confirm what was stored, or to reconcile with your own records. These calls need the party.read and account.read scopes described under GET /v3/parties and GET /v3/accounts.

curl -X GET "$TAPI_HOST/v3/parties/P12345" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY"

curl -X GET "$TAPI_HOST/v3/accounts/A12345" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY"

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "party": {
    "partyId": "P12345",
    "firstName": "Jane",
    "lastName": "Smith",
    "domicile": "U.S. citizen",
    "emailAddress": "jane.smith@example.com",
    "kycStatus": "",
    "amlStatus": "",
    "partystatus": "Active"
  }
}

The single-record responses use the same fields as the list endpoints, under a party or account key. To list the links on the account, call GET /v3/links?filter[firstEntry]=A12345 (see GET /v3/links).

Verify the Party¶

Run KYC/AML on the party (partyId) before the investor subscribes. See KYC/AML Verification in the next step.

Webhooks¶

• createParty: sends partyId and any KYC/AML status. See Parties and Entities.
• createAccount: sends the stored account fields. See Accounts.
• createLink: sends the link fields. See Links.

Common Errors¶

See Error Codes for the full list.

Next¶

Continue to Qualify Investors. For other investor types, see Onboard Joint Accounts and Onboard Entities.