openapi: 3.0.0
info:
  title: Agent Connect Coaching Requests API
  description: Agent Connect API
  termsOfService: https://medallia.com/about/legal/terms/api
  version: 1.0.0
servers:
- url: https://{subdomain}.api.stellaconnect.net
  variables:
    subdomain:
      description: Subdomain for the Agent Connect API
      default: subdomain
security:
- ApiKeyInHeader: []
  JwtAuth: []
tags:
- name: Requests
paths:
  /v1/requests:
    post:
      summary: Create a standard feedback request
      operationId: createRequest
      parameters:
      - name: x-api-key
        in: header
        description: Production API Key
        required: true
        style: simple
        explode: false
        schema:
          type: string
        example: '[insert your API key here]'
      - name: Accept
        in: header
        required: false
        style: simple
        explode: false
        schema:
          type: string
        example: application/json
      - name: Content-Type
        in: header
        required: false
        style: simple
        explode: false
        schema:
          type: string
        example: application/json
      requestBody:
        description: An object describing the Feedback request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestBodyCreateFeedbackRequest'
        required: true
      responses:
        '200':
          description: For a 200 response code, the response body contains an object describing the Feedback request
          headers:
            Content-Type:
              style: simple
              explode: false
              schema:
                type: string
              example: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBodyCreateFeedbackRequest'
        '400':
          description: Validation Error — The request was invalid. Please check the required request parameters and try again.
        '403':
          description: Forbidden — The request was denied due to an authentication failure.
        '500':
          description: Internal Server Error — The server encountered an unexpected condition that prevented it from fulfilling the request. File a Support ticket if this error is reproducible.
      tags:
      - Requests
