Unify Tasks API

openapi: 3.0.0
info:
  title: Unify Tasks API
  summary: List and manage tasks within the Unify platform.
  version: '1'
  termsOfService: https://www.unifygtm.com/legal/terms-and-conditions
  contact:
    name: Unify Support
    url: https://www.unifygtm.com/support
    email: support@unifygtm.com
servers:
- url: https://api.unifygtm.com
  variables: {}
security:
- ApiKeyAuth: []
tags:
- name: Tasks
paths:
  /tasks/v1/tasks:
    get:
      operationId: list_tasks
      description: 'List tasks — units of outreach work (emails, phone calls, LinkedIn

        touches, and action items) tied to a person and assignable to a user.

        By default, tasks are ordered by `created_at` descending, with `id`

        descending for tasks created at the same time. Supply the returned

        `next_cursor` unchanged to retrieve the next page with the same filters

        and sort order. Pages at most 100 tasks per request; to export more

        than a few hundred tasks, create an asynchronous query job instead.'
      parameters:
      - name: cursor
        in: query
        required: false
        description: Opaque cursor returned by the previous page.
        schema:
          type: string
        explode: false
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
        explode: false
      - name: sort_by
        in: query
        required: false
        description: Field to sort by. Defaults to `created_at`.
        schema:
          $ref: '#/components/schemas/TaskSortField'
        explode: false
      - name: sort_order
        in: query
        required: false
        description: Sort direction. Defaults to descending.
        schema:
          $ref: '#/components/schemas/SortOrder'
        explode: false
      - name: status
        in: query
        required: false
        description: Filter tasks by status.
        schema:
          $ref: '#/components/schemas/TaskStatus'
        explode: false
      - name: assigned_user_id
        in: query
        required: false
        description: Filter tasks by assignee.
        schema:
          $ref: '#/components/schemas/uuid'
        explode: false
      - name: person_id
        in: query
        required: false
        description: Filter tasks by person.
        schema:
          $ref: '#/components/schemas/uuid'
        explode: false
      - name: person_email
        in: query
        required: false
        description: 'Filter tasks by the person''s exact email address. Cannot be combined with

          `person_id`. Email matching is case-insensitive.'
        schema:
          $ref: '#/components/schemas/email'
        explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTasksResponse'
        '400':
          description: Response for any operation that results in a bad request error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - bad_request
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/UResponses.BadRequestError'
                  message:
                    type: string
                description: Response for any operation that results in a bad request error.
        '401':
          description: Response for any operation that results in an unauthorized error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - unauthorized
                  message:
                    type: string
                description: Response for any operation that results in an unauthorized error.
        '403':
          description: Response for any operation that results in a forbidden error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - forbidden
                  message:
                    type: string
                description: Response for any operation that results in a forbidden error.
        '429':
          description: Response for any operation that exceeds a rate limit.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - rate_limited
                  message:
                    type: string
                description: Response for any operation that exceeds a rate limit.
        '500':
          description: Response for any operation that results in an internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - error
                  message:
                    type: string
                description: Response for any operation that results in an internal server error.
      tags:
      - Tasks
      x-mcp-tool:
        readOnlyHint: true
        openWorldHint: false
    post:
      operationId: create_task
      description: 'Create a task for a person. The request is discriminated by `type`:

        `EMAIL` tasks carry a draft subject, body, and the mailbox to send from,

        while phone call, LinkedIn, and action item tasks carry an optional

        note.'
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTaskResponse'
        '400':
          description: Response for any operation that results in a bad request error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - bad_request
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/UResponses.BadRequestError'
                  message:
                    type: string
                description: Response for any operation that results in a bad request error.
        '401':
          description: Response for any operation that results in an unauthorized error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - unauthorized
                  message:
                    type: string
                description: Response for any operation that results in an unauthorized error.
        '403':
          description: Response for any operation that results in a forbidden error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - forbidden
                  message:
                    type: string
                description: Response for any operation that results in a forbidden error.
        '404':
          description: Response for any operation that results in a not found error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - not_found
                  message:
                    type: string
                description: Response for any operation that results in a not found error.
        '409':
          description: Response for any operation that results in a conflict error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - conflict
                  message:
                    type: string
                description: Response for any operation that results in a conflict error.
        '429':
          description: Response for any operation that exceeds a rate limit.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - rate_limited
                  message:
                    type: string
                description: Response for any operation that exceeds a rate limit.
        '500':
          description: Response for any operation that results in an internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - error
                  message:
                    type: string
                description: Response for any operation that results in an internal server error.
      tags:
      - Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
      x-mcp-tool:
        destructiveHint: false
        openWorldHint: false
  /tasks/v1/tasks/query-jobs:
    post:
      operationId: create_task_query_job
      description: 'Start an asynchronous query job that exports tasks matching the optional

        filter; omitting `filter` exports all tasks. Poll the job until it is

        `FINISHED`, then page through the results.'
      parameters: []
      responses:
        '201':
          description: Response returned when creating a Bulk API query job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateBulkApiJobSuccessResponse'
        '400':
          description: Response for any operation that results in a bad request error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - bad_request
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/UResponses.BadRequestError'
                  message:
                    type: string
                description: Response for any operation that results in a bad request error.
        '401':
          description: Response for any operation that results in an unauthorized error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - unauthorized
                  message:
                    type: string
                description: Response for any operation that results in an unauthorized error.
        '429':
          description: Response for any operation that exceeds a rate limit.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - rate_limited
                  message:
                    type: string
                description: Response for any operation that exceeds a rate limit.
        '500':
          description: Response for any operation that results in an internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - error
                  message:
                    type: string
                description: Response for any operation that results in an internal server error.
      tags:
      - Tasks
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBulkApiTasksJobRequest'
    get:
      operationId: list_task_query_jobs
      description: List task query jobs, optionally filtered by status.
      parameters:
      - name: cursor
        in: query
        required: false
        description: Opaque cursor returned by the previous page.
        schema:
          type: string
        explode: false
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
        explode: false
      - name: status
        in: query
        required: false
        description: Filter jobs by status.
        schema:
          $ref: '#/components/schemas/BulkApiJobStatus'
        explode: false
      responses:
        '200':
          description: Response returned when listing Bulk API jobs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBulkApiJobsSuccessResponse'
        '400':
          description: Response for any operation that results in a bad request error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - bad_request
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/UResponses.BadRequestError'
                  message:
                    type: string
                description: Response for any operation that results in a bad request error.
        '401':
          description: Response for any operation that results in an unauthorized error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - unauthorized
                  message:
                    type: string
                description: Response for any operation that results in an unauthorized error.
        '429':
          description: Response for any operation that exceeds a rate limit.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - rate_limited
                  message:
                    type: string
                description: Response for any operation that exceeds a rate limit.
        '500':
          description: Response for any operation that results in an internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - error
                  message:
                    type: string
                description: Response for any operation that results in an internal server error.
      tags:
      - Tasks
  /tasks/v1/tasks/query-jobs/{job_id}:
    get:
      operationId: get_task_query_job
      description: 'Get a query job''s status. Poll until the status is terminal; results are

        available once the job is `FINISHED`. Jobs expire 24 hours after

        creation.'
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response returned when fetching a Bulk API job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBulkApiJobSuccessResponse'
        '400':
          description: Response for any operation that results in a bad request error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - bad_request
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/UResponses.BadRequestError'
                  message:
                    type: string
                description: Response for any operation that results in a bad request error.
        '401':
          description: Response for any operation that results in an unauthorized error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - unauthorized
                  message:
                    type: string
                description: Response for any operation that results in an unauthorized error.
        '404':
          description: Response returned when a Bulk API job cannot be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBulkApiJobNotFoundResponse'
        '429':
          description: Response for any operation that exceeds a rate limit.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - rate_limited
                  message:
                    type: string
                description: Response for any operation that exceeds a rate limit.
        '500':
          description: Response for any operation that results in an internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - error
                  message:
                    type: string
                description: Response for any operation that results in an internal server error.
      tags:
      - Tasks
  /tasks/v1/tasks/query-jobs/{job_id}/cancel:
    post:
      operationId: cancel_task_query_job
      description: Cancel a query job. Only `IN_PROGRESS` jobs can be canceled.
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response returned when canceling a Bulk API job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelBulkApiJobSuccessResponse'
        '400':
          description: Response for any operation that results in a bad request error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - bad_request
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/UResponses.BadRequestError'
                  message:
                    type: string
                description: Response for any operation that results in a bad request error.
        '401':
          description: Response for any operation that results in an unauthorized error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - unauthorized
                  message:
                    type: string
                description: Response for any operation that results in an unauthorized error.
        '404':
          description: Response returned when a Bulk API job cannot be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBulkApiJobNotFoundResponse'
        '409':
          description: Response returned when a Bulk API job is not cancelable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelBulkApiJobNotCancelableResponse'
        '429':
          description: Response for any operation that exceeds a rate limit.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - rate_limited
                  message:
                    type: string
                description: Response for any operation that exceeds a rate limit.
        '500':
          description: Response for any operation that results in an internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - error
                  message:
                    type: string
                description: Response for any operation that results in an internal server error.
      tags:
      - Tasks
  /tasks/v1/tasks/query-jobs/{job_id}/results:
    get:
      operationId: get_task_query_job_results
      description: 'Get Bulk API job results. By default this returns JSON. Send

        `Accept: application/x-ndjson` to stream newline-delimited JSON.'
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
        explode: false
      - name: page_size
        in: query
        required: false
        description: 'Maximum is 2,000 for JSON responses and 10,000 when `Accept` is

          `application/x-ndjson`.'
        schema:
          type: integer
          minimum: 1
          maximum: 10000
        explode: false
      responses:
        '200':
          description: Successful response returned when fetching completed Bulk API job results.
          headers:
            x-total:
              required: false
              description: Total result count. Present for NDJSON responses.
              schema:
                type: integer
            x-page:
              required: false
              description: Result page number. Present for NDJSON responses.
              schema:
                type: integer
            x-page-size:
              required: false
              description: Result page size. Present for NDJSON responses.
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                required:
                - total
                - page
                - page_size
                - data
                properties:
                  total:
                    type: integer
                  page:
                    type: integer
                  page_size:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaskQueryJobResult'
                description: Successful response returned when fetching completed Bulk API job results.
            application/x-ndjson:
              schema:
                type: string
        '400':
          description: Response for any operation that results in a bad request error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - bad_request
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/UResponses.BadRequestError'
                  message:
                    type: string
                description: Response for any operation that results in a bad request error.
        '401':
          description: Response for any operation that results in an unauthorized error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - unauthorized
                  message:
                    type: string
                description: Response for any operation that results in an unauthorized error.
        '404':
          description: Response returned when a Bulk API job cannot be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBulkApiJobNotFoundResponse'
        '409':
          description: Response returned when Bulk API job results are not ready yet.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/GetBulkApiJobResultsNotReadyResponse'
                - $ref: '#/components/schemas/GetBulkApiJobResultsFailedResponse'
                - $ref: '#/components/schemas/GetBulkApiJobResultsCanceledResponse'
        '410':
          description: Response returned when Bulk API job results have expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBulkApiJobResultsExpiredResponse'
        '413':
          description: Response returned when a requested Bulk API results page is too large.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBulkApiJobResultsPayloadTooLargeResponse'
        '429':
          description: Response for any operation that exceeds a rate limit.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - rate_limited
                  message:
                    type: string
                description: Response for any operation that exceeds a rate limit.
        '500':
          description: Response for any operation that results in an internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - error
                  message:
                    type: string
                description: Response for any operation that results in an internal server error.
      tags:
      - Tasks
  /tasks/v1/tasks/{id}:
    get:
      operationId: retrieve_task
      description: Get a single task by its ID.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveTaskResponse'
        '400':
          description: Response for any operation that results in a bad request error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - bad_request
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/UResponses.BadRequestError'
                  message:
                    type: string
                description: Response for any operation that results in a bad request error.
        '401':
          description: Response for any operation that results in an unauthorized error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - unauthorized
                  message:
                    type: string
                description: Response for any operation that results in an unauthorized error.
        '403':
          description: Response for any operation that results in a forbidden error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - forbidden
                  messag

# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/unify/refs/heads/main/openapi/unify-tasks-api-openapi.yml