> ## Documentation Index
> Fetch the complete documentation index at: https://docs.straddle.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Manage embedded platform accounts
> Create, update, and manage embedded business accounts for your platform users in Straddle, including verification status, capabilities, and settings.
Accounts are the foundation of an interaction with Straddle. Each account represents a distinct business entity that has entered into a contractual relationship with Straddle to utilize our payment services. Understanding how to work with accounts is crucial for leveraging Straddle's full potential.
## Understanding Accounts
An account in Straddle is a comprehensive representation of a business entity with the following key aspects:
1. **Legal Entity**: Each account corresponds to a specific legal business entity.
2. **Immediate Sandbox Access**: Upon creation, accounts can instantly access the Straddle API Sandbox.
3. **Production Readiness**: To activate production access, accounts need to complete an automated onboarding process.
4. **Customizable**: Accounts can be tailored with specific capabilities, settings, and metadata.
5. **Hierarchical**: Accounts can be organized under parent Organizations for streamlined management.
As a platform integrating with Straddle, you have the unique ability to create and manage accounts on behalf of your clients. This process involves several key steps to ensure a smooth onboarding experience for your clients and compliance with Straddle's requirements.
## Step-by-Step Account Creation and Onboarding Process
Always create an Organization before creating an Account.
Use the Create Account endpoint to establish the initial account record for your client. This step sets up the basic structure of the account in Straddle's system
After creating the account, you need to add several related objects to complete the account profile:
Use the Create Representative endpoint to add individuals who have legal authority or significant responsibility within the business. At least one representative is required.
Use the Create Linked Bank Account endpoint to associate your client's bank account with their Straddle account. This is necessary for processing payments and payouts.
Use the Request Capabilities endpoint to specify which Straddle features your client needs (e.g., accepting payments, making payouts).
Once all required information and related objects are in place, use the Onboard Account endpoint to start the formal onboarding process. This triggers Straddle's compliance checks and moves the account towards production readiness
Be sure to capture the [Payment Services Agreement](https://legal.straddle.com) consent data prior to calling the [onboarding](/api-reference/accounts/onboard) endpoint. You must be able to reproduce the agreement consent as requested by Straddle.
### Key Considerations
Ensure you collect and provide accurate, up-to-date information from your clients. This is crucial for successful onboarding and ongoing compliance.
Consider implementing a step-by-step process in your platform to collect information from clients gradually, aligning with Straddle's account creation and onboarding flow.
Implement robust error handling in your integration. Ensure your system can gracefully handle and communicate these errors.
Enable webhooks to track the status of your accounts to ensure your integration always stays in sync
## Best Practices
While you can automate much of the account creation and onboarding process, always provide a way for human intervention when needed.
Offer clear instructions and possibly a guided workflow in your platform UI to help clients understand what information they need to provide and why.
Use Straddle's webhook functionality to receive real-time updates about account status changes, allowing you to promptly respond to any issues or next steps.
Ensure all sensitive client data is handled securely, both in transit and at rest. Implement proper encryption and access controls in your platform.
Be prepared to offer support to your clients throughout the onboarding process. Consider providing FAQs, live chat, or direct support for complex issues.
By following these guidelines and best practices, you can create a smooth, efficient process for creating and onboarding client accounts through your platform. This not only enhances your clients' experience but also helps ensure compliance and reduces potential delays in getting accounts production-ready.
## Creating an Account
Use the Create Account endpoint to set up a new account in Straddle.
You must create an Organization before you can create an Account.
### Attributes
When creating an account, you can specify the following attributes:
| Field | Type | Description |
| ----------------------------------------- | ------ | --------------------------------------------------------------------------- |
| organization\_id | string | The unique identifier of the organization this account belongs to. |
| account\_type | string | The type of account. Currently, only 'business' is supported. |
| business\_profile | object | Detailed information about the business associated with this account. |
| business\_profile.name | string | The operating or trade name of the business. |
| business\_profile.website | string | URL of the business's primary marketing website. |
| business\_profile.legal\_name | string | The official registered name of the business. |
| business\_profile.description | string | A brief description of the business and its products or services. |
| business\_profile.use\_case | string | A description of how the business intends to use Straddle's services. |
| business\_profile.tax\_id | string | The business's tax identification number (e.g., EIN in the US). |
| business\_profile.phone | string | The primary contact phone number for the business. |
| business\_profile.address | object | The primary address of the business. |
| business\_profile.address.line1 | string | Primary address line (e.g., street, PO Box). |
| business\_profile.address.line2 | string | Secondary address line (e.g., apartment, suite, unit, or building). |
| business\_profile.address.city | string | City, district, suburb, town, or village. |
| business\_profile.address.state | string | Two-letter state code. |
| business\_profile.address.postal\_code | string | Postal or ZIP code. |
| business\_profile.address.country | string | The country of the address, in ISO 3166-1 alpha-2 format. |
| business\_profile.industry | object | Information about the business's industry. |
| business\_profile.industry.mcc | string | The Merchant Category Code (MCC) that best describes the business. |
| business\_profile.industry.sector | string | The specific sector within the industry category. |
| business\_profile.industry.category | string | The general category of the industry. |
| business\_profile.support\_channels | object | Contact information for customer support. |
| business\_profile.support\_channels.email | string | The email address for customer support inquiries. |
| business\_profile.support\_channels.phone | string | The phone number for customer support. |
| business\_profile.support\_channels.url | string | The URL of the business's customer support page or contact form. |
| access\_level | string | The desired access level for the account. Can be 'standard' or 'managed'. |
| metadata | object | Additional key-value pairs for storing extra information about the account. |
| external\_id | string | Your own unique identifier for the account, useful for cross-referencing. |
### Example Request
Here's how you might create a new account with all possible fields:
```bash Create Account Request theme={null}
curl https://api.straddle.com/v1/accounts \
-X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"organization_id": "org_12345abcde",
"account_type": "business",
"business_profile": {
"name": "Tech Innovators LLC",
"website": "https://techinnovators.com",
"legal_name": "Tech Innovators Limited Liability Company",
"description": "Cutting-edge software solutions for businesses",
"use_case": "Providing SaaS products and accepting online payments",
"tax_id": "12-3456789",
"phone": "+1 (555) 123-4567",
"address": {
"line1": "123 Innovation Drive",
"line2": "Suite 200",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
},
"industry": {
"mcc": "5734",
"sector": "Technology",
"category": "Software"
},
"support_channels": {
"email": "support@techinnovators.com",
"phone": "+1 (555) 987-6543",
"url": "https://techinnovators.com/support"
}
},
"access_level": "standard",
"metadata": {
"internal_id": "TI2023",
"account_manager": "jane.doe@straddle.com"
},
"external_id": "TechInnovators2023"
}'
```
```javascript theme={null}
const createAccount = async () => {
const res = await fetch('https://api.straddle.com/v1/accounts', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
organization_id: 'org_12345abcde',
account_type: 'business',
business_profile: {
name: 'Tech Innovators LLC',
website: 'https://techinnovators.com',
legal_name: 'Tech Innovators Limited Liability Company',
description: 'Cutting-edge software solutions for businesses',
use_case: 'Providing SaaS products and accepting online payments',
tax_id: '12-3456789',
phone: '+1 (555) 123-4567',
address: {
line1: '123 Innovation Drive',
line2: 'Suite 200',
city: 'San Francisco',
state: 'CA',
postal_code: '94105',
country: 'US'
},
industry: {
mcc: '5734',
sector: 'Technology',
category: 'Software'
},
support_channels: {
email: 'support@techinnovators.com',
phone: '+1 (555) 987-6543',
url: 'https://techinnovators.com/support'
}
},
access_level: 'standard',
metadata: {
internal_id: 'TI2023',
account_manager: 'jane.doe@straddle.com'
},
external_id: 'TechInnovators2023'
})
})
const data = await res.json()
console.log(data)
}
```
### Response
```json Account Created Response theme={null}
{
"id": "acc_12345abcde",
"organization_id": "org_12345abcde",
"account_type": "business",
"business_profile": {
"name": "Tech Innovators LLC",
"website": "https://techinnovators.com",
"legal_name": "Tech Innovators Limited Liability Company",
"description": "Cutting-edge software solutions for businesses",
"use_case": "Providing SaaS products and accepting online payments",
"tax_id": "12-3456789",
"phone": "+1 (555) 123-4567",
"address": {
"line1": "123 Innovation Drive",
"line2": "Suite 200",
"city": "San Francisco",
"state": "CA",
"postal_code": "94105",
"country": "US"
},
"industry": {
"mcc": "5734",
"sector": "Technology",
"category": "Software"
},
"support_channels": {
"email": "support@techinnovators.com",
"phone": "+1 (555) 987-6543",
"url": "https://techinnovators.com/support"
}
},
"capabilities": {
"payment_types": {
"charges": {
"capability_status": "inactive"
},
"payouts": {
"capability_status": "inactive"
}
},
"customer_types": {
"individuals": {
"capability_status": "inactive"
},
"businesses": {
"capability_status": "inactive"
}
},
"consent_types": {
"signed_agreement": {
"capability_status": "inactive"
},
"internet": {
"capability_status": "inactive"
}
}
},
"settings": {
"charges": {},
"payouts": {}
},
"terms_of_service": null,
"metadata": {
"internal_id": "TI2023",
"account_manager": "jane.doe@straddle.com"
},
"access_level": "standard",
"external_id": "TechInnovators2023",
"created_at": "2023-06-15T10:30:00Z",
"updated_at": "2023-06-15T10:30:00Z"
}
```
## Account Onboarding
### Onboard a Straddle Account
After you've created an account, added representatives, and linked a bank account, you'll need to onboard the account to initiate the straddle process. This endpoint handles the final activation step for the account.
### Important: Consent Requirement
Before calling this endpoint, you must obtain the user's consent to the Straddle Terms of Service. The full terms can be found at [legal.straddle.com](https://legal.straddle.com).
### Request
```bash theme={null}
curl --request POST \
--url https://{environment}.straddle.com/v1/accounts/{account_id}/onboard \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"terms_of_service": {
"accepted_date": "2025-03-21T10:30:00Z",
"accepted_ip": "192.168.1.1",
"accepted_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
"agreement_url": null,
"agreement_type": "embedded"
}
}'
```
#### Path Parameters
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ----------------------------------------------- |
| `account_id` | string | Yes | The unique identifier of the account to onboard |
#### Request Body Parameters
| Parameter | Type | Required | Description |
| ------------------ | ------ | -------- | ---------------------------------------------------------------------- |
| `terms_of_service` | object | Yes | Information about the user's acceptance of Straddle's terms of service |
#### terms\_of\_service Object
| Field | Type | Required | Description |
| --------------------- | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accepted_date` | string | Yes | The datetime when the terms of service were accepted, in ISO 8601 format (e.g., "2025-03-21T10:30:00Z") |
| `agreement_type` | enum\ | Yes | The type or version of the agreement accepted. Available options: `embedded`, `direct`. Use `embedded` unless your platform was specifically enabled for `direct` agreements |
| `accepted_ip` | string | No | The IP address from which the terms of service were accepted |
| `accepted_user_agent` | string | No | The user agent string of the browser or application used to accept the terms |
| `agreement_url` | string | Yes | The URL where the full text of the accepted agreement can be found |
### Response
A successful request returns a `200 OK` response with details about the account.
```json theme={null}
{
"meta": {
"api_request_id": "123e4567-e89b-12d3-a456-426614174000",
"api_request_timestamp": "2025-03-21T16:14:51.342Z"
},
"response_type": "object",
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "123e4567-e89b-12d3-a456-426614174000",
"type": "business",
"status": "created",
"status_detail": {
"reason": "unverified",
"source": "watchtower",
"code": "…",
"message": "…"
},
"business_profile": {
"name": "…",
"website": "https://example.com",
"legal_name": null,
"description": null,
"use_case": null,
"tax_id": null,
"phone": null,
"address": {
"line1": null,
"line2": null,
"city": null,
"state": null,
"postal_code": null,
"country": null
},
"industry": {
"mcc": null,
"sector": null,
"category": null
},
"support_channels": {
"email": null,
"phone": null,
"url": null
}
},
"capabilities": {
"payment_types": {
"charges": {
"capability_status": "active"
},
"payouts": {
"capability_status": "active"
}
},
"customer_types": {
"individuals": {
"capability_status": "active"
},
"businesses": {
"capability_status": "active"
}
},
"consent_types": {
"signed_agreement": {
"capability_status": "active"
},
"internet": {
"capability_status": "active"
}
}
},
"settings": {
"charges": {
"max_amount": 1,
"monthly_amount": 1,
"daily_amount": 1,
"monthly_count": 1,
"funding_time": "immediate",
"linked_bank_account_id": "123e4567-e89b-12d3-a456-426614174000"
},
"payouts": {
"max_amount": 1,
"monthly_amount": 1,
"daily_amount": 1,
"monthly_count": 1,
"funding_time": "immediate",
"linked_bank_account_id": "123e4567-e89b-12d3-a456-426614174000"
}
},
"terms_of_service": {
"accepted_date": "2025-03-21T16:14:51.342Z",
"accepted_ip": null,
"accepted_user_agent": null,
"agreement_url": null,
"agreement_type": "embedded"
},
"metadata": null,
"access_level": "standard",
"external_id": null,
"created_at": null,
"updated_at": null
}
}
```
## Account Status
Account statuses in Straddle reflect the current state of an account in its lifecycle. Understanding these statuses is crucial for managing accounts effectively and knowing when certain actions can be performed.
| Status | Description |
| ---------- | ------------------------------------------------------------------- |
| Created | Initial status when an account is first created. |
| Onboarding | The account is going through the onboarding process. |
| Active | The account has completed onboarding and is fully operational. |
| Rejected | The account has failed the onboarding process or compliance checks. |
| Inactive | The account has been temporarily or permanently suspended. |
The account exists but is not yet ready for use.
When to update:
You can update account details, add representatives, and link bank accounts at this stage.
Next step:
Complete the account setup and initiate onboarding.
Additional information may be required during this process.
When to update:
You can still update certain account details if additional information is requested.
Next step:
Wait for the onboarding process to complete. Monitor for any requests for additional information.
When to update:
You can update non-critical information. Major changes may require re-verification.
Next step:
The account can now process transactions and use Straddle's services.
When to update:
Updates are generally not possible in this state. Contact Straddle support for more information.
Next step:
Review the rejection reason in the status\_detail and consider creating a new account if appropriate.
When to update:
Updates are generally not possible in this state. Contact Straddle support for more information.
Next step:
Review the inactivation reason in the status\_detail and work with Straddle support to resolve any issues.
### Understanding status\_detail
The `status_detail` object provides more granular information about the account's current status. It includes the following fields:
A more specific reason for the current status. Possible values include:
unverified
: Initial state, pending verification
in\_review
: Account is being reviewed
pending
: Waiting for additional information
stuck
: Issues in the verification process
verified
: Successfully verified
failed\_verification
: Verification process failed
disabled
: Account has been disabled
terminated
: Account has been permanently closed
Indicates the system or process that set the current status. Currently, this is always "watchtower", Straddle's compliance monitoring system.
A specific code related to the status reason. This can be useful for programmatically handling different status scenarios.
A human-readable message providing more context about the current status.
Always check both the `status` and `status_detail` when handling accounts in your integration. The `status_detail` can provide crucial information for resolving issues or proceeding with account management.
## Next Steps
Once your platform has successfully created an account, you can move forward with the next steps: adding representatives and linking bank accounts. These actions ensure that the account is fully set up to operate and receive funds. Representatives allow you to associate key individuals with the account for compliance purposes, while adding bank accounts enables the platform to facilitate payouts and other financial transactions. Moving through these stages will complete the onboarding process and prepare the account for full functionality on the Straddle platform.