Business Trading Accounts

Overview

The Broker API now supports opening business trading accounts through a party-based model. Instead of embedding all entity and individual details into a single account creation request, each person and entity is created as a distinct Party resource. These parties are then linked together and associated with a trading account.

What Changed from Phase 1

Key Concepts

Parties

A Party represents either a natural person or a legal entity. Every individual and business involved in an account is modeled as a party.

Relationships

A legal entity party references its associated natural person parties through:

• ubos — Ultimate Beneficial Owners (individuals who ultimately own ≥10% of the entity)
• authorized_signers — Individuals authorized to legally act on behalf of the entity

Agreements

Agreements are split into two levels:

• Party-level agreements (e.g., certifications_and_resolutions_statement) — attached when creating the legal entity party
• Account-level agreements (e.g., customer_agreement) — attached when creating the trading account

Prerequisites

Beta Access: Business trading account onboarding is currently available by allowlist only. Please reach out to your Alpaca integration team to get your correspondent enabled before proceeding.

• CIP API enabled for your correspondent (your own KYC/KYB provider is responsible for the verifications)
• Base URL: https://broker-api.sandbox.alpaca.markets (sandbox)
• Authentication: Multiple methods are supported. See Authentication for details on API key authentication, OAuth2, and other options.

Integration Flow

The end-to-end flow for onboarding a business trading account:

┌─────────────────────────────────────────────────────────┐
│                                                         │
│  1. Create Natural Person Parties                       │
│     ├── UBO 1 (natural_person)                          │
│     ├── UBO 2 (natural_person)                          │
│     ├── Authorized Signer 1 (natural_person)            │
│     └── Authorized Signer 2 (natural_person)            │
│              │                                          │
│              ▼                                          │
│  2. Create Legal Entity Party                           │
│     (references UBO + signer party IDs)                 │
│              │                                          │
│              ▼                                          │
│  3. Upload Documents (per party)                        │
│              │                                          │
│              ▼                                          │
│  4. Submit Verifications (per party)                    │
│              │                                          │
│              ▼                                          │
│  5. Create Trading Account                              │
│     (references legal entity party ID)                  │
│              │                                          │
│              ▼                                          │
│  6. Account is APPROVED → ACTIVE                        │
│                                                         │
└─────────────────────────────────────────────────────────┘

Important: Natural person parties must be created before the legal entity party, because the legal entity references them by ID.

Step 1: Create Natural Person Parties

Create a party for each individual associated with the entity — every UBO and every authorized signer. A single person can serve as both a UBO and an authorized signer.

Request

POST /v1/parties
Content-Type: application/json
Authorization: <see Authentication docs>

Sample Request — UBO / Authorized Signer

{
  "party_type": "natural_person",
  "given_name": "Jane",
  "family_name": "Smith",
  "date_of_birth": "1985-06-15",
  "country_of_citizenship": "USA",
  "email": "[email protected]",
  "phone_number": "+14155551234",
  "residential_address": {
    "street_address": ["742 Evergreen Terrace"],
    "city": "San Francisco",
    "subdivision": "CA",
    "postal_code": "94103",
    "country": "USA"
  },
  "id_numbers": [
    {
      "type": "USA_SSN",
      "value": "123-45-6789",
      "issuing_country": "USA"
    }
  ],
  "country_of_tax_residence": "USA",
  "funding_source": ["employment_income"],
  "disclosures": {
    "is_control_person": false,
    "is_affiliated_exchange_or_finra": false,
    "is_politically_exposed": false,
    "immediate_family_exposed": false
  }
}

Sample Response (201 Created)

