# Organizations ## Create an organization `client.embed.organizations.create(OrganizationCreateParamsparams, RequestOptionsoptions?): 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 - `params: OrganizationCreateParams` - `name: string` Body param: The name of the organization. - `external_id?: string | null` Body param: Unique identifier for the organization in your database, used for cross-referencing between Straddle and your systems. - `metadata?: Record | null` Body param: Up to 20 additional user-defined key-value pairs. Useful for storing additional information about the organization in a structured format. - `correlationID?: string` Header param: Optional client generated identifier to trace and debug a series of requests. - `idempotencyKey?: string` Header param: Optional client generated value to use for idempotent requests. - `requestID?: string` Header param: Optional client generated identifier to trace and debug a request. ### Returns - `OrganizationV1` - `data: Data` - `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?: string | null` Unique identifier for the organization in your database, used for cross-referencing between Straddle and your systems. - `metadata?: Record | null` 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" | "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 ```typescript import Straddle from '@straddlecom/straddle'; const client = new Straddle({ apiKey: process.env['STRADDLE_API_KEY'], // This is the default and can be omitted }); const organizationV1 = await client.embed.organizations.create({ name: 'name' }); console.log(organizationV1.data); ``` #### 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 `client.embed.organizations.list(OrganizationListParamsparams?, RequestOptionsoptions?): PageNumberSchema` **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 - `params: OrganizationListParams` - `external_id?: string` Query param: List organizations by their external ID. - `name?: string` Query param: List organizations by name (partial match supported). - `page_number?: number` Query param: Results page number. Starts at page 1. - `page_size?: number` Query param: Page size. Max value: 1000 - `sort_by?: string` Query param: Sort By. - `sort_order?: "asc" | "desc"` Query param: Sort Order. - `"asc"` - `"desc"` - `correlationID?: string` Header param: Optional client generated identifier to trace and debug a series of requests. - `requestID?: string` Header param: Optional client generated identifier to trace and debug a request. ### Returns - `Data` - `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?: string | null` Unique identifier for the organization in your database, used for cross-referencing between Straddle and your systems. - `metadata?: Record | null` Up to 20 additional user-defined key-value pairs. Useful for storing additional information about the organization in a structured format. ### Example ```typescript import Straddle from '@straddlecom/straddle'; const client = new Straddle({ apiKey: process.env['STRADDLE_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const organization of client.embed.organizations.list()) { console.log(organization.id); } ``` #### 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 `client.embed.organizations.get(stringorganizationID, OrganizationGetParamsparams?, RequestOptionsoptions?): 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 - `organizationID: string` - `params: OrganizationGetParams` - `correlationID?: string` Optional client generated identifier to trace and debug a series of requests. - `requestID?: string` Optional client generated identifier to trace and debug a request. ### Returns - `OrganizationV1` - `data: Data` - `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?: string | null` Unique identifier for the organization in your database, used for cross-referencing between Straddle and your systems. - `metadata?: Record | null` 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" | "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 ```typescript import Straddle from '@straddlecom/straddle'; const client = new Straddle({ apiKey: process.env['STRADDLE_API_KEY'], // This is the default and can be omitted }); const organizationV1 = await client.embed.organizations.get('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); console.log(organizationV1.data); ``` #### 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` - `data: Array` - `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?: string | null` Unique identifier for the organization in your database, used for cross-referencing between Straddle and your systems. - `metadata?: Record | null` 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" | "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" | "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 - `OrganizationV1` - `data: Data` - `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?: string | null` Unique identifier for the organization in your database, used for cross-referencing between Straddle and your systems. - `metadata?: Record | null` 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" | "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"`