# Organizations

## Create an organization

`embed.organizations.create(**kwargs) -> OrganizationV1`

**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`

  The name of the organization.

- `external_id: String`

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

- `metadata: Hash[Symbol, String]`

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

- `correlation_id: String`

- `idempotency_key: String`

- `request_id: String`

### Returns

- `class OrganizationV1`

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

    - `id: String`

      Straddle's unique identifier for the organization.

    - `created_at: Time`

      Timestamp of when the organization was created.

    - `name: String`

      The name of the organization.

    - `updated_at: Time`

      Timestamp of the most recent update to the organization.

    - `external_id: String`

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

    - `metadata: Hash[Symbol, String]`

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

  - `meta: ResponseMetadata`

    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: Time`

      Timestamp for this API request, useful for troubleshooting.

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

```ruby
require "straddle"

straddle = Straddle::Client.new(
  api_key: "My API Key",
  environment: "production" # defaults to "sandbox"
)

organization_v1 = straddle.embed.organizations.create(name: "name")

puts(organization_v1)
```

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

`embed.organizations.list(**kwargs) -> PageNumberSchema<{ id, created_at, name, 3 more}>`

**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: String`

  List organizations by their external ID.

- `name: String`

  List organizations by name (partial match supported).

- `page_number: Integer`

  Results page number. Starts at page 1.

- `page_size: Integer`

  Page size. Max value: 1000

- `sort_by: String`

  Sort By.

- `sort_order: :asc | :desc`

  Sort Order.

  - `:asc`

  - `:desc`

- `correlation_id: String`

- `request_id: String`

### Returns

- `{ id, created_at, name, 3 more}`

  - `id: String`

    Straddle's unique identifier for the organization.

  - `created_at: Time`

    Timestamp of when the organization was created.

  - `name: String`

    The name of the organization.

  - `updated_at: Time`

    Timestamp of the most recent update to the organization.

  - `external_id: String`

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

  - `metadata: Hash[Symbol, String]`

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

### Example

```ruby
require "straddle"

straddle = Straddle::Client.new(
  api_key: "My API Key",
  environment: "production" # defaults to "sandbox"
)

page = straddle.embed.organizations.list

puts(page)
```

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

`embed.organizations.get(organization_id, **kwargs) -> OrganizationV1`

**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: String`

- `request_id: String`

### Returns

- `class OrganizationV1`

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

    - `id: String`

      Straddle's unique identifier for the organization.

    - `created_at: Time`

      Timestamp of when the organization was created.

    - `name: String`

      The name of the organization.

    - `updated_at: Time`

      Timestamp of the most recent update to the organization.

    - `external_id: String`

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

    - `metadata: Hash[Symbol, String]`

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

  - `meta: ResponseMetadata`

    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: Time`

      Timestamp for this API request, useful for troubleshooting.

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

```ruby
require "straddle"

straddle = Straddle::Client.new(
  api_key: "My API Key",
  environment: "production" # defaults to "sandbox"
)

organization_v1 = straddle.embed.organizations.get("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")

puts(organization_v1)
```

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

- `class OrganizationPagedV1`

  - `data: Array[{ id, created_at, name, 3 more}]`

    - `id: String`

      Straddle's unique identifier for the organization.

    - `created_at: Time`

      Timestamp of when the organization was created.

    - `name: String`

      The name of the organization.

    - `updated_at: Time`

      Timestamp of the most recent update to the organization.

    - `external_id: String`

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

    - `metadata: Hash[Symbol, String]`

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

  - `meta: PagedResponseMetadata`

    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: Time`

      Timestamp for this API request, useful for troubleshooting.

    - `max_page_size: Integer`

      Maximum allowed page size for this endpoint.

    - `page_number: Integer`

      Page number for paginated results.

    - `page_size: Integer`

      Number of items per page in this response.

    - `sort_by: String`

      The field that the results were sorted by.

    - `sort_order: :asc | :desc`

      - `:asc`

      - `:desc`

    - `total_items: Integer`

      Total number of items returned in this response.

    - `total_pages: Integer`

      The number of pages available.

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

- `class OrganizationV1`

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

    - `id: String`

      Straddle's unique identifier for the organization.

    - `created_at: Time`

      Timestamp of when the organization was created.

    - `name: String`

      The name of the organization.

    - `updated_at: Time`

      Timestamp of the most recent update to the organization.

    - `external_id: String`

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

    - `metadata: Hash[Symbol, String]`

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

  - `meta: ResponseMetadata`

    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: Time`

      Timestamp for this API request, useful for troubleshooting.

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