openapi: 3.1.0
info:
  version: 1.0.0
  title: Ashby API Key Department & Team API
  description: Complete public API for accessing resources in your Ashby instance. Includes applications, candidates, jobs, interviews, offers, surveys, custom fields, organization metadata, files, reports, approvals, and webhooks.
  contact:
    name: Ashby Support
    url: https://app.ashbyhq.com/support
    email: support@ashbyhq.com
servers:
- url: https://api.ashbyhq.com
security:
- BasicAuth: []
tags:
- name: Department & Team
paths:
  /department.create:
    post:
      summary: department.create
      description: 'Creates a department


        **Requires the [`organizationWrite`](authentication#permissions-departmentcreate) permission.**

        '
      operationId: departmentcreate
      tags:
      - Department & Team
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the department or team
                  example: Engineering Operations
                externalName:
                  type: string
                  description: 'An alternate candidate-facing name for this department that will be used on Ashby job boards

                    '
                  example: Engineering
                parentId:
                  type: string
                  format: uuid
                  description: The id of the department's parent department
                  example: 1be42b8e-cafd-4beb-8121-f4981eb20f42
                extraData:
                  $ref: '#/paths/~1location.create/post/requestBody/content/application~1json/schema/properties/extraData'
      responses:
        '200':
          description: Responses for the department.create endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        $ref: '#/paths/~1department.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                    required:
                    - results
                - title: Error response
                  $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /department.archive:
    post:
      summary: department.archive
      description: 'Archives a department


        **Requires the [`organizationWrite`](authentication#permissions-departmentarchive) permission.**

        '
      operationId: departmentarchive
      tags:
      - Department & Team
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - departmentId
              properties:
                departmentId:
                  type: string
                  description: The department's ID
                  example: 1be42b8e-cafd-4beb-8121-f4981eb20f42
      responses:
        '200':
          description: Responses for the department.archive endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        $ref: '#/paths/~1department.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                    required:
                    - results
                - title: Error response
                  $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /department.restore:
    post:
      summary: department.restore
      description: 'Restores a department


        **Requires the [`organizationWrite`](authentication#permissions-departmentrestore) permission.**

        '
      operationId: departmentrestore
      tags:
      - Department & Team
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - departmentId
              properties:
                departmentId:
                  type: string
                  description: The department's ID
                  example: 1be42b8e-cafd-4beb-8121-f4981eb20f42
      responses:
        '200':
          description: Responses for the department.restore endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        $ref: '#/paths/~1department.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                    required:
                    - results
                - title: Error response
                  $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /department.move:
    post:
      summary: department.move
      description: 'Moves a department to another parent


        **Requires the [`organizationWrite`](authentication#permissions-departmentmove) permission.**

        '
      operationId: departmentmove
      tags:
      - Department & Team
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - departmentId
              properties:
                departmentId:
                  type: string
                  description: The department's ID
                  example: 1be42b8e-cafd-4beb-8121-f4981eb20f42
                parentId:
                  type: string
                  description: The department parent's ID
                  example: 1be42b8e-cafd-4beb-8121-f4981eb20f42
      responses:
        '200':
          description: Responses for the department.move endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        $ref: '#/paths/~1department.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                    required:
                    - results
                - title: Error response
                  $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /department.update:
    post:
      summary: department.update
      description: 'Updates a department


        **Requires the [`organizationWrite`](authentication#permissions-departmentupdate) permission.**

        '
      operationId: departmentupdate
      tags:
      - Department & Team
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - departmentId
              properties:
                departmentId:
                  type: string
                  description: The department's ID
                  example: 1be42b8e-cafd-4beb-8121-f4981eb20f42
                name:
                  $ref: '#/paths/~1department.create/post/requestBody/content/application~1json/schema/properties/name'
                externalName:
                  $ref: '#/paths/~1department.create/post/requestBody/content/application~1json/schema/properties/externalName'
                extraData:
                  $ref: '#/paths/~1location.create/post/requestBody/content/application~1json/schema/properties/extraData'
      responses:
        '200':
          description: Responses for the department.update endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        $ref: '#/paths/~1department.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                    required:
                    - results
                - title: Error response
                  $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Auth. Send your Ashby API key as the username and leave the password blank.
    WebhookSignature:
      type: apiKey
      in: header
      name: Ashby-Signature
      description: HMAC-SHA256 signature of the webhook payload, used to verify webhook authenticity.