> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jobin.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Update contact task

> Update or complete an existing task associated with a contact.

Update only the supplied fields on the task identified by the path; omitted fields and the task ID remain unchanged. For example, send `{"title":"Review assessment","date":"2026-11-12"}` to change the title and due date, or `{"done":true}` after the work is complete.

Set optional Job, pipeline, stage, sub-stage, queue, or assignee fields to `null` to clear them. Clear related fields together when leaving some in place would make the relationship invalid.

An enabled reminder requires an assignee. Disable the reminder in the task editor before clearing the assignee; this endpoint does not change reminder settings.

The task must belong to the contact and authenticated workgroup. Supplied Job, pipeline, stage and sub-stage values must form a valid relationship. Synced provider tasks are read-only. Completing a task may continue a waiting sequence and remove the task from open queue counts; retrying a completion keeps the same task.

*Rate limit: 30 requests/minute per endpoint and workgroup. [Details](https://docs.jobin.cloud/development.md#rate-limits).*


## OpenAPI

````yaml openapi/jobin-integration.json PATCH /contacts/{contactId}/tasks/{taskId}
openapi: 3.1.0
info:
  title: Jobin Integration API
  version: 1.0.0
  description: >-
    Work with Jobin contacts and outreach sequences from your recruiting tools
    and AI assistants. See [integration
    guidelines](https://docs.jobin.cloud/development#rate-limits) for rate
    limits and retries.
servers:
  - url: https://my.jobin.cloud/api/openapi/v1
    description: Public OpenAPI base URL. Append each path below to this base URL.
security: []
paths:
  /contacts/{contactId}/tasks/{taskId}:
    patch:
      summary: Update or complete a contact task
      description: >-
        Updates an existing native task associated with the contact. Use
        done=true only after the work is performed; completion can continue a
        sequence. Provider-owned tasks are read-only.
      parameters:
        - name: contactId
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-fA-F0-9]{24}$
        - name: taskId
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-fA-F0-9]{24}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactTaskUpdateRequest'
      responses:
        '200':
          description: Updated task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactTask'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/ApiError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ContactTaskUpdateRequest:
      type: object
      description: >-
        Partial update. Omitted fields are preserved. Completing a task may
        continue a sequence.
      additionalProperties: false
      minProperties: 1
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 256
        description:
          type: string
          maxLength: 4000
        date:
          type: string
          format: date
        time:
          type: string
          pattern: ^([01]\d|2[0-3]):[0-5]\d$
        done:
          type: boolean
        priority:
          type: string
          enum:
            - low
            - medium
            - high
        assigneeId:
          type:
            - string
            - 'null'
          pattern: ^[a-fA-F0-9]{24}$
        queueId:
          type:
            - string
            - 'null'
          pattern: ^[a-fA-F0-9]{24}$
        jobspecId:
          type:
            - string
            - 'null'
          pattern: ^[a-fA-F0-9]{24}$
        pipelineId:
          type:
            - string
            - 'null'
          pattern: ^[a-fA-F0-9]{24}$
        stageName:
          type:
            - string
            - 'null'
          minLength: 1
          maxLength: 256
        subStageName:
          type:
            - string
            - 'null'
          minLength: 1
          maxLength: 256
    ContactTask:
      type: object
      description: A native Jobin task associated with a contact.
      properties:
        id:
          type: string
          description: Task identifier.
        contactId:
          type:
            - string
            - 'null'
          description: Associated contact identifier.
        title:
          type: string
        type:
          type: string
          enum:
            - task
            - call
            - meeting
        date:
          type:
            - string
            - 'null'
          pattern: ^\d{4}-\d{2}-\d{2}$
        time:
          type:
            - string
            - 'null'
          pattern: ^\d{2}:\d{2}$
        description:
          type:
            - string
            - 'null'
        links:
          type: array
          items:
            type: string
        location:
          type:
            - string
            - 'null'
        phoneNumber:
          type:
            - string
            - 'null'
        meetingLink:
          type:
            - string
            - 'null'
        done:
          type: boolean
        flagged:
          type: boolean
        outcome:
          type:
            - string
            - 'null'
        priority:
          type:
            - string
            - 'null'
          enum:
            - low
            - medium
            - high
            - null
        assigneeId:
          type:
            - string
            - 'null'
        candidateIds:
          type: array
          items:
            type: string
        queueId:
          type:
            - string
            - 'null'
        jobspecId:
          type:
            - string
            - 'null'
        pipelineId:
          type:
            - string
            - 'null'
        stageName:
          type:
            - string
            - 'null'
        subStageName:
          type:
            - string
            - 'null'
        reminderEnabled:
          type: boolean
        reminderMinutesBefore:
          type:
            - integer
            - 'null'
        source:
          type: string
        readOnly:
          type: boolean
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
        updatedAt:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - id
        - title
        - type
        - done
    Error:
      type: object
      required:
        - code
        - error
      properties:
        code:
          type: string
          description: Stable error code. Input validation uses VALIDATION_ERROR.
        error:
          type: string
          description: >-
            User-facing message. Unknown failures return a generic message
            without internal details.
      example:
        code: UNHANDLED_EXCEPTION
        error: Unexpected error
    RateLimitError:
      type: object
      description: Returned when a public OpenAPI rate limit is exceeded.
      properties:
        statusCode:
          type: integer
          example: 429
        error:
          type: string
          example: Too Many Requests
        message:
          type: string
          description: Human-readable description of the limit that was exceeded.
        retryAfterSeconds:
          type: integer
          description: Seconds to wait before retrying the request.
  responses:
    BadRequest:
      description: Invalid request or expected business-rule failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: >-
        Missing or invalid authentication, or missing required authentication
        context.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found in the authenticated workgroup.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimitExceeded:
      description: >-
        Rate limit exceeded. Wait for the retry-after header before sending the
        next request.
      headers:
        retry-after:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        x-ratelimit-limit:
          description: Maximum requests allowed in the current window.
          schema:
            type: integer
        x-ratelimit-remaining:
          description: Requests remaining in the current window.
          schema:
            type: integer
        x-ratelimit-reset:
          description: Seconds until the current window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/RateLimitError'
              - $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Unexpected server failure. Internal details are masked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ApiError:
      description: Other client or server failure. Unknown errors expose a generic message.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Primary public authentication method. Create keys in Jobin.cloud under
        Workgroups > Integrations > Custom integration.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.