Skip to content
straddle API Docs
  • Auto
  • Light
  • Dark
Get started
API Reference
Embed
Accounts
View as Markdown
Copy Markdown
Open in Claude
Open in ChatGPT

Onboard an account

embed.accounts.onboard(straccount_id, AccountOnboardParams**kwargs) -> AccountV1
post/v1/accounts/{account_id}/onboard

Initiates the onboarding process for a new account. This endpoint can only be used for accounts where at least one representative and one bank account have already been created.

ParametersExpand Collapse
account_id: str
terms_of_service: TermsOfServiceV1Param
accepted_date: datetime

The datetime of when the terms of service were accepted, in ISO 8601 format.

formatdate-time
agreement_type: Literal["embedded", "direct"]

The type or version of the agreement accepted. Use embedded unless your platform was specifically enabled for direct agreements.

Accepts one of the following:
"embedded"
"direct"
agreement_url: Optional[str]

The URL where the full text of the accepted agreement can be found.

accepted_ip: Optional[str]

The IP address from which the terms of service were accepted.

accepted_user_agent: Optional[str]

The user agent string of the browser or application used to accept the terms.

correlation_id: Optional[str]
idempotency_key: Optional[str]
request_id: Optional[str]
ReturnsExpand Collapse
class AccountV1: …
data: Data
id: str

Unique identifier for the account.

formatuuid
access_level: Literal["standard", "managed"]

The access level granted to the account. This is determined by your platform configuration. Use standard unless instructed otherwise by Straddle.

Accepts one of the following:
"standard"
"managed"
organization_id: str

The unique identifier of the organization this account belongs to.

formatuuid
status: Literal["created", "onboarding", "active", 2 more]

The current status of the account (e.g., 'active', 'inactive', 'pending').

Accepts one of the following:
"created"
"onboarding"
"active"
"rejected"
"inactive"
status_detail: DataStatusDetail
code: str

A machine-readable code for the specific status, useful for programmatic handling.

message: str

A human-readable message describing the current status.

reason: Literal["unverified", "in_review", "pending", 6 more]

A machine-readable identifier for the specific status, useful for programmatic handling.

Accepts one of the following:
"unverified"
"in_review"
"pending"
"stuck"
"verified"
"failed_verification"
"disabled"
"terminated"
"new"
source: Literal["watchtower"]

Identifies the origin of the status change (e.g., bank_decline, watchtower). This helps in tracking the cause of status updates.

Accepts one of the following:
"watchtower"
type: Literal["business"]

The type of account (e.g., 'individual', 'business').

Accepts one of the following:
"business"
business_profile: Optional[BusinessProfileV1]
name: str

The operating or trade name of the business.

website: str

URL of the business's primary marketing website.

formaturi
address: Optional[AddressV1]

The address object is optional. If provided, it must be a valid address.

address1: str

Primary address line (e.g., street, PO Box).

city: Optional[str]

City, district, suburb, town, or village.

state: Optional[str]

Two-letter state code.

zip: str

Zip or postal code.

address2: Optional[str]

Secondary address line (e.g., apartment, suite, unit, or building).

country: Optional[str]

The country of the address, in ISO 3166-1 alpha-2 format.

line1: Optional[str]

Primary address line (e.g., street, PO Box).

line2: Optional[str]

Secondary address line (e.g., apartment, suite, unit, or building).

postal_code: Optional[str]

Postal or ZIP code.

description: Optional[str]

A brief description of the business and its products or services.

industry: Optional[IndustryV1]
category: Optional[str]

The general category of the industry. Required if not providing MCC.

mcc: Optional[str]

The Merchant Category Code (MCC) that best describes the business. Optional.

sector: Optional[str]

The specific sector within the industry category. Required if not providing MCC.

The official registered name of the business.

phone: Optional[str]

The primary contact phone number for the business.

support_channels: Optional[SupportChannelsV1]
email: Optional[str]

The email address for customer support inquiries.

formatemail
phone: Optional[str]

The phone number for customer support.

url: Optional[str]

The URL of the business's customer support page or contact form.

formaturi
tax_id: Optional[str]

The business's tax identification number (e.g., EIN in the US).

use_case: Optional[str]

A description of how the business intends to use Straddle's services.

capabilities: Optional[DataCapabilities]

Whether the internet payment authorization capability is enabled for the account.

Accepts one of the following:

Whether the signed agreement payment authorization capability is enabled for the account.