{
  "id": "b5c7e1a2-3d4f-4e5a-8b6c-9d0e1f2a3b4c",
  "party_type": "natural_person",
  "given_name": "Jane",
  "family_name": "Smith",
  "date_of_birth": "1985-06-15",
  "country_of_citizenship": "USA",
  "email": "[email protected]",
  "phone_number": "+14155551234",
  "residential_address": {
    "street_address": ["742 Evergreen Terrace"],
    "city": "San Francisco",
    "subdivision": "CA",
    "postal_code": "94103",
    "country": "USA"
  },
  "id_numbers": [
    {
      "type": "USA_SSN",
      "value": "***-**-6789",
      "issuing_country": "USA"
    }
  ],
  "country_of_tax_residence": "USA",
  "funding_source": ["employment_income"],
  "disclosures": {
    "is_control_person": false,
    "is_affiliated_exchange_or_finra": false,
    "is_politically_exposed": false,
    "immediate_family_exposed": false
  }
}

Save the id from each response — you will need these party IDs when creating the legal entity.

Required Fields — Natural Person

Optional Fields — Natural Person

Step 2: Create the Legal Entity Party

After creating all natural person parties, create the legal entity party. This links UBOs and authorized signers by their party IDs and includes the party-level certifications_and_resolutions_statement agreement.

Request

POST /v1/parties
Content-Type: application/json
Authorization: <see Authentication docs>

Sample Request — Legal Entity

{
  "party_type": "legal_entity",
  "legal_name": "Acme Corporation",
  "legal_entity_type": "c_corporation",
  "country_of_incorporation": "USA",
  "state_of_incorporation": "DE",
  "date_of_incorporation": "2015-08-20",
  "email": "[email protected]",
  "phone_number": "+14155559999",
  "legal_address": {
    "street_address": ["100 Market Street", "Suite 500"],
    "city": "San Francisco",
    "subdivision": "CA",
    "postal_code": "94105",
    "country": "USA"
  },
  "id_numbers": [
    {
      "type": "USA_EIN",
      "value": "12-3456789",
      "issuing_country": "USA"
    }
  ],
  "country_of_tax_residence": "USA",
  "financial_profile": {
    "annual_income_min": 1000000,
    "annual_income_max": 5000000,
    "liquid_net_worth_min": 500000,
    "liquid_net_worth_max": 2000000,
    "total_net_worth_min": 2000000,
    "total_net_worth_max": 10000000
  },
  "funding_source": ["business_revenue", "investors"],
  "industry": "technology",
  "disclosures": {
    "is_participating_fatca": false,
    "is_exempt_from_tax_under_501a": false
  },
  "ubos": [
    {
      "id": "b5c7e1a2-3d4f-4e5a-8b6c-9d0e1f2a3b4c",
      "percentage_ownership": 51
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "percentage_ownership": 30
    }
  ],
  "authorized_signers": [
    {
      "id": "b5c7e1a2-3d4f-4e5a-8b6c-9d0e1f2a3b4c",
      "title_at_company": "CEO"
    },
    {
      "id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
      "title_at_company": "CFO"
    }
  ],
  "agreements": [
    {
      "agreement": "certifications_and_resolutions_statement",
      "signed_at": "2026-05-14T10:00:00Z",
      "ip_address": "203.0.113.42",
      "revision": "01.2024.02",
      "signer_party_id": "b5c7e1a2-3d4f-4e5a-8b6c-9d0e1f2a3b4c"
    }
  ]
}

Sample Response (201 Created)

{
  "id": "e4d3c2b1-a098-7654-3210-fedcba987654",
  "party_type": "legal_entity",
  "legal_name": "Acme Corporation",
  "legal_entity_type": "c_corporation",
  "...": "..."
}

Save the legal entity id — this is used as the primary_account_holder_id when creating the trading account.

Required Fields — Legal Entity

Optional Fields — Legal Entity

UBO Object

Authorized Signer Object

Party-Level Agreements

When creating a legal entity, include the certifications_and_resolutions_statement agreement:

Step 3: Upload Documents

Upload required documents for each party. Documents are associated at the party level, allowing you to attach identity documents to individuals and business documents to the entity.

Request

POST /v1/documents
Content-Type: application/json
Authorization: <see Authentication docs>

Sample — Entity Document

