# Organizations

## Create an organization

`$ straddle embed:organizations create`

**post** `/v1/organizations`

Creates a new organization related to your Straddle integration. Organizations can be used to group related accounts and manage permissions across multiple users.

### Parameters

- `--name: string`

  Body param: The name of the organization.

- `--external-id: optional string`

  Body param: Unique identifier for the organization in your database, used for cross-referencing between Straddle and your systems.

- `--metadata: optional map[string]`

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

- `--correlation-id: optional string`

  Header param: Optional client generated identifier to trace and debug a series of requests.

- `--idempotency-key: optional string`

  Header param: Optional client generated value to use for idempotent requests.

- `--request-id: optional string`

  Header param: Optional client generated identifier to trace and debug a request.

### Returns

- `organizationV1: object { data, meta, response_type }`

  - `data: object { id, created_at, name, 3 more }`

    - `id: string`

      Straddle's unique identifier for the organization.

    - `created_at: string`

      Timestamp of when the organization was created.

    - `name: string`

      The name of the organization.

    - `updated_at: string`

      Timestamp of the most recent update to the organization.

    - `external_id: optional string`

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

    - `metadata: optional map[string]`

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

  - `meta: object { api_request_id, api_request_timestamp }`

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

    - `api_request_id: string`

      Unique identifier for this API request, useful for troubleshooting.

    - `api_request_timestamp: string`

      Timestamp for this API request, useful for troubleshooting.

  - `response_type: "object" or "array" or "error" or "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.

    - `"object"`

    - `"array"`

    - `"error"`

    - `"none"`

### Example

```cli
straddle embed:organizations create \
  --api-key 'My API Key' \
  --name name
```

#### Response

```json
{
  "data": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "created_at": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "external_id": "external_id",
    "metadata": {
      "foo": "string"
    }
  },
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z"
  },
  "response_type": "object"
}
```

## List organizations

`$ straddle embed:organizations list`

**get** `/v1/organizations`

Retrieves a list of organizations associated with your Straddle integration. The organizations are returned sorted by creation date, with the most recently created organizations appearing first. This endpoint supports advanced sorting and filtering options to help you find specific organizations.

### Parameters

- `--external-id: optional string`

  Query param: List organizations by their external ID.

- `--name: optional string`

  Query param: List organizations by name (partial match supported).

- `--page-number: optional number`

  Query param: Results page number. Starts at page 1.

- `--page-size: optional number`

  Query param: Page size. Max value: 1000

- `--sort-by: optional string`

  Query param: Sort By.

- `--sort-order: optional "asc" or "desc"`

  Query param: Sort Order.

- `--correlation-id: optional string`

  Header param: Optional client generated identifier to trace and debug a series of requests.

- `--request-id: optional string`

  Header param: Optional client generated identifier to trace and debug a request.

### Returns

- `organizationPagedV1: object { data, meta, response_type }`

  - `data: array of object { id, created_at, name, 3 more }`

    - `id: string`

      Straddle's unique identifier for the organization.

    - `created_at: string`

      Timestamp of when the organization was created.

    - `name: string`

      The name of the organization.

    - `updated_at: string`

      Timestamp of the most recent update to the organization.

    - `external_id: optional string`

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

    - `metadata: optional map[string]`

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

  - `meta: object { api_request_id, api_request_timestamp, max_page_size, 6 more }`

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

    - `api_request_id: string`

      Unique identifier for this API request, useful for troubleshooting.

    - `api_request_timestamp: string`

      Timestamp for this API request, useful for troubleshooting.

    - `max_page_size: number`

      Maximum allowed page size for this endpoint.

    - `page_number: number`

      Page number for paginated results.

    - `page_size: number`

      Number of items per page in this response.

    - `sort_by: string`

      The field that the results were sorted by.

    - `sort_order: "asc" or "desc"`

      - `"asc"`

      - `"desc"`

    - `total_items: number`

      Total number of items returned in this response.

    - `total_pages: number`

      The number of pages available.

  - `response_type: "object" or "array" or "error" or "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.

    - `"object"`

    - `"array"`

    - `"error"`

    - `"none"`

### Example

```cli
straddle embed:organizations list \
  --api-key 'My API Key'
```

#### Response

