# Organizations

## Create an organization

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

### Header Parameters

- `"correlation-id": optional string`

- `"idempotency-key": optional string`

- `"request-id": optional string`

### Body Parameters

- `name: string`

  The name of 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.

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

```http
curl https://sandbox.straddle.com/v1/organizations \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $STRADDLE_API_KEY" \
    -d '{
          "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

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

### Query Parameters

- `external_id: optional string`

  List organizations by their external ID.

- `name: optional string`

  List organizations by name (partial match supported).

- `page_number: optional number`

  Results page number. Starts at page 1.

- `page_size: optional number`

  Page size. Max value: 1000

- `sort_by: optional string`

  Sort By.

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

  Sort Order.

  - `"asc"`

  - `"desc"`

### Header Parameters

- `"correlation-id": optional string`

- `"request-id": optional string`

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

```http
curl https://sandbox.straddle.com/v1/organizations \
    -H "Authorization: Bearer $STRADDLE_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

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

### Path Parameters

- `organization_id: string`

### Header Parameters

- `"correlation-id": optional string`

- `"request-id": optional string`

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

```http
curl https://sandbox.straddle.com/v1/organizations/$ORGANIZATION_ID \
    -H "Authorization: Bearer $STRADDLE_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"
  },
  "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: 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: 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: 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: 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"`