###
# How to edit this (dumb version for November 2021):
# 1. Go to https://editor.swagger.io/
# 2. Paste the full content of this file into the editor
# 3. Make edits and review them live
# 4. Paste editor content back into this file
# 5. Run the linter locally:
#   `npx @stoplight/spectral lint docs/v1/openapi.yaml --fail-severity hint`
# 6. Commit and push
#
# Note that you CAN use authenticated requests using https://editor.swagger.io/
###
openapi: 3.0.2
info:
  title: Conversocial Customer Profiles API
  termsOfService: https://www.verint.com/our-company/legal-documents/verintcom-terms-of-service/
  license:
    name: Verint Master Customer Agreement
    url: https://www.verint.com/our-company/legal-documents/master-agreement/
  contact:
    name: Conversocial Support
    url: https://support.conversocial.com
    email: support@conversocial.com
  # Verint Connect values
  x-vc-product_code: cnvs-aw-customer-profiles-api
  x-vc-product_suite: cnvs
  x-vc-app-id-uri: https://not-available-yet/
  description: |-
    # Customer Profiles API

    Customer Profiles allows agents using Conversocial to store data against
    Social Media Authors. A Social Media Author becomes available to the API
    whenever they contact customer service through Conversocial.

    The Customer Profiles API is a RESTful JSON API allowing programmatic access
    to data stored against Social Media Authors' Conversocial customer profile.

    Agents can store Notes, Tags, and Annotations against an Authors Profile. See relevant section for details about accessing each object type.

    An entire Customer profile including all notes, annotations, and tags can also
    be returned for a given `author_id`. Please see the Authors section for an explanation of what is available.

    ## Authentication

    The Customer Profiles API uses Basic Authentication to authenticate requests.

    Credentials are generated on the Conversocial platform by Account
    administrators. The credentials give you access to both the Customer Profiles
    API and the Data API.

    If you do not have API credentials, please contact your account manager.


    ## Data Location

    There are two locations the customer profile data is stored. One holds data for
    US clients and one holds data for EMEA/APAC/other clients.

    Because of this, there are two different URLs to access the Customer Profiles
    API.

    * USA: [https://ca-us.conversocial.com/api/](https://ca-us.conversocial.com/api/)
    * EMEA/APAC/other: [https://ca-eu.conversocial.com/api/](https://ca-eu.conversocial.com/api/)

    If you are unsure which URL to use, please contact your Account Manager.

    ## Making Requests

    Requests are made in REST style over HTTP. The request URL is made up of a **base_url**, dependent on the region; a **version** number, currently only v1; and an end point name.

    ```bash
    curl -u "iamausername:iamapassword" "https://ca-eu.conversocial.com/api/1/annotation-types"
    ```

    ### Response body
    The response body is JSON by default, no other types are supported.
    HTTP states codes are used to differentiate successful requests from error conditions. <br />
    A successful request will return a HTTP "200" status code

    ```json
    http status: "200"
    {
      "annotations": [{
        "type_id": "564b5d709bd56c14074805ec",
        "value": "me@example.com",
        "created_date": "2016-05-50T01:10:00",
        "moderator_id": f17
      }],
      "paging": {
        "next_page": "https://ca-eu.conversocial.com/api/1/annotations?page_token=123fwdwfwedq312123"
      }
    }
    ```

    An unsuccessful request will return a HTTP status code relevent to the error and a message describing the error encountered.

    ```json
    http status: 404
    {
      "status": "error",
      "message": "Customer with that ID does not exist",
    }
    ```

    ### Pagination
    Queries that return more than the maximum number of results (**50**) will be paginated. A `paging` object is returned with a `next_page` property that should be called to return the next page of results. The special query string parameter `page_token` stores the start position of the next set of results. Modifying this value will result in uninteded consequences.<br/>
    Page size can be changed with the `page_size` parameter.

    ```bash
    curl "https://ca-eu.conversocial.com/api/1/annotation-types?page_size=10"
    ```

    ```json
    {
      "annotationtypes": [
          {
              "format": "short",
              "id": "564b5d709bd56c14074805ec",
              "is_active": true,
              "name": "Email"
          },
          {
              "format": "short",
              "id": "564b5d709bd56c14074805ed",
              "is_active": true,
              "name": "Phone number"
          },
          {
              "format": "long",
              "id": "564b5d709bd56c14074805ee",
              "is_active": true,
              "name": "Address"
          }
        {...},
        {...},
        {...},
        {...},
        {...},
        {...}
      ],
      "paging": {
        "next_page": "https://ca-eu.conversocial.com/api/1/annotation-types?page_size=10&page_token=1ond02mi3e9h20eimn29dn2e0rj203r"
      }
    }
    ```

    ### Date Formats

    All dates and times stated in API responses are given in "Coordinated Universal Time", (UTC). These times can be converted to your local timezone after you receive the response. A time field will be formatted as follows `2023-11-18T11:20:24`
  version: "1.0.0"
externalDocs:
  description: Legacy Documentation
  url: https://api-docs.conversocial.com/landing/index.html
servers:
  - url: https://ca-us.conversocial.com/api/1
    description: Default API (US)
  - url: https://ca-eu.conversocial.com/api/1
    description: Default API (EU)
  - url: "{scheme}://{host}/{path}"
    description: Dynamic
    variables:
      scheme:
        enum:
        - http
        - https
        default: https
      host:
        default: ca-us.conversocial.com
      path:
        default: api/1
tags:
  - name: Annotation Types
    description: Operations on Annotation Type data
  - name: Annotations
    description: Operations on Annotations data
  - name: Authors
    description: Operations on Author data
  - name: Notes
    description: Operations on Note data
  - name: Tags
    description: Operations on Tag data

components:
  securitySchemes:
    basicAuth:
      description: |-
        [Provision and manage API credentials in the Agent Workspace application](https://app.conversocial.com/account/api/#/).
      type: http
      scheme: basic

  parameters:
    page_size:
      name: page_size
      in: query
      description: >
        The number of results to return. This value is capped at `50`.
      schema:
        type: integer
        default: 50

    page_token:
      name: page_token
      in: query
      description: >
        Pagination token, as provided in the `next_page` link.
      schema:
        type: string

    created_date_from:
      name: created_date_from
      in: query
      required: true
      description: >
        Filter objects that were created on and after this date
      schema:
        type: string

    created_date_to:
      name: created_date_to
      in: query
      required: true
      description: >
        Filter objects that were created before this date
      schema:
        type: string

  schemas:
    Paging:
      type: object
      properties:
        next_page:
          type: string
          example: "https://ca-eu.conversocial.com/api/1/annotations?page_token=123fwdwfwedq312123"
      required:
        - next_page

    Author:
      type: object
      description: |-
        The author is a single object encompassing all data in Customer profiles, stored against that _author_id.<br/><br/>

        The author is an object that details the Conversocial Agent Workspace author ID and the Customer Profiles internal ID. Each Social Media Author in Conversocial Agent Workspace has an ID, this is known as the `author_id`. This `author_id` is the Social Media platforms unique ID prepended with a letter e.g. a Facebook author_id will look something like `f:123121231231` whereas a Twitter `author_id` will be prepended with `t:`.<br/><br/>
      required:
        - author_ids
        - customer_profiles_id
      properties:
        author_ids:
          items:
            type: string
          type: array
          example: ["t:2825986021"]
          description: a list of the author IDs in Conversocial which are attached to this Customer profile
        customer_profiles_id:
          type: string
          example: "574805f264b5d8e9bd56c140"
          description: the ID of this Customer profile

    Note:
      type: object
      description: |-
        A note object represents a single text based note attached to a Social Media Author.
      required:
        - action
        - created_date
        - author
        - id
        - text
        - user
      properties:
        action:
          type: string
          example: "add_note"
        author:
          $ref: "#/components/schemas/Author"
        created_date:
          type: string
          example: "2021-11-17T17:02:06"
        id:
          type: string
          description: unique ID of the note
          example: "56e84b019bd56c6a6c692a5a"
        text:
          type: string
          description: contents of the note
          example: "A Thaum is the basic unit of magical strength."
        user:
          type: integer
          description: ID of the agent that created or modified this note
          example: 122

    Annotation:
      type: object
      description: |-
        An **annotation** is a key value piece of data that is stored against a Social Media Author. The annotations have types which are created through the Conversocial Agent Workspace interface, which act as the key.<br/><br>
        For instance, one of the default types is "Email" and an email value can be stored against it.

        ```json
        "email": "rincewind@unseenuniversity.disc"
        ```
        The annotations are exposed as an object with its value and its type.
      required:
        - action
        - created_date
        - author
        - id
        - text
        - type_id
        - user
      properties:
        action:
          type: string
          description: The action type that created this annotation
          example: "add_annotation"
        author:
          $ref: "#/components/schemas/Author"
        created_date:
          type: string
          example: "2021-11-17T17:02:06"
        id:
          type: string
          example: "564b5d8e9bd56c14074805f2"
          description: "unique ID of the annotation"
        text:
          type: string
          example: "rincewind@unseenuniversity.ac.disc"
          description: "value of the annotation"
        type_id:
          type: string
          example: "564b5d8e9bd56c14074805f2"
          description: "unique ID of the annotation"
        user:
          type: integer
          example: 16
          description: "ID of the agent that created or modified this annotation"

    AnnotationType:
      type: object
      description: |-
        An **annotation_type** is the key for an **Annotation**. These are created through Conversocial Agent Workspace and every annotation will have a _type_id_ that corresponds to an **annotation_type**.
      required:
        - format
        - id
        - is_active
        - name
      properties:
        format:
          type: string
          example: "short"
        id:
          type: string
          example: "564b5d8e9bd56c14074805f2"
          description: "the ID of the annotation type"
        is_active:
          type: boolean
          description: "If true, this field can currently be used by agents"
        name:
          type: string
          example: "Email"

    Tag:
      type: object
      description: |-
        A **tag** is a simple string attached to a Customer Profile. Any number of tags can be attached to a Social Media Author as long as these have been defined through the Conversocial Agent Workspace interface. In a similar fashion to Notes and Annotations, tags are represented by a tag object with properties.
      required:
        - action
        - created_date
        - author
        - id
        - name
        - user
      properties:
        action:
          type: string
          description: action type that created this tag
          example: "add_tag"
        author:
          $ref: "#/components/schemas/Author"
        created_date:
          type: string
          example: "2021-11-17T17:02:06"
        id:
          type: string
          example: "564b5d8e9bd56c14074805f2"
        name:
          type: string
          example: "VIP"
        user:
          type: integer
          example: 654
          description: ID of the agent that created or modified this annotation

    AuthorResponse:
      type: object
      description: |-
        An AuthorResponse fully represents all active properties of an Authors Profile. Retrieved by its author_id property, it returns all notes, annotations, and tags.<br/><br/>

        **Note**: The inner `author` object may not be set on items inside these arrays: `notes`, `tags`, `annotations`.
      required:
        - customer
        - status_code
        - success
      properties:
        customer:
          properties:
            annotations:
              type: array
              items:
                $ref: "#/components/schemas/Annotation"
            author:
              $ref: "#/components/schemas/Author"
            notes:
              type: array
              items:
                $ref: "#/components/schemas/Note"
            tags:
              type: array
              items:
                $ref: "#/components/schemas/Tag"
          required:
            - annotations
            - author
            - notes
            - tags
          title: Customer
          type: object
        status_code:
          type: integer
          example: 200
        success:
          type: boolean
          example: true

    AnnotationsResponse:
      type: object
      required:
        - annotations
        - paging
      properties:
        annotations:
          type: array
          items:
            $ref: "#/components/schemas/Annotation"
        paging:
          $ref: "#/components/schemas/Paging"

    AnnotationTypesResponse:
      type: object
      required:
        - annotationtypes
        - paging
      properties:
        annotationtypes:
          type: array
          items:
            $ref: "#/components/schemas/AnnotationType"
        paging:
          $ref: "#/components/schemas/Paging"

    NotesResponse:
      type: object
      required:
        - notes
        - paging
      properties:
        notes:
          type: array
          items:
            $ref: "#/components/schemas/Note"
        paging:
          $ref: "#/components/schemas/Paging"

    TagsResponse:
      type: object
      required:
        - tags
        - paging
      properties:
        tags:
          type: array
          items:
            $ref: "#/components/schemas/Tag"
        paging:
          $ref: "#/components/schemas/Paging"

    UnauthorizedResponse:
      type: object
      required:
        - description
        - message
        - status_code
        - success
      properties:
        description:
          type: string
        message:
          type: string
        status_code:
          type: integer
        success:
          type: boolean
      example:
        description: Authorization header missing from request
        message: Not Authorized
        status_code: 401
        success: false


    ForbiddenResponse:
      type: object
      required:
        - description
        - message
        - status_code
        - success
      properties:
        description:
          type: string
        message:
          type: string
        status_code:
          type: integer
        success:
          type: boolean
      example:
        description: Error connecting to the API authorization server
        message: You are not authorized to make requests to this subdomain please use ca-eu
        status_code: 403
        success: false


    ErrorResponse:
      type: object
      required:
        - description
        - message
        - status_code
        - success
      properties:
        description:
          type: string
        message:
          type: string
        status_code:
          type: integer
        success:
          type: boolean
      example:
        description: There has been an error with your request
        message: "'authenticated'"
        status_code: 500
        success: false

security:
  - basicAuth: []

paths:
  /author/{author_guid}:
    get:
      tags:
        - Authors
      summary: Returns all data for a single Author
      description: >
        A request requires a valid `author_guid`. These can be found using the Conversocial Data API.<br/><br/>
        Note that the `author` field on sub-objects like Notes is hoisted to the top-level response object in order to avoid data duplication.
      operationId: getAuthorByGuid
      parameters:
        - name: author_guid
          required: true
          in: path
          description: >
            Author GUID
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "500":
          description: Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /annotations:
    get:
      tags:
        - Annotations
      summary: Returns a list of annotation objects by created date
      description: >
        A request requires a date range that can be supplied by using `created_date_from` and `created_date_to`.
      operationId: getAnnotations
      parameters:
        - $ref: "#/components/parameters/created_date_from"
        - $ref: "#/components/parameters/created_date_to"
        - $ref: "#/components/parameters/page_size"
        - $ref: "#/components/parameters/page_token"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnnotationsResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenResponse"
        "500":
          description: Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /annotation-types:
    get:
      tags:
        - Annotation Types
      summary: Returns a list of Annotation Type objects
      description: |-
        Get a paginated list of Annotation Type objects.
      operationId: getAnnotationTypes
      parameters:
        - $ref: "#/components/parameters/page_size"
        - $ref: "#/components/parameters/page_token"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnnotationTypesResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenResponse"
        "500":
          description: Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /notes:
    get:
      tags:
        - Notes
      summary: Returns a list of Note objects
      description: |-
        Get an optionally date-filtered paginated list of Note objects.
      operationId: getNotes
      parameters:
        - $ref: "#/components/parameters/created_date_from"
        - $ref: "#/components/parameters/created_date_to"
        - $ref: "#/components/parameters/page_size"
        - $ref: "#/components/parameters/page_token"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotesResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenResponse"
        "500":
          description: Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /tags:
    get:
      tags:
        - Tags
      summary: Returns a list of Tag objects
      description: |-
        Get an optionally date-filtered paginated list of Tag objects.
      operationId: getTags
      parameters:
        - $ref: "#/components/parameters/created_date_from"
        - $ref: "#/components/parameters/created_date_to"
        - $ref: "#/components/parameters/page_size"
        - $ref: "#/components/parameters/page_token"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagsResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenResponse"
        "500":
          description: Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
