Skip to main content
POST
/
investors
Create a new investor
curl --request POST \
  --url https://api.bluumfinance.com/v1/investors \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_type": "individual",
  "management_type": "self_directed",
  "tax_advantaged": false,
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "1990-05-15",
  "email": "jane.doe@example.com",
  "phone": "+14155551234",
  "address": {
    "street": [
      "456 Oak Avenue"
    ],
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  },
  "tax_id": "987-65-4321",
  "tax_id_type": "SSN",
  "country_of_tax_residence": "US",
  "country_of_citizenship": "US",
  "country_of_birth": "US",
  "funding_source": [
    "employment_income"
  ],
  "annual_income": {
    "min": "75000",
    "max": "99999"
  },
  "liquid_net_worth": {
    "min": "20000",
    "max": "49999"
  },
  "is_control_person": false,
  "is_affiliated_exchange_or_finra": false,
  "is_politically_exposed": false,
  "immediate_family_exposed": false,
  "employment_status": "employed",
  "employer_name": "Acme Inc",
  "signed_agreements": [
    {
      "type": "investor_agreement",
      "signed_at": "2026-01-15T10:30:00.000Z",
      "ip_address": "203.0.113.42"
    },
    {
      "type": "margin_disclosure_acknowledged",
      "signed_at": "2026-01-15T10:30:00.000Z",
      "ip_address": "203.0.113.42"
    }
  ]
}
'
{
  "id": "inv_01j9x8m2k7qpzwv3t5r6y8n0ab",
  "object": "investor",
  "created": 1747776000,
  "livemode": false,
  "metadata": {},
  "status": "onboarding",
  "account_type": "individual",
  "management_type": "self_directed",
  "tax_advantaged": false,
  "tax_designation": null,
  "account_number": null,
  "currency": "USD",
  "balance": "0.00",
  "buying_power": "0",
  "cash_withdrawable": "0",
  "last_equity": "0.00",
  "crypto_status": null,
  "trading_type": null,
  "first_name": "Jane",
  "middle_name": null,
  "last_name": "Doe",
  "date_of_birth": "1990-05-15",
  "email": "jane.doe@example.com",
  "phone": "+14155551234",
  "address": {
    "street": [
      "456 Oak Avenue"
    ],
    "unit": null,
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  },
  "tax_id_type": "SSN",
  "country_of_tax_residence": "US",
  "country_of_citizenship": "US",
  "country_of_birth": "US",
  "funding_source": [
    "employment_income"
  ],
  "is_control_person": false,
  "is_affiliated_exchange_or_finra": false,
  "is_affiliated_exchange_or_iiroc": null,
  "is_politically_exposed": false,
  "immediate_family_exposed": false,
  "employment_status": "employed",
  "employer_name": "Acme Inc",
  "employer_address": null,
  "employment_position": null,
  "signed_agreements": [
    {
      "type": "investor_agreement",
      "signed_at": "2026-01-15T10:30:00.000Z",
      "ip_address": "203.0.113.42"
    }
  ],
  "trusted_contact": null,
  "portfolios": [],
  "compliance_checks": [
    {
      "workflow_id": "cw_01j9x8m2k7qpzwv3t5r6y8n0cd",
      "check_type": "identity_verification",
      "status": "pending",
      "provider": "persona-identity",
      "external_id": "inq_abc123def456",
      "verification_url": "https://withpersona.com/verify?inquiry-id=inq_abc123def456",
      "verification_token": null
    },
    {
      "workflow_id": "cw_01j9x8m2k7qpzwv3t5r6y8n0cd",
      "check_type": "screening",
      "status": "pending",
      "provider": "persona-screening",
      "external_id": null,
      "verification_url": null,
      "verification_token": null
    }
  ]
}

Authorizations

​
Authorization
string
header
required

HTTP Basic Authentication using the API Key as username and API Secret as password.

Body

application/json

flat investor creation body. Regulatory fields live at the top level; only address, signed_agreements[], and trusted_contact are nested (each is an independent sub-object).

​
account_type
enum<string>
required
Available options:
individual,
joint,
corporate
Example:

"individual"

​
first_name
string
required
Example:

"Jane"

​
last_name
string
required
Example:

"Doe"

​
date_of_birth
string<date>
required
Example:

"1990-01-01"

​
email
string<email>
required
Example:

"jane@example.com"

​
phone
string
required
Example:

"+15555550123"

​
address
object
required
​
tax_id
string
required
Example:

"401-23-4567"

​
tax_id_type
enum<string>
required
Available options:
SSN,
ITIN,
EIN,
SIN,
NINO,
TFN,
VAT,
TIN,
UTR,
PAN,
NIN,
KRA_PIN,
OTHER
​
country_of_tax_residence
string
required
Example:

"US"

​
country_of_citizenship
string
required
Example:

"US"

​
country_of_birth
string
required
Example:

"US"

​
funding_source
enum<string>[]
required
Available options:
employment_income,
investments,
inheritance,
business_income,
savings,
family,
other
Example:
["employment_income"]
​
annual_income
object
required
​
liquid_net_worth
object
required
​
is_control_person
boolean
required
​
is_affiliated_exchange_or_finra
boolean
required
​
is_politically_exposed
boolean
required
​
immediate_family_exposed
boolean
required
​
employment_status
enum<string>
required
Available options:
employed,
unemployed,
student,
retired
​
signed_agreements
object[]
required