{
  "party_id": "e4d3c2b1-a098-7654-3210-fedcba987654",
  "type": "entity_operating_document",
  "sub_type": "articles_of_incorporation",
  "content": {
    "content_type": "base64",
    "data": "JVBERi0xLjQK..."
  },
  "original_filename": "articles_of_incorporation.pdf"
}

Sample — Individual Identity Document

{
  "party_id": "b5c7e1a2-3d4f-4e5a-8b6c-9d0e1f2a3b4c",
  "type": "identity_verification",
  "sub_type": "passport",
  "content": {
    "content_type": "base64",
    "data": "/9j/4AAQSkZJRg..."
  },
  "original_filename": "jane_passport.jpg"
}

Required Documents

For the legal entity:

For each natural person (UBO / authorized signer):

Retrieving Documents

GET /v1/documents?party_id={party_id}
GET /v1/documents/{document_id}
GET /v1/documents/{document_id}/download    → 302 redirect to pre-signed URL

Step 4: Submit Verifications

After running KYC/KYB through your verification provider, submit the results to Alpaca for each party.

Request

POST /v1/verifications
Content-Type: application/json
Authorization: <see Authentication docs>

Sample — KYC for Natural Person

{
  "party_type": "natural_person",
  "party_id": "b5c7e1a2-3d4f-4e5a-8b6c-9d0e1f2a3b4c",
  "providers": [{ "name": "onfido" }],
  "result": "clear",
  "risk_level": "low",
  "risk_score": 15,
  "completed_at": "2026-07-14T10:31:00Z",
  "reviewed_by": "automated",
  "review_reason": "All checks passed automated thresholds",
  "reviewed_at": "2026-07-14T10:31:05Z",
  "checks": [
    {
      "type": "IDENTITY",
      "result": "clear",
      "details": {},
      "initiated_at": "2026-07-14T10:29:55Z",
      "completed_at": "2026-07-14T10:30:00Z"
    },
    {
      "type": "PHOTO",
      "result": "clear",
      "details": { "facial_similarity": "match" },
      "initiated_at": "2026-07-14T10:30:00Z",
      "completed_at": "2026-07-14T10:30:05Z"
    },
    {
      "type": "DOCUMENT",
      "result": "clear",
      "details": { "document_type": "passport", "authenticity": "valid" },
      "initiated_at": "2026-07-14T10:30:05Z",
      "completed_at": "2026-07-14T10:30:10Z"
    },
    {
      "type": "WATCHLIST",
      "result": "clear",
      "details": { "pep": "clear", "sanction": "clear" },
      "initiated_at": "2026-07-14T10:30:10Z",
      "completed_at": "2026-07-14T10:30:15Z"
    },
    {
      "type": "ADDRESS",
      "result": "clear",
      "details": { "address_match": "exact" },
      "initiated_at": "2026-07-14T10:30:10Z",
      "completed_at": "2026-07-14T10:30:20Z"
    },
    {
      "type": "DATE_OF_BIRTH",
      "result": "clear",
      "details": {},
      "initiated_at": "2026-07-14T10:30:20Z",
      "completed_at": "2026-07-14T10:30:25Z"
    },
    {
      "type": "IDENTIFICATIONS",
      "result": "clear",
      "details": {
        "results": [
          { "type": "USA_SSN", "issuing_country": "USA", "result": "clear" }
        ]
      },
      "initiated_at": "2026-07-14T10:30:25Z",
      "completed_at": "2026-07-14T10:30:30Z"
    }
  ],
  "raw_data": "{\"provider_response\": \"...\"}",
  "ip_addresses": ["203.0.113.42", "2001:db8::1"]
}

Sample — KYB for Legal Entity