```json
{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "created_at": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "external_id": "external_id",
      "metadata": {
        "foo": "string"
      }
    }
  ],
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z",
    "max_page_size": 0,
    "page_number": 0,
    "page_size": 0,
    "sort_by": "sort_by",
    "sort_order": "asc",
    "total_items": 0,
    "total_pages": 0
  },
  "response_type": "object"
}
```

## Retrieve organization details

`$ straddle embed:organizations get`

**get** `/v1/organizations/{organization_id}`

Retrieves the details of an Organization that has previously been created. Supply the unique organization ID that was returned from your previous request, and Straddle will return the corresponding organization information.

### Parameters

- `--organization-id: string`

- `--correlation-id: optional string`

  Optional client generated identifier to trace and debug a series of requests.

- `--request-id: optional string`

  Optional client generated identifier to trace and debug a request.

### Returns

- `organizationV1: object { data, meta, response_type }`

  - `data: object { id, created_at, name, 3 more }`

    - `id: string`

      Straddle's unique identifier for the organization.

    - `created_at: string`

      Timestamp of when the organization was created.

    - `name: string`

      The name of the organization.

    - `updated_at: string`

      Timestamp of the most recent update to the organization.

    - `external_id: optional string`

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

    - `metadata: optional map[string]`

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

  - `meta: object { api_request_id, api_request_timestamp }`

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

    - `api_request_id: string`

      Unique identifier for this API request, useful for troubleshooting.

    - `api_request_timestamp: string`

      Timestamp for this API request, useful for troubleshooting.

  - `response_type: "object" or "array" or "error" or "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.

    - `"object"`

    - `"array"`

    - `"error"`

    - `"none"`

### Example

```cli
straddle embed:organizations get \
  --api-key 'My API Key' \
  --organization-id 182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e
```

#### Response

```json
{
  "data": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "created_at": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "updated_at": "2019-12-27T18:11:19.117Z",
    "external_id": "external_id",
    "metadata": {
      "foo": "string"
    }
  },
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z"
  },
  "response_type": "object"
}
```

## Domain Types

### Organization Paged V1

- `organizationPagedV1: object { data, meta, response_type }`

  - `data: array of object { id, created_at, name, 3 more }`

    - `id: string`

      Straddle's unique identifier for the organization.

    - `created_at: string`

      Timestamp of when the organization was created.

    - `name: string`

      The name of the organization.

    - `updated_at: string`

      Timestamp of the most recent update to the organization.

    - `external_id: optional string`

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

    - `metadata: optional map[string]`

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

  - `meta: object { api_request_id, api_request_timestamp, max_page_size, 6 more }`

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

    - `api_request_id: string`

      Unique identifier for this API request, useful for troubleshooting.

    - `api_request_timestamp: string`

      Timestamp for this API request, useful for troubleshooting.

    - `max_page_size: number`

      Maximum allowed page size for this endpoint.

    - `page_number: number`

      Page number for paginated results.

    - `page_size: number`

      Number of items per page in this response.

    - `sort_by: string`

      The field that the results were sorted by.

    - `sort_order: "asc" or "desc"`

      - `"asc"`

      - `"desc"`

    - `total_items: number`

      Total number of items returned in this response.

    - `total_pages: number`

      The number of pages available.

  - `response_type: "object" or "array" or "error" or "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.

    - `"object"`

    - `"array"`

    - `"error"`

    - `"none"`

### Organization V1

- `organizationV1: object { data, meta, response_type }`

  - `data: object { id, created_at, name, 3 more }`

    - `id: string`

      Straddle's unique identifier for the organization.

    - `created_at: string`

      Timestamp of when the organization was created.

    - `name: string`

      The name of the organization.

    - `updated_at: string`

      Timestamp of the most recent update to the organization.

    - `external_id: optional string`

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

    - `metadata: optional map[string]`

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

  - `meta: object { api_request_id, api_request_timestamp }`

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

    - `api_request_id: string`

      Unique identifier for this API request, useful for troubleshooting.

    - `api_request_timestamp: string`

      Timestamp for this API request, useful for troubleshooting.

  - `response_type: "object" or "array" or "error" or "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.

    - `"object"`

    - `"array"`

    - `"error"`

    - `"none"`