openapi: 3.1.0
info:
  title: Brand API - Tasks
  description: API for retrieving tasks, which are assignments for partners or other members of your impact.com account.
  version: v12
servers:
- url: https://api.impact.com
paths:
  /Advertisers/{AccountSID}/Programs/{ProgramId}/Tasks:
    get:
      summary: List All Tasks
      description: Returns a list of existing, non-archived tasks for a specific program, with optional date filtering.
      operationId: listTasks
      tags:
      - Tasks
      parameters:
      - name: AccountSID
        in: path
        required: true
        schema:
          type: string
        description: Your unique Account SID.
      - name: ProgramId
        in: path
        required: true
        schema:
          type: integer
        description: The ID of the program (campaign) the tasks belong to.
      - name: DateLastUpdatedBefore
        in: query
        schema:
          type: string
          format: date-time
        description: Filter for tasks last updated before this date.
      - name: DateLastUpdatedAfter
        in: query
        schema:
          type: string
          format: date-time
        description: Filter for tasks last updated after this date.
      responses:
        '200':
          description: A paginated list of task objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Tasks:
                    type: array
                    description: The list of task objects.
                    items:
                      $ref: '#/components/schemas/Task'
  /Advertisers/{AccountSID}/Programs/{ProgramId}/Tasks/{TaskId}:
    get:
      summary: Retrieve a Task
      description: Retrieves the details of a single, existing task by its unique ID.
      operationId: getTaskById
      tags:
      - Tasks
      parameters:
      - name: AccountSID
        in: path
        required: true
        description: Your unique Account SID.
        schema:
          type: string
      - name: ProgramId
        in: path
        required: true
        description: The ID of the program the task belongs to.
        schema:
          type: integer
      - name: TaskId
        in: path
        required: true
        description: The unique identifier for the task.
        schema:
          type: integer
      responses:
        '200':
          description: A single task object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
components:
  schemas:
    Task:
      type: object
      properties:
        Id:
          type: string
          description: The unique identifier for the task.
          example: '3562529'
        Reference:
          $ref: '#/components/schemas/TaskReference'
          description: Identifies the partner by ID and custom values.
        Details:
          $ref: '#/components/schemas/TaskDetails'
          description: Details about the task itself.
        Attachments:
          type: array
          description: Details about each attachment.
          items:
            $ref: '#/components/schemas/Attachment'
        DueDate:
          type: string
          format: date-time
          description: Date and time at which the task is due (ISO 8601).
          example: 2021-08-31T04:00:00.000+0000
        AssigneeUser:
          $ref: '#/components/schemas/User'
          description: The user of the partner account that the task is assigned to.
        AssigneeAccount:
          type: string
          description: Name of the partner account that the task is assigned to.
          example: Acme Partners
        TotalActions:
          type: integer
          description: Total number of actions that have been recorded for this task.
          example: 0
        Actions:
          type: array
          description: Describes actions that have occurred on this task.
          items:
            type: object
        TotalComments:
          type: integer
          description: Total number of comments that have been recorded for this task.
          example: 1
        Comments:
          type: array
          description: Details about each comment on this task.
          items:
            $ref: '#/components/schemas/Comment'
        DateCreated:
          type: string
          format: date-time
          description: The date and time the task was created.
          example: 2021-08-18T16:47:21.000+0000
        DateLastUpdated:
          type: string
          format: date-time
          description: The date and time the task was last updated.
          example: 2021-08-18T22:45:42.000+0000
        CreatedBy:
          $ref: '#/components/schemas/User'
          description: The user that created the task.
        LastUpdatedBy:
          $ref: '#/components/schemas/User'
          description: The user that last updated the task.
    TaskReference:
      type: object
      properties:
        PartnerId:
          type: integer
          description: Unique identifier of the partner this task is about.
          example: 2552842
        PartnerValue1:
          type: string
          description: Custom partner tracking value 1.
          example: vip
        PartnerValue2:
          type: string
          description: Custom partner tracking value 2.
          example: north-america
        PartnerValue3:
          type: string
          description: Custom partner tracking value 3.
          example: tennis
    TaskDetails:
      type: object
      properties:
        Summary:
          type: string
          description: Title of the task.
          example: Acme Rewards Card Update
        Description:
          type: string
          description: Detailed description of the task.
          example: The Acme Rewards Card APR has changed, please update your ads to reflect this new value.
        Urgent:
          type: boolean
          description: Whether the task is marked urgent.
          example: true
        State:
          type: string
          description: The current state of the task.
          enum:
          - NEW
          - INPROGRESS
          - DUPLICATE
          - INVALID
          - BLOCKED
          - COMPLETED
          - APPROVED
          example: INPROGRESS
        Type:
          type: string
          description: The category of the task.
          enum:
          - COMPLIANCE
          - TECHNICAL
          - GENERAL
          - CREATIVE
          - FINANCE
          - CONTRACTS
          - ANALYTICS
          - SEARCH_ENGINE_MONITORING
          example: COMPLIANCE
        SubtypeId:
          type: integer
          nullable: true
          description: The unique identifier of the task subtype.
          example: 1001
        SubtypeName:
          type: string
          nullable: true
          description: The display name of the task subtype.
          example: Tracking Issue
        ResolutionId:
          type: string
          nullable: true
          description: The unique identifier of the task resolution.
          example: '5'
        ResolutionName:
          type: string
          nullable: true
          description: The display name of the task resolution.
          example: Resolved
    Attachment:
      type: object
      properties:
        Id:
          type: string
          description: Unique identifier for the attachment.
          example: task_1223456_988957a0-e0ed-4f16-984b-f5a9259e6be7
        Filename:
          type: string
          description: Original filename of the attachment.
          example: acme_reward_card_details.pdf
        Location:
          type: string
          format: uri
          description: URL to download the attachment.
          example: https://cdn.example.com/task_123456_988957a0-e0ed-4f16-984b-f5a9259e6be7.pdf
    User:
      type: object
      properties:
        Username:
          type: string
          description: The user's username.
          example: Wile E. Coyote
        EmailAddress:
          type: string
          format: email
          description: The user's email address.
          example: wilecoyote@example.com
    Comment:
      type: object
      properties:
        Id:
          type: integer
          description: Unique identifier for the comment.
          example: 98765
        Comment:
          type: string
          description: The comment text.
          example: I've updated our home page with the latest ads, see attached screenshot.
        Commenter:
          type: string
          description: Name of the user who posted the comment.
          example: Wile E. Coyote
        Attachments:
          type: array
          description: Details about each attachment on the comment.
          items:
            $ref: '#/components/schemas/Attachment'