{
  "party_type": "legal_entity",
  "party_id": "e4d3c2b1-a098-7654-3210-fedcba987654",
  "providers": [{ "name": "middesk" }],
  "result": "clear",
  "risk_level": "low",
  "risk_score": 10,
  "completed_at": "2026-07-14T10:31:00Z",
  "reviewed_by": "[email protected]",
  "review_reason": "Manual review completed; no adverse findings",
  "reviewed_at": "2026-07-14T10:31:10Z",
  "checks": [
    {
      "type": "BUSINESS_REGISTRATION",
      "result": "clear",
      "details": {
        "registration_number": "verified",
        "jurisdiction": "Delaware"
      },
      "initiated_at": "2026-07-14T10:29:55Z",
      "completed_at": "2026-07-14T10:30:00Z"
    },
    {
      "type": "BUSINESS_STATUS",
      "result": "clear",
      "details": { "status": "active", "good_standing": true },
      "initiated_at": "2026-07-14T10:30:00Z",
      "completed_at": "2026-07-14T10:30:05Z"
    },
    {
      "type": "OWNERSHIP",
      "result": "clear",
      "details": { "beneficial_owners_verified": true },
      "initiated_at": "2026-07-14T10:30:05Z",
      "completed_at": "2026-07-14T10:30:10Z"
    },
    {
      "type": "ADDRESS",
      "result": "clear",
      "details": { "address_match": "exact" },
      "initiated_at": "2026-07-14T10:30:15Z",
      "completed_at": "2026-07-14T10:30:20Z"
    },
    {
      "type": "WATCHLIST",
      "result": "clear",
      "details": { "sanctions": "clear", "adverse_media": "clear" },
      "initiated_at": "2026-07-14T10:30:20Z",
      "completed_at": "2026-07-14T10:30:25Z"
    },
    {
      "type": "IDENTIFICATIONS",
      "result": "clear",
      "details": {
        "results": [
          { "type": "EIN", "issuing_country": "USA", "result": "clear" }
        ]
      },
      "initiated_at": "2026-07-14T10:30:25Z",
      "completed_at": "2026-07-14T10:30:30Z"
    }
  ],
  "raw_data": "{\"provider_response\": \"...\"}",
  "ip_addresses": ["203.0.113.42", "2001:db8::1"]
}

Providers

providers is an array of objects, not strings. Each entry requires a name, with an optional reference_id for the provider's external identifier:

"providers": [
  { "name": "onfido", "reference_id": "ref-123" },
  { "name": "complyadvantage" }
]

Check Types

Natural Person:
IDENTITY, PHOTO, DOCUMENT, WATCHLIST, ADDRESS, DATE_OF_BIRTH, IDENTIFICATIONS

Legal Entity:
BUSINESS_REGISTRATION, BUSINESS_STATUS, OWNERSHIP, ADDRESS, WATCHLIST, IDENTIFICATIONS

All checks listed for a given party type are mandatory, with one exception: PHOTO is optional for natural persons whose country of tax residence Alpaca rates as low or medium risk, and required for all other ratings. A country's risk rating can be retrieved from the Broker API /v1/country-info endpoint. PHOTO is always accepted regardless of rating, so we recommend including it whenever a photo check was performed. Exactly one of each other required check type must be present in the checks array, or the request is rejected with 400. DATE_OF_BIRTH is natural-person only; sending it for a legal_entity verification is rejected.

Check Object Fields

details is optional. You may omit it, send null, or send an empty object {} — all three are accepted. When present, it is a free-form key/value object carrying provider-specific data for that check and is not validated against a fixed schema.

New Check Semantics

IDENTIFICATIONS is a single rollup check covering all of the party's identification numbers (previously submitted via id_numbers on the party). Its result is consider if any single identification is flagged consider, and clear otherwise. An optional details.results array may break down the result per identification, keyed by the same type and issuing_country values the correspondent already sent on POST /v1/parties id_numbers — never by internal ID or by the identification value itself.

"details": {
  "results": [
    { "type": "USA_SSN",  "issuing_country": "USA", "result": "clear" },
    { "type": "PASSPORT", "issuing_country": "GBR", "result": "consider" }
  ]
}

Verification-Level Fields

In addition to the existing party_type, party_id, providers, result, risk_level, risk_score, and checks fields, every verification submission must now also include:

Retrieving Verifications

GET /v1/verifications?party_id={party_id}
GET /v1/verifications/{verification_id}

Step 5: Create the Trading Account