components:
  schemas:
    RequestBodyCreateFeedbackRequest:
      $ref: '#/components/schemas/FeedbackRequestModel'
    ResponseBodyCreateFeedbackRequest:
      type: object
      properties:
        customer:
          type: object
          properties:
            custom_id:
              type: string
              description: Discuss with the Agent Connect team before using this field
            name:
              type: string
              description: Name of the customer that the interaction occured with; this is used to customize the header of the survey when available.
            email:
              type: string
              description: Email address of the customer that the interaction occured with
          additionalProperties: false
          description: Information about the customer with whom the interaction occured
        employee:
          type: object
          properties:
            custom_id:
              type: string
              description: "A custom identifier of the employee that this survey should be sent on behalf of\n\n This must match the custom identifier that this user is set up with on the Agent Connect platform. Either one of the email or custom_id fields are required."
            email:
              type: string
              description: "The email address of the employee that this survey should be sent on behalf of\n\n This must match the email that this user is set up with on the Agent Connect platform. Either one of the email or custom_id fields are required."
          additionalProperties: false
          description: Information about the employee who interacted with the customer
        channel:
          type: string
          description: "The service channel in which this interaction occurred \n\n This value must match the values that are set up within the platform. By default, these are 'phone', 'chat', and 'email'."
        tags:
          type: array
          description: "A collection of categories under which this interaction can be classified \n\n Call reason or disposition are good uses. These are intended to be broad rather than uniquely identifying tags. Up to 20 are allowed. Note: Values have a maximum limit of 2,000 characters; any payload exceeding this will be truncated by the server to the first 2,000 characters."
          items:
            type: string
        ext_interaction_id:
          type: string
          description: "An identifier for this interaction, supplied from the calling system \n\n Ideally this will be a unique identifier, but non-unique identifiers such as an order number are allowed."
        external_url:
          type: string
          description: "A URL to link the request back to a ticketing system where it originated \n\n This link will be presented to users in the Agent Connect interface for easy access."
        do_not_send:
          type: boolean
          description: "A flag to indicate that no feedback request email should be sent as a result of this interaction\n\n This is used to ensure accurate reporting of interaction counts."
        brand:
          type: string
          description: The name that identifies a particular brand with a subdomain that requests will be associated with (only required for multi-brand companies).
        language:
          type: string
          description: "The standard ISO 639-1 language designator and optional 639-2 regional designator separated by hyphen (for example, en-US represents English US) \n\n This field is only required if you are set up with multiple languages."
        country:
          type: string
          description: "The country of residence of the customer, if known \n\n The country must be provided in ISO-3166 alpha-2 format. This is used for compliance with PII regulations and reporting."
        custom_properties:
          maxLength: 2000
          type: object
          properties: {}
          additionalProperties: false
          description: "Custom properties allow you to pass additional metadata about an interaction to Agent Connect. This data can then be used to filter responses, shown on each feedback response, and can be used for QA selection. \n\n The object must be key/value pairs of strings. New keys do not need to be pre-configured in Agent Connect; you can do that afterwards by contacting the Agent Connect team. The object must be a single level and does not support nesting. Note: Values have a maximum limit of 2,000 characters; any payload exceeding this will be truncated by the server to the first 2,000 characters."
      additionalProperties: false
    FeedbackRequestModel:
      required:
      - channel
      type: object
      properties:
        customer:
          type: object
          properties:
            custom_id:
              type: string
              description: Discuss with the Agent Connect team before using this field
            name:
              type: string
              description: Name of the customer that the interaction occured with; this is used to customize the header of the survey when available.
            email:
              type: string
              description: Email address of the customer that the interaction occured with
          additionalProperties: false
          description: Information about the customer with whom the interaction occured
        employee:
          type: object
          properties:
            custom_id:
              type: string
              description: "A custom identifier of the employee that this survey should be sent on behalf of\n\n This must match the custom identifier that this user is set up with on the Agent Connect platform. Either one of the email or custom_id fields are required."
            email:
              type: string
              description: "The email address of the employee that this survey should be sent on behalf of\n\n This must match the email that this user is set up with on the Agent Connect platform. Either one of the email or custom_id fields are required."
          additionalProperties: false
          description: Information about the employee who interacted with the customer
        channel:
          type: string
          description: "The service channel in which this interaction occurred \n\n This value must match the values that are set up within the platform. By default, these are 'phone', 'chat', and 'email'."
        tags:
          type: array
          description: "A collection of categories under which this interaction can be classified \n\n Call reason or disposition are good uses. These are intended to be broad rather than uniquely identifying tags. Up to 20 are allowed. Note: Values have a maximum limit of 2,000 characters; any payload exceeding this will be truncated by the server to the first 2,000 characters."
          items:
            type: string
        ext_interaction_id:
          type: string
          description: "An identifier for this interaction, supplied from the calling system \n\n Ideally this will be a unique identifier, but non-unique identifiers such as an order number are allowed."
        external_url:
          type: string
          description: "A URL to link the request back to a ticketing system where it originated \n\n This link will be presented to users in the Agent Connect interface for easy access."
        do_not_send:
          type: boolean
          description: "A flag to indicate that no feedback request email should be sent as a result of this interaction\n\n This is used to ensure accurate reporting of interaction counts."
        brand:
          type: string
          description: The name that identifies a particular brand with a subdomain that requests will be associated with (only required for multi-brand companies)
        language:
          type: string
          description: "The standard ISO 639-1 language designator and optional 639-2 regional designator separated by hyphen (for example, en-US represents English US) \n\n This field is only required if you are set up with multiple languages."
        country:
          type: string
          description: "The country of residence of the customer, if known \n\n The country must be provided in ISO-3166 alpha-2 format. This is used for compliance with PII regulations and reporting."
        custom_properties:
          maxLength: 2000
          type: object
          properties: {}
          additionalProperties: false
          description: "Custom properties allow you to pass additional metadata about an interaction to Agent Connect. This data can then be used to filter responses, shown on each feedback response, and can be used for QA selection. \n\n The object must be key/value pairs of strings. New keys do not need to be pre-configured in Agent Connect; you can do that afterwards by contacting the Agent Connect team. The object must be a single level and does not support nesting. Note: Values have a maximum limit of 2,000 characters; any payload exceeding this will be truncated by the server to the first 2,000 characters."
      additionalProperties: false
  securitySchemes:
    ApiKeyInHeader:
      type: apiKey
      name: x-api-key
      in: header
    JwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT