> ## Documentation Index
> Fetch the complete documentation index at: https://docs.greenflash.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create or Update an Organization

> Group your users by company, team, or any organizational structure that makes sense for your business.

Provide an `externalOrganizationId` to identify the organization—your ID from your own system. Don't worry about whether it already exists; we'll create it if it's new or update it if it already exists. This makes syncing organization data effortless.

Reference this organization when creating users (via `/users`) or logging messages (via `/messages`) using the same `externalOrganizationId`. Perfect for B2B products where you need to track which company each user belongs to.



## OpenAPI

````yaml https://www.greenflash.ai/api/openapi post /organizations
openapi: 3.1.0
info:
  title: Greenflash API Reference
  version: 1.0.0
  description: >-
    Greenflash endpoints for capturing interactions, managing prompts, and
    identifying users.
servers:
  - url: https://www.greenflash.ai/api/v1
    description: Greenflash API v1
security: []
tags:
  - name: Interactions
    description: Capture interactions between users and AI
  - name: Business Events
    description: Capture business events
  - name: Analytics
    description: Understand chat and agentic interactions analyses
  - name: Inbox
    description: Review flagged conversations
  - name: Segments
    description: Manage user segments
  - name: Prompts
    description: Manage prompts
  - name: Chat
    description: Stream chat and agentic conversations
  - name: Models
    description: Manage AI models
  - name: Products
    description: Manage products
  - name: Users
    description: Manage users
  - name: Organizations
    description: Manage organizations
paths:
  /organizations:
    post:
      tags:
        - Users
        - Organizations
      summary: Create or Update an Organization
      description: >-
        Group your users by company, team, or any organizational structure that
        makes sense for your business.


        Provide an `externalOrganizationId` to identify the organization—your ID
        from your own system. Don't worry about whether it already exists; we'll
        create it if it's new or update it if it already exists. This makes
        syncing organization data effortless.


        Reference this organization when creating users (via `/users`) or
        logging messages (via `/messages`) using the same
        `externalOrganizationId`. Perfect for B2B products where you need to
        track which company each user belongs to.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrganizationRequest'
            example:
              externalOrganizationId: org-456
              name: Acme Corporation
              properties:
                industry: technology
                size: enterprise
      responses:
        '200':
          description: Organization created or updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrganizationResponse'
              example:
                success: true
                organization:
                  id: org-001
                  externalId: org-456
                  name: Acme Corporation
                  properties:
                    industry: technology
                    size: enterprise
                  createdAt: '2025-07-01T12:00:00Z'
                  updatedAt: '2025-07-01T12:00:00Z'
        '400':
          description: Bad request - invalid input data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the API call was successful (false for errors).
                  error:
                    type: string
                    description: Error message describing what went wrong.
                description: Error response for organization creation operations.
              example:
                success: false
                error: Invalid request body
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the API call was successful (false for errors).
                  error:
                    type: string
                    description: Error message describing what went wrong.
                description: Error response for organization creation operations.
              example:
                success: false
                error: Internal server error
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Greenflash from 'greenflash';


            const client = new Greenflash({
              apiKey: process.env['GREENFLASH_API_KEY'], // This is the default and can be omitted
            });


            const createOrganizationResponse = await
            client.organizations.create({
              externalOrganizationId: 'org-456',
              name: 'Acme Corporation',
              properties: { industry: 'technology', size: 'enterprise' },
            });


            console.log(createOrganizationResponse.organization);
        - lang: Python
          source: |-
            import os
            from greenflash import Greenflash

            client = Greenflash(
                api_key=os.environ.get("GREENFLASH_API_KEY"),  # This is the default and can be omitted
            )
            create_organization_response = client.organizations.create(
                external_organization_id="org-456",
                name="Acme Corporation",
                properties={
                    "industry": "technology",
                    "size": "enterprise",
                },
            )
            print(create_organization_response.organization)
components:
  schemas:
    CreateOrganizationRequest:
      type: object
      properties:
        externalOrganizationId:
          type: string
          description: >-
            Your unique identifier for the organization. Use this same ID in
            other API calls to reference this organization.
        name:
          type: string
          description: The organization's name.
        properties:
          type: object
          additionalProperties: {}
          description: Custom organization properties.
      required:
        - externalOrganizationId
      description: Request payload for creating a new organization.
    CreateOrganizationResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the API call was successful.
        organization:
          $ref: '#/components/schemas/TenantOrganization'
      required:
        - success
        - organization
      description: Success response for organization creation.
    TenantOrganization:
      type: object
      properties:
        id:
          type: string
          description: The Greenflash organization ID.
        externalId:
          type: string
          description: Your external organization ID.
        name:
          type: string
          description: The organization name.
        properties:
          type: object
          additionalProperties: {}
          description: Custom organization properties.
        createdAt:
          type: string
          format: date-time
          description: When the organization was first created.
        updatedAt:
          type: string
          format: date-time
          description: When the organization was last updated.
      required:
        - id
        - properties
      description: The organization that was created or updated.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````