Once all parties, documents, and verifications are in place, create the trading account. The account references the legal entity party as the primary account holder.

Important: The legal entity party must have at least one ubos entry and at least one authorized_signers entry before account creation will succeed. If you created the legal entity without them, use PATCH /v1/parties/{id} to add them first.

Request

POST /v1/accounts
Content-Type: application/json
Authorization: <see Authentication docs>

Sample Request

{
  "account_type": "trading",
  "primary_account_holder_id": "e4d3c2b1-a098-7654-3210-fedcba987654",
  "agreements": [
    {
      "agreement": "customer_agreement",
      "signed_at": "2026-05-14T10:00:00Z",
      "ip_address": "203.0.113.42"
    }
  ],
  "enabled_assets": ["us_equity"],
  "investment_objective": "market_speculation"
}

Sample Response (200 OK)

{
  "id": "7a8b9c0d-1e2f-3456-7890-abcdef123456",
  "account_number": "123456789",
  "status": "APPROVED",
  "account_type": "trading",
  "primary_account_holder_id": "e4d3c2b1-a098-7654-3210-fedcba987654",
  "enabled_assets": ["us_equity"],
  "created_at": "2026-05-14T10:05:00Z"
}

Account-Level Agreements

Account Creation Fields

Step 6: Verify Account Status

The account will be created in APPROVED status and transition to ACTIVE shortly after.

Request

GET /v1/accounts/{account_id}
Authorization: <see Authentication docs>

Account Statuses

Updating Party Information

Party information can be updated via the API using a partial update (PATCH).

Request

PATCH /v1/parties/{party_id}
Content-Type: application/json
Authorization: <see Authentication docs>

Sample Request — Update Address

{
  "residential_address": {
    "street_address": ["456 New Avenue"],
    "city": "Los Angeles",
    "subdivision": "CA",
    "postal_code": "90001",
    "country": "USA"
  }
}

Note: Only include the fields you want to update. Fields not included will remain unchanged.

Error Handling

Error Response Format

{
  "error": "invalid_request",
  "error_description": "Validation failed",
  "fields": [
    {
      "name": "email"
    },
    {
      "name": "id_numbers[0].value"
    }
  ]
}

Common Error Codes

Validation Tips

• All schemas use additionalProperties: false — unknown fields will be rejected
• String fields enforce printable ASCII (U+0020–U+007E) with no leading/trailing whitespace
• subdivision is required in any address object whose country is "USA"
• controlling_firms is required when is_control_person is true
• affiliated_firm is required when is_affiliated_exchange_or_finra is true
• Agreement revision format: XX.YYYY.MM (e.g., "01.2024.02")
• id_numbers[].issued_date cannot be in the future; id_numbers[].expiry_date must be in the future

Field Reference

Address Object

ID Numbers

issued_date and expiry_date are optional. They are most relevant for document-based identifiers such as PASSPORT, NATIONAL_ID, or DRIVER_LICENSE, and can be omitted entirely for tax identifiers like USA_SSN or USA_EIN. Either field may be supplied independently of the other.

{
  "type": "PASSPORT",
  "value": "X1234567",
  "issuing_country": "GBR",
  "issued_date": "2019-03-12",
  "expiry_date": "2029-03-11"
}

US identifiers:

International tax IDs:

Generic / document-based:

Legal Entity Types

banking_institution, broker_or_dealer, c_corporation, foreign_financial_institution, fund_or_hedge_fund, general_partnership, irrevocable_trust, limited_liability_corporation, limited_partnership, revocable_trust, s_corporation, unincorporated, other

Industry Types

administration_or_public_relations, agriculture, architecture, arts_or_film_or_music, construction, design, education, finance, food_production, government_or_public_services, healthcare, legal_services, media_or_marketing, oil_or_energy_or_mining, pharmaceuticals_or_biochemicals, real_estate, retail_restaurants, technology, sports_or_sports_medicine_or_fitness, tourism, transport, other

Funding Source — Natural Person

employment_income, investments, inheritance, business_income, savings, family, other

Funding Source — Legal Entity

