# Update a HumanTask

`PATCH /v1/human_tasks/:id`

Updates a HumanTask in the Organization's staff task queue. Set `completed_at` to an ISO 8601 timestamp to complete it, or to `null` to reopen it. Replace `assignees` to reassign it. Add a Comment with `POST /v1/human_tasks/{id}/comments`. Look up assignable StaffMembers with `GET /v1/staff_members`.

**Required API scopes:** `human_tasks.update`

## Parameters

- `id` (path, `string`) (required)
- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `assignees` (`array`) - The people to assign to the HumanTask. Each object requires `assignee_type` and `assignee_id`. Currently only `staff_member` is supported. Replaces the current assignees.
    - `items` (`object`)
      - `assignee_id` (`string`) - format: `uuid`; The identifier of the assignee. For `staff_member`, use an identifier from `GET /v1/staff_members`.
      - `assignee_type` (`string`) - enum: `staff_member`; The type of assignee. Currently only `staff_member` is supported.
  - `completed_at` (`string | null`) - format: `date-time`; Set an ISO 8601 timestamp to complete the HumanTask. Set it to null to reopen the HumanTask.
  - `content` (`string`) - The description of the work to complete.
  - `document_id` (`string | null`) - format: `uuid`; The optional Document associated with the HumanTask, for example a Letter, TestResult, Photo, or BookingForm. Set it to null to clear it.
  - `due_date` (`string`) - format: `date`; The date by which staff should complete the HumanTask.
  - `is_remindable` (`boolean`) - Whether Carebit can send reminders when the HumanTask becomes due.
  - `is_urgent` (`boolean`) - Whether the HumanTask should be marked as urgent.
  - `patient_id` (`string | null`) - format: `uuid`; The optional Patient associated with the HumanTask. Set it to null to clear it.

### Example

```json
{
  "completed_at": "2026-01-04T10:00:00Z"
}
```

## Response `200`

The requested `HumanTask`.

- `object`
  - `assignees` (`array`) - The people assigned to the HumanTask. Currently only `staff_member` is supported.
    - `items` (`object`)
      - `assignee_id` (`string`) - format: `uuid`; The identifier of the assignee. For `staff_member`, use an identifier from `GET /v1/staff_members`.
      - `assignee_type` (`string`) - enum: `staff_member`; The type of assignee. Currently only `staff_member` is supported.
  - `comments` (`array`) - Comments on the HumanTask, oldest first. Discarded Comments are omitted.
    - `items` (`object`)
      - `content` (`string`) - The sanitized comment text.
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `created_by_staff_member_id` (`string | null`) - format: `uuid`; The StaffMember who wrote the Comment in Carebit. Null when the Comment was created through the API.
      - `human_task_id` (`string`) - format: `uuid`; The HumanTask this Comment belongs to.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `links` (`object`) - URLs to related resources.
        - `created_by_staff_member` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `human_task` (`string`) - format: `uri`; The full URL of a related resource.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `completed_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `completed_by_staff_member_id` (`string | null`) - format: `uuid`; The StaffMember who completed the HumanTask in Carebit. Null when the HumanTask is open, or when it was completed through the API without a StaffMember.
  - `content` (`string`) - The sanitized description of the work to complete.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `creation_source` (`string | null`) - enum: `api`, `app`, `automation`, `import`, `staff_member`, `null`; How the HumanTask was created. `api` means the record was created through the Developer Platform API. Read-only.
  - `document_id` (`string | null`) - format: `uuid`; The Document associated with the HumanTask, when the HumanTask belongs to a Letter, TestResult, Photo, or BookingForm.
  - `due_date` (`string`) - format: `date`; The date by which staff should complete the HumanTask.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `is_remindable` (`boolean`) - Whether Carebit can send reminders when the HumanTask becomes due.
  - `is_urgent` (`boolean`) - Whether the HumanTask is marked as urgent.
  - `links` (`object`) - URLs to related resources.
    - `completed_by_staff_member` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `document` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `patient` (`string | null`) - format: `uri`; The full URL of a related resource.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `patient_id` (`string | null`) - format: `uuid`; The Patient associated with the HumanTask.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "8408d9e2-6643-4aee-8ebd-8edf57ead496",
  "object": "human_task",
  "assignees": [
    {
      "assignee_id": "00000000-0000-4000-8000-000000000021",
      "assignee_type": "staff_member"
    }
  ],
  "comments": [
    {
      "id": "e7bcd0e1-df8c-456f-8242-ef51dac3b061",
      "object": "comment",
      "content": "Moved this to the secretary after the Patient called.",
      "created_at": "2026-01-01T09:00:00Z",
      "created_by_staff_member_id": "820b1195-41c0-476a-8add-3f2e706e2c01",
      "human_task_id": "8408d9e2-6643-4aee-8ebd-8edf57ead496",
      "links": {
        "created_by_staff_member": "https://api.carebit.co/v1/created_by_staff_members/820b1195-41c0-476a-8add-3f2e706e2c01",
        "human_task": "https://api.carebit.co/v1/human_tasks/8408d9e2-6643-4aee-8ebd-8edf57ead496"
      },
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "completed_at": "2026-01-01T09:00:00Z",
  "completed_by_staff_member_id": "d5988084-3224-4174-8e46-83702cadb572",
  "content": "Review the Patient's completed consent form.",
  "created_at": "2026-01-01T09:00:00Z",
  "creation_source": "api",
  "document_id": "78aa99b3-1b45-47c3-8608-ece2f58b39ee",
  "due_date": "2026-01-01",
  "is_remindable": true,
  "is_urgent": true,
  "links": {
    "completed_by_staff_member": "https://api.carebit.co/v1/completed_by_staff_members/d5988084-3224-4174-8e46-83702cadb572",
    "document": "https://api.carebit.co/v1/documents/78aa99b3-1b45-47c3-8608-ece2f58b39ee",
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
  },
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X PATCH "https://api.carebit.co/v1/human_tasks/8408d9e2-6643-4aee-8ebd-8edf57ead496" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "completed_at": "2026-01-04T10:00:00Z"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/human_tasks/8408d9e2-6643-4aee-8ebd-8edf57ead496", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "completed_at": "2026-01-04T10:00:00Z"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.patch(
    "https://api.carebit.co/v1/human_tasks/8408d9e2-6643-4aee-8ebd-8edf57ead496",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "completed_at": "2026-01-04T10:00:00Z"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.patch(
  "https://api.carebit.co/v1/human_tasks/8408d9e2-6643-4aee-8ebd-8edf57ead496",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "completed_at" => "2026-01-04T10:00:00Z"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->patch("https://api.carebit.co/v1/human_tasks/8408d9e2-6643-4aee-8ebd-8edf57ead496", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "completed_at" => "2026-01-04T10:00:00Z"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```