Organizations

Organizations are the foundation of Crane Ledger's multi-tenant architecture. Each organization represents a separate business entity with its own chart of accounts, transactions, and financial data. Organizations can be structured hierarchically, allowing for complex business relationships like parent companies and subsidiaries.

The Organization Object

GET/organizations/:organization_id

Auth required

An organization contains all financial data for a business entity.

{
  "id": "org_xxxxxxxxxxxxxxxx",
  "object": "organization",
  "name": "Acme Corporation",
  "domain": "acme.com",
  "tax_number": "US123456789",
  "fiscal_year_start": 1,
  "base_currency": {
    "code": "USD",
    "name": "US Dollar",
    "symbol": "$",
    "decimal_places": 2
  },
  "is_root": true,
  "parent_organization_id": null,
  "stripe_customer_id": "cus_xxxxxxxxxxxxxxxx",
  "stripe_subscription_id": "sub_xxxxxxxxxxxxxxxx",
  "stripe_meter_id": "mtr_xxxxxxxxxxxxxxxx",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:22:00Z",
  "metadata": {
    "industry": "technology",
    "employee_count": "50-100"
  }
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier with `org_` prefix
`name`	string	Organization display name
`domain`	string	Custom domain for organization
`tax_number`	string	Tax/VAT registration number
`fiscal_year_start`	integer	Fiscal year start month (1-12)
`base_currency`	object	Default currency with full metadata
`is_root`	boolean	Whether this is a root organization
`parent_organization_id`	string	Parent organization ID for hierarchy
`stripe_customer_id`	string	Stripe customer identifier
`stripe_subscription_id`	string	Stripe subscription identifier
`stripe_meter_id`	string	Stripe usage meter identifier
`metadata`	object	Additional organization data

Create Master Account

POST/accounts/master

Auth required

10 credits

Creates a new root organization (master account) for a user. This is typically the first API call a new user makes after signing up.

Request Body

Parameter	Type	Required	Description
`organization_name`	string	Yes	Name of the organization
`user_github_id`	string	Yes	GitHub user ID
`user_email`	string	Yes	User email address
`base_currency_code`	string	No	ISO currency code (default: "USD")
`domain`	string	No	Custom domain
`tax_number`	string	No	Tax/VAT registration number
`fiscal_year_start`	integer	No	Fiscal year start month (1-12, default: 1)

Response

{
  "id": "org_xxxxxxxxxxxxxxxx",
  "object": "organization",
  "name": "Acme Corporation",
  "domain": "acme.com",
  "tax_number": "US123456789",
  "fiscal_year_start": 1,
  "base_currency": {
    "code": "USD",
    "name": "US Dollar",
    "symbol": "$",
    "decimal_places": 2
  },
  "is_root": true,
  "parent_organization_id": null,
  "stripe_customer_id": "cus_xxxxxxxxxxxxxxxx",
  "stripe_subscription_id": null,
  "stripe_meter_id": "mtr_xxxxxxxxxxxxxxxx",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "metadata": {}
}

Create Sub-Organization

POST/accounts/sub

Auth required

8 credits

Creates a new sub-organization under an existing parent organization. All sub-organizations use shared billing with the master organization.

Request Body

Parameter	Type	Required	Description
`parent_organization_id`	string	Yes	ID of the parent organization
`organization_name`	string	Yes	Name of the sub-organization
`relationship_type`	string	Yes	"owned" (shared data) or "linked" (isolated data)
`billing_type`	string	Yes	Must be "shared" - all sub-organizations use the master organization's credit pool
`base_currency_code`	string	No	ISO currency code (inherits from parent if not specified)
`domain`	string	No	Custom domain
`tax_number`	string	No	Tax/VAT registration number
`fiscal_year_start`	integer	No	Fiscal year start month (inherits from parent if not specified)

Response

{
  "id": "org_yyyyyyyyyyyyyyyy",
  "object": "organization",
  "name": "Acme Europe GmbH",
  "domain": "acme.eu",
  "tax_number": "DE123456789",
  "fiscal_year_start": 1,
  "base_currency": {
    "code": "EUR",
    "name": "Euro",
    "symbol": "€",
    "decimal_places": 2
  },
  "is_root": false,
  "parent_organization_id": "org_xxxxxxxxxxxxxxxx",
  "stripe_customer_id": null,
  "stripe_subscription_id": null,
  "stripe_meter_id": null,
  "relationship_type": "owned",
  "billing_type": "shared",
  "created_at": "2024-01-15T11:00:00Z",
  "updated_at": "2024-01-15T11:00:00Z",
  "metadata": {}
}

List User Organizations

GET/organizations

Auth required

Returns a list of all organizations the authenticated user has access to, including their own organizations and any sub-organizations they can access.

Response

[
  {
    "id": "org_xxxxxxxxxxxxxxxx",
    "name": "Acme Corporation",
    "is_root": true,
    "parent_organization_id": null,
    "base_currency": {
      "code": "USD",
      "name": "US Dollar",
      "symbol": "$",
      "decimal_places": 2
    },
    "created_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": "org_yyyyyyyyyyyyyyyy",
    "name": "Acme Europe GmbH",
    "is_root": false,
    "parent_organization_id": "org_xxxxxxxxxxxxxxxx",
    "base_currency": {
      "code": "EUR",
      "name": "Euro",
      "symbol": "€",
      "decimal_places": 2
    },
    "created_at": "2024-01-15T11:00:00Z"
  }
]

Get Organization

GET/organizations/:organization_id

Auth required

Retrieves detailed information about a specific organization. The user must have access to the organization.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The ID of the organization to retrieve

Response

{
  "id": "org_xxxxxxxxxxxxxxxx",
  "name": "Acme Corporation",
  "domain": "acme.com",
  "tax_number": "US123456789",
  "fiscal_year_start": 1,
  "base_currency": {
    "code": "USD",
    "name": "US Dollar",
    "symbol": "$",
    "decimal_places": 2
  },
  "is_root": true,
  "parent_organization_id": null,
  "stripe_customer_id": "cus_xxxxxxxxxxxxxxxx",
  "stripe_subscription_id": "sub_xxxxxxxxxxxxxxxx",
  "stripe_meter_id": "mtr_xxxxxxxxxxxxxxxx",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:22:00Z",
  "metadata": {
    "industry": "technology",
    "employee_count": "50-100"
  }
}

Update Organization

PUT/organizations/:organization_id

Auth required

1 credits

Updates an organization's information and settings. Some fields like is_root and parent_organization_id cannot be modified after creation.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The ID of the organization to update

Request Body

Parameter	Type	Required	Description
`name`	string	No	Organization display name
`domain`	string	No	Custom domain
`tax_number`	string	No	Tax/VAT registration number
`fiscal_year_start`	integer	No	Fiscal year start month (1-12)
`metadata`	object	No	Additional organization data

Response

Returns the updated organization object with the same structure as the GET response.

Get Organization Billing Info

GET/organizations/:organization_id/billing

Auth required

Retrieves Stripe billing information for an organization, including customer ID, subscription details, and usage meter information.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The ID of the organization

Response

{
  "organization_id": "org_xxxxxxxxxxxxxxxx",
  "stripe_customer_id": "cus_xxxxxxxxxxxxxxxx",
  "stripe_subscription_id": "sub_xxxxxxxxxxxxxxxx",
  "stripe_meter_id": "mtr_xxxxxxxxxxxxxxxx",
  "credits_remaining": 850,
  "credits_total": 1000,
  "billing_email": "billing@acme.com",
  "has_billing_setup": true,
  "subscription_status": "active",
  "current_period_start": "2024-01-01T00:00:00Z",
  "current_period_end": "2024-02-01T00:00:00Z"
}

Get Billing Organization

GET/organizations/:organization_id/billing-organization

Auth required

For sub-organizations, this returns the root organization that handles billing. For root organizations, it returns the organization itself.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The ID of the organization

Response

{
  "id": "org_xxxxxxxxxxxxxxxx",
  "name": "Acme Corporation",
  "is_root": true,
  "base_currency": {
    "code": "USD",
    "name": "US Dollar",
    "symbol": "$",
    "decimal_places": 2
  },
  "stripe_customer_id": "cus_xxxxxxxxxxxxxxxx",
  "stripe_subscription_id": "sub_xxxxxxxxxxxxxxxx",
  "stripe_meter_id": "mtr_xxxxxxxxxxxxxxxx",
  "has_billing_setup": true
}

Get Consolidated Reporting Organizations

GET/organizations/:organization_id/consolidated-reporting

Auth required

Returns a list of organizations that can share financial data with the specified organization for consolidated reporting purposes.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The ID of the organization

Response

[
  {
    "id": "org_xxxxxxxxxxxxxxxx",
    "name": "Acme Corporation",
    "is_root": true,
    "base_currency": {
      "code": "USD",
      "name": "US Dollar",
      "symbol": "$",
      "decimal_places": 2
    },
    "created_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": "org_yyyyyyyyyyyyyyyy",
    "name": "Acme Europe GmbH",
    "is_root": false,
    "base_currency": {
      "code": "EUR",
      "name": "Euro",
      "symbol": "€",
      "decimal_places": 2
    },
    "created_at": "2024-01-15T11:00:00Z"
  },
  {
    "id": "org_zzzzzzzzzzzzzzzz",
    "name": "Acme Asia Ltd",
    "is_root": false,
    "base_currency": {
      "code": "SGD",
      "name": "Singapore Dollar",
      "symbol": "S$",
      "decimal_places": 2
    },
    "created_at": "2024-01-15T12:00:00Z"
  }
]

GET/organizations/can-share-data/:org1_id/:org2_id

Auth required

Determines whether two organizations can share financial data based on their hierarchical relationship and data sharing policies.

Path Parameters

Parameter	Type	Required	Description
`org1_id`	string	Yes	First organization ID
`org2_id`	string	Yes	Second organization ID

Response

{
  "organization1_id": "org_xxxxxxxxxxxxxxxx",
  "organization2_id": "org_yyyyyyyyyyyyyyyy",
  "can_share_data": true,
  "description": "Organizations can share data for consolidated reporting"
}

Data Sharing Rules

Organizations can share data if they are in the same hierarchy (parent-child relationship) and have "owned" relationship type. Organizations with "linked" relationship type maintain isolated data.

Need help?

Create a free account to access our support portal. Once signed in, use the Support tab in your dashboard to submit a support ticket — our team typically responds within 24 hours.

✨ For LLMs/AI assistants: Read our structured API reference

Organizations

The Organization Object

Attributes

Create Master Account

Request Body

Response

Create Sub-Organization

Request Body

Response

List User Organizations

Response

Get Organization

Path Parameters

Response

Update Organization

Path Parameters

Request Body

Response

Get Organization Billing Info

Path Parameters

Response

Get Billing Organization

Path Parameters

Response

Get Consolidated Reporting Organizations

Path Parameters

Response

Check Data Sharing

Path Parameters

Response

Data Sharing Rules

Need help?