Suitability¶

Suitability is often required when a broker-dealer is involved in the offering. TransactAPI collects the investor's suitability information on the account with calculateSuitability. Despite its name, the method does not calculate a score: it stores the answers so that a registered representative can decide whether the investment is suitable. Use it with the approval of the managing broker-dealer on the offering, if there is one.

Before You Start¶

• Create the account and link it to the investor with Onboard Investors. Suitability is stored per account.
• Collect the investor's answers, for example with your own questionnaire. If you want a numeric suitability score, calculate it yourself; TransactAPI does not.
• Confirm your API key has permission for each field you plan to send. calculateSuitability stores only the fields your key is permitted to write and leaves any others empty.

Steps¶

1. Store the suitability answers¶

Call calculateSuitability with the account ID and the investor's answers. Only accountId is required. riskProfile, investmentExperience, privOffExperience, and timeHorizon must be whole numbers. The first three are scores; timeHorizon is the investment time horizon in years. An account can have only one suitability record.

curl -X PUT "$TAPI_HOST/v3/calculateSuitability" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d accountId=A12345 \
  -d riskProfile=3 \
  -d investmentExperience=3 \
  -d privOffExperience=2 \
  -d investmentObjective="Both Capital Preservation and Growth" \
  -d pctPrivSecurities=5 \
  -d pctIlliquidSecurities=10 \
  -d pctLiquidSecurities=60 \
  -d pctRealEstate=25 \
  -d timeHorizon=10 \
  -d education="4 Year College or University" \
  -d financialAdvisor=Yes

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "accountDetails": [
    { "accountId": "A12345" }
  ]
}

The response confirms the accountId. See calculateSuitability for every field.

2. Read or correct the answers¶

Call getSuitability to read the stored answers, and updateSuitability to change them. Use updateSuitability rather than a second calculateSuitability, which returns 151.

curl -X POST "$TAPI_HOST/v3/getSuitability" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d accountId=A12345

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "accountDetails": {
    "accountId": "A12345",
    "riskProfile": "3",
    "investmentExperience": "3",
    "timeHorizon": "10"
  }
}

See getSuitability and updateSuitability for the full field lists.

3. Record the review on the account¶

A registered representative reviews the answers. The outcome is recorded on the account with updateAccount, either by your integration or in the Transact Portal: suitabilityScore (1 to 5, where 5 is most suitable), suitabilityDate, and suitabilityApprover.

curl -X PUT "$TAPI_HOST/v3/updateAccount" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d accountId=A12345 \
  -d suitabilityScore=4 \
  -d suitabilityDate=2026-01-15 \
  -d suitabilityApprover="Jane Doe"

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "accountDetails": [
    { "accountId": "A12345", "suitabilityScore": "4", "approvalStatus": "Pending" }
  ]
}

Read the result back with GET /v3/accounts/{id}. See updateAccount for every account field.

Webhooks¶

calculateSuitability, updateSuitability, and getSuitability send no webhook. Recording the review with updateAccount sends the updateAccount webhook; see Accounts.

Common Errors¶

See Error Codes for the full list.

Next¶

If the offering requires it, continue to Accredited Investor Verification. Otherwise continue to Create the Trade.