Accepts one of the following:
customer_types: DataCapabilitiesCustomerTypes
businesses: CapabilityV1
capability_status: Literal["active", "inactive"]
Accepts one of the following:
"active"
"inactive"
individuals: CapabilityV1
capability_status: Literal["active", "inactive"]
Accepts one of the following:
"active"
"inactive"
payment_types: DataCapabilitiesPaymentTypes
charges: CapabilityV1
capability_status: Literal["active", "inactive"]
Accepts one of the following:
"active"
"inactive"
payouts: CapabilityV1
capability_status: Literal["active", "inactive"]
Accepts one of the following:
"active"
"inactive"
created_at: Optional[datetime]

Timestamp of when the account was created.

formatdate-time
external_id: Optional[str]

Unique identifier for the account in your database, used for cross-referencing between Straddle and your systems.

metadata: Optional[Dict[str, Optional[str]]]

Up to 20 additional user-defined key-value pairs. Useful for storing additional information about the account in a structured format.

settings: Optional[DataSettings]
charges: DataSettingsCharges
daily_amount: int

The maximum dollar amount of charges in a calendar day.

formatint32
funding_time: Literal["immediate", "next_day", "one_day", 2 more]

The amount of time it takes for a charge to be funded. This value is defined by Straddle.

Accepts one of the following:
"immediate"
"next_day"
"one_day"
"two_day"
"three_day"
linked_bank_account_id: str

The unique identifier of the linked bank account associated with charges. This value is defined by Straddle.

formatuuid
max_amount: int

The maximum amount of a single charge.

formatint32
monthly_amount: int

The maximum dollar amount of charges in a calendar month.

formatint32
monthly_count: int

The maximum number of charges in a calendar month.

formatint32
payouts: DataSettingsPayouts
daily_amount: int

The maximum dollar amount of payouts in a day.

formatint32
funding_time: Literal["immediate", "next_day", "one_day", 2 more]

The amount of time it takes for a payout to be funded. This value is defined by Straddle.

Accepts one of the following:
"immediate"
"next_day"
"one_day"
"two_day"
"three_day"
linked_bank_account_id: str

The unique identifier of the linked bank account to use for payouts.

formatuuid
max_amount: int

The maximum amount of a single payout.

formatint32
monthly_amount: int

The maximum dollar amount of payouts in a month.

formatint32
monthly_count: int

The maximum number of payouts in a month.

formatint32
terms_of_service: Optional[TermsOfServiceV1]
accepted_date: datetime

The datetime of when the terms of service were accepted, in ISO 8601 format.

formatdate-time
agreement_type: Literal["embedded", "direct"]

The type or version of the agreement accepted. Use embedded unless your platform was specifically enabled for direct agreements.

Accepts one of the following:
"embedded"
"direct"
agreement_url: Optional[str]

The URL where the full text of the accepted agreement can be found.

accepted_ip: Optional[str]

The IP address from which the terms of service were accepted.

accepted_user_agent: Optional[str]

The user agent string of the browser or application used to accept the terms.

updated_at: Optional[datetime]

Timestamp of the most recent update to the account.

formatdate-time

Metadata about the API request, including an identifier and timestamp.

api_request_id: str

Unique identifier for this API request, useful for troubleshooting.

formatuuid
api_request_timestamp: datetime

Timestamp for this API request, useful for troubleshooting.

formatdate-time
response_type: Literal["object", "array", "error", "none"]

Indicates the structure of the returned content.

  • "object" means the data field contains a single JSON object.
  • "array" means the data field contains an array of objects.
  • "error" means the data field contains an error object with details of the issue.
  • "none" means no data is returned.
Accepts one of the following:
"object"
"array"
"error"
"none"
Onboard an account
  • HTTP
  • TypeScript
  • Python
  • Ruby
from datetime import datetime
from straddle import Straddle