Audit trail for each regulated acknowledgement the user clicked. Must contain at least investor_agreement and margin_disclosure_acknowledged; non-US tax residents must additionally include w8ben_certification.

Minimum array length: 2
​
management_type
enum<string>
default:self_directed
Available options:
self_directed,
advised
​
tax_advantaged
boolean
default:false
​
tax_designation
string | null
​
middle_name
string | null
​
tax_id_country
string | null

ISO 3166-1 alpha-2 of the tax-id issuing country.

​
total_net_worth
object
​
permanent_resident
boolean | null
​
visa_type
enum<string> | null
Available options:
E1,
E2,
E3,
F1,
H1B,
TN1,
O1,
J1,
L1,
DACA,
G4,
OTHER
​
visa_expiration_date
string<date> | null
​
is_affiliated_exchange_or_iiroc
boolean | null
​
affiliated_company
object

Required when is_affiliated_exchange_or_finra or is_control_person is true. ticker is additionally required for control persons of a publicly traded company.

​
employer_name
string | null
​
employer_address
string | null
​
employment_position
string | null
​
trusted_contact
object

FINRA-defined "designated trusted contact" record. Per FINRA SR Rule 4512, partners must give end-users a way to add or update a trusted contact post-onboarding. All four fields are required together.

​
metadata
object

Response

Investor created. Pending compliance approval.

The investor (account) resource. flat: regulatory fields are flat at the top level; only address, signed_agreements[], and trusted_contact retain meaningful nesting. The Alpaca-style contact / identity / disclosures block grouping is intentionally absent.

​
object
string
required

The resource type discriminator.

Example:

"investor"

​
livemode
boolean
required

Whether this resource was created against a live API key. Test-mode keys always return false.

Example:

false

​
id
string

Prefixed public id (e.g. inv_…, ord_…, dep_…).

Example:

"inv_01j9x8m2k7qpzwv3t5r6y8n0ab"

​
created
integer | null

Unix-seconds timestamp of resource creation.

Example:

1747776000

​
metadata
object

Partner-set key/value map for cross-referencing.

​
status
enum<string>

Bluum-native account status.

Available options:
onboarding,
under_review,
awaiting_documents,
active,
suspended,
closed,
declined,
setup_failed
Example:

"onboarding"

​
account_type
enum<string>
Available options:
individual,
joint,
corporate
Example:

"individual"

​
management_type
enum<string>
Available options:
self_directed,
advised
Example:

"self_directed"

​
tax_advantaged
boolean
Example:

false

​
tax_designation
string | null
​
account_number
string | null
​
currency
string
Example:

"USD"

​
balance
string
Example:

"0.00"

​
buying_power
string

Available buying power from the custodian brokerage account. Defaults to "0" when no custodian account exists yet.

Example:

"10000.00"

​
cash_withdrawable
string

Amount of cash available for withdrawal from the custodian brokerage account. Defaults to "0" when no custodian account exists yet.

Example:

"5000.00"

​
last_equity
string
Example:

"0.00"

​
crypto_status
string | null
​
trading_type
enum<string> | null
Available options:
cash,
margin,
null
​
high_yield_cash_status
enum<string>

High-Yield-Cash enrollment lifecycle for this account.

Available options:
not_registered,
pending,
active,
unenrolled
Example:

"active"

​
high_yield_cash_status_at
string<date-time> | null

Timestamp of the transition into the current HYC status (null when not_registered).

​
first_name
string
Example:

"Jane"

​
middle_name
string | null
​
last_name
string
Example:

"Doe"

​
date_of_birth
string<date> | null
Example:

"1990-01-01"

​
email
string<email>
Example:

"jane@example.com"

​
phone
string | null
Example:

"+15555550123"

​
address
object

Address record. street is an array of one or more street lines (multi-line addresses keep one entry per line).

​
tax_id_type
enum<string> | null
Available options:
SSN,
ITIN,
EIN,
SIN,
NINO,
TFN,
VAT,
TIN,
UTR,
PAN,
NIN,
KRA_PIN,
OTHER
​
country_of_tax_residence
string | null

ISO 3166-1 alpha-2.

​
country_of_citizenship
string | null

ISO 3166-1 alpha-2.

​
country_of_birth
string | null

ISO 3166-1 alpha-2.

​
funding_source
enum<string>[]
Available options:
employment_income,
investments,
inheritance,
business_income,
savings,
family,
other
​
is_control_person
boolean
​
is_affiliated_exchange_or_finra
boolean
​
is_affiliated_exchange_or_iiroc
boolean | null
​
is_politically_exposed
boolean
​
immediate_family_exposed
boolean
​
employment_status
enum<string> | null
Available options:
employed,
unemployed,
student,
retired
​
employer_name
string | null
​
employer_address
string | null
​
employment_position
string | null
​
signed_agreements
object[]
​
trusted_contact
object
​
portfolios
object[]
​
compliance_checks
object[] | null