> ## 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.

# Organizations: group multiple accounts

> Use organizations to group related Straddle accounts under a single umbrella for businesses with multiple departments, brands, or legal entities.

Organizations are a powerful feature in Straddle that allow you to manage multiple accounts under a single umbrella. This hierarchical structure is particularly useful for businesses with complex operations, multiple departments, or those managing payments for various clients.

## Understanding Organizations

Think of an organization as the parent entity that can house multiple Straddle accounts. This structure offers several advantages:

1. **Centralized Management**: Oversee all your accounts from a single dashboard.
2. **Streamlined Onboarding**: Easily create new accounts using existing KYC information.
3. **Consolidated Reporting**: Get a holistic view of your business operations across all accounts.
4. **Unified Team Management**: Manage user roles and permissions at the organization level.
5. **Cross-Account Search**: Quickly find information across all your accounts.

## Creating an Organization

To start leveraging the power of organizations, you first need to create one. Use the Create Organization endpoint to set up a new organization in Straddle.

### Attributes

When creating an organization, you can specify the following attributes:

| Field        | Type   | Description                                                                      |
| ------------ | ------ | -------------------------------------------------------------------------------- |
| name         | string | The name of your organization. Choose something recognizable and unique.         |
| metadata     | object | Additional key-value pairs for storing extra information about the organization. |
| external\_id | string | Your own unique identifier for the organization, useful for cross-referencing.   |

### Example Request

Here's how you might create a new organization:

<CodeGroup>
  ```bash theme={null}
  curl https://api.straddle.com/v1/organizations \
    -X POST \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Global Tech Solutions",
      "metadata": {
        "industry": "Information Technology",
        "size": "Enterprise",
        "headquarters": "San Francisco"
      },
      "external_id": "GTS-2023"
    }'
  ```

  ```javascript theme={null}
  async function createOrganization() {
    const res = await fetch('https://api.straddle.com/v1/organizations', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: 'Global Tech Solutions',
        metadata: {
          industry: 'Information Technology',
          size: 'Enterprise',
          headquarters: 'San Francisco'
        },
        external_id: 'GTS-2023'
      })
    })
    const json = await res.json()
    console.log(json)
  }
  ```
</CodeGroup>

### Response

Upon successful creation, Straddle will respond with the details of the newly created organization:

| Field        | Type   | Description                                           |
| ------------ | ------ | ----------------------------------------------------- |
| id           | string | Straddle's unique identifier for the organization.    |
| name         | string | The name you provided for the organization.           |
| external\_id | string | Your provided unique identifier for the organization. |
| metadata     | object | The additional key-value pairs you provided.          |

## Managing Organizations

Once you've created an organization, you can start adding accounts to it, managing team access, and leveraging its capabilities for streamlined operations.

### Listing Organizations

To view all the organizations you've created, use the List Organizations endpoint. This is particularly useful when managing multiple organizations or when you need to retrieve a specific organization's ID.

#### Query Parameters

| Parameter    | Type    | Description                                               |
| ------------ | ------- | --------------------------------------------------------- |
| name         | string  | Filter organizations by name (supports partial matching). |
| external\_id | string  | Filter organizations by their external ID.                |
| page\_number | integer | The page number for paginated results (default: 1).       |
| page\_size   | integer | Number of results per page (default: 100, max: 1000).     |
| sort\_by     | string  | Field to sort by (default: 'id').                         |
| sort\_order  | string  | Sort order: 'asc' or 'desc' (default: 'asc').             |

#### Example Request

Here's how you might list your organizations:

<CodeGroup>
  ```bash theme={null}
  curl https://api.straddle.com/v1/organizations?page_size=5&sort_by=name \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript theme={null}
  async function listOrganizations() {
    const url = new URL('https://api.straddle.com/v1/organizations')
    const res = await fetch('https://api.straddle.com/v1/organizations?page_size=5&sort_by=name', {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    })
    const json = await res.json()
    console.log(json)
  }
  ```
</CodeGroup>

## Best Practices

When working with organizations in Straddle, consider the following best practices:

<AccordionGroup>
  <Accordion title="Meaningful Names">
    Choose clear, descriptive names for your clients' organizations. This will make it easier to manage them as your use of Straddle grows.
  </Accordion>

  <Accordion title="Utilize Metadata">
    Take advantage of the metadata field to store additional information about the organizations. This can be invaluable for internal categorization or integration with other systems.
  </Accordion>

  <Accordion title="Consistent External IDs">
    If you choose to use external IDs, we strongly recommend the usage of UUIDs. This will help maintain clarity when cross-referencing between Straddle and your own systems.
  </Accordion>

  <Accordion title="Regular Audits">
    Periodically review your organizations and their associated accounts. This can help ensure that your Straddle setup continues to align with the business structure.
  </Accordion>
</AccordionGroup>

## Next Steps

Now that you understand how to create and manage organizations, you're ready to start leveraging their power in Straddle. Here are some next steps you might consider:

<CardGroup cols={2}>
  <Card title="Create Accounts" icon="plus-circle" href="/api-reference/accounts/create">
    Start adding accounts to your organization to take full advantage of Straddle's hierarchical structure.
  </Card>

  <Card title="Manage Accounts" icon="users" href="/guides/embed/accounts">
    Learn how to create and manage accounts under your organization for streamlined operations.
  </Card>

  <Card title="Explore Reporting" icon="chart-line" href="/guides/payments/reports">
    Discover how to use Straddle's reporting features to gain insights across all accounts in your organization.
  </Card>

  <Card title="Update Account Details" icon="pen-to-square" href="/api-reference/accounts/update">
    Learn how to keep your account details up-to-date as your business evolves.
  </Card>
</CardGroup>