openapi: 3.0.1
info:
  title: Gladly Agents Tasks API
  version: '1.0'
  description: '# Introducing the Gladly API


    At Gladly, we believe that customer service is best when it''s a conversation.

    That means more than just helping customers with one-off questions or issues: it''s about making them feel known, valued, and respected for the individuals they are.


    The Gladly API was built to help facilitate those relationships, providing agents with the rich customer context

    they need to deliver seamless experiences that make customers feel like they''re more than just a number in a sea of others.


    # Overview


    You can integrate easily with Gladly by calling Gladly''s [REST API](#section/Overview/REST-API)

    and implementing the [Lookup API](#section/Overview/Lookup-API) to provide data from your own services.


    Some examples of what you do through Gladly APIs include managing customer profile data, interacting with a customer''s timeline,

    providing the latest information about a customer''s orders, and more.


    ## REST API


    Clients can access the **REST API** via HTTPS at your organization''s Gladly domain (e.g. `https://{organization}.gladly.com`).


    Resources follow REST semantics and utilize industry-standard HTTP verbs, response codes, and authentication schemes.

    In addition, all responses and payloads are in JSON with consistent error codes and formats.


    ## Lookup API


    The Gladly **Lookup API** allows your organization to provide data services to power the agent''s experience with a complete view of your customers''

    information, transactions, and activity. You can provide a web service that implements the Lookup API and Gladly will call it when that data is needed.


    Like the REST API, the Lookup API is specified using REST semantics, and exchanges JSON requests and responses authenticated and signed with secure keys.


    Gladly will perform lookups when certain activities occur within Gladly, such as when a customer''s profile is loaded.


    A detailed overview of Lookup Adaptor architecture, requests, resposnes and more can be found [here](https://help.gladly.com/developer/docs/lookup-adapter-introduction).


    ## Testing


    Test the myriad possibilities of the Gladly API in a safe, secure space. We''ll enable the Gladly API in a separate sandbox environment, so you can experiment freely without impacting your production environment (or vice versa).


    Your sandbox environment is accessible at `https://{organization}.gladly.qa`, where `organization` is your company name. For specific API endpoints, see documentation below.


    # Getting Started


    Think of this section as getting the keys to unlocking your access to the Gladly APIs.

    First, you''ll need to set up an account with the necessary API [permissions](#/section/Getting-Started/Permissions).

    With these permissions, you can then go on to create the [API Token(s)](#section/Getting-Started/Creating-API-Tokens) you need to access Gladly''s API [resources](#section/Overview/Resources).


    ## Permissions


    Gladly Administrators can set API permissions on an agent-by-agent basis.

    We''ll discuss how this maps to API access in the section on [authentication](#section/Authentication) below.


    To allow a user to create API tokens and access the API:

    1. Log in to your Gladly instance.

    2. Open the menu on the top left-hand corner of the page.

    3. Navigate to **Settings** > **Users*

    4. Search and click the user profile you wish to give access to.

    5. You''ll see a permission called **API User**. Select it, while making sure to keep the user''s **Agent** role intact.

    6. Hit **Save** to give access.


    ![Agent profile screen](assets/permissions-agent.png)


    We recommend creating a dedicated user to make API calls, whose account won''t be used for agent and organization management.

    This will help you with any future audits of API activity vs. agent activity.


    ## Creating API Tokens


    You must create an API token to access Gladly API resources (see above [Permissions](#/section/Getting-Started/Permissions)).

    If your profile already has access to the **API User** permission, you''ll see a menu item titled **More settings**. Click **More settings**:


    ![API Token Menu](assets/permissions-token-nav.png)


    Click **API Tokens**, then the **Create Token** button on the upper right-hand corner of the page:


    ![API Token Add](assets/permissions-token-add.png)


    A token will be generated and named, by default, **New Token** (though depending on whether you have existing tokens, it may be named New Token 2, or New Token 3, etc.).

    You can rename the token to something more easily referenceable by clicking the name to edit.


    This token will be associated with your agent profile, which we refer to as the API User in this document.


    ![API Token View](assets/permissions-token-view.png)


    For security purposes, you''ll only see a new token once before you navigate away from the page.


    ## Replacing/Rotating API Tokens


    Should you lose this token, or wish to rotate your application keys, you can do the following:


    1. Generate a new token.

    2. Store the new token in a secure location.

    3. Delete the old token.

    4. Update your applications/scripts with the new token.


    # Authentication


    <!-- ReDoc-Inject: <security-definitions> -->'
servers:
- url: https://{organization}.gladly.com/api/v1
  description: Production
  variables:
    organization:
      default: organization
      description: Your Gladly organization subdomain
- url: https://{organization}.gladly.qa/api/v1
  description: Sandbox
  variables:
    organization:
      default: organization
      description: Your Gladly QA organization subdomain
security:
- basicAuth: []
tags:
- name: Tasks
  description: 'A task is a way to create and do internal follow-up work for a customer within Gladly. Tasks have a due date, an assignee, a description of what is needed for a customer, and can be commented on. These can be created through the API to assign items to work within Gladly.

    ![Task](assets/task.png)

    '
paths:
  /api/v1/tasks:
    post:
      operationId: createTaskAndCustomer
      tags:
      - Tasks
      summary: Create Task
      description: 'To add tasks to the timeline for a customer specified by identifying information. If the customer doesn''t exist, a new customer profile is created.

        '
      requestBody:
        description: Task to create
        content:
          application/json:
            schema:
              required:
              - body
              - dueAt
              - assignee
              - customer
              properties:
                id:
                  maxLength: 50
                  type: string
                  description: Specifies the id of the task
                  example: pOVVdzweSumI4bFxjlT8LA
                assignee:
                  title: Assignee
                  description: Inbox and Agent assignee for a Task
                  required:
                  - inboxId
                  properties:
                    inboxId:
                      type: string
                      description: Id of the inbox the task should be assigned to. You can look up the id in the Gladly UI.
                      example: NFpDZtfqhk2pI6fjaVDlFf
                    agentId:
                      type: string
                      description: Id of the agent the task should be assigned to. You can look up the id in the Gladly UI.
                      example: zGaHXjD4SR-moMR9LbULDa
                body:
                  maxLength: 10000
                  type: string
                  description: Text to describe what task to complete. Constrained HTML [Rich Content](#tag/Rich-Content) is supported.
                  example: Call customer back with information about booking
                dueAt:
                  description: Time when the task will be due. This must be set to a time in the future.
                  type: string
                  format: RFC3339
                  example: '2020-03-15T06:13:00.125Z'
                customer:
                  title: Customer Specification
                  description: Specifies the customer this belongs to. You must provide exactly one of the values.
                  type: object
                  properties:
                    emailAddress:
                      type: string
                      example: michelle.smith@example.org
                    mobilePhone:
                      type: string
                      example: '+16505551987'
      responses:
        '201':
          description: task created
          headers:
            Location:
              schema:
                type: string
                description: path to the created task
                example: /api/v1/tasks/OOrlNMXeS72gs_WEX2TtMg
        '400':
          description: Invalid field(s) in request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /api/v1/customers/{customerId}/tasks:
    post:
      tags:
      - Tasks
      summary: Create Task for Customer
      description: 'Add a task to an existing customer''s conversation timeline

        '
      operationId: createTask
      parameters:
      - in: path
        name: customerId
        schema:
          type: string
        required: true
        description: 'Id of the customer associated with the task to create.


          You can look up the id using the [Find customers](index.html#tag/Customers) API.

          '
      requestBody:
        description: Create Task
        content:
          application/json:
            schema:
              title: Create Task
              description: A task to be completed for a specific customer
              required:
              - body
              - dueAt
              - assignee
              properties:
                id:
                  maxLength: 50
                  type: string
                  description: Unique task id. Must be URL safe and under 50 characters. An id will be automatically generated if one is not included.
                  example: pOVVdzweSumI4bFxjlT8LA
                assignee:
                  $ref: '#/paths/~1api~1v1~1tasks/post/requestBody/content/application~1json/schema/properties/assignee'
                body:
                  maxLength: 10000
                  type: string
                  description: Text to describe what task to complete. Constrained HTML [Rich Content](#tag/Rich-Content) is supported.
                  example: Call customer back with information about booking
                dueAt:
                  description: Time when the task will be due. This must be set to a time in the future.
                  type: string
                  format: RFC3339
                  example: '2020-03-15T06:13:00.125Z'
      responses:
        '201':
          description: task created
          headers:
            Location:
              schema:
                type: string
                description: path to the created task
                example: /api/v1/tasks/OOrlNMXeS72gs_WEX2TtMg
        '400':
          description: Invalid field(s) in request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Customer with customerId does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrors'
        '409':
          description: Specified id is in use
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - attr: newConversationItems
                  code: taken
                  detail: task already exists
    get:
      tags:
      - Tasks
      summary: List Tasks
      description: "Fetch all tasks for a customer.\n\nThe list is not paginated and will return at most 2000 tasks. The tasks are returned in descending order by timestamp. \nThe `Gladly-Limited-Data` header flag in the response will indicate if the customer has more tasks than returned.        \n\nTo see and act on any newly created tasks, webhooks can be used to listen for task related events.\nTasks older than the limit can be viewed using the Task Export.\n"
      operationId: getTasks
      parameters:
      - in: path
        name: customerId
        schema:
          type: string
        required: true
        description: 'Id of the customer whose tasks you''d like to view.

          '
      - in: query
        name: status
        description: 'Fetch tasks with the provided status.

          '
        required: false
        schema:
          type: string
          enum:
          - OPEN
          - CLOSED
      responses:
        '200':
          description: Array of tasks
          content:
            application/json:
              schema:
                title: Tasks
                type: array
                items:
                  $ref: '#/paths/~1api~1v1~1tasks~1%7BtaskId%7D/get/responses/200/content/application~1json/schema'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: A customer with the given id does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrors'
  /api/v1/tasks/{taskId}:
    patch:
      tags:
      - Tasks
      summary: Update Task
      description: 'Update an existing task

        '
      operationId: updateTask
      parameters:
      - in: path
        name: taskId
        schema:
          type: string
        required: true
        description: 'Id of the task that is to be updated

          '
      requestBody:
        description: Task properties to create
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                  - OPEN
                  - CLOSED
                body:
                  maxLength: 10000
                  type: string
                  description: Text to describe what task to complete. Constrained HTML [Rich Content](#tag/Rich-Content) is supported.
                  example: Call customer back with information about booking
                dueAt:
                  type: string
                  description: Due date of task
                  format: RFC3339 with millis
                  example: '2021-04-11T14:09:23.000Z'
                assignee:
                  type: object
                  $ref: '#/paths/~1api~1v1~1tasks/post/requestBody/content/application~1json/schema/properties/assignee'
      responses:
        '204':
          description: The task was created task
        '400':
          description: Invalid field(s) in request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Task with taskId does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrors'
    get:
      tags:
      - Tasks
      summary: Get Task
      description: 'Get task

        '
      operationId: getTask
      parameters:
      - in: path
        name: taskId
        schema:
          type: string
        required: true
        description: 'Id of the task requested

          '
      responses:
        '200':
          description: Returns requested task
          content:
            application/json:
              schema:
                title: Task
                type: object
                required:
                - customerId
                - content
                - timestamp
                properties:
                  id:
                    type: string
                    description: the id of the task
                    example: pOVVdzweSumI4bFxjlT8LA
                  customerId:
                    type: string
                    description: The Id of the customer profile to which the task is associated.
                    example: gHufx-U3QqOmhvFuViceTw
                  timestamp:
                    type: string
                    format: RFC3339
                    description: Time the task occurred
                    example: '2019-07-03T04:30:12.07Z'
                  createdBy:
                    allOf:
                    - $ref: '#/paths/~1api~1v1~1conversation-items/post/responses/200/content/application~1json/schema/properties/responder'
                    - example:
                        id: gHufx-U3QqOmhvFuViceTw
                        type: CUSTOMER
                  assignee:
                    $ref: '#/paths/~1api~1v1~1tasks/post/requestBody/content/application~1json/schema/properties/assignee'
                  body:
                    maxLength: 10000
                    type: string
                    description: Text to describe what task to complete. Constrained HTML [Rich Content](#tag/Rich-Content) is supported.
                    example: Call customer back with information about booking
                  dueAt:
                    description: Time when the task will be due. This must be set to a time in the future.
                    type: string
                    format: RFC3339
                    example: '2020-03-15T06:13:00.125Z'
                  status:
                    type: string
                    enum:
                    - OPEN
                    - CLOSED
        '404':
          description: Given task id does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrors'
  /api/v1/tasks/{taskId}/comments:
    post:
      tags:
      - Tasks
      summary: Add Task Comment
      description: 'Create a comment on a task.  Note that you can’t create comments on closed tasks.

        ![Task Comment](assets/task-comment.png)

        '
      operationId: createTaskComment
      parameters:
      - in: path
        name: taskId
        schema:
          type: string
        required: true
        description: 'Id of the task that will be commented on.

          '
      requestBody:
        description: Add comment to task
        content:
          application/json:
            schema:
              title: Task Comment Request
              description: Add a comment to an open task.
              type: object
              required:
              - agentId
              - message
              properties:
                id:
                  maxLength: 50
                  type: string
                  description: Unique comment id. Must be URL safe and under 50 characters. An id will be automatically generated if one is not included.
                  example: pOVVdzweSumI4bFxjlT8LA
                agentId:
                  type: string
                  description: the id of the agent making the comment
                  example: dzweSumI4bFxjlT8LApOVV
                comment:
                  maxLength: 10000
                  type: string
                  description: Comment body
                  example: Return call to customer
      responses:
        '201':
          description: comment added
          headers:
            Location:
              schema:
                type: string
                description: path to the created task
                example: /api/v1/tasks/OOrlNMXeS72gs_WEX2TtMg/comments/77323sf2fj2k
        '400':
          description: Invalid field(s) in request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Task with taskId does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrors'
    get:
      tags:
      - Tasks
      summary: Get Task Comments
      description: 'The comments are returned in ascending order by createdAt timestamp. The list is not paginated and will return at most 1000 task comments. The `Gladly-Limited-Data` header flag in the response will indicate if the task has more comments than returned.


        To see and act on any newly created task comments, webhooks can be used to listen to any task comment related events.

        '
      operationId: getTaskComments
      parameters:
      - in: path
        name: taskId
        schema:
          type: string
        required: true
        description: 'Id of the task comments are requested for.

          '
      responses:
        '200':
          description: All comments that belong to task
          content:
            application/json:
              schema:
                title: Task Comments
                type: array
                items:
                  $ref: '#/paths/~1api~1v1~1tasks~1%7BtaskId%7D~1comments~1%7BcommentId%7D/get/responses/200/content/application~1json/schema'
        '404':
          description: Task with taskId does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrors'
  /api/v1/tasks/{taskId}/comments/{commentId}:
    get:
      tags:
      - Tasks
      summary: Get Task Comment
      description: 'Get task comment.

        '
      operationId: getTaskComment
      parameters:
      - in: path
        name: taskId
        schema:
          type: string
        required: true
        description: 'Task id

          '
      - in: path
        name: commentId
        schema:
          type: string
        required: true
        description: 'Comment id

          '
      responses:
        '200':
          description: Returns task comment
          content:
            application/json:
              schema:
                title: Task Comment
                type: object
                properties:
                  id:
                    type: string
                    description: The id of the comment.
                    example: pOVVdzweSumI4bFxjlT8LA
                  agentId:
                    type: string
                    description: The id of the agent who owns the message.
                    example: dzweSumI4bFxjlT8LApOVV
                  comment:
                    type: string
                    description: Comment body.
                    example: Return call to customer.
                  taskId:
                    type: string
                    description: The id of the task being commented on.
                    example: dzweSumI4bFxjlT8LApOVV
                  createdAt:
                    type: string
                    format: RFC3339
                    example: '2020-03-15T06:13:00.125Z'
                    description: The time this comment was created
        '404':
          description: Comment with commentId does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrors'
components:
  schemas:
    NotFoundErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          example:
          - code: not_exist
            detail: entity does not exist
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          example:
          - attr: content
            code: blank
            detail: content cannot be blank
    Error:
      type: object
      properties:
        attr:
          type: string
          description: Identifies the field causing the error
        code:
          type: string
          description: Code indicating the error type
        detail:
          type: string
          description: More details describing what went wrong
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: 'Gladly API uses token-based **Basic Authentication**. API tokens are associated with designated Gladly users.

        To create and use an API token, your user must have the API User permission. An API token can be used to perform any API request without restriction.


        | user name   | password  |

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

        | agent email | API token |


        The credentials must be passed via an `Authorization` HTTP header. All requests must be made over HTTPS.


        ```shell

        curl -u user@organization.com:$GLADLY_API_TOKEN \

        https://organization.gladly.com/api/v1/organization

        ```

        '
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic auth — username is the API user email; password is the API token. Requires the "API User" permission.
x-tagGroups:
- name: REST API
  tags:
  - Agents
  - Public Answer
  - Answer Management
  - Audiences
  - Business Hours
  - Communications
  - Conversations
  - Customers
  - Events
  - Export
  - Freeform Topics
  - Inboxes
  - Organization
  - Proactive Conversations
  - Reports
  - Tasks
  - Teams
  - User Identity
  - Topics
  - Webhooks
- name: Webhooks
  tags:
  - Summary
  - Payloads
- name: Lookup API
  tags:
  - Customer Lookup
- name: Resources
  tags:
  - Versioning
  - Error Handling
  - Rate Limit
  - Rich Content
  - Launching Soon