Zendesk Organizations API

openapi: 3.1.0
info:
  version: '1.0'
  title: Zendesk Account Account Settings Organizations API
  description: Needs a description.
tags:
- name: Organizations
paths:
  /api/v2/organizations/autocomplete:
    parameters:
    - $ref: '#/components/parameters/OrganizationQueryFragment'
    - $ref: '#/components/parameters/LookupRelationshipAutocompleteFieldIdFragment'
    - $ref: '#/components/parameters/LookupRelationshipAutocompleteSourceFragment'
    get:
      operationId: AutocompleteOrganizations
      tags:
      - Organizations
      summary: Zendesk Get  Api V2 Organizations Autocomplete
      description: 'Returns an array of organizations whose name starts with the

        value specified in the `name` parameter.


        #### Pagination


        * Offset pagination only


        See [Using Offset Pagination](/api-reference/introduction/pagination/#using-offset-pagination).


        #### Allowed For


        * Agents

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationsResponse'
              examples:
                default:
                  $ref: '#/components/examples/AutocompleteOrganizationsResponseExample'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                default:
                  value:
                    errors:
                    - code: QueryError
                      title: Invalid type:sample_type
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                default:
                  value:
                    errors:
                    - code: TooManyRequests
                      title: Too many requests to autocomplete
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                default:
                  value:
                    errors:
                    - code: Unavailable
                      title: Internal Server Error
  /api/v2/organization_merges/{organization_merge_id}:
    parameters:
    - $ref: '#/components/parameters/OrganizationMergeId'
    get:
      operationId: ShowOrganizationMerge
      tags:
      - Organizations
      summary: Zendesk Get  Api V2 Organization_merges Organization_merge_id
      description: 'Retrieves the details of a specific organization merge operation. This endpoint is useful for obtaining the status and outcome of a merge that was previously initiated. It provides information such as the winning and losing organization IDs, the status of the merge, and the associated URLs.


        This endpoint can be used to determine if a merge is still in progress, has completed successfully, or has encountered an error.


        #### Allowed For


        * Admins

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationMergeResponse'
              examples:
                default:
                  $ref: '#/components/examples/OrganizationMergeResponseExample'
  /api/v2/organizations:
    get:
      operationId: ListOrganizations
      tags:
      - Organizations
      summary: Zendesk Get  Api V2 Organizations
      description: '#### Pagination


        * Cursor pagination (recommended)

        * Offset pagination


        See [Pagination](/api-reference/introduction/pagination/).


        Returns a maximum of 100 records per page.


        #### Allowed For


        * Agents, with certain restrictions


        If the agent has a custom agent role that restricts their access to only users in their own organization, a 403 Forbidden error is returned. See [Creating custom agent roles](https://support.zendesk.com/hc/en-us/articles/203662026-Creating-custom-roles-and-assigning-agents#topic_cxn_hig_bd) in Zendesk help.

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationsResponse'
              examples:
                default:
                  $ref: '#/components/examples/OrganizationsResponseExample'
    post:
      operationId: CreateOrganization
      tags:
      - Organizations
      summary: Zendesk Post  Api V2 Organizations
      description: 'You must provide a unique `name` for each organization. Normally

        the system doesn''t allow records to be created with identical names.

        However, a race condition can occur if you make two or more identical

        POSTs very close to each other, causing the records to have identical

        organization names.


        **Note**: Leading and trailing whitespace in `name` is automatically trimmed before validation. This means that names differing only by whitespace are treated as duplicates. For example, "API Company" and "API Company " are considered the same name.


        #### Allowed For


        * Admins

        * Agents assigned to a custom role with permissions to manage organizations (Enterprise only)

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrganizationRequest'
            examples:
              default:
                $ref: '#/components/examples/CreateOrganizationRequestExample'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationResponse'
              examples:
                default:
                  $ref: '#/components/examples/CreatedOrganizationResponseExample'
  /api/v2/organizations/{organization_id}:
    parameters:
    - $ref: '#/components/parameters/OrganizationId'
    get:
      operationId: ShowOrganization
      tags:
      - Organizations
      summary: Zendesk Get  Api V2 Organizations Organization_id
      description: '#### Allowed For


        * Admins

        * Agents

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationResponse'
              examples:
                default:
                  $ref: '#/components/examples/OrganizationResponseExample'
    put:
      operationId: UpdateOrganization
      tags:
      - Organizations
      summary: Zendesk Put  Api V2 Organizations Organization_id
      description: "#### Allowed For\n\n* Admins\n* Agents\n\nAgents with no permissions restrictions can only update \"notes\" on organizations.\n\n**Note:** Updating an organization's `domain_names` property overwrites all existing `domain_names` values. To prevent this, submit a complete list of `domain_names` for the organization in your request.\n\n#### Example Request\n\n```js\n{\n  \"organization\": {\n    \"notes\": \"Something interesting\"\n  }\n}\n```\n"
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationResponse'
              examples:
                default:
                  $ref: '#/components/examples/UpdateOrganizationResponseExample'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                default:
                  value:
                    errors:
                    - code: TooManyRequests
                      title: Too many requests to update
    delete:
      operationId: DeleteOrganization
      tags:
      - Organizations
      summary: Zendesk Delete  Api V2 Organizations Organization_id
      description: '#### Allowed For


        * Admins

        * Agents assigned to a custom role with permissions to manage organizations (Enterprise only)

        '
      responses:
        '204':
          description: No Content Response
  /api/v2/organizations/{organization_id}/merge:
    parameters:
    - $ref: '#/components/parameters/OrganizationId'
    post:
      operationId: CreateOrganizationMerge
      tags:
      - Organizations
      summary: Zendesk Post  Api V2 Organizations Organization_id Merge
      description: "Merges two organizations by moving all users, tickets, and domain names from the organization specified by `{organization_id}` to the organization specified by `winner_id`. After the merge:\n\n- The \"losing\" organization will be deleted.\n- Other organization fields and their values will not be carried over to the \"winning\" organization.\n- The merge operation creates an `Organization Merge` record which contains a status indicating the progress of the merge.\n\n**Note**: This operation is irreversible.\n\n#### Merge Statuses\n\n| Status | Description |\n|--------|-------------|\n| new | A job has been queued to merge the two organizations. |\n| in progress | The job to merge the two organizations has started. |\n| error | An error occurred during the merge job. The merge can be retried by repeating the API call. | \n| complete | The merge has been completed successfully. |\n\n#### Allowed For\n\n* Admins\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationMergeRequest'
            examples:
              default:
                $ref: '#/components/examples/OrganizationMergeRequestExample'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationMergeResponse'
              examples:
                default:
                  $ref: '#/components/examples/OrganizationMergeResponseExample'
  /api/v2/organizations/{organization_id}/merges:
    parameters:
    - $ref: '#/components/parameters/OrganizationId'
    get:
      operationId: ListOrganizationMerges
      tags:
      - Organizations
      summary: Zendesk Get  Api V2 Organizations Organization_id Merges
      description: 'Retrieves a list of all organization merge operations associated with a given organization. This endpoint allows you to track the history of merge actions for an organization, including ongoing and completed merges.


        Each entry in the list contains details such as the ID of the merge, the winning and losing organization IDs, the current status of the merge, and a URL to access the `Organization Merge` record.


        #### Pagination


        - Cursor pagination is used for this endpoint.

        - A maximum of 100 records can be returned per page.


        See [Pagination](/api-reference/introduction/pagination/) for more details.


        #### Allowed For


        * Admins

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationMergeListResponse'
              examples:
                default:
                  $ref: '#/components/examples/OrganizationMergeListResponseExample'
  /api/v2/organizations/{organization_id}/related:
    parameters:
    - $ref: '#/components/parameters/OrganizationId'
    get:
      operationId: OrganizationRelated
      tags:
      - Organizations
      summary: Zendesk Get  Api V2 Organizations Organization_id Related
      description: '#### Allowed For


        * Agents

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationsRelatedResponse'
              examples:
                default:
                  $ref: '#/components/examples/OrganizationsRelatedResponse'
  /api/v2/organizations/count:
    get:
      operationId: CountOrganizations
      tags:
      - Organizations
      summary: Zendesk Get  Api V2 Organizations Count
      description: 'Returns an approximate count of organizations. If the count exceeds

        100,000, it is updated every 24 hours.


        The `refreshed_at` property of the `count` object is a timestamp that indicates

        when the count was last updated.


        When the count exceeds 100,000, the `refreshed_at` property may

        occasionally be null. This indicates that the count is being

        updated in the background and the `value` property of the `count` object is limited to

        100,000 until the update is complete.


        #### Allowed For


        * Agents

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountOrganizationResponse'
              examples:
                default:
                  $ref: '#/components/examples/CountOrganizationsResponseExample'
  /api/v2/organizations/create_many:
    post:
      operationId: CreateManyOrganizations
      tags:
      - Organizations
      summary: Zendesk Post  Api V2 Organizations Create_many
      description: 'Accepts an array of up to 100 organization objects.


        #### Response


        This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job''s completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information.


        #### Allowed For


        * Agents, with restrictions applying on certain actions

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatusResponse'
              examples:
                default:
                  $ref: '#/components/examples/ShowJobStatusResponseExample'
  /api/v2/organizations/create_or_update:
    post:
      operationId: CreateOrUpdateOrganization
      tags:
      - Organizations
      summary: Zendesk Post  Api V2 Organizations Create_or_update
      description: 'Creates an organization if it doesn''t already exist, or updates

        an existing organization. Using this method means one less call

        to check if an organization exists before creating it. You need

        to specify the id or external id when updating

        an organization to avoid a duplicate error response. Name is

        not available as a matching criteria.


        #### Allowed For


        * Agents, with restrictions on certain actions

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationResponse'
              examples:
                default:
                  $ref: '#/components/examples/CreatedOrganizationResponseExample'
        '201':
          description: Created response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationResponse'
              examples:
                default:
                  $ref: '#/components/examples/CreatedOrganizationResponseExample'
  /api/v2/organizations/destroy_many:
    parameters:
    - $ref: '#/components/parameters/OrganizationIds'
    - $ref: '#/components/parameters/OrganizationExternalIds'
    delete:
      operationId: DeleteManyOrganizations
      tags:
      - Organizations
      summary: Zendesk Delete  Api V2 Organizations Destroy_many
      description: 'Accepts a comma-separated list of up to 100 organization ids or external ids.


        #### Response


        This endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job''s completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information.


        #### Allowed For


        * Admins

        * Agents assigned to a custom role with permissions to manage organizations (Enterprise only)

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatusResponse'
              examples:
                default:
                  $ref: '#/components/examples/JobStatusBulkDeleteResponseExample'
  /api/v2/organizations/search:
    parameters:
    - $ref: '#/components/parameters/OrganizationExternalId'
    - $ref: '#/components/parameters/OrganizationName'
    get:
      operationId: SearchOrganizations
      tags:
      - Organizations
      summary: Zendesk Get  Api V2 Organizations Search
      description: 'Returns an array of organizations matching the criteria. You may search by an organization''s `external_id` or `name`, but not both:


        #### Searching by `external_id`


        If you set the `external_id` value of an organization to associate it to an external record, you can use it to search for the organization.


        For an organization to be returned, its `external_id` must exactly match the value provided (case insensitive).


        #### Searching by `name`


        For an organization to be returned, its `name` must exactly match the value provided (case insensitive).


        #### Allowed For:


        * Admins

        * Agents assigned to a custom role with permissions to add or modify organizations (Enterprise only)


        See [Creating custom agent roles](https://support.zendesk.com/hc/en-us/articles/203662026#topic_cxn_hig_bd) in the Support Help Center.

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationsResponse'
              examples:
                default:
                  $ref: '#/components/examples/OrganizationsResponseExample'
  /api/v2/organizations/show_many:
    parameters:
    - $ref: '#/components/parameters/OrganizationIds'
    - $ref: '#/components/parameters/OrganizationExternalIds'
    get:
      operationId: ShowManyOrganizations
      tags:
      - Organizations
      summary: Zendesk Get  Api V2 Organizations Show_many
      description: 'Accepts a comma-separated list of up to 100 organization ids or external ids.


        #### Allowed For


        * Admins

        * Agents

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationsResponse'
              examples:
                default:
                  $ref: '#/components/examples/AutocompleteOrganizationsResponseExample'
  /api/v2/organizations/update_many:
    parameters:
    - $ref: '#/components/parameters/OrganizationIds'
    - $ref: '#/components/parameters/OrganizationExternalIds'
    put:
      operationId: UpdateManyOrganizations
      tags:
      - Organizations
      summary: Zendesk Put  Api V2 Organizations Update_many
      description: "Bulk or batch updates up to 100 organizations.\n\n#### Bulk update\n\nTo make the same change to multiple organizations, use the following endpoint and data format:\n\n`https://{subdomain}.zendesk.com/api/v2/organizations/update_many.json?ids=1,2,3`\n\n```js\n{\n  \"organization\": {\n    \"notes\": \"Priority\"\n  }\n}\n```\n\n#### Batch update\n\nTo make different changes to multiple organizations, use the following endpoint and data format:\n\n`https://{subdomain}.zendesk.com/api/v2/organizations/update_many.json`\n\n```js\n{\n  \"organizations\": [\n    { \"id\": 1, \"notes\": \"Priority\" },\n    { \"id\": 2, \"notes\": \"Normal\" }\n  ]\n}\n```\n\n#### Response\n\nThis endpoint returns a `job_status` [JSON object](/api-reference/ticketing/ticket-management/job_statuses/#json-format) and queues a background job to do the work. Use the [Show Job Status](/api-reference/ticketing/ticket-management/job_statuses/#show-job-status) endpoint to check for the job's completion. Only a certain number of jobs can be queued or running at the same time. See [Job limit](/api-reference/introduction/rate-limits/#job-limit) for more information.\n\n#### Allowed For\n\n* Admins\n* Agents\n\nAgents with no permissions restrictions can only update \"notes\" on organizations.\n"
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatusResponse'
              examples:
                default:
                  $ref: '#/components/examples/ShowJobStatusResponseExample'
  /organizations:
    get:
      operationId: listOrganizations
      summary: Zendesk List Organizations
      description: Returns a paginated list of all organizations in the account.
      tags:
      - Organizations
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  organizations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Organization'
                  next_page:
                    type: string
                    format: uri
                    nullable: true
                  previous_page:
                    type: string
                    format: uri
                    nullable: true
                  count:
                    type: integer
              examples:
                Listorganizations200Example:
                  summary: Default listOrganizations 200 response
                  x-microcks-default: true
                  value:
                    organizations:
                    - id: abc123
                      url: https://www.example.com
                      name: Example Title
                      details: example_value
                      notes: example_value
                      domain_names:
                      - {}
                      group_id: '500123'
                      shared_tickets: true
                      shared_comments: true
                      external_id: '500123'
                      tags:
                      - {}
                      organization_fields: example_value
                      created_at: '2026-01-15T10:30:00Z'
                      updated_at: '2026-01-15T10:30:00Z'
                    next_page: https://www.example.com
                    previous_page: https://www.example.com
                    count: 10
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createOrganization
      summary: Zendesk Create Organization
      description: Creates a new organization. You must provide a name. You can optionally set domains, tags, notes, and custom fields.
      tags:
      - Organizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - organization
              properties:
                organization:
                  $ref: '#/components/schemas/OrganizationCreate'
            examples:
              CreateorganizationRequestExample:
                summary: Default createOrganization request
                x-microcks-default: true
                value:
                  organization:
                    name: Example Title
                    details: example_value
                    notes: example_value
                    domain_names:
                    - example_value
                    group_id: '500123'
                    shared_tickets: true
                    shared_comments: true
                    external_id: '500123'
                    tags:
                    - example_value
                    organization_fields: example_value
      responses:
        '201':
          description: Organization created
          content:
            application/json:
              schema:
                type: object
                properties:
                  organization:
                    $ref: '#/components/schemas/Organization'
              examples:
                Createorganization201Example:
                  summary: Default createOrganization 201 response
                  x-microcks-default: true
                  value:
                    organization:
                      id: abc123
                      url: https://www.example.com
                      name: Example Title
                      details: example_value
                      notes: example_value
                      domain_names:
                      - example_value
                      group_id: '500123'
                      shared_tickets: true
                      shared_comments: true
                      external_id: '500123'
                      tags:
                      - example_value
                      organization_fields: example_value
                      created_at: '2026-01-15T10:30:00Z'
                      updated_at: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /organizations/{organization_id}:
    parameters:
    - $ref: '#/components/parameters/OrganizationId'
    get:
      operationId: getOrganization
      summary: Zendesk Show Organization
      description: Returns the details of a specific organization.
      tags:
      - Organizations
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  organization:
                    $ref: '#/components/schemas/Organization'
              examples:
                Getorganization200Example:
                  summary: Default getOrganization 200 response
                  x-microcks-default: true
                  value:
                    organization:
                      id: abc123
                      url: https://www.example.com
                      name: Example Title
                      details: example_value
                      notes: example_value
                      domain_names:
                      - example_value
                      group_id: '500123'
                      shared_tickets: true
                      shared_comments: true
                      external_id: '500123'
                      tags:
                      - example_value
                      organization_fields: example_value
                      created_at: '2026-01-15T10:30:00Z'
                      updated_at: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateOrganization
      summary: Zendesk Update Organization
      description: Updates an organization. You can update the name, domains, notes, tags, details, and custom fields.
      tags:
      - Organizations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - organization
              properties:
                organization:
                  $ref: '#/components/schemas/OrganizationUpdate'
            examples:
              UpdateorganizationRequestExample:
                summary: Default updateOrganization request
                x-microcks-default: true
                value:
                  organization:
                    name: Example Title
                    details: example_value
                    notes: example_value
                    domain_names:
                    - example_value
                    group_id: '500123'
                    shared_tickets: true
                    shared_comments: true
                    external_id: '500123'
                    tags:
                    - example_value
                    organization_fields: example_value
      responses:
        '200':
          description: Organization updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  organization:
                    $ref: '#/components/schemas/Organization'
              examples:
                Updateorganization200Example:
                  summary: Default updateOrganization 200 response
                  x-microcks-default: true
                  value:
                    organization:
                      id: abc123
                      url: https://www.example.com
                      name: Example Title
                      details: example_value
                      notes: example_value
                      domain_names:
                      - example_value
                      group_id: '500123'
                      shared_tickets: true
                      shared_comments: true
                      external_id: '500123'
                      tags:
                      - example_value
                      organization_fields: example_value
                      created_at: '2026-01-15T10:30:00Z'
                      updated_at: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteOrganization
      summary: Zendesk Delete Organization
      description: Permanently deletes an organization. Users associated with the organization are not deleted, but their organization membership is removed.
      tags:
      - Organizations
      responses:
        '204':
          description: Organization deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /organizations/search:
    get:
      operationId: searchOrganizations
      summary: Zendesk Search Organizations
      description: Searches for organizations by name or external ID.
      tags:
      - Organizations
      parameters:
      - name: external_id
        in: query
        description: Search by external ID.
        schema:
          type: string
      

# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zendesk/refs/heads/main/openapi/zendesk-organizations-api-openapi.yml