Zendesk Skill Based Routing API

openapi: 3.1.0
info:
  version: '1.0'
  title: Zendesk Account Account Settings Skill Based Routing API
  description: Needs a description.
tags:
- name: Skill Based Routing
paths:
  /api/v2/routing/agents/{user_id}/instance_values:
    parameters:
    - $ref: '#/components/parameters/UserId'
    get:
      operationId: ListAGentAttributeValues
      tags:
      - Skill Based Routing
      summary: Zendesk Get  Api V2 Routing Agents User_id Instance_values
      description: 'Returns an attribute value.


        #### Allowed For


        * Agents and admins

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillBasedRoutingAttributeValuesResponse'
              examples:
                default:
                  $ref: '#/components/examples/SkillBasedRoutingAttributeValuesResponseExample'
    post:
      operationId: SetAgentAttributeValues
      tags:
      - Skill Based Routing
      summary: Zendesk Post  Api V2 Routing Agents User_id Instance_values
      description: 'Adds the specified attributes if no attributes exists, or replaces all existing attributes with the specified attributes.


        #### Allowed For


        * Admins

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillBasedRoutingAttributeValuesResponse'
              examples:
                default:
                  $ref: '#/components/examples/SkillBasedRoutingAttributeValuesResponseExample'
  /api/v2/routing/agents/instance_values:
    get:
      operationId: ListManyAgentsAttributeValues
      tags:
      - Skill Based Routing
      summary: Zendesk Get  Api V2 Routing Agents Instance_values
      description: 'Accepts a comma-separated list of up to 100 agent ids and returns attribute values for each agent in the list.


        #### Allowed For

        * Admins

        * [Agents in custom role with permission to manage skills](https://support.zendesk.com/hc/en-us/articles/4408882153882-Creating-custom-roles-and-assigning-agents)


        #### Pagination

        * [Cursor pagination](/api-reference/introduction/pagination/#cursor-pagination) only.

        Note: `page[before]` and `page[after]` can''t be used together in the same request.

        '
      parameters:
      - name: filter[agent_ids]
        in: query
        description: A comma-separated list of agent ids
        required: true
        schema:
          type: string
        example: 224,225
      - name: page[before]
        in: query
        description: 'A [pagination cursor](/documentation/api-basics/pagination/paginating-through-lists-using-cursor-pagination) that tells the endpoint which page to start on. It should be a `meta.before_cursor` value from a previous request.

          '
        schema:
          type: string
      - name: page[after]
        in: query
        description: 'A [pagination cursor](/documentation/api-basics/pagination/paginating-through-lists-using-cursor-pagination) that tells the endpoint which page to start on. It should be a `meta.after_cursor` value from a previous request.

          '
        schema:
          type: string
      - name: page[size]
        in: query
        description: The number of items to return per page
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManySkillBasedRoutingAttributeValuesResponse'
              examples:
                default:
                  $ref: '#/components/examples/ManySkillBasedRoutingAttributeValuesResponseExample'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillBasedRoutingAttributeValuesError'
              examples:
                default:
                  $ref: '#/components/examples/ManySkillBasedRoutingAttributeValuesErrorExample'
  /api/v2/routing/agents/instance_values/job:
    post:
      operationId: BulkSetAgentAttributeValuesJob
      tags:
      - Skill Based Routing
      summary: Zendesk Post  Api V2 Routing Agents Instance_values Job
      description: "Adds, replaces or removes multiple attributes for up to 100 agents.\n\n#### Allowed For\n* Admins\n* [Agents in custom role with permission to manage skills](https://support.zendesk.com/hc/en-us/articles/4408882153882-Creating-custom-roles-and-assigning-agents)\n\n#### Available Parameters\n\nThe request takes a data object with the following properties:\n| Name       | Type   | Required | Description                                                                                       |\n| ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |\n| action     | string | true     | The action to perform on the attribute values. One of the following: \"upsert\", \"update\", \"delete\" |\n| attributes | object | true     | The attribute values to update. See [Attribute Values](#attribute-values)                         |\n| items      | array  | true     | The list of agent ids                                                                             |\n\nAction can be one of the following:\n  * upsert: Adds new attribute values to the agents\n  * update: Replaces all the current attribute values of the agents with the new values\n  * delete: Removes specified attribute values from the agents\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.\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkSkillBasedRoutingAttributeValuesRequest'
            examples:
              default:
                $ref: '#/components/examples/BulkSkillBasedRoutingAttributeValuesRequestExample'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatusResponse'
              examples:
                default:
                  $ref: '#/components/examples/BulkSkillBasedRoutingAttributeValuesJobStatusResponseExample'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillBasedRoutingAttributeValuesError'
              examples:
                default:
                  $ref: '#/components/examples/BulkSkillBasedRoutingAttributeValuesErrorExample'
  /api/v2/routing/attributes:
    get:
      operationId: ListAccountAttributes
      tags:
      - Skill Based Routing
      summary: Zendesk Get  Api V2 Routing Attributes
      description: 'Returns a list of attributes for the account.


        #### Sideloads


        The following sideloads are supported:


        | Name             | Will sideload

        | ---------------- | -------------

        | attribute_values | The attribute values available on the account


        #### Allowed For


        * Agents and admins

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillBasedRoutingAttributesResponse'
              examples:
                default:
                  $ref: '#/components/examples/SkillBasedRoutingAttributesResponseExample'
    post:
      operationId: CreateAttribute
      tags:
      - Skill Based Routing
      summary: Zendesk Post  Api V2 Routing Attributes
      description: 'Creates an attribute.


        #### Allowed For


        * Agents

        '
      responses:
        '201':
          description: Created response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillBasedRoutingAttributeResponse'
              examples:
                default:
                  $ref: '#/components/examples/SkillBasedRoutingAttributeCreateResponseExample'
  /api/v2/routing/attributes/{attribute_id}:
    parameters:
    - $ref: '#/components/parameters/SkillBasedRoutingAttributeId'
    get:
      operationId: ShowAttribute
      tags:
      - Skill Based Routing
      summary: Zendesk Get  Api V2 Routing Attributes Attribute_id
      description: 'Returns an attribute.


        #### Allowed For


        * Admins

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillBasedRoutingAttributeResponse'
              examples:
                default:
                  $ref: '#/components/examples/SkillBasedRoutingAttributeResponseExample'
    put:
      operationId: UpdateAttribute
      tags:
      - Skill Based Routing
      summary: Zendesk Put  Api V2 Routing Attributes Attribute_id
      description: 'Updates an attribute.


        #### Allowed For


        * Admins

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillBasedRoutingAttributeResponse'
              examples:
                default:
                  $ref: '#/components/examples/SkillBasedRoutingAttributeUpdateResponseExample'
    delete:
      operationId: DeleteAttribute
      tags:
      - Skill Based Routing
      summary: Zendesk Delete  Api V2 Routing Attributes Attribute_id
      description: 'Deletes an attribute.


        #### Allowed For


        * Admins

        '
      responses:
        '204':
          description: No Content response
  /api/v2/routing/attributes/{attribute_id}/values:
    parameters:
    - $ref: '#/components/parameters/SkillBasedRoutingAttributeId'
    get:
      operationId: ListAttributeValues
      tags:
      - Skill Based Routing
      summary: Zendesk Get  Api V2 Routing Attributes Attribute_id Values
      description: 'Returns a list of attribute values for a provided attribute.


        #### Allowed For


        * Agents

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillBasedRoutingAttributeValuesResponse'
              examples:
                default:
                  $ref: '#/components/examples/SkillBasedRoutingAttributeValuesResponseExample'
    post:
      operationId: CreateAttributeValue
      tags:
      - Skill Based Routing
      summary: Zendesk Post  Api V2 Routing Attributes Attribute_id Values
      description: 'Creates an attribute value.


        #### Allowed For


        * Admins

        '
      responses:
        '201':
          description: Created response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillBasedRoutingAttributeValueResponse'
              examples:
                default:
                  $ref: '#/components/examples/SkillBasedRoutingAttributeValueCreateResponseExample'
  /api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id}:
    parameters:
    - $ref: '#/components/parameters/SkillBasedRoutingAttributeId'
    - $ref: '#/components/parameters/SkillBasedRoutingAttributeValueId'
    get:
      operationId: ShowAttributeValue
      tags:
      - Skill Based Routing
      summary: Zendesk Get  Api V2 Routing Attributes Attribute_id Values Attribute_value_id
      description: 'Returns an attribute value.


        #### Allowed For


        * Agents

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillBasedRoutingAttributeValueResponse'
              examples:
                default:
                  $ref: '#/components/examples/SkillBasedRoutingAttributeValueResponseExample'
    patch:
      operationId: UpdateAttributeValue
      tags:
      - Skill Based Routing
      summary: Zendesk Patch  Api V2 Routing Attributes Attribute_id Values Attribute_value_id
      description: 'Updates the name and ticket conditions of a skill. When a ticket is created, the skill is applied to a ticket  if the ticket meets the specified condition or conditions. See the [Conditions reference](/documentation/ticketing/reference-guides/conditions-reference/) for more information.


        #### Allowed For


        * Admins

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillBasedRoutingAttributeValueResponse'
              examples:
                default:
                  $ref: '#/components/examples/SkillBasedRoutingAttributeValueUpdateResponseExample'
    delete:
      operationId: DeleteAttributeValue
      tags:
      - Skill Based Routing
      summary: Zendesk Delete  Api V2 Routing Attributes Attribute_id Values Attribute_value_id
      description: 'Deletes an attribute value.


        #### Allowed For


        * Agents

        '
      responses:
        '204':
          description: No Content response
  /api/v2/routing/attributes/definitions:
    get:
      operationId: ListRoutingAttributeDefinitions
      tags:
      - Skill Based Routing
      summary: Zendesk Get  Api V2 Routing Attributes Definitions
      description: 'Returns the condition definitions that can be configured to apply attributes to a ticket.


        #### Allowed For


        * Admins

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillBasedRoutingAttributeDefinitions'
              examples:
                default:
                  $ref: '#/components/examples/SkillBasedRoutingAttributeDefinitionsExample'
  /api/v2/routing/requirements/fulfilled:
    get:
      operationId: ListTicketsFullfilledByUser
      tags:
      - Skill Based Routing
      summary: Zendesk Get  Api V2 Routing Requirements Fulfilled
      description: 'Returns a list of ticket ids that contain attributes matching the current user''s attributes. Accepts a `ticket_ids` parameter for relevant tickets to check for matching attributes.


        #### Allowed For


        * Agents and admins

        '
      parameters:
      - name: ticket_ids
        in: query
        description: The IDs of the relevant tickets to check for matching attributes
        required: true
        schema:
          type: integer
        example: 1
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillBasedRoutingTicketFulfilledResponse'
              examples:
                default:
                  $ref: '#/components/examples/SkillBasedRoutingTicketFulfilledResponseExample'
  /api/v2/routing/tickets/{ticket_id}/instance_values:
    parameters:
    - $ref: '#/components/parameters/TicketId'
    get:
      operationId: ListTicketAttributeValues
      tags:
      - Skill Based Routing
      summary: Zendesk Get  Api V2 Routing Tickets Ticket_id Instance_values
      description: 'Returns a list of attributes values for the ticket.


        #### Allowed For


        * Agents and admins

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillBasedRoutingAttributeValuesResponse'
              examples:
                default:
                  $ref: '#/components/examples/SkillBasedRoutingTicketAttributesResponseExample'
    post:
      operationId: SetTicketAttributeValues
      tags:
      - Skill Based Routing
      summary: Zendesk Post  Api V2 Routing Tickets Ticket_id Instance_values
      description: 'Adds the specified attributes if no attributes exists, or replaces all existing attributes with the specified attributes.


        Invalid or deleted attributes are ignored.


        #### Allowed For


        * Admins

        '
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillBasedRoutingAttributeValuesResponse'
              examples:
                default:
                  $ref: '#/components/examples/SkillBasedRoutingTicketAttributesResponseExample'
components:
  schemas:
    SkillBasedRoutingAttributeValuesResponse:
      type: object
      properties:
        attribute_values:
          type: array
          items:
            $ref: '#/components/schemas/SkillBasedRoutingAttributeValueObject'
    SkillBasedRoutingAttributeValueResponse:
      type: object
      properties:
        attribute_value:
          $ref: '#/components/schemas/SkillBasedRoutingAttributeValueObject'
    SkillBasedRoutingTicketFulfilledResponse:
      type: object
      properties:
        fulfilled_ticket_ids:
          type: array
          items:
            type: integer
    JobStatusResponse:
      type: object
      properties:
        job_status:
          $ref: '#/components/schemas/JobStatusObject'
    ManySkillBasedRoutingAttributeValuesResponse:
      type: object
      properties:
        count:
          type: integer
          format: int32
          description: The number of instance values returned
          readOnly: true
        instance_values:
          type: array
          items:
            $ref: '#/components/schemas/ManySkillBasedRoutingAttributeValues'
        next_page:
          type: string
          description: The URL for the next page of results
          nullable: true
          readOnly: true
        previous_page:
          type: string
          description: The URL for the previous page of results
          nullable: true
          readOnly: true
    SkillBasedRoutingAttributeDefinitions:
      type: object
      properties:
        definitions:
          type: object
          properties:
            conditions_all:
              type: array
              items:
                type: object
                properties:
                  subject:
                    type: string
                  title:
                    type: string
            conditions_any:
              type: array
              items:
                type: object
                properties:
                  subject:
                    type: string
                  title:
                    type: string
    SkillBasedRoutingAttributesResponse:
      type: object
      properties:
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/SkillBasedRoutingAttributeObject'
        count:
          type: integer
          readOnly: true
        next_page:
          type: string
          nullable: true
          readOnly: true
        previous_page:
          type: string
          nullable: true
          readOnly: true
    SkillBasedRoutingAttributeResponse:
      type: object
      properties:
        attribute:
          $ref: '#/components/schemas/SkillBasedRoutingAttributeObject'