business_revenue, asset_appreciation, sales_of_assets, investors, other

Investment Objectives

balance_preserve_wealth_with_growth, generate_income, growth, market_speculation, preserve_wealth

Disclosures — Natural Person

Disclosures — Legal Entity

The disclosures object is required in the request body, but all subfields are optional.

Financial Profile — Legal Entity

Employment (Natural Person, Optional)

Employment status values: employed, unemployed, retired, student

Employment sector values: agriculture, business_management, computers_and_it, construction, education, finance, government, healthcare, hospitality, manufacturing, marketing, media, other, science, self_employed, transportation, not_employed

Document Types

Entity documents:

Individual documents:

Migration from Phase 1

Phase 1 of the entity account API (where entity details were embedded directly in POST /v1/accounts) remains functional and there is no immediate requirement to migrate. However, Phase 1 is not a public API and has known limitations — most notably it does not create discrete party records for UBOs and authorized signers, making those individuals unmanageable via API.

Phase 1 will eventually be deprecated. We will communicate timelines in advance.

Migrating Existing Accounts to Phase 2

If you want to manage previously created Phase 1 business accounts using the Phase 2 Party API, you will need to backfill all missing party records and link them to the existing legal entity.

We strongly recommend reaching out to your Alpaca integration team before attempting to migrate existing accounts. The process requires careful coordination to avoid data inconsistencies.

Key Differences

FAQ

Can one person be both a UBO and an authorized signer?

Yes. Create a single natural_person party and reference their ID in both the ubos and authorized_signers arrays on the legal entity.

What if the entity has no UBOs with ≥10% ownership?

Contact your Alpaca integration support team to discuss the specific entity structure. In most cases, at least one control person should be identified.

Can I create parties and the account in any order?

No. Natural person parties must be created first, then the legal entity party (which references them), and finally the trading account (which references the legal entity). The flow is sequential.

What happens if I submit a verification with result consider?

A consider result means your KYC/KYB provider flagged the check for manual review. Verifications are submitted by your correspondent and are independent of account creation — submitting a verification does not directly trigger account approval or rejection. Work with Alpaca support if you have questions about how a specific verification result affects a party's standing.

Is sandbox available for testing?

Yes. Use https://broker-api.sandbox.alpaca.markets with your sandbox credentials. All endpoints described in this guide are available in sandbox.

How do I handle international entities?

The API supports international entities. Use the appropriate ISO 3166-1 alpha-3 country codes for country_of_incorporation, country_of_tax_residence, and address fields. ID types support international formats (see the full ID types list in the OpenAPI spec).

What agreement revisions should I use?

If no revision is provided, the latest active revision will be used automatically. You may optionally specify a revision in the format XX.YYYY.MM (e.g., "01.2024.02") if you need to pin to a specific version — contact your Alpaca integration team if you are unsure.

Is there a maximum limit on the number of UBOs or Authorized Signers?

Yes. You can link at most 10 UBOs and 10 authorized signers per legal entity. The total UBO ownership percentage cannot exceed 100%.

What happens if I update a party's information after the account is already ACTIVE?

Certain updates may trigger a compliance review and cause the account to transition away from ACTIVE. See the Account Statuses documentation for the full list of fields that trigger a review and what to expect during each status.

How are complex, multi-layered corporate structures handled?

UBO stands for Ultimate Beneficial Owner — the natural person(s) who ultimately own or control the legal entity. The API is interested in the ultimate owner, not immediate parent entities.

If a business is owned by another business, you should trace ownership through the chain until you reach the natural person(s) who own ≥10% of the top-level entity. Only those natural persons should be listed as UBOs. Intermediate holding companies or parent entities are not captured as UBOs.

Support & Feedback

This is a Beta API — we actively welcome feedback on the API design, documentation, and developer experience.

• Integration Support: Contact your Alpaca integration team
• API Issues: Report via your designated support channel
• Documentation Feedback: Let us know what could be clearer or what's missing

© 2026 Alpaca Securities LLC. All rights reserved.