Organizations: group multiple accounts

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:

Centralized Management: Oversee all your accounts from a single dashboard.
Streamlined Onboarding: Easily create new accounts using existing KYC information.
Consolidated Reporting: Get a holistic view of your business operations across all accounts.
Unified Team Management: Manage user roles and permissions at the organization level.
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:

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"
  }'

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)
}

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:

curl https://api.straddle.com/v1/organizations?page_size=5&sort_by=name \
  -H "Authorization: Bearer YOUR_API_KEY"

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)
}

Best Practices

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

Meaningful Names

Choose clear, descriptive names for your clients’ organizations. This will make it easier to manage them as your use of Straddle grows.

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.

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.

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.

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:

Create Accounts

Start adding accounts to your organization to take full advantage of Straddle’s hierarchical structure.

Manage Accounts

Learn how to create and manage accounts under your organization for streamlined operations.

Explore Reporting

Discover how to use Straddle’s reporting features to gain insights across all accounts in your organization.

Update Account Details

Learn how to keep your account details up-to-date as your business evolves.

Get Started

Identity

Bridge

Payments

Embed

Resources

Organizations: group multiple accounts

Understanding Organizations

Creating an Organization

Attributes

Example Request

Response

Managing Organizations

Listing Organizations

Query Parameters

Example Request

Best Practices

Next Steps

Create Accounts

Manage Accounts

Explore Reporting

Update Account Details

​Understanding Organizations

​Creating an Organization

​Attributes

​Example Request

​Response

​Managing Organizations

​Listing Organizations

​Query Parameters

​Example Request

​Best Practices

​Next Steps

Create Accounts

Manage Accounts

Explore Reporting

Update Account Details

Understanding Organizations

Creating an Organization

Attributes

Example Request

Response

Managing Organizations

Listing Organizations

Query Parameters

Example Request

Best Practices

Next Steps