Onboard Joint Accounts¶

A joint account is one account owned by two people, such as "Jane and John Smith JTWROS". You create a party for each person, one account, and a link from the account to each party. The first owner is the primary party; the second is linked with linkType=secondary, which is how TransactAPI identifies the second signer for subscription documents.

Before You Start¶

You have completed Onboard Individuals at least once; this page uses the same calls and fields.
An offering exists. See Set Up an Offering.
Webhooks are registered for createParty, createAccount, and createLink if you want event notifications. See Register Webhooks.

Steps¶

1. Create a party for each owner¶

Call createParty once per person, with the same required fields as for an individual. See Onboard Individuals, step 1.

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 "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": "" }]]
}

Repeat for the second owner (for example John Smith, P67890). Keep both partyId values.

2. Create the joint account¶

Create one account for both owners. Set accountRegistration to the exact registration and type to the form of joint ownership, for example JTWROS, TIC, or Joint. The other required fields are the same as for an individual account; see Onboard Individuals, step 2.

curl -X PUT "$TAPI_HOST/v3/createAccount" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d "accountRegistration=Jane Smith and John Smith JTWROS" \
  -d "type=JTWROS" \
  -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.

3. Link the primary owner¶

Link the first owner with linkType=owner and primary_value=1. This party signs first and receives subscription documents.

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" }]]
}

4. Link the second owner¶

Link the second owner with linkType=secondary and primary_value=0 (or omit it). Subscription documents look for a non-primary secondary link to find the joint signer, so a different linkType such as spouse or owner does not add the second person as a signer.

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=P67890" \
  -d "linkType=secondary" \
  -d "primary_value=0"

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

Keep both link id values if you may need to remove a link later.

5. Confirm the links (optional)¶

List the account's links to confirm both owners are attached with the expected linkType.

curl -X GET "$TAPI_HOST/v3/links?filter[firstEntry]=A12345" \
  --globoff \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY"

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "links": [
    {
      "id": "12346",
      "firstEntryType": "Account",
      "firstEntry": "A12345",
      "relatedEntry": "P67890",
      "relatedEntryType": "IndivACParty",
      "linkType": "secondary",
      "notes": ""
    },
    {
      "id": "12345",
      "firstEntryType": "Account",
      "firstEntry": "A12345",
      "relatedEntry": "P12345",
      "relatedEntryType": "IndivACParty",
      "linkType": "owner",
      "notes": ""
    }
  ],
  "pagination": { "totalRecords": 2, "startIndex": 0, "endIndex": 1 }
}

The link list does not include primary_value. To check a party or the account itself, use GET /v3/parties/{partyId} or GET /v3/accounts/{accountId} as shown in Onboard Individuals, step 4. See GET /v3/links.

Verify Both Parties¶

Run KYC/AML on each party, not only the primary owner. See KYC/AML Verification.

Webhooks¶

createParty: once per party. See Parties and Entities.
createAccount: once for the joint account. See Accounts.
createLink: once per link. See Links.

Common Errors¶

See Error Codes for the full list.

Code	HTTP status	Cause
`106`	404	A required `createParty` or `createAccount` parameter is missing or invalid. The `Error(s)` field lists the fields.
`1400`	400	A link between this account and party already exists, or `firstEntry` and `relatedEntry` are the same.
`1404`	404	The account or party ID in `createLink` does not exist for your client.
`1422`	422	`primary_value=1` was sent for the second owner while the account already has a primary party, or `linkType` is not a valid value.

Next¶

Continue to Qualify Investors.