client = Straddle(
    api_key="My API Key",
)
account_v1 = client.embed.accounts.onboard(
    account_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    terms_of_service={
        "accepted_date": datetime.fromisoformat("2019-12-27T18:11:19.117"),
        "agreement_type": "embedded",
        "agreement_url": "agreement_url",
    },
)
print(account_v1.data)
{
  "data": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "access_level": "standard",
    "organization_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "status": "created",
    "status_detail": {
      "code": "code",
      "message": "message",
      "reason": "unverified",
      "source": "watchtower"
    },
    "type": "business",
    "business_profile": {
      "name": "name",
      "website": "https://example.com",
      "address": {
        "address1": "address1",
        "city": "city",
        "state": "SE",
        "zip": "zip",
        "address2": "address2",
        "country": "country",
        "line1": "line1",
        "line2": "line2",
        "postal_code": "21029-1360"
      },
      "description": "description",
      "industry": {
        "category": "category",
        "mcc": "mcc",
        "sector": "sector"
      },
      "legal_name": "legal_name",
      "phone": "+46991022",
      "support_channels": {
        "email": "dev@stainless.com",
        "phone": "+46991022",
        "url": "https://example.com"
      },
      "tax_id": "210297980",
      "use_case": "use_case"
    },
    "capabilities": {
      "consent_types": {
        "internet": {
          "capability_status": "active"
        },
        "signed_agreement": {
          "capability_status": "active"
        }
      },
      "customer_types": {
        "businesses": {
          "capability_status": "active"
        },
        "individuals": {
          "capability_status": "active"
        }
      },
      "payment_types": {
        "charges": {
          "capability_status": "active"
        },
        "payouts": {
          "capability_status": "active"
        }
      }
    },
    "created_at": "2019-12-27T18:11:19.117Z",
    "external_id": "external_id",
    "metadata": {
      "foo": "string"
    },
    "settings": {
      "charges": {
        "daily_amount": 0,
        "funding_time": "immediate",
        "linked_bank_account_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "max_amount": 0,
        "monthly_amount": 0,
        "monthly_count": 0
      },
      "payouts": {
        "daily_amount": 0,
        "funding_time": "immediate",
        "linked_bank_account_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "max_amount": 0,
        "monthly_amount": 0,
        "monthly_count": 0
      }
    },
    "terms_of_service": {
      "accepted_date": "2019-12-27T18:11:19.117Z",
      "agreement_type": "embedded",
      "agreement_url": "agreement_url",
      "accepted_ip": "accepted_ip",
      "accepted_user_agent": "accepted_user_agent"
    },
    "updated_at": "2019-12-27T18:11:19.117Z"
  },
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z"
  },
  "response_type": "object"
}
Returns Examples
{
  "data": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "access_level": "standard",
    "organization_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "status": "created",
    "status_detail": {
      "code": "code",
      "message": "message",
      "reason": "unverified",
      "source": "watchtower"
    },
    "type": "business",
    "business_profile": {
      "name": "name",
      "website": "https://example.com",
      "address": {
        "address1": "address1",
        "city": "city",
        "state": "SE",
        "zip": "zip",
        "address2": "address2",
        "country": "country",
        "line1": "line1",
        "line2": "line2",
        "postal_code": "21029-1360"
      },
      "description": "description",
      "industry": {
        "category": "category",
        "mcc": "mcc",
        "sector": "sector"
      },
      "legal_name": "legal_name",
      "phone": "+46991022",
      "support_channels": {
        "email": "dev@stainless.com",
        "phone": "+46991022",
        "url": "https://example.com"
      },
      "tax_id": "210297980",
      "use_case": "use_case"
    },
    "capabilities": {
      "consent_types": {
        "internet": {
          "capability_status": "active"
        },
        "signed_agreement": {
          "capability_status": "active"
        }
      },
      "customer_types": {
        "businesses": {
          "capability_status": "active"
        },
        "individuals": {
          "capability_status": "active"
        }
      },
      "payment_types": {
        "charges": {
          "capability_status": "active"
        },
        "payouts": {
          "capability_status": "active"
        }
      }
    },
    "created_at": "2019-12-27T18:11:19.117Z",
    "external_id": "external_id",
    "metadata": {
      "foo": "string"
    },
    "settings": {
      "charges": {
        "daily_amount": 0,
        "funding_time": "immediate",
        "linked_bank_account_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "max_amount": 0,
        "monthly_amount": 0,
        "monthly_count": 0
      },
      "payouts": {
        "daily_amount": 0,
        "funding_time": "immediate",
        "linked_bank_account_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "max_amount": 0,
        "monthly_amount": 0,
        "monthly_count": 0
      }
    },
    "terms_of_service": {
      "accepted_date": "2019-12-27T18:11:19.117Z",
      "agreement_type": "embedded",
      "agreement_url": "agreement_url",
      "accepted_ip": "accepted_ip",
      "accepted_user_agent": "accepted_user_agent"
    },
    "updated_at": "2019-12-27T18:11:19.117Z"
  },
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z"
  },
  "response_type": "